{"openapi":"3.1.0","info":{"title":"Forge Platform API","version":"0.23.0","description":"HTTP API for the Gloo Forge hybrid workforce orchestration platform. Resources are organized along REST-style paths with named operations (RPC-style verbs for state changes). Supported credentials are OAuth2 client_credentials JWTs for External Apps, platform API keys, and Personal keys (person-bound `fmcp_…` keys); direct bearer use of an External App companion key is deprecated. What a key or an app may call is its role grants, narrowed by its key or token scopes; each operation names the permissions it requires, and a refusal answers 403 with `error.requiredPermission`.","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"}}}]}},"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/v2/agents/list":{"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`.","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."}],"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"}},"/api/v2/agents/get":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/agents/getCard":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/agents/create":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/update":{"patch":{"operationId":"updateAgent","tags":["Agents"],"summary":"Update an agent","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentBody"}}}},"responses":{"200":{"description":"Agent updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UpdateAgentResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}}},"headers":{"X-Request-Id":{"$ref":"#/components/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-conditional-permissions":[{"permission":"switches:use","bodyField":"status","when":"the patch carries a status"}],"x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/delete":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveAgentBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/deletePermanently":{"delete":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAgentPermanentlyBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/assignToolSet":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignAgentToolSetBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/unassignToolSet":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnassignAgentToolSetBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/assignSkill":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignAgentSkillBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/listVersions":{"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`.","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/agents/listConsumers":{"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`.","parameters":[{"name":"id","in":"query","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}}],"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"}},"/api/v2/agents/reinstateVersion":{"post":{"operationId":"reinstateAgentVersion","tags":["Agents"],"summary":"Roll an agent back to a prior version","description":"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReinstateAgentVersionBody"}}}},"responses":{"200":{"description":"Version reinstated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReinstateAgentVersionResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}}},"headers":{"X-Request-Id":{"$ref":"#/components/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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/unassignSkill":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnassignAgentSkillBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/listTaskRuns":{"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.","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`."}],"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"}},"/api/v2/agents/listConsultations":{"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.","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`."}],"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"}},"/api/v2/agents/getConfiguration":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"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"}},"/api/v2/agents/getReadiness":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"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"}},"/api/v2/agents/getSetupRequest":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"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"}},"/api/v2/agents/listProcedureGrants":{"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.","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/agents/listGrants":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"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"}},"/api/v2/agents/getRelationships":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"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"}},"/api/v2/agents/listKnowledgeActivity":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's slug (`agentId`) or definition id."}],"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"}},"/api/v2/agents/listReadableScopes":{"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.","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/agents/listTemplates":{"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.","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`."}],"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"}},"/api/v2/agents/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKillSwitchBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKillSwitchBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKillSwitchBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/assignOwner":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignAgentOwnerBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/acknowledgeReview":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcknowledgeAgentReviewBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/attestIdentity":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttestAgentIdentityBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/createFromTemplate":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentFromTemplateBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/assignProcedure":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProcedureAssignmentBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/unassignProcedure":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProcedureAssignmentBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/assignTool":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentToolAssignmentBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/unassignTool":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentToolAssignmentBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/replaceExemplars":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceAgentExemplarsBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/requestSetup":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestAgentSetupBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/skills/list":{"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.","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}}],"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"}},"/api/v2/skills/get":{"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`.","parameters":[{"name":"id","in":"query","required":true,"description":"The skill's `skillId`.","schema":{"type":"string"}}],"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"}},"/api/v2/skills/listVersions":{"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`.","parameters":[{"name":"skillId","in":"query","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`."}],"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"}},"/api/v2/skills/create":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkillBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/skills/update":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSkillBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/list":{"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`.","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"}}],"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"}},"/api/v2/tools/get":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/tools/listSets":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/tools/listVersions":{"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`.","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/skills/listSets":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/skills/createSet":{"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.","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"}}}},"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"}},"/api/v2/skills/updateSet":{"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.","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/UpdateSkillSetRequest"}}}},"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"}},"/api/v2/skills/deleteSet":{"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.","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/SetIdRequest"}}}},"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"}},"/api/v2/skills/addSetMember":{"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.","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/SkillSetMemberRequest"}}}},"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"}},"/api/v2/skills/removeSetMember":{"post":{"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.","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/SkillSetMemberRequest"}}}},"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"}},"/api/v2/tools/createSet":{"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.","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"}}}},"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"}},"/api/v2/tools/updateSet":{"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.","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/UpdateToolSetRequest"}}}},"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"}},"/api/v2/tools/deleteSet":{"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.","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/SetIdRequest"}}}},"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"}},"/api/v2/tools/listAgents":{"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`.","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/tools/listExecutions":{"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`.","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/tools/getUsage":{"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`.","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/tools/listMostUsed":{"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.","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`."}],"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"}},"/api/v2/tools/listNeedingAttention":{"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.","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`."}],"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"}},"/api/v2/tools/listAuditHistory":{"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`.","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/tools/getSandboxRejections":{"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`.","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/models/list":{"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`.","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`."}],"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"}},"/api/v2/models/get":{"get":{"operationId":"getModel","tags":["Models"],"summary":"Get a model by ID","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/models/getDetail":{"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=`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"The model's `modelId`, for example `anthropic/claude-opus-4`."}],"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"}},"/api/v2/models/listFallbackChains":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/objectives/create":{"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.","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"}}}},"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"}},"/api/v2/objectives/update":{"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.","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/UpdateObjectiveRequest"}}}},"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"}},"/api/v2/objectives/archive":{"post":{"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.","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/ArchiveObjectiveRequest"}}}},"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"}},"/api/v2/objectives/addKeyResult":{"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.","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/AddKeyResultRequest"}}}},"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"}},"/api/v2/objectives/updateKeyResult":{"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.","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/UpdateKeyResultRequest"}}}},"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"}},"/api/v2/objectives/removeKeyResult":{"post":{"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.","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/RemoveKeyResultRequest"}}}},"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"}},"/api/v2/objectives/list":{"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.","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}}],"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"}},"/api/v2/objectives/get":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/objectives/listKeyResults":{"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.","parameters":[{"name":"objectiveId","in":"query","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`."}],"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"}},"/api/v2/roadmaps/list":{"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`.","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}}],"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"}},"/api/v2/roadmaps/get":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/workstreams/list":{"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`.","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}}],"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"}},"/api/v2/workstreams/get":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/milestones/list":{"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`.","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}}],"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"}},"/api/v2/milestones/get":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/roadmaps/create":{"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.","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"}}}},"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"}},"/api/v2/roadmaps/update":{"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.","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/UpdateRoadmapRequest"}}}},"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"}},"/api/v2/workstreams/create":{"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.","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"}}}},"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"}},"/api/v2/workstreams/update":{"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.","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/UpdateWorkstreamRequest"}}}},"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"}},"/api/v2/milestones/create":{"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.","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"}}}},"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"}},"/api/v2/milestones/update":{"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.","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/UpdateMilestoneRequest"}}}},"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"}},"/api/v2/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.","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"}}}},"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"}},"/api/v2/planning/getCriticalPath":{"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.","parameters":[{"name":"roadmapId","in":"query","schema":{"type":"string"},"required":true},{"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}}],"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"}},"/api/v2/planning/listBlockedTasks":{"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.","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`."}],"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"}},"/api/v2/workflows/create":{"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.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkflowBody"}}}},"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"}},"/api/v2/workflows/updateDraft":{"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.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkflowDraftBody"}}}},"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"}},"/api/v2/workflows/list":{"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.","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`."}],"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"}},"/api/v2/workflows/get":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"Workflow document 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"}},"/api/v2/workflows/get-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.","parameters":[{"name":"id","in":"query","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)."}],"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"}},"/api/v2/workflows/getDraft":{"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`**.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"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"}},"/api/v2/workflows/listTriggers":{"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.","parameters":[{"name":"workflowId","in":"query","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."}],"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"}},"/api/v2/workflows/getTrigger":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Trigger id from `listTriggers`."}],"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"}},"/api/v2/workflows/listFiscalCalendars":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/workflows/getFiscalCalendar":{"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.","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"}}],"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"}},"/api/v2/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).","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}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"expensive"}},"/api/v2/workflows/getDraftGraph":{"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`**.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"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"}},"/api/v2/workflows/validateDraft":{"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`**.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"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"}},"/api/v2/workflows/createDraftNode":{"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`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkflowDraftNodeBody"}}}},"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"}},"/api/v2/workflows/updateDraftNode":{"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`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkflowDraftNodeBody"}}}},"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"}},"/api/v2/workflows/deleteDraftNode":{"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`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteWorkflowDraftNodeBody"}}}},"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"}},"/api/v2/workflows/createDraftEdge":{"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`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkflowDraftEdgeBody"}}}},"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"}},"/api/v2/workflows/updateDraftEdge":{"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`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkflowDraftEdgeBody"}}}},"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"}},"/api/v2/workflows/deleteDraftEdge":{"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`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteWorkflowDraftEdgeBody"}}}},"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"}},"/api/v2/workflows/listVersions":{"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`.","parameters":[{"name":"workflowId","in":"query","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."}],"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"}},"/api/v2/workflows/getVersion":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Version id from `listVersions`. Give it exactly once."}],"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"}},"/api/v2/workflows/getVersionGraph":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Version id from `listVersions`. Give it exactly once."}],"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"}},"/api/v2/workflows/getArchitectStatus":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"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"}},"/api/v2/workflows/getArchitectPlan":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"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"}},"/api/v2/workflows/getArchitectProgress":{"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\".","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"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"}},"/api/v2/workflows/getSynthesisConfirmation":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"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"}},"/api/v2/workflows/getArchitectDecisions":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"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"}},"/api/v2/workflows/getArchitectJitMode":{"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\".","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Workflow document id. Give it exactly once."}],"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"}},"/api/v2/workflows/askArchitectToFixRun":{"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.","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/AskArchitectToFixRunBody"}}}},"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"}},"/api/v2/workflows/createFromChatTask":{"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.","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"}}}},"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"}},"/api/v2/workflows/setArchitectJitMode":{"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.","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/SetArchitectJitModeBody"}}}},"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"}},"/api/v2/workflows/startArchitectConversation":{"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.","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"}}}},"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"}},"/api/v2/workflows/sendArchitectMessage":{"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.","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/SendArchitectMessageBody"}}}},"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"}},"/api/v2/workflows/resetArchitectConversation":{"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.","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/ArchitectConversationBody"}}}},"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"}},"/api/v2/workflows/cancelArchitectTurn":{"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.","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/ArchitectConversationBody"}}}},"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"}},"/api/v2/workflows/listArchitectMessages":{"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\".","parameters":[{"name":"id","in":"query","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)."}],"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"}},"/api/v2/workflows/previewProcedureRepin":{"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.","parameters":[{"name":"procedureId","in":"query","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."}],"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"}},"/api/v2/workflows/repinProcedure":{"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.","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/RepinProcedureBody"}}}},"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"}},"/api/v2/workflows/testRouteCondition":{"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.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestRouteConditionBody"}}}},"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"}},"/api/v2/workflows/getDebugOptions":{"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\".","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/workflows/prepareDebugAttempt":{"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.","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/PrepareDebugAttemptBody"}}}},"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"}},"/api/v2/workflows/launchDebugAttempt":{"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.","parameters":[{"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/LaunchDebugAttemptBody"}}}},"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"}},"/api/v2/workflows/getDebugAttempt":{"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\".","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The debug attempt's id. Give it exactly once."}],"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"}},"/api/v2/workflows/cancelDebugAttempt":{"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.","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/CancelDebugAttemptBody"}}}},"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"}},"/api/v2/workflows/listDebugAttemptHistory":{"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\".","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/workflows/compareDebugAttempts":{"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\".","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/workflows/listDebugFiles":{"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\".","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The debug attempt's id. Give it exactly once."}],"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"}},"/api/v2/workflows/getDebugFileUrl":{"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\".","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The debug attempt's id. Give it exactly once."},{"name":"fileId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The file's id, from `listDebugFiles`. Give it exactly once."}],"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"}},"/api/v2/workflows/listDebugToolCalls":{"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\".","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/workflows/getDebugPreviewOptions":{"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\".","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow version's id. Give it exactly once."}],"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"}},"/api/v2/workflows/previewDebugSlice":{"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\".","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/runs/list":{"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.","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}}],"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"}},"/api/v2/runs/get":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/runs/listEvents":{"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.","parameters":[{"name":"runId","in":"query","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}}],"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"}},"/api/v2/runs/listArtifacts":{"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.","parameters":[{"name":"runId","in":"query","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`."}],"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"}},"/api/v2/runs/getTrustStatus":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/runs/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRunBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/runs/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestartRunBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"expensive"}},"/api/v2/runs/retryNotification":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetryRunNotificationBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/runs/startAnalysis":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartRunAnalysisBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"expensive"}},"/api/v2/runs/setKillSwitch":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetRunKillSwitchBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/runs/getProvenance":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"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"}},"/api/v2/runs/getStep":{"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\".","parameters":[{"name":"runId","in":"query","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."}],"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"}},"/api/v2/runs/getTimeline":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"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"}},"/api/v2/runs/listValidatorRuns":{"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.","parameters":[{"name":"runId","in":"query","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."}],"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"}},"/api/v2/runs/listStepContext":{"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.","parameters":[{"name":"runId","in":"query","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`."}],"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"}},"/api/v2/runs/resolveCitation":{"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.","parameters":[{"name":"runId","in":"query","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`."}],"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"}},"/api/v2/runs/getArtifactProducer":{"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\".","parameters":[{"name":"runId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."},{"name":"fileId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The run's output file id."}],"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"}},"/api/v2/runs/listNotificationObligations":{"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.","parameters":[{"name":"runId","in":"query","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."}],"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"}},"/api/v2/runs/getDebugBundle":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"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"}},"/api/v2/runs/getMarkdown":{"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.","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/runs/listStepMessages":{"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.","parameters":[{"name":"runId","in":"query","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."}],"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"}},"/api/v2/runs/getDiagnosticTimeline":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"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"}},"/api/v2/runs/listAnalyses":{"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.","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."}],"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"}},"/api/v2/runs/getAnalysis":{"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\".","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The run id."}],"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"}},"/api/v2/runs/listAnalysisMessages":{"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.","parameters":[{"name":"runId","in":"query","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."}],"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"}},"/api/v2/sandboxes/listRuns":{"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.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Rows, 1-100. Default 50."}],"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"}},"/api/v2/sandboxes/getFleetSummary":{"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.","parameters":[],"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"}},"/api/v2/sandboxes/getLineage":{"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.","parameters":[{"name":"runId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow run."}],"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"}},"/api/v2/sandboxes/listActive":{"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.","parameters":[{"name":"runId","in":"query","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`."}],"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"}},"/api/v2/sandboxes/listCommands":{"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.","parameters":[{"name":"runId","in":"query","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."}],"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"}},"/api/v2/sandboxes/diffSnapshots":{"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.","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}],"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"}},"/api/v2/sandboxes/replayCommand":{"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.","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 never runs the command again; it answers 409 because the result is not stored."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaySandboxCommandRequest"}}}},"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"}},"/api/v2/outcomes/get":{"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).","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/outcomes/getDossier":{"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).","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/outcomes/getForRun":{"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).","parameters":[{"name":"runId","in":"query","required":true,"schema":{"type":"string","minLength":1}},{"name":"attempt","in":"query","schema":{"type":"integer","minimum":1}}],"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"}},"/api/v2/outcomes/list":{"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).","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}}],"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"}},"/api/v2/outcomes/listObjectiveContributions":{"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.","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/outcomes/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.","parameters":[{"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/RateOutcomeRequest"}}}},"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"}},"/api/v2/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`).","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"}}}},"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"}},"/api/v2/files/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.","parameters":[{"name":"id","in":"query","required":true,"description":"The `fileId` returned by an upload or listed as a run artifact.","schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/chat/listChannels":{"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.","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}}],"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"}},"/api/v2/chat/getSession":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/chat/listMessages":{"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`.","parameters":[{"name":"id","in":"query","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}}],"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"}},"/api/v2/chat/createSession":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channelId":{"type":"string","minLength":1},"title":{"type":"string","minLength":1},"description":{"type":"string"},"purpose":{"type":"string"},"autoArchiveAfterMinutes":{"type":"number"},"relevancyScoringModeOverride":{"type":"string"},"restrictedParticipants":{"type":"array","items":{"type":"string"}}},"required":["channelId","title"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/sendMessage":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","minLength":1},"content":{"type":"string","minLength":1},"contentType":{"type":"string","minLength":1},"toolName":{"type":"string"},"toolInput":{},"toolOutput":{}},"required":["sessionId","content","contentType"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/memory/list":{"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.","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."}],"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"}},"/api/v2/memory/get":{"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.","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/memory/create":{"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`.","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"}}}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/memory/update":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"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":["id","layer"],"additionalProperties":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/memory/delete":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string","enum":["longterm"],"description":"Must be `longterm`. Any other value, or an omitted layer, answers 400."}},"required":["id","layer"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/knowledge/history":{"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.","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}]}}}},"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"}},"/api/v2/knowledge/records/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.","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}}],"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"}},"/api/v2/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.","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}}}},"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"}},"/api/v2/knowledge/cases/list":{"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.","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}}],"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"}},"/api/v2/knowledge/cases/get":{"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.","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}}],"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"}},"/api/v2/knowledge/cases/listVersions":{"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.","parameters":[{"name":"entryId","in":"query","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`."}],"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"}},"/api/v2/knowledge/cases/getRevision":{"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.","parameters":[{"name":"entryId","in":"query","required":true,"description":"The case id (`id` from `listKnowledgeCases`).","schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/knowledge/cases/listUses":{"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.","parameters":[{"name":"entryId","in":"query","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`."}],"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"}},"/api/v2/knowledge/cases/create":{"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.","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"}}}},"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"}},"/api/v2/knowledge/cases/update":{"post":{"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.","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/UpdateKnowledgeCaseRequest"}}}},"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"}},"/api/v2/knowledge/cases/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.","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/VerifyKnowledgeCaseRequest"}}}},"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"}},"/api/v2/knowledge/cases/setGrade":{"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.","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/SetKnowledgeCaseGradeRequest"}}}},"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"}},"/api/v2/knowledge/cases/setSteward":{"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.","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/SetKnowledgeCaseStewardRequest"}}}},"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"}},"/api/v2/knowledge/records/list":{"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.","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}}}},"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"}},"/api/v2/knowledge/records/get":{"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.","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}]}}}},"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"}},"/api/v2/knowledge/collections/list":{"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.","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`."}],"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"}},"/api/v2/knowledge/collections/get":{"get":{"operationId":"getKnowledgeRecordCollection","tags":["Knowledge"],"summary":"Get a knowledge record collection","parameters":[{"in":"query","name":"collectionId","schema":{"type":"string","minLength":1},"required":true}],"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"}},"/api/v2/knowledge/records/create":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string","minLength":1},"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":["collectionId","externalId","attributes"],"additionalProperties":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/knowledge/records/update":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string","minLength":1},"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},"expectedVersion":{"type":"integer","minimum":1}},"required":["collectionId","externalId","attributes","expectedVersion"],"additionalProperties":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/knowledge/records/remove":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string","minLength":1},"externalId":{"type":"string","minLength":1},"expectedVersion":{"type":"integer","minimum":1},"reason":{"type":"string","minLength":1}},"required":["collectionId","externalId","expectedVersion","reason"],"additionalProperties":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/knowledge/collections/create":{"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`.","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"}}}},"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"}},"/api/v2/knowledge/subjectCollections/list":{"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.","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`."}],"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"}},"/api/v2/knowledge/goldenSets/list":{"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.","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`."}],"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"}},"/api/v2/knowledge/goldenSets/listRuns":{"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.","parameters":[{"name":"goldenSetId","in":"query","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`."}],"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"}},"/api/v2/knowledge/goldenSets/create":{"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.","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"}}}},"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"}},"/api/v2/knowledge/goldenSets/update":{"post":{"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.","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/UpdateKnowledgeGoldenSetRequest"}}}},"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"}},"/api/v2/knowledge/goldenSets/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.","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/RunKnowledgeGoldenSetRequest"}}}},"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"}},"/api/v2/knowledge/synchronized-sources/listProviders":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/knowledge/synchronized-sources/create":{"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.","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"}}}},"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"}},"/api/v2/knowledge/synchronized-sources/remove":{"post":{"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.","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/RemoveKnowledgeSourceRequest"}}}},"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"}},"/api/v2/knowledge/synchronized-sources/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.","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/RelistKnowledgeSourceRequest"}}}},"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"}},"/api/v2/knowledge/settings/get":{"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"}},"/api/v2/knowledge/settings/set":{"post":{"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`.","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/SetKnowledgeSettingRequest"}}}},"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"}},"/api/v2/knowledge/reembed/start":{"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`.","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"}}}},"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"}},"/api/v2/knowledge/reembed/getLatestRun":{"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"}},"/api/v2/knowledge/scopes/list":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/knowledge/scopes/get":{"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.","parameters":[{"name":"namespace","in":"query","required":true,"description":"One knowledge namespace from `scopes/list` (for example `company` or `team:<orgUnitId>`).","schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/knowledge/synchronized-sources/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.","parameters":[{"name":"sourceId","in":"query","required":true,"description":"The source id returned by `listSynchronizedSources`.","schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/knowledge/synchronized-sources/reviewDiff":{"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).","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/ReviewKnowledgeSourceDiffRequest"}}}},"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"}},"/api/v2/knowledge/synchronized-sources/setDiffPolicy":{"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.","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/SetKnowledgeSourceDiffPolicyRequest"}}}},"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"}},"/api/v2/knowledge/synchronized-sources/approveDiff":{"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.","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/ApproveKnowledgeSourceDiffRequest"}}}},"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"}},"/api/v2/knowledge/synchronized-sources/rejectDiff":{"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.","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/KnowledgeSourceRunDecisionRequest"}}}},"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"}},"/api/v2/knowledge/synchronized-sources/approveShrink":{"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.","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/KnowledgeSourceRunDecisionRequest"}}}},"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"}},"/api/v2/knowledge/synchronized-sources/overrideShrink":{"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.","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/OverrideKnowledgeSourceShrinkRequest"}}}},"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"}},"/api/v2/knowledge/synchronized-sources/listContainers":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListKnowledgeSourceContainersRequest"}}}},"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,"parameters":[{"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`."}],"x-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"write"}},"/api/v2/knowledge/synchronized-sources/getKindStates":{"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.","parameters":[{"name":"sourceId","in":"query","required":true,"description":"The source's id, from `synchronized-sources/list`.","schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/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.","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"}}],"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"}},"/api/v2/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.","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}}],"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"}},"/api/v2/knowledge/retryPendingEntry":{"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.","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":{"entryId":{"type":"string","description":"The pending entry's id (`pending.entries[].entryId` in knowledge health)."}},"required":["entryId"]}}}},"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"}},"/api/v2/knowledge/synchronized-sources/requestSync":{"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.","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","description":"The source's id (`sources.items[].id` in knowledge health)."}},"required":["sourceId"]}}}},"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"}},"/api/v2/knowledge/synchronized-sources/list":{"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.","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`."}],"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"}},"/api/v2/knowledge/synchronized-sources/get":{"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.","parameters":[{"name":"sourceId","in":"query","required":true,"description":"The source id returned by `listSynchronizedSources`.","schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/knowledge/synchronized-sources/listRuns":{"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.","parameters":[{"name":"sourceId","in":"query","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`."}],"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"}},"/api/v2/knowledge/synchronized-sources/update":{"post":{"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`.","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/UpdateKnowledgeSourceRequest"}}}},"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"}},"/api/v2/knowledge/getChunks":{"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.","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"]}}}},"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"}},"/api/v2/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.","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"]}}}},"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"}},"/api/v2/knowledge/addKnowledge":{"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.","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"]}}}},"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"}},"/api/v2/knowledge/get":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Knowledge entry id (the `id` returned by `getChunks` or `addKnowledge`)."},"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":["id"]}}}},"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"}},"/api/v2/knowledge/listReviews":{"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.","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}}],"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"}},"/api/v2/knowledge/getReview":{"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.","parameters":[{"name":"id","in":"query","required":true,"description":"The review item id (`id` from `listReviews`).","schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/knowledge/decideReview":{"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.","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/DecideKnowledgeReviewRequest"}}}},"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"}},"/api/v2/knowledge/listLearning":{"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.","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}}],"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"}},"/api/v2/knowledge/delete":{"post":{"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.","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":{"id":{"type":"string","description":"Knowledge entry id (the `id` returned by `getChunks` or `addKnowledge`)."},"reason":{"type":"string","maxLength":500,"description":"Why the entry is deleted; recorded on the audit event."}},"required":["id"]}}}},"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"}},"/api/v2/factories/list":{"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.","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}}],"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"}},"/api/v2/factories/get":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/factories/listTasks":{"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.","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}}],"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"}},"/api/v2/factories/getTask":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/factories/createTask":{"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.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFactoryTaskBody"}}}},"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"}},"/api/v2/factories/updateTask":{"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.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFactoryTaskBody"}}}},"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"}},"/api/v2/factories/assignTask":{"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.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignFactoryTaskBody"}}}},"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"}},"/api/v2/factories/transitionTask":{"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.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionFactoryTaskBody"}}}},"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"}},"/api/v2/factories/listWorkers":{"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`.","parameters":[{"name":"id","in":"query","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}}],"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"}},"/api/v2/factories/getSpend":{"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.","parameters":[{"name":"factoryId","in":"query","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}}],"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"}},"/api/v2/factories/listBlueprints":{"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.","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}}],"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"}},"/api/v2/factories/getBlueprint":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/factories/listAssignments":{"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`.","parameters":[{"name":"factoryId","in":"query","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}}],"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"}},"/api/v2/factories/listReleases":{"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.","parameters":[{"name":"factoryId","in":"query","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`."}],"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"}},"/api/v2/factories/listCodebaseFiles":{"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\"`.","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`."}],"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"}},"/api/v2/factories/searchCodebase":{"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\"`.","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`."}],"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"}},"/api/v2/factories/getType":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"The factory type's `typeId`."}],"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"}},"/api/v2/factories/getTaskSpend":{"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`).","parameters":[{"name":"taskId","in":"query","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"}}],"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"}},"/api/v2/factories/getProjectSpend":{"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`).","parameters":[{"name":"projectId","in":"query","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"}}],"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"}},"/api/v2/factories/getWorkerSpend":{"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`).","parameters":[{"name":"workerId","in":"query","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"}}],"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"}},"/api/v2/factories/sendMessage":{"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.","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/SendFactoryMessageRequest"}}}},"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"}},"/api/v2/factories/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.","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/FactoryControlRequest"}}}},"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"}},"/api/v2/factories/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.","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/FactoryControlRequest"}}}},"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"}},"/api/v2/factories/archive":{"post":{"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.","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/FactoryControlRequest"}}}},"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"}},"/api/v2/governance/listRoles":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/governance/listGrants":{"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`.","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."}],"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"}},"/api/v2/governance/listAgentAccountability":{"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.","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`."}],"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"}},"/api/v2/governance/getAgentAccountability":{"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.","parameters":[{"name":"agentId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The agent's id; missing is `400`."}],"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"}},"/api/v2/governance/listApprovals":{"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`.","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`."}],"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"}},"/api/v2/governance/getApproval":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/governance/listPolicies":{"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.","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`."}],"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"}},"/api/v2/governance/explainDecision":{"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.","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/governance/listEvidence":{"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.","parameters":[{"name":"startAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window start, epoch milliseconds (inclusive). Must be before `endAt`."},{"name":"endAt","in":"query","required":true,"schema":{"type":"integer","minimum":0},"description":"Window end, epoch milliseconds (inclusive)."},{"name":"limit","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Maximum items on this page, 1 to 100."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"The previous page's `continueCursor`, with every other parameter unchanged."},{"name":"disposition","in":"query","required":false,"schema":{"type":"string","enum":["pass","block","hold"]},"description":"Only decisions with this disposition."},{"name":"runId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only decisions whose `correlation.runId` is this run."},{"name":"agentId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only decisions recorded for this agent."},{"name":"gate","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only decisions with a recorded result for this gate."},{"name":"gateOutcome","in":"query","required":false,"schema":{"type":"string","enum":["failed"]},"description":"With `gate`: only decisions where that gate ran and failed. Without `gate` it is `400`."},{"name":"dispatchSurface","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only decisions recorded on this dispatch surface."},{"name":"policyId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only decisions recorded against this policy."},{"name":"includeClientReported","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"Include client-reported decisions. Defaults to `false` (server-recorded only)."},{"name":"includeDecisionFields","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"default":"false"},"description":"With `true`, each item adds the recorded non-person decision fields: `policyId`, `dispatchSurface`, `missingPermissionKeys`, `blockedByGate`, `heldBy`, `retryable` and `evidence.sourceKind`. It filters nothing and is not bound to the cursor."}],"responses":{"200":{"description":"A page of recorded decisions with its coverage","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecordedEvidencePage"},"meta":{"allOf":[{"$ref":"#/components/schemas/PlatformMeta"},{"$ref":"#/components/schemas/ListPageMeta"}]}},"required":["data","meta"]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse401"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"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"}},"/api/v2/governance/getEvidence":{"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`.","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/governance/getGatePathRegistry":{"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"}},"/api/v2/governance/listRunApprovals":{"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.","parameters":[{"name":"runId","in":"query","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`."}],"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"}},"/api/v2/governance/listTrustPolicies":{"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).","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`."}],"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"}},"/api/v2/governance/listTrustPolicyRevisions":{"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).","parameters":[{"name":"policyId","in":"query","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`."}],"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"}},"/api/v2/governance/simulateTrustPolicy":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustPolicySimulationRequest"}}}},"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"}},"/api/v2/governance/createTrustPolicy":{"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.","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"}}}},"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"}},"/api/v2/governance/editTrustPolicy":{"post":{"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.","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/EditTrustPolicyRequest"}}}},"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"}},"/api/v2/governance/toggleTrustPolicy":{"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.","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/ToggleTrustPolicyRequest"}}}},"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"}},"/api/v2/governance/removeTrustPolicy":{"post":{"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.","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/RemoveTrustPolicyRequest"}}}},"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"}},"/api/v2/governance/createApprovalPolicy":{"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.","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"}}}},"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"}},"/api/v2/governance/updateApprovalPolicy":{"post":{"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.","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/UpdateApprovalPolicyRequest"}}}},"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"}},"/api/v2/governance/removeApprovalPolicy":{"post":{"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.","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/RemoveApprovalPolicyRequest"}}}},"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"}},"/api/v2/governance/getDoorSwitchBoard":{"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"}},"/api/v2/governance/getAgentAccessOnBehalfOfReport":{"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`.","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)."}],"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"}},"/api/v2/governance/getGateDenyReport":{"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).","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`."}],"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"}},"/api/v2/governance/getPolicyFiredReport":{"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).","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."}],"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"}},"/api/v2/governance/getAuthzSurfaceReport":{"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).","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."}],"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"}},"/api/v2/governance/getDenialsByPersonReport":{"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).","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."}],"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"}},"/api/v2/governance/listMyWork":{"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","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-forge-actor-kinds":["personal_key"],"security":[{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/governance/getHumanTask":{"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`.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The human task id (`humanTaskId` on a My Work item)."}],"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"}},"/api/v2/governance/listMyAttention":{"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.","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."}],"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"}},"/api/v2/governance/listHumanTaskInputFiles":{"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`.","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`."}],"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"}},"/api/v2/governance/getHumanTaskInputFileUrl":{"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`.","parameters":[{"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."},{"name":"fileId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The input file's `fileId` from `listHumanTaskInputFiles`."}],"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"}},"/api/v2/governance/listAttention":{"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.","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`."}],"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"}},"/api/v2/governance/getAttentionItem":{"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`.","parameters":[{"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."},{"name":"id","in":"query","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."}],"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"}},"/api/v2/governance/actOnHumanTask":{"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.","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/ActOnHumanTaskRequest"}}}},"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"}},"/api/v2/governance/completeHumanTask":{"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.","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/CompleteHumanTaskRequest"}}}},"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"}},"/api/v2/governance/reassignHumanTask":{"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.","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"}}}},"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"}},"/api/v2/governance/attachHumanTaskOutputFile":{"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.","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"}}}},"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"}},"/api/v2/governance/inviteUser":{"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`.","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"}}}},"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"}},"/api/v2/governance/revokeOnBehalfOfGrant":{"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`.","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/RevokeOnBehalfOfGrantRequest"}}}},"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"}},"/api/v2/governance/giveRole":{"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`.","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/GiveRoleRequest"}}}},"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"}},"/api/v2/governance/revokeRole":{"post":{"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`.","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/RevokeRoleRequest"}}}},"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"}},"/api/v2/governance/requestHumanTask":{"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`.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestHumanTaskRequest"}}}},"responses":{"200":{"description":"A repeat of a client reference you used before: that ask","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HumanTaskRequestResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"201":{"description":"The ask was created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HumanTaskRequestResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"description":"`bad_request`, with `error.reason`: `invalid_body` (an invalid or unknown field), `form_invalid` (the message names the first problem), `form_secret_like` (the text asks for a password, code or key), `eligibility_invalid` (not a catalog permission, or an elevated one), `due_out_of_range`, `no_candidates` (a person is unknown, inactive or outside your reach; one answer whatever the cause), or `org_unit_required` (the credential has no acting organization)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400Keyed"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"`unauthorized`: missing or invalid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse401"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"403":{"description":"`forbidden`: the credential's scopes do not name `human_tasks:use` (`error.requiredPermission`), or it is a Personal key, which acts as a person and cannot ask one; or `requester_unavailable` (`error.reason`): the app or key can no longer ask (deactivated, revoked or expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"409":{"description":"`conflict`, with `error.reason`: `requester_open_cap` (200 open asks) or `person_open_cap` (10 open asks of one person from you, or 20 open asks of one person across every app); or `idempotency_result_unavailable`: a request with this Idempotency-Key already completed and its response cannot be disclosed now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409Keyed"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"422":{"description":"`idempotency_*`: the Idempotency-Key was used with a different body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse422Keyed"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"429":{"description":"`rate_limited`, with `error.reason`: more than 200 asks in 24 hours, 10 of one person in 24 hours, or too many open asks across the deployment; retry after `Retry-After` seconds","headers":{"Retry-After":{"description":"Seconds to wait before asking again.","schema":{"type":"integer","minimum":1}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse429"}}}},"500":{"description":"`internal_error`: unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"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"}},"/api/v2/governance/getRequestedHumanTask":{"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.","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."}],"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"}},"/api/v2/governance/withdrawRequestedHumanTask":{"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`.","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"}}}},"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"}},"/api/v2/governance/getPermissionCatalog":{"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"}},"/api/v2/governance/listRoleDefinitions":{"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,"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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/governance/getMyAuthority":{"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.","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."}],"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"}},"/api/v2/governance/listEnforcementSites":{"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.","parameters":[{"name":"permissionKey","in":"query","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`."}],"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"}},"/api/v2/governance/listHoldersAt":{"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.","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`."}],"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"}},"/api/v2/governance/getEffectiveAuthority":{"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`.","parameters":[{"name":"actorKind","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"`person`, `agent`, `api_key` or `external_app`."},{"name":"actorId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The holder's id."},{"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."}],"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"}},"/api/v2/governance/explainActorPermission":{"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`.","parameters":[{"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":"actorId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The person's or agent's id."},{"name":"permissionKey","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The permission to explain, such as `audit:read`."}],"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"}},"/api/v2/governance/getCompanyAccessOverview":{"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.","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`."}],"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"}},"/api/v2/governance/listOnBehalfOfGrants":{"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.","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`."}],"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"}},"/api/v2/governance/listMyGrants":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/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"}},"/api/v2/mcp/updateConfig":{"post":{"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`.","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"}}}},"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"}},"/api/v2/synthesis/listRequests":{"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.","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."}],"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"}},"/api/v2/synthesis/listBuilderHolds":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/synthesis/getRequest":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The synthesis request id."}],"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"}},"/api/v2/synthesis/getBuilderConversation":{"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.","parameters":[{"name":"requestId","in":"query","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."}],"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"}},"/api/v2/synthesis/promoteRequests":{"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.","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"}}}},"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"}},"/api/v2/synthesis/demoteRequests":{"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.","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"}}}},"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"}},"/api/v2/synthesis/acceptRequests":{"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.","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"}}}},"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"}},"/api/v2/synthesis/assignReviewer":{"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.","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"}}}},"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"}},"/api/v2/synthesis/listCuratorRecommendations":{"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.","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."}],"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"}},"/api/v2/synthesis/getCuratorRecommendation":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The recommendation's id."}],"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"}},"/api/v2/synthesis/decideCuratorRecommendation":{"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.","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/DecideCuratorRecommendationRequest"}}}},"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"}},"/api/v2/synthesis/closeKeepBothCuratorRecommendations":{"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.","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"}}}},"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"}},"/api/v2/synthesis/listTemplates":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/synthesis/createTemplate":{"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.","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"}}}},"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"}},"/api/v2/synthesis/updateTemplate":{"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.","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/UpdateSynthesisTemplateRequest"}}}},"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"}},"/api/v2/synthesis/deleteTemplate":{"post":{"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.","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/DeleteSynthesisTemplateRequest"}}}},"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"}},"/api/v2/synthesis/getBudget":{"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"}},"/api/v2/synthesis/setBudget":{"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.","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"}}}},"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"}},"/api/v2/synthesis/getJitDefault":{"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"}},"/api/v2/synthesis/setJitDefault":{"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.","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"}}}},"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"}},"/api/v2/judges/list":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/judges/get":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The judge's id."}],"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"}},"/api/v2/judges/getRubric":{"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.","parameters":[{"name":"judgeId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The judge's id."}],"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"}},"/api/v2/judges/listDriftAlerts":{"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.","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`."}],"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"}},"/api/v2/judges/listVerdicts":{"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.","parameters":[{"name":"judgeId","in":"query","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`."}],"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"}},"/api/v2/judges/listAdmissions":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/judges/getAdmission":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The admission's id."}],"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"}},"/api/v2/judges/listSubjectVerdicts":{"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.","parameters":[{"name":"subjectKind","in":"query","required":true,"schema":{"type":"string","enum":["skill","agent","procedure","workflow_graph","workflow_run"]},"description":"The kind of subject."},{"name":"subjectId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The subject's stored key."},{"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`."}],"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"}},"/api/v2/judges/getSubjectActivity":{"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.","parameters":[{"name":"subjectKind","in":"query","required":true,"schema":{"type":"string","enum":["skill","agent","procedure","workflow_graph","workflow_run"]},"description":"The kind of subject."},{"name":"subjectId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The subject's stored key."},{"name":"judgeId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only this judge's verdicts."}],"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"}},"/api/v2/judges/getLatestVerdict":{"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.","parameters":[{"name":"subjectKind","in":"query","required":true,"schema":{"type":"string","enum":["skill","agent","procedure","workflow_graph","workflow_run"]},"description":"The kind of subject."},{"name":"subjectId","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The subject's stored key."},{"name":"judgeId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Only this judge's verdicts."}],"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"}},"/api/v2/judges/overrideVerdict":{"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.","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/OverrideJudgeVerdictRequest"}}}},"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"}},"/api/v2/judges/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.","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/PromoteJudgeRequest"}}}},"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"}},"/api/v2/judges/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.","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/DemoteJudgeRequest"}}}},"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"}},"/api/v2/judges/resolveAdmission":{"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.","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/ResolveJudgeAdmissionRequest"}}}},"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"}},"/api/v2/judges/rejudgeSkill":{"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.","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"}}}},"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"}},"/api/v2/judges/rejudgeAgent":{"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.","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"}}}},"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"}},"/api/v2/judges/rejudgeProcedure":{"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.","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"}}}},"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"}},"/api/v2/judges/rejudgeWorkflow":{"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.","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"}}}},"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"}},"/api/v2/budgets/getStatus":{"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,"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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/evals/list":{"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.","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}}],"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"}},"/api/v2/evals/get":{"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`.","parameters":[{"name":"id","in":"query","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}}],"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"}},"/api/v2/evals/create":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSetCreateBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/evals/update":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSetUpdateBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/evals/archive":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSetArchiveBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/evals/compareRuns":{"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.","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}}],"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"}},"/api/v2/evals/startRun":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalRunStartBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"expensive"}},"/api/v2/evals/cancelRun":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalRunCancelBody"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/externalApps/list":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/externalApps/get":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"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"}},"/api/v2/externalApps/create":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"External App fields including ownerType, ownerId, allowed scopes.","additionalProperties":true}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/externalApps/update":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Partial External App fields, with the `id` of the app they patch.","properties":{"id":{"type":"string","description":"The External App's id."}},"required":["id"],"additionalProperties":true}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/externalApps/deactivate":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/externalApps/rotateSecret":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/externalApps/rotateCallbackSecret":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/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"}},"/api/v2/external/findOrCreateAgent":{"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`.","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"]}}}},"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"}},"/api/v2/external/listAvailableModelsForAgent":{"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.","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"}}],"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"}},"/api/v2/webhooks":{"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.","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"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"},"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"List webhooks for this app","description":"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.","responses":{"200":{"description":"Webhook subscription list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}},"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":["webhooks:read"],"x-forge-mcp-group":"webhooks","x-forge-paging":"database","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-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"read"},"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"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"}},"/api/v2/webhooks/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Webhook subscription ID"}},"required":["id"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/deliveries/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deliveryId":{"type":"string","description":"The delivery to replay: the original `X-Forge-Delivery` header value"}},"required":["deliveryId"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/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.","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"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/deliveries/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.","parameters":[{"name":"deliveryId","in":"query","required":true,"schema":{"type":"string"},"description":"The delivery: its `X-Forge-Delivery` header value"}],"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"}},"/api/v2/webhooks/test":{"post":{"operationId":"sendWebhookTest","tags":["Webhooks"],"summary":"Send a test event to a webhook","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Webhook subscription ID"}},"required":["id"]}}}},"responses":{"202":{"description":"Test delivery queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookTestResult"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]}}},"headers":{"X-Request-Id":{"$ref":"#/components/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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409Keyed"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"422":{"description":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse422Keyed"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/update":{"post":{"operationId":"updateWebhook","tags":["Webhooks"],"summary":"Update a webhook","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Webhook subscription ID"},"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":["id"]}}}},"responses":{"200":{"description":"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`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"},"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 webhook is revoked, or 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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"webhooks","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/pause":{"post":{"operationId":"pauseWebhook","tags":["Webhooks"],"summary":"Pause a webhook","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Webhook subscription ID"}},"required":["id"]}}}},"responses":{"200":{"description":"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`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"},"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 webhook is revoked, or 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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"webhooks","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/resume":{"post":{"operationId":"resumeWebhook","tags":["Webhooks"],"summary":"Resume a webhook","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Webhook subscription ID"}},"required":["id"]}}}},"responses":{"200":{"description":"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`).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookSubscription"},"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 webhook is revoked, or 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"},"503":{"$ref":"#/components/responses/LimiterUnavailable"}},"x-forge-permissions":["webhooks:manage"],"x-forge-mcp-group":"webhooks","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhooks"],"summary":"List a webhook's deliveries","description":"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.","parameters":[{"name":"subscriptionId","in":"query","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":"One page of the webhook's deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDeliverySummary"}},"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":["webhooks:read"],"x-forge-mcp-group":"webhooks","x-forge-paging":"database","x-forge-actor-kinds":["external_app"],"security":[{"BearerAuth":[]}],"x-forge-rate-limit":"read"}},"/api/v2/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.","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`"}],"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"}},"/api/v2/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.","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."}],"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"}},"/api/v2/cost/customer":{"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.","parameters":[{"name":"customerId","in":"query","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."}],"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"}},"/api/v2/external/customers":{"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).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExternalCustomerRequest"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"},"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.","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}}],"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"}},"/api/v2/external/customers/findOrCreate":{"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).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExternalCustomerRequest"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/external/customers/unlink":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"The customer id"}},"required":["id"],"additionalProperties":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/external/customers/{id}":{"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.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The customer id"}],"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"},"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).","parameters":[{"name":"id","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"}}}},"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"}},"/api/v2/customers/list":{"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.","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}}],"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"}},"/api/v2/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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The customer id"}],"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"}},"/api/v2/customers/listScopes":{"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.","parameters":[{"name":"customerId","in":"query","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`."}],"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"}},"/api/v2/customers/create":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerRequest"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/customers/update":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerRequest"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/customers/archive":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveCustomerRequest"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/customers/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.","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"}],"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"},"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.","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}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/procedures/list":{"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`.","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."}],"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"}},"/api/v2/procedures/get":{"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`.","parameters":[{"name":"procedureId","in":"query","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."}],"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"}},"/api/v2/procedures/listVersions":{"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`.","parameters":[{"name":"procedureId","in":"query","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`."}],"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"}},"/api/v2/procedures/getSource":{"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.","parameters":[{"name":"procedureId","in":"query","required":true,"schema":{"type":"string","minLength":1}},{"name":"version","in":"query","required":false,"schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/procedures/listConsumers":{"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`.","parameters":[{"name":"procedureId","in":"query","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}}],"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"}},"/api/v2/procedures/listReferences":{"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`.","parameters":[{"name":"procedureId","in":"query","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`."}],"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"}},"/api/v2/procedures/listVersionCallers":{"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`.","parameters":[{"name":"procedureId","in":"query","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`."}],"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"}},"/api/v2/procedures/findSimilar":{"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.","parameters":[{"name":"procedureId","in":"query","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."}],"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"}},"/api/v2/procedures/getConnectionBinding":{"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.","parameters":[{"name":"procedureId","in":"query","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."}],"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"}},"/api/v2/procedures/delete":{"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.","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"}}}},"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"}},"/api/v2/procedures/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.","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/DeprecateProcedureRequest"}}}},"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"}},"/api/v2/procedures/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.","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/RenameProcedureRequest"}}}},"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"}},"/api/v2/procedures/setConnections":{"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.","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/SetProcedureConnectionsRequest"}}}},"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"}},"/api/v2/procedures/getLatestValidationRun":{"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.","parameters":[{"name":"procedureId","in":"query","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."}],"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"}},"/api/v2/procedures/cancelValidationRun":{"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.","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/CancelValidationRunRequest"}}}},"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"}},"/api/v2/procedures/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.","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/CloneProcedureRequest"}}}},"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"}},"/api/v2/procedures/dismissScriptPromotion":{"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.","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/DismissScriptPromotionRequest"}}}},"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"}},"/api/v2/procedures/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.","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/ProcedureVersionRequest"}}}},"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"}},"/api/v2/procedures/requestReview":{"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.","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/ProcedureVersionRequest"}}}},"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"}},"/api/v2/procedures/resolveReviewHold":{"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.","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/ResolveProcedureReviewHoldRequest"}}}},"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"}},"/api/v2/procedures/startBuilder":{"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.","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"}}}},"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"}},"/api/v2/procedures/openInBuilder":{"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.","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/OpenProcedureInBuilderRequest"}}}},"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"}},"/api/v2/procedures/sendBuilderMessage":{"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.","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/SendProcedureBuilderMessageRequest"}}}},"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"}},"/api/v2/procedures/retryBuilderTurn":{"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.","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/ProcedureVersionRequest"}}}},"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"}},"/api/v2/procedures/resetBuilder":{"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.","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/ProcedureVersionRequest"}}}},"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"}},"/api/v2/procedures/stopBuilderTurn":{"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.","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/ProcedureVersionRequest"}}}},"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"}},"/api/v2/procedures/acceptScriptPromotion":{"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.","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/AcceptScriptPromotionRequest"}}}},"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"}},"/api/v2/procedures/listBuilderMessages":{"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.","parameters":[{"name":"procedureId","in":"query","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)."}],"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"}},"/api/v2/projects/list":{"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.","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}}],"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"}},"/api/v2/projects/listForPlanning":{"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.","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}}],"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"}},"/api/v2/projects/get":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/projects/listObjectives":{"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.","parameters":[{"name":"id","in":"query","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`."}],"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"}},"/api/v2/projects/create":{"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.","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"}}}},"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"}},"/api/v2/projects/update":{"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.","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/UpdateProjectRequest"}}}},"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"}},"/api/v2/projects/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.","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/TransitionProjectRequest"}}}},"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"}},"/api/v2/projects/linkObjective":{"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.","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/LinkProjectObjectiveRequest"}}}},"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"}},"/api/v2/projects/unlinkObjective":{"post":{"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.","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/UnlinkProjectObjectiveRequest"}}}},"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"}},"/api/v2/projects/changeCustomer":{"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.","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/ChangeProjectCustomerRequest"}}}},"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"}},"/api/v2/projects/transferOwnership":{"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.","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/TransferProjectOwnershipRequest"}}}},"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"}},"/api/v2/projects/listTasks":{"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.","parameters":[{"name":"projectId","in":"query","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}}],"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"}},"/api/v2/projects/getTask":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/projects/createTask":{"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.","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/CreateProjectTaskRequest"}}}},"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"}},"/api/v2/projects/updateTask":{"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.","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/UpdateProjectTaskRequest"}}}},"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"}},"/api/v2/projects/transitionTask":{"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.","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/TransitionProjectTaskRequest"}}}},"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"}},"/api/v2/projects/getStaffing":{"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.","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/projects/previewStaffingAssignment":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewProjectStaffingAssignmentRequest"}}}},"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"}},"/api/v2/projects/confirmStaffingAssignment":{"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.","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/ConfirmProjectStaffingAssignmentRequest"}}}},"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"}},"/api/v2/projects/amendStaffingAssignment":{"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.","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/AmendProjectStaffingAssignmentRequest"}}}},"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"}},"/api/v2/projects/releaseStaffingAssignment":{"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.","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/ReleaseProjectStaffingAssignmentRequest"}}}},"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"}},"/api/v2/projects/getPodStaffing":{"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.","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/projects/previewPodStaffing":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewProjectPodStaffingRequest"}}}},"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"}},"/api/v2/projects/confirmPodStaffing":{"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.","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/ConfirmProjectPodStaffingRequest"}}}},"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"}},"/api/v2/projects/previewPodStaffingReconciliation":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectPodStaffingReference"}}}},"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"}},"/api/v2/projects/reconcilePodStaffing":{"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.","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/ReconcileProjectPodStaffingRequest"}}}},"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"}},"/api/v2/projects/previewPodStaffingRelease":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectPodStaffingReference"}}}},"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"}},"/api/v2/projects/releasePodStaffing":{"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.","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/ReleaseProjectPodStaffingRequest"}}}},"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"}},"/api/v2/workforce/listOrgUnits":{"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.","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}}],"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"}},"/api/v2/workforce/getOrgUnit":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/workforce/listPositions":{"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.","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}}],"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"}},"/api/v2/workforce/getPosition":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/workforce/listEngineers":{"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.","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}}],"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"}},"/api/v2/workforce/listPodPlanning":{"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.","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"}}],"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"}},"/api/v2/workforce/listCustomerPlanning":{"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.","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"}}],"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"}},"/api/v2/workforce/getPersonAllocation":{"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.","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."}],"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"}},"/api/v2/workforce/getEngineeringScope":{"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.","parameters":[{"name":"at","in":"query","required":true,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"multipleOf":86400000},"description":"The evaluation date, UTC midnight epoch milliseconds."}],"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"}},"/api/v2/workforce/setEngineeringScope":{"post":{"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.","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"}}}},"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"}},"/api/v2/workforce/listReportingCategories":{"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.","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`."}],"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"}},"/api/v2/workforce/createReportingCategory":{"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.","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"}}}},"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"}},"/api/v2/workforce/updateReportingCategory":{"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.","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/UpdateReportingCategoryRequest"}}}},"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"}},"/api/v2/workforce/listBandwidthFeedback":{"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.","parameters":[{"name":"workerId","in":"query","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`."}],"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"}},"/api/v2/workforce/createOrgUnit":{"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.","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"}}}},"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"}},"/api/v2/workforce/moveOrgUnit":{"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.","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/MoveOrgUnitRequest"}}}},"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"}},"/api/v2/workforce/createPosition":{"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.","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"}}}},"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"}},"/api/v2/workforce/updatePosition":{"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.","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/UpdatePositionRequest"}}}},"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"}},"/api/v2/workforce/setPositionReporting":{"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.","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/SetPositionReportingRequest"}}}},"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"}},"/api/v2/workforce/createPositionAssignment":{"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.","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/CreatePositionAssignmentRequest"}}}},"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"}},"/api/v2/workforce/updatePositionAssignment":{"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.","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/UpdatePositionAssignmentRequest"}}}},"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"}},"/api/v2/workforce/endPositionAssignment":{"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.","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/EndPositionAssignmentRequest"}}}},"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"}},"/api/v2/workforce/reassignPrimaryPosition":{"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.","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/ReassignPrimaryPositionRequest"}}}},"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"}},"/api/v2/workforce/listWorkerRoles":{"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","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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/workforce/listPods":{"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).","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."}}],"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"}},"/api/v2/workforce/getPod":{"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).","parameters":[{"name":"id","in":"query","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."}}],"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"}},"/api/v2/workforce/listPodMembershipHistory":{"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).","parameters":[{"name":"podId","in":"query","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})$"}}],"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"}},"/api/v2/workforce/previewPodMembership":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewPodMembershipRequest"}}}},"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"}},"/api/v2/workforce/listAssignmentHistory":{"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.","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`."}],"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"}},"/api/v2/workforce/addPodMembership":{"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.","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/AddPodMembershipRequest"}}}},"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"}},"/api/v2/workforce/changePodMembershipEffective":{"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.","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/ChangePodMembershipEffectiveRequest"}}}},"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"}},"/api/v2/workforce/updateFuturePodMembership":{"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.","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/UpdateFuturePodMembershipRequest"}}}},"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"}},"/api/v2/workforce/endPodMembership":{"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.","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/EndPodMembershipRequest"}}}},"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"}},"/api/v2/workforce/deleteFuturePodMembership":{"post":{"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.","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/PodMembershipReferenceRequest"}}}},"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"}},"/api/v2/workforce/confirmPodMembershipAccuracy":{"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.","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/PodMembershipReferenceRequest"}}}},"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"}},"/api/v2/workforce/createPod":{"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.","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"}}}},"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"}},"/api/v2/workforce/updatePod":{"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.","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/UpdatePodRequest"}}}},"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"}},"/api/v2/workforce/archivePod":{"post":{"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.","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/ArchivePodRequest"}}}},"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"}},"/api/v2/workforce/assignPodOwner":{"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.","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/AssignPodOwnerRequest"}}}},"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"}},"/api/v2/workforce/changePodOwnerEffective":{"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.","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/ChangePodOwnerEffectiveRequest"}}}},"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"}},"/api/v2/workforce/endPodOwner":{"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.","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/EndPodOwnerRequest"}}}},"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"}},"/api/v2/workforce/setPodInternalProfile":{"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.","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/SetPodInternalProfileRequest"}}}},"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"}},"/api/v2/workforce/endPodInternalProfile":{"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.","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/EndPodInternalProfileRequest"}}}},"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"}},"/api/v2/workforce/listPodOwners":{"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.","parameters":[{"name":"podId","in":"query","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`."}],"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"}},"/api/v2/workforce/listPodInternalProfiles":{"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.","parameters":[{"name":"podId","in":"query","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`."}],"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"}},"/api/v2/workforce/getWorker":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/workforce/createPerson":{"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`.","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"}}}},"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"}},"/api/v2/workforce/updatePerson":{"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.","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/UpdatePersonRequest"}}}},"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"}},"/api/v2/workforce/previewPersonMerge":{"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.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewPersonMergeRequest"}}}},"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"}},"/api/v2/workforce/mergePersons":{"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.","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"}}}},"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"}},"/api/v2/workforce/offboardPerson":{"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.","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/OffboardPersonRequest"}}}},"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"}},"/api/v2/workforce/reactivatePerson":{"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.","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/ReactivatePersonRequest"}}}},"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"}},"/api/v2/workforce/getPerson":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/workforce/listWorkers":{"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.","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}}],"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"}},"/api/v2/workforce/updateWorkerSeat":{"post":{"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.","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/UpdateWorkerSeatRequest"}}}},"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"}},"/api/v2/workflows/createFiscalCalendar":{"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.","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"}}}},"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"}},"/api/v2/workflows/updateFiscalCalendar":{"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.","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/UpdateFiscalCalendarRequest"}}}},"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"}},"/api/v2/workflows/deleteFiscalCalendar":{"post":{"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.","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/DeleteFiscalCalendarRequest"}}}},"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"}},"/api/v2/workflows/listSteps":{"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.","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`."}],"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"}},"/api/v2/workflows/createStep":{"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`.","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"}}}},"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"}},"/api/v2/workflows/updateStep":{"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.","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/UpdateWorkflowStepRequest"}}}},"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"}},"/api/v2/workflows/deleteStep":{"post":{"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.","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/DeleteWorkflowStepRequest"}}}},"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"}},"/api/v2/workflows/listIngressInvocations":{"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.","parameters":[{"name":"triggerId","in":"query","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`."}],"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"}},"/api/v2/workflows/createTrigger":{"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.","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/CreateWorkflowTriggerRequest"}}}},"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"}},"/api/v2/workflows/updateTrigger":{"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.","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/UpdateWorkflowTriggerRequest"}}}},"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"}},"/api/v2/workflows/pauseTrigger":{"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.","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/WorkflowTriggerTargetRequest"}}}},"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"}},"/api/v2/workflows/resumeTrigger":{"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.","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/WorkflowTriggerTargetRequest"}}}},"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"}},"/api/v2/workflows/deleteTrigger":{"post":{"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.","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/WorkflowTriggerTargetRequest"}}}},"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"}},"/api/v2/workflows/createIngressTrigger":{"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.","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/CreateIngressTriggerRequest"}}}},"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"}},"/api/v2/workflows/setIngressStatus":{"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.","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/SetIngressStatusRequest"}}}},"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"}},"/api/v2/workflows/rotateIngressToken":{"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.","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/WorkflowTriggerTargetRequest"}}}},"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"}},"/api/v2/workflows/updateIngressConfig":{"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.","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/UpdateIngressConfigRequest"}}}},"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"}},"/api/v2/workflows/listScheduleRoster":{"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.","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."}],"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"}},"/api/v2/workflows/publishDraft":{"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.","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/PublishWorkflowDraftRequest"}}}},"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"}},"/api/v2/workflows/testRunDraft":{"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.","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/TestRunWorkflowDraftRequest"}}}},"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"}},"/api/v2/workflows/rollback":{"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.","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/RollbackWorkflowRequest"}}}},"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"}},"/api/v2/workflows/resetDraft":{"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.","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/ResetWorkflowDraftRequest"}}}},"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"}},"/api/v2/workflows/getCapabilityReadiness":{"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).","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."}],"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"}},"/api/v2/workflows/getAgentReadiness":{"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.","parameters":[{"name":"id","in":"query","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."}],"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"}},"/api/v2/workflows/getRunCostForecast":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow."}],"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"}},"/api/v2/workflows/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.","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/WorkflowCatalogTargetRequest"}}}},"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"}},"/api/v2/workflows/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.","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/WorkflowCatalogTargetRequest"}}}},"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"}},"/api/v2/workflows/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.","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/WorkflowCatalogTargetRequest"}}}},"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"}},"/api/v2/workflows/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.","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/WorkflowCatalogTargetRequest"}}}},"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"}},"/api/v2/workflows/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.","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/WorkflowCatalogTargetRequest"}}}},"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"}},"/api/v2/workflows/setTags":{"patch":{"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.","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/SetWorkflowTagsRequest"}}}},"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"}},"/api/v2/workflows/setOwningOrgUnit":{"patch":{"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.","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/SetWorkflowOwningOrgUnitRequest"}}}},"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"}},"/api/v2/workflows/replaceAsset":{"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.","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/ReplaceWorkflowAssetRequest"}}}},"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"}},"/api/v2/workflows/createFromTemplate":{"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.","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"}}}},"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"}},"/api/v2/workflows/listAssets":{"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.","parameters":[{"name":"workflowId","in":"query","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`."}],"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"}},"/api/v2/workflows/listTemplates":{"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.","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`."}],"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"}},"/api/v2/workflows/getByName":{"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.","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."}],"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"}},"/api/v2/workflows/exportBundle":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"The workflow."}],"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"}},"/api/v2/workforce/listPersonIdentities":{"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.","parameters":[{"name":"personId","in":"query","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`."}],"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"}},"/api/v2/workforce/linkPersonIdentity":{"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`.","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/LinkPersonIdentityRequest"}}}},"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"}},"/api/v2/workforce/unlinkPersonIdentity":{"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`.","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/UnlinkPersonIdentityRequest"}}}},"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"}},"/api/v2/workforce/listPersonEmailClaims":{"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.","parameters":[{"name":"personId","in":"query","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`."}],"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"}},"/api/v2/workforce/upsertPersonEmailClaim":{"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`.","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/UpsertPersonEmailClaimRequest"}}}},"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"}},"/api/v2/workforce/revokePersonEmailClaim":{"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`.","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/RevokePersonEmailClaimRequest"}}}},"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"}},"/api/v2/workforce/getPersonCommunicationProfile":{"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.","parameters":[{"name":"personId","in":"query","required":true,"schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/workforce/savePersonCommunicationProfile":{"post":{"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.","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/SavePersonCommunicationProfileRequest"}}}},"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"}},"/api/v2/workforce/listPersonCommunicationProfileHistory":{"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.","parameters":[{"name":"personId","in":"query","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}}],"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"}},"/api/v2/workforce/listPersonAuditEvents":{"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.","parameters":[{"name":"personId","in":"query","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}}],"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"}},"/api/v2/workforce/assignPodCustomer":{"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.","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/AssignPodCustomerRequest"}}}},"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"}},"/api/v2/workforce/changePodCustomerAssignmentEffective":{"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.","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/ChangePodCustomerAssignmentEffectiveRequest"}}}},"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"}},"/api/v2/workforce/updateFuturePodCustomerAssignment":{"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.","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/UpdateFuturePodCustomerAssignmentRequest"}}}},"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"}},"/api/v2/workforce/deleteFuturePodCustomerAssignment":{"post":{"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.","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/DeleteFuturePodCustomerAssignmentRequest"}}}},"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"}},"/api/v2/workforce/endPodCustomerAssignment":{"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.","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/EndPodCustomerAssignmentRequest"}}}},"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"}},"/api/v2/workforce/confirmPodCustomerAssignmentAccuracy":{"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.","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/ConfirmPodCustomerAssignmentAccuracyRequest"}}}},"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"}},"/api/v2/workforce/previewPodCustomerAssignment":{"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).","parameters":[],"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"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewPodCustomerAssignmentRequest"}}}},"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"}},"/api/v2/workforce/listPodCustomerAssignments":{"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).","parameters":[{"name":"podId","in":"query","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`."}],"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"}},"/api/v2/workforce/listCustomerPodAssignments":{"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).","parameters":[{"name":"customerId","in":"query","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`."}],"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"}},"/api/v2/workforce/listPodCustomerAssignmentHistory":{"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).","parameters":[{"name":"podId","in":"query","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}}],"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"}},"/api/v2/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"}},"/api/v2/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"}},"/api/v2/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"}},"/api/v2/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.","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"}}],"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"}},"/api/v2/capabilities/list":{"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,"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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/capabilities/get":{"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.","parameters":[{"name":"domain","in":"query","required":true,"description":"The capability domain, as `listCapabilities` returns it (for example `inference`).","schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/capabilities/listAuditEvents":{"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`.","parameters":[{"name":"domain","in":"query","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}}],"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"}},"/api/v2/providers/list":{"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,"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-forge-actor-kinds":["external_app","platform_key","personal_key"],"security":[{"BearerAuth":[]},{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/providers/get":{"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.","parameters":[{"name":"key","in":"query","required":true,"description":"The provider key, as `listProviders` returns it (for example `openai`).","schema":{"type":"string","minLength":1}}],"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"}},"/api/v2/capabilities/setChain":{"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.","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/SetCapabilityChainRequest"}}}},"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"}},"/api/v2/capabilities/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.","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/DisableCapabilityRequest"}}}},"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"}},"/api/v2/providers/setOptions":{"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.","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/SetProviderOptionsRequest"}}}},"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"}},"/api/v2/providers/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.","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/ProviderKeyRequest"}}}},"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"}},"/api/v2/providers/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.","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/ProviderKeyRequest"}}}},"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"}},"/api/v2/providers/createRecord":{"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.","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"}}}},"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"}},"/api/v2/capabilities/bindOrganization":{"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.","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/BindCapabilityOrganizationRequest"}}}},"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"}},"/api/v2/providers/listAuditEvents":{"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`.","parameters":[{"name":"key","in":"query","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`."}],"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"}},"/api/v2/capabilities/getBindingReadiness":{"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.","parameters":[{"name":"domain","in":"query","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}}],"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"}},"/api/v2/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.","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."}],"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"}},"/api/v2/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.","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."}],"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"}},"/api/v2/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.","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."}],"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"}},"/api/v2/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"}},"/api/v2/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"}},"/api/v2/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"}},"/api/v2/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.","parameters":[{"name":"decisionId","in":"path","required":true,"description":"The `decisionId` a 403 refusal named.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"}}],"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"}},"/api/v2/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.","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}$"}}],"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"}},"/api/v2/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"}},"/api/v2/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.","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}}}},"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"}},"/api/v2/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.","parameters":[{"name":"confirmationId","in":"path","required":true,"description":"The `confirmationId` the request answered.","schema":{"type":"string","minLength":1,"maxLength":256}}],"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"}},"/api/v2/me/confirmations/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.","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":{"confirmationId":{"type":"string","minLength":1,"maxLength":256},"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":["confirmationId","callDigest"],"additionalProperties":false}}}},"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"}},"/api/v2/agents/admin/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.","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}}],"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"}},"/api/v2/agents/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"}},"required":["agentId"],"additionalProperties":false},"example":{"agentId":"triage"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"},"text":{"type":"string"},"fileIds":{"type":"array","items":{"type":"string"}}},"required":["agentId","text"],"additionalProperties":false},"example":{"agentId":"triage","text":"Sort by vendor."}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"expensive"}},"/api/v2/agents/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/admin/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`.","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"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/admin/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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/admin/update-prompt":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"agentId":{"type":"string"},"core":{"type":"string"},"extension":{"type":"string"}},"required":["agentId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","agentId":"triage","core":"Sort by vendor."}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/admin/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.","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`."}],"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"}},"/api/v2/agents/admin/reinstate-version":{"post":{"operationId":"reinstateAgentVersionAdmin","tags":["Agents"],"summary":"Make an exact prior version of an agent its active version again; never on a paused, terminated or archived agent.","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\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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"agentId":{"type":"string"},"version":{"type":"string"},"reason":{"type":"string"}},"required":["agentId","version"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","agentId":"triage","version":"1.0.0"}}}},"responses":{"200":{"description":"Make an exact prior version of an agent its active version again; never on a paused, terminated or archived agent.","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":{"status":"active","headChanged":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`: A platform key cannot make an agent personal or system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400Keyed"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse401"}}},"headers":{"X-Request-Id":{"$ref":"#/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, or a version it does not have among its newest 101","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"headers":{"X-Request-Id":{"$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 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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse409Keyed"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"422":{"description":"The Idempotency-Key was used with a different request (`idempotency_key_reuse`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse422Keyed"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse500"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/admin/update-capabilities":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"agentId":{"type":"string"},"skills":{"type":"array","items":{"type":"string"}},"toolSets":{"type":"array","items":{"type":"string"}}},"required":["agentId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","agentId":"triage","skills":["invoice-reading"],"toolSets":["ledger"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/agents/admin/update":{"post":{"operationId":"updateAgentAdmin","tags":["Agents"],"summary":"Update an agent's definition fields by its slug; a change to a canonical field 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\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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"agentId":{"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":["agentId","patch"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","agentId":"triage","patch":{"description":"Sorts invoices."}}}}},"responses":{"200":{"description":"Update an agent's definition fields by its slug; a change to a canonical field 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; `bad_request`: A platform key cannot make an agent personal or system.; `bad_request`: externalModelAllowlist names more than 1000 models, its maximum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400Keyed"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse401"}}},"headers":{"X-Request-Id":{"$ref":"#/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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/api-keys/admin/own-keys/delete":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keyId":{"type":"string"}},"required":["keyId"],"additionalProperties":false},"example":{"keyId":"pk_own_revoked"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/api-keys/admin/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.","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}}],"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"}},"/api/v2/api-keys/admin/own-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.","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}}],"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"}},"/api/v2/api-keys/admin/own-keys/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keyId":{"type":"string"},"reason":{"type":"string"}},"required":["keyId"],"additionalProperties":false},"example":{"keyId":"pk_own_active","reason":"Lost laptop"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/api-keys/admin/personal-keys/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keyId":{"type":"string"},"reason":{"type":"string"}},"required":["keyId"],"additionalProperties":false},"example":{"keyId":"pk_active","reason":"Lost laptop"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/add-reaction":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messageId":{"type":"string"},"emoji":{"type":"string"}},"required":["messageId","emoji"],"additionalProperties":false},"example":{"messageId":"chatMessages:one","emoji":"thumbs_up"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/remove-reaction":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messageId":{"type":"string"}},"required":["messageId"],"additionalProperties":false},"example":{"messageId":"chatMessages:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/archive":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":false},"example":{"sessionId":"channelSessions:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/assign-agent":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channelId":{"type":"string","minLength":1},"agentDefinitionId":{"type":"string"},"role":{"anyOf":[{"type":"string","const":"participant"},{"type":"string","const":"judge"},{"type":"string","const":"observer"}]},"priority":{"type":"number"}},"required":["channelId","agentDefinitionId"],"additionalProperties":false},"example":{"channelId":"channels:one","agentDefinitionId":"agentDefinitions:helper","role":"observer"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/remove-agent":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignmentId":{"type":"string"}},"required":["assignmentId"],"additionalProperties":false},"example":{"assignmentId":"channelAgents:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/capture-turn-snapshot":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"turnMetaId":{"type":"string"},"redacted":{"type":"boolean"},"visibility":{"anyOf":[{"type":"string","const":"operator"},{"type":"string","const":"workspace"},{"type":"string","const":"link"}]},"capturedNote":{"type":"string"}},"required":["turnMetaId"],"additionalProperties":false},"example":{"turnMetaId":"agentTurnMeta:owner"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":false},"example":{"sessionId":"channelSessions:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/discoverable-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"}},"/api/v2/chat/admin/turn-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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"turnMetaId","in":"query","required":true,"schema":{"type":"string"},"example":"agentTurnMeta:owner"},{"name":"redacted","in":"query","required":false,"schema":{"type":"boolean"}}],"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"}},"/api/v2/chat/admin/channel":{"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.","parameters":[{"name":"channelId","in":"query","required":true,"schema":{"type":"string"},"example":"channels:one"}],"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"}},"/api/v2/chat/admin/turn-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.","parameters":[{"name":"turnMetaId","in":"query","required":true,"schema":{"type":"string"},"example":"agentTurnMeta:owner"}],"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"}},"/api/v2/chat/admin/turn-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.","parameters":[{"name":"turnMetaId","in":"query","required":true,"schema":{"type":"string"},"example":"agentTurnMeta:owner"}],"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"}},"/api/v2/chat/admin/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.","parameters":[{"name":"sessionId","in":"query","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"}}],"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"}},"/api/v2/chat/admin/join-channel":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channelId":{"type":"string","minLength":1},"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":["channelId","orgUnitId","connectionId","workspaceId","externalChannelId"],"additionalProperties":false},"example":{"channelId":"channels:one","orgUnitId":"orgUnits:A","connectionId":"slack-connection-1","workspaceId":"T123","externalChannelId":"C0999999"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/remove-slack-link":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channelId":{"type":"string","minLength":1}},"required":["channelId"],"additionalProperties":false},"example":{"channelId":"channels:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/turn":{"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.","parameters":[{"name":"turnMetaId","in":"query","required":true,"schema":{"type":"string"},"example":"agentTurnMeta:owner"}],"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"}},"/api/v2/chat/admin/thread-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.","parameters":[{"name":"threadId","in":"query","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}}],"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"}},"/api/v2/chat/admin/thread-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.","parameters":[{"name":"threadId","in":"query","required":true,"schema":{"type":"string"},"example":"agent-thread:one"}],"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"}},"/api/v2/chat/admin/session-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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"sessionId","in":"query","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":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}}],"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"}},"/api/v2/chat/admin/channel-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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"channelId","in":"query","required":true,"schema":{"type":"string"},"example":"channels: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":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}}],"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"}},"/api/v2/chat/admin/channel-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.","parameters":[{"name":"channelId","in":"query","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}}],"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"}},"/api/v2/chat/admin/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.","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}}],"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"}},"/api/v2/chat/admin/my-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.","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}}],"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"}},"/api/v2/chat/admin/channel-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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"channelId","in":"query","required":true,"schema":{"type":"string"},"example":"channels:one"},{"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}}],"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"}},"/api/v2/chat/admin/channel-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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"channelId","in":"query","required":true,"schema":{"type":"string"},"example":"channels:one"},{"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}}],"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"}},"/api/v2/chat/admin/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":false},"example":{"sessionId":"channelSessions:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/slack-link":{"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.","parameters":[{"name":"channelId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"}],"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"}},"/api/v2/chat/admin/trace-snapshot":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shortId":{"type":"string"}},"required":["shortId"],"additionalProperties":false},"example":{"shortId":"deploy01"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/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.","parameters":[{"name":"channelId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"channels:one"}],"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"}},"/api/v2/chat/admin/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.","parameters":[{"name":"messageId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"chatMessages:one"}],"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"}},"/api/v2/chat/admin/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":false},"example":{"sessionId":"channelSessions:paused"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/thread-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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"threadId":{"type":"string"},"query":{"type":"string"},"limit":{"type":"number"}},"required":["threadId","query"],"additionalProperties":false},"example":{"threadId":"agent-thread:one","query":"deploy"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channelId":{"type":"string","minLength":1},"agentDefinitionId":{"type":"string"}},"required":["channelId","agentDefinitionId"],"additionalProperties":false},"example":{"channelId":"channels:one","agentDefinitionId":"agentDefinitions:judge"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/remove-judge":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channelId":{"type":"string","minLength":1}},"required":["channelId"],"additionalProperties":false},"example":{"channelId":"channels:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/direct-message":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/worker-direct-message":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":false},"example":{"sessionId":"channelSessions:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"}},"required":["sessionId"],"additionalProperties":false},"example":{"sessionId":"channelSessions:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channelId":{"type":"string","minLength":1},"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":["channelId","modality"],"additionalProperties":false},"example":{"channelId":"channels:one","modality":"broadcast"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channelId":{"type":"string","minLength":1},"enabled":{"type":"boolean"}},"required":["channelId","enabled"],"additionalProperties":false},"example":{"channelId":"channels:one","enabled":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"initialChannelsShown":{"type":"number"}},"additionalProperties":false},"example":{"initialChannelsShown":8}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/chat/admin/session":{"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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"sessionId","in":"query","required":true,"schema":{"type":"string"},"example":"channelSessions:one"}],"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"}},"/api/v2/chat/admin/session-detail":{"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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"sessionId","in":"query","required":true,"schema":{"type":"string"},"example":"channelSessions:one"}],"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"}},"/api/v2/chat/admin/my-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.","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}}],"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"}},"/api/v2/chat/admin/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.","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`."}],"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"}},"/api/v2/chat/admin/session-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.","parameters":[{"name":"sessionId","in":"query","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}}],"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"}},"/api/v2/chat/admin/session-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.","parameters":[{"name":"sessionId","in":"query","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"}}],"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"}},"/api/v2/connections/admin/credentials/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credentialId":{"type":"string"},"reviewNote":{"type":"string"}},"required":["credentialId"],"additionalProperties":false},"example":{"credentialId":"credentials:a"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/credentials/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credentialId":{"type":"string"},"reviewNote":{"type":"string"}},"required":["credentialId"],"additionalProperties":false},"example":{"credentialId":"credentials:a"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/oauth/bindings/create":{"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.","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}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/procedure-credentials":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"procedureId":{"type":"string"},"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":["procedureId","target","name","fields"],"additionalProperties":false},"example":{"procedureId":"procedure-acme","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"}]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"},"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"procedureId":{"type":"string"},"credentialId":{"type":"string"}},"required":["procedureId","credentialId"],"additionalProperties":false},"example":{"credentialId":"credentials:a","procedureId":"procedure-1"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/tools/credentials":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"toolId":{"type":"string"},"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":["toolId","scopeType","scopeId","name","fields"],"additionalProperties":false},"example":{"toolId":"tool-acme","scopeType":"org_unit","scopeId":"orgUnits:A","name":"Acme","fields":{"token":"WRITE-SECRET-MATERIAL-SENTINEL"},"secretType":"bearer_token"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"},"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).","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"toolId","in":"query","required":true,"schema":{"type":"string"},"example":"tool-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}}],"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"}},"/api/v2/connections/admin/external-tools/configuration":{"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`.","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":[]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"},"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).","parameters":[{"name":"configurationId","in":"query","required":true,"schema":{"type":"string"},"example":"externalToolConfigurations:google"}],"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"}},"/api/v2/connections/admin/credentials/remove":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"credentialId":{"type":"string"}},"required":["credentialId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","credentialId":"credentials:a"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/secret":{"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).","parameters":[{"name":"secretId","in":"query","required":true,"schema":{"type":"string"},"example":"secret_00000000-0000-4000-8000-000000000001"}],"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"}},"/api/v2/connections/admin/credentials/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credentialId":{"type":"string"},"allowBuildValidation":{"type":"boolean"}},"required":["credentialId","allowBuildValidation"],"additionalProperties":false},"example":{"credentialId":"credentials:a","allowBuildValidation":true}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/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).","parameters":[{"name":"vendorKey","in":"query","required":true,"schema":{"type":"string"},"example":"okta"},{"name":"connectionName","in":"query","required":true,"schema":{"type":"string"},"example":"sso"}],"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"}},"/api/v2/connections/admin/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.","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}}],"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"}},"/api/v2/connections/admin/secret/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).","parameters":[{"name":"secretId","in":"query","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}}],"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"}},"/api/v2/connections/admin/procedures/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).","parameters":[{"name":"procedureId","in":"query","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}}],"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"}},"/api/v2/connections/admin/tools/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).","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"toolId","in":"query","required":true,"schema":{"type":"string"},"example":"tool-acme"}],"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"}},"/api/v2/connections/admin/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).","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}}],"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"}},"/api/v2/connections/admin/credentials/by-state":{"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).","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"approvalState","in":"query","required":true,"schema":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"approved"},{"type":"string","const":"rejected"},{"type":"string","const":"revoked"}]},"example":"pending"},{"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}}],"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"}},"/api/v2/connections/admin/credentials/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.","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"}}],"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"}},"/api/v2/connections/admin/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).","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}}],"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"}},"/api/v2/connections/admin/external-tools/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).","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`."}],"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"}},"/api/v2/connections/admin/external-tools/identity":{"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.","parameters":[{"name":"identityId","in":"query","required":true,"schema":{"type":"string"},"example":"externalToolIdentities:agent"}],"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"}},"/api/v2/connections/admin/external-tools/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.","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}}],"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"}},"/api/v2/connections/admin/external-tools/identities/by-principal":{"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.","parameters":[{"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":"forgePrincipalId","in":"query","required":true,"schema":{"type":"string"},"example":"agentDefinitions:support"},{"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}}],"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"}},"/api/v2/connections/admin/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.","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}}],"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"}},"/api/v2/connections/admin/slack/delivery/operation":{"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.","parameters":[{"name":"orgUnitId","in":"query","required":true,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"operationId","in":"query","required":true,"schema":{"type":"string"},"example":"dead-a"}],"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"}},"/api/v2/connections/admin/credentials/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credentialId":{"type":"string"},"environment":{"anyOf":[{"type":"string","const":"production"},{"type":"string","const":"sandbox"}]}},"required":["credentialId","environment"],"additionalProperties":false},"example":{"credentialId":"credentials:a","environment":"sandbox"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/secret/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.","parameters":[{"name":"secretId","in":"query","required":true,"schema":{"type":"string"},"example":"secret_00000000-0000-4000-8000-000000000001"}],"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"}},"/api/v2/connections/admin/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`.","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"}]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/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.","parameters":[{"name":"orgUnitId","in":"query","required":true,"schema":{"type":"string"},"example":"orgUnits:A"}],"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"}},"/api/v2/connections/admin/credentials/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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"credentialId","in":"query","required":true,"schema":{"type":"string"},"example":"credentials: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`."}],"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"}},"/api/v2/connections/admin/oauth/grants/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.","parameters":[{"name":"grantId","in":"query","required":true,"schema":{"type":"string"},"example":"oauthGrants:ada"}],"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"}},"/api/v2/connections/admin/credentials/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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"}],"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"}},"/api/v2/connections/admin/oauth/bindings/remove":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"credentialId":{"type":"string"}},"required":["credentialId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","credentialId":"credentials:bound"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/slack/delivery/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"operationId":{"type":"string"},"operatorNote":{"type":"string"}},"required":["orgUnitId","operationId","operatorNote"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","operationId":"dead-a","operatorNote":"retry after the outage"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/slack/delivery/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"operationId":{"type":"string"},"resolution":{"anyOf":[{"type":"string","const":"confirm_delivered"},{"type":"string","const":"abandon"}]},"operatorNote":{"type":"string"},"slackChannelId":{"type":"string"},"slackMessageTs":{"type":"string"}},"required":["orgUnitId","operationId","resolution","operatorNote"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","operationId":"unknown-a","resolution":"abandon","operatorNote":"no message reached Slack"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/slack/workspaces/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"connectionId":{"type":"string"}},"required":["orgUnitId","connectionId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","connectionId":"slack-connection-a"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/credentials/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credentialId":{"type":"string"},"reviewNote":{"type":"string"}},"required":["credentialId"],"additionalProperties":false},"example":{"credentialId":"credentials:a"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/external-tools/configuration/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configurationId":{"type":"string"},"dwdServiceAccountKey":{"type":"string"},"oauthClientSecret":{"type":"string"}},"required":["configurationId"],"additionalProperties":false},"example":{"configurationId":"externalToolConfigurations:google","oauthClientSecret":"WRITE-SECRET-MATERIAL-SENTINEL"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/slack/workspaces/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"connectionId":{"type":"string"}},"required":["orgUnitId","connectionId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","connectionId":"slack-connection-a"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/credentials/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credentialId":{"type":"string"},"sharedWithDescendants":{"type":"boolean"}},"required":["credentialId","sharedWithDescendants"],"additionalProperties":false},"example":{"credentialId":"credentials:a","sharedWithDescendants":true}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/connection-credentials/sharing":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"credentialId":{"type":"string"},"sharedWithDescendants":{"type":"boolean"}},"required":["credentialId","sharedWithDescendants"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","credentialId":"credentials:a","sharedWithDescendants":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/slack/workspaces/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"connectionId":{"type":"string"},"enabled":{"type":"boolean"}},"required":["orgUnitId","connectionId","enabled"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","connectionId":"slack-connection-a","enabled":true}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/external-tools/configuration/update":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configurationId":{"type":"string"},"displayName":{"type":"string"},"workspaceDomain":{"type":"string"},"oauthClientId":{"type":"string"},"oauthRedirectUri":{"type":"string"},"defaultScopes":{"type":"array","items":{"type":"string"}},"allowedToolIds":{"type":"array","items":{"type":"string"}}},"required":["configurationId"],"additionalProperties":false},"example":{"configurationId":"externalToolConfigurations:google","displayName":"Google"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/external-tools/configuration/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configurationId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"active"},{"type":"string","const":"suspended"}]}},"required":["configurationId","status"],"additionalProperties":false},"example":{"configurationId":"externalToolConfigurations:google","status":"suspended"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/external-tools/identity/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"identityId":{"type":"string"},"displayName":{"type":"string"},"grantedScopes":{"type":"array","items":{"type":"string"}}},"required":["identityId"],"additionalProperties":false},"example":{"identityId":"externalToolIdentities:agent","displayName":"Support agent"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/external-tools/identity/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"identityId":{"type":"string"},"status":{"anyOf":[{"type":"string","const":"pending"},{"type":"string","const":"active"},{"type":"string","const":"suspended"},{"type":"string","const":"revoked"}]}},"required":["identityId","status"],"additionalProperties":false},"example":{"identityId":"externalToolIdentities:agent","status":"suspended"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/credentials/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"credentialId":{"type":"string"}},"required":["credentialId"],"additionalProperties":false},"example":{"credentialId":"credentials:a"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/credentials/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"credentialId":{"type":"string"}},"required":["credentialId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","credentialId":"credentials:a"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/external-tools/identity/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"identityId":{"type":"string"},"overrideSuccess":{"type":"boolean"},"overrideError":{"type":"string"}},"required":["identityId"],"additionalProperties":false},"example":{"identityId":"externalToolIdentities:agent"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/oauth/registrations/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"registrationId":{"type":"string"},"expectedGeneration":{"type":"number"},"clientSecret":{"type":"string"}},"required":["registrationId","expectedGeneration","clientSecret"],"additionalProperties":false},"example":{"registrationId":"oauthClientRegistrations:okta","expectedGeneration":1,"clientSecret":"WRITE-SECRET-MATERIAL-SENTINEL"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/connections/admin/oauth/grants/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"grantId":{"type":"string"},"expectedGeneration":{"type":"number"},"reason":{"type":"string"}},"required":["grantId","expectedGeneration","reason"],"additionalProperties":false},"example":{"grantId":"oauthGrants:ada","expectedGeneration":1,"reason":"rotated out"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/budgets/alerts/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"alertId":{"type":"string"}},"required":["alertId"],"additionalProperties":false},"example":{"alertId":"budgetalert_open"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/budgets/alerts/create":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"budgetId":{"type":"string"},"thresholdPercent":{"type":"number"}},"required":["budgetId","thresholdPercent"],"additionalProperties":false},"example":{"budgetId":"budgethierarchy_eng","thresholdPercent":90}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/budgets/create":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/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`.","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}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/limits/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false},"example":{"id":"budget_agent_alpha"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/limits/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","enabled"],"additionalProperties":false},"example":{"id":"budget_global_daily","enabled":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/limits/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"budgetId":{"type":"string"},"reason":{"type":"string"}},"required":["budgetId","reason"],"additionalProperties":false},"example":{"budgetId":"budget_global_daily","reason":"runaway spend test"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/limits/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"budgetId":{"type":"string"},"reason":{"type":"string"}},"required":["budgetId","reason"],"additionalProperties":false},"example":{"budgetId":"budget_agent_alpha","reason":"spend reviewed and cleared"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/runs/step-sandbox-cost":{"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.","parameters":[{"name":"runId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:none"},{"name":"nodeId","in":"query","required":true,"schema":{"type":"string"},"example":"n1"}],"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"}},"/api/v2/costs/admin/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.","parameters":[{"name":"scope","in":"query","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}}],"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"}},"/api/v2/costs/admin/limits/all":{"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.","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}}],"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"}},"/api/v2/costs/admin/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.","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}}],"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"}},"/api/v2/costs/admin/token-events/time-range":{"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.","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}}],"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"}},"/api/v2/costs/admin/token-events/agent":{"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.","parameters":[{"name":"agentId","in":"query","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}}],"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"}},"/api/v2/costs/admin/token-events/workflow":{"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.","parameters":[{"name":"workflowId","in":"query","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}}],"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"}},"/api/v2/costs/admin/token-events/session":{"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.","parameters":[{"name":"sessionKey","in":"query","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}}],"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"}},"/api/v2/costs/admin/token-events/session/in-scope":{"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.","parameters":[{"name":"sessionKey","in":"query","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}}],"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"}},"/api/v2/costs/admin/agents/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.","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"}}],"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"}},"/api/v2/costs/admin/thread-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.","parameters":[{"name":"threadId","in":"query","required":true,"schema":{"type":"string"},"example":"agent-thread:one"}],"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"}},"/api/v2/costs/admin/session-tokens":{"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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"sessionId","in":"query","required":true,"schema":{"type":"string"},"example":"channelSessions:one"},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}}],"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"}},"/api/v2/costs/admin/budgets/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.","parameters":[{"name":"budgetId","in":"query","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}}],"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"}},"/api/v2/costs/admin/budgets/alerts/pending":{"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.","parameters":[{"name":"budgetId","in":"query","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}}],"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"}},"/api/v2/costs/admin/budgets/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.","parameters":[{"name":"budgetId","in":"query","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}}],"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"}},"/api/v2/costs/admin/budgets/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.","parameters":[{"name":"budgetId","in":"query","required":true,"schema":{"type":"string"},"example":"budgethierarchy_eng"}],"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"}},"/api/v2/costs/admin/pricing/current":{"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","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-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/costs/admin/pricing/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","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-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/costs/admin/pricing/latest":{"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.","parameters":[{"name":"modelId","in":"query","required":true,"schema":{"type":"string"},"example":"claude-sonnet-4-6"}],"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"}},"/api/v2/costs/admin/pricing/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.","parameters":[{"name":"modelId","in":"query","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}}],"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"}},"/api/v2/costs/admin/pricing/at":{"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.","parameters":[{"name":"modelId","in":"query","required":true,"schema":{"type":"string"},"example":"claude-sonnet-4-6"},{"name":"timestamp","in":"query","required":true,"schema":{"type":"number"},"example":"1700000000000"}],"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"}},"/api/v2/costs/admin/pricing/history/in-scope":{"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.","parameters":[{"name":"modelId","in":"query","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}}],"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"}},"/api/v2/costs/admin/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.","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"}],"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"}},"/api/v2/costs/admin/aggregates/agent":{"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.","parameters":[{"name":"bucket","in":"query","required":true,"schema":{"type":"string"},"example":"daily"},{"name":"agentId","in":"query","required":true,"schema":{"type":"string"},"example":"agent_alpha_sentinel"},{"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}}],"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"}},"/api/v2/costs/admin/aggregates/model":{"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.","parameters":[{"name":"bucket","in":"query","required":true,"schema":{"type":"string"},"example":"daily"},{"name":"model","in":"query","required":true,"schema":{"type":"string"},"example":"claude-sonnet-4-6"},{"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}}],"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"}},"/api/v2/costs/admin/aggregates/workflow":{"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.","parameters":[{"name":"bucket","in":"query","required":true,"schema":{"type":"string"},"example":"daily"},{"name":"workflowId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"workflow_wf1_sentinel"},{"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}}],"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"}},"/api/v2/costs/admin/budgets/transactions/record":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"budgetId":{"type":"string"},"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":["budgetId","type","amountCents"],"additionalProperties":false},"example":{"budgetId":"budgethierarchy_eng","type":"allocation","amountCents":1000}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/budgets/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"budgetId":{"type":"string"},"limitCents":{"type":"number"}},"required":["budgetId","limitCents"],"additionalProperties":false},"example":{"budgetId":"budgethierarchy_eng","limitCents":200000}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/costs/admin/budgets/get":{"get":{"operationId":"getBudgetAdmin","tags":["Costs and budgets"],"summary":"Get one budget.","description":"Requires permission `cost:read`.\n\nGet one budget.","parameters":[{"name":"budgetId","in":"query","required":true,"schema":{"type":"string"},"example":"budgethierarchy_eng"}],"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"}},"/api/v2/costs/admin/budgets/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,"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-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/costs/admin/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.","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"}],"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"}},"/api/v2/customers/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string"}},"required":["customerId"],"additionalProperties":false},"example":{"customerId":"customers:acme"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/email/admin/routes/create":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/email/admin/routes/delete":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"routeId":{"type":"string","minLength":1}},"required":["routeId"],"additionalProperties":false},"example":{"routeId":"emailRoutes:support"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/email/admin/routes/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"routeId":{"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"}},"required":["routeId"],"additionalProperties":false},"example":{"routeId":"emailRoutes:support","enabled":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/email/admin/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.","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}}],"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"}},"/api/v2/email/admin/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.","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}}],"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"}},"/api/v2/email/admin/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.","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}}],"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"}},"/api/v2/email/admin/ingress/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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/email/admin/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"}},"/api/v2/email/admin/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"}},"/api/v2/environments/admin/connections/create":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/environments/admin/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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/environments/admin/connections/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"operationId":{"type":"string"}},"required":["connectionId","operationId"],"additionalProperties":false},"example":{"connectionId":"environmentConnections:one","operationId":"secretop_0b9f8c7d-6e5a-4b3c-9d2e-1f0a9b8c7d6e"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/environments/admin/connections/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"name":{"type":"string"}},"required":["connectionId"],"additionalProperties":false},"example":{"connectionId":"environmentConnections:one","name":"Renamed deploys"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/environments/admin/connections/list":{"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.","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}}],"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"}},"/api/v2/environments/admin/connections/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1},"credential":{"type":"string"},"operationId":{"type":"string"}},"required":["connectionId","credential","operationId"],"additionalProperties":false},"example":{"connectionId":"environmentConnections:one","credential":"ghp_contract_credential_never_answered","operationId":"secretop_0b9f8c7d-6e5a-4b3c-9d2e-1f0a9b8c7d6e"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/external-apps/admin/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.","parameters":[{"name":"id","in":"query","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}}],"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"}},"/api/v2/files/admin/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"channelId":{"type":"string"},"fileId":{"type":"string"}},"required":["channelId","fileId"],"additionalProperties":false},"example":{"channelId":"channels:one","fileId":"files:attached"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/roles/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rolesId":{"type":"string"},"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":["rolesId","changes"],"additionalProperties":false},"example":{"rolesId":"roles_operator","changes":[{"kind":"tool","targetId":"tool_fetch","mode":"grant"}]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/roles/admin/create":{"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`.","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}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/roles/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"roleId":{"type":"string"},"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":["roleId","field"],"additionalProperties":false},"example":{"roleId":"roles_operator","field":"jobDescription"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"expensive"}},"/api/v2/roles/admin/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.","parameters":[{"name":"rolesId","in":"query","required":true,"schema":{"type":"string"},"example":"roles_operator"}],"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"}},"/api/v2/roles/admin/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false},"example":{"id":"roles_operator"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/roles/admin/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"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":["id","patch"],"additionalProperties":false},"example":{"id":"roles_operator","patch":{"name":"Senior Operator"}}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/roles/admin/grants/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.","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}}],"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"}},"/api/v2/roles/admin/content/generation":{"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.","parameters":[{"name":"requestId","in":"query","required":true,"schema":{"type":"string"},"example":"rolegen_world"}],"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"}},"/api/v2/identity/admin/unmapped-attempts/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"attemptId":{"type":"string","minLength":1},"reason":{"type":"string"},"ttlDays":{"type":"number"}},"required":["attemptId","reason"],"additionalProperties":false},"example":{"attemptId":"unmappedIdentityAttempts:email","reason":"Not one of ours.","ttlDays":30}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/identity/admin/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.","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}}],"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"}},"/api/v2/identity/admin/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.","parameters":[{"name":"userId","in":"query","required":false,"schema":{"type":"string"}}],"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"}},"/api/v2/identity/admin/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"}},"additionalProperties":false},"example":{}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/knowledge/admin/distillations/get":{"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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"requestId","in":"query","required":true,"schema":{"type":"string"},"example":"primitiveSynthesisRequests:improve"}],"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"}},"/api/v2/knowledge/admin/search-as":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"agentId":{"type":"string"},"limit":{"type":"number"},"namespace":{"type":"string"}},"required":["query","agentId"],"additionalProperties":false},"example":{"query":"vpn","agentId":"routed"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/memory/admin/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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/memory/admin/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.","parameters":[{"name":"agentDefinitionId","in":"query","required":true,"schema":{"type":"string"},"example":"agentdef_worker"},{"name":"limit","in":"query","required":false,"schema":{"type":"number"}}],"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"}},"/api/v2/models/admin/catalog/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"modelId":{"type":"string"}},"required":["modelId"],"additionalProperties":false},"example":{"modelId":"acme/small"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/catalog/create":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/fallback-chains/create":{"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`.","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}]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/slots/create":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/fallback-chains/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false},"example":{"id":"llmfallbackchain_custom"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/routing/agents/delete":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"}},"required":["agentId"],"additionalProperties":false},"example":{"agentId":"agentdef_routed"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/slots/delete":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slotId":{"type":"string"}},"required":["slotId"],"additionalProperties":false},"example":{"slotId":"modelslot_fast"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/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.","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}}],"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"}},"/api/v2/models/admin/slots/get":{"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.","parameters":[{"name":"slotName","in":"query","required":true,"schema":{"type":"string"},"example":"fast"},{"name":"environment","in":"query","required":false,"schema":{"type":"string"},"example":"production"}],"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"}},"/api/v2/models/admin/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.","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}}],"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"}},"/api/v2/models/admin/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"}},"/api/v2/models/admin/routing/agents/get":{"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.","parameters":[{"name":"agentId","in":"query","required":true,"schema":{"type":"string"},"example":"agentdef_routed"}],"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"}},"/api/v2/models/admin/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.","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}}],"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"}},"/api/v2/models/admin/catalog/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"modelId":{"type":"string"}},"required":["modelId"],"additionalProperties":false},"example":{"modelId":"acme/small"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/catalog/search-with-usage":{"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.","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}}],"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"}},"/api/v2/models/admin/routing/agents/set":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"},"tiers":{"type":"object","properties":{"low":{"type":"string"},"medium":{"type":"string"},"high":{"type":"string"}},"required":["low","medium","high"],"additionalProperties":false},"enabled":{"type":"boolean"}},"required":["agentId","tiers","enabled"],"additionalProperties":false},"example":{"agentId":"agentdef_routed","tiers":{"low":"acme/small","medium":"acme/medium","high":"acme/large"},"enabled":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/routing/org-default/set":{"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`.","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}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/catalog/suggest-replacement":{"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.","parameters":[{"name":"modelId","in":"query","required":true,"schema":{"type":"string"},"example":"acme/old"}],"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"}},"/api/v2/models/admin/catalog/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"modelId":{"type":"string"},"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":["modelId","patch"],"additionalProperties":false},"example":{"modelId":"acme/old","patch":{"displayName":"Older"}}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/fallback-chains/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"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}}},"required":["id"],"additionalProperties":false},"example":{"id":"llmfallbackchain_custom","name":"Renamed"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/slots/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slotId":{"type":"string"},"resolvedModelId":{"type":"string"},"description":{"type":"string"}},"required":["slotId"],"additionalProperties":false},"example":{"slotId":"modelslot_fast","resolvedModelId":"acme/old"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/models/admin/catalog/list-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.","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}}],"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"}},"/api/v2/notifications/admin/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,"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-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/notifications/admin/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.","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}}],"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"}},"/api/v2/planning/admin/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.","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}}],"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"}},"/api/v2/planning/admin/my-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.","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}}],"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"}},"/api/v2/ops/admin/attention/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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/ops/admin/notes/add":{"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`.","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."}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/ops/admin/runs/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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"runId","in":"query","required":true,"schema":{"type":"string","minLength":1},"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}}],"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"}},"/api/v2/ops/admin/attention":{"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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"includeAcknowledged","in":"query","required":false,"schema":{"type":"boolean"}}],"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"}},"/api/v2/ops/admin/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.","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}}],"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"}},"/api/v2/ops/admin/runs/recent-failures":{"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.","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}}],"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"}},"/api/v2/ops/admin/steps/slowest":{"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.","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`."}],"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"}},"/api/v2/ops/admin/runs/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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"runId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:failedAtA"}],"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"}},"/api/v2/ops/admin/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.","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"}}],"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"}},"/api/v2/ops/admin/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.","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"}}],"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"}},"/api/v2/org-units/admin/drafts/positions/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"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"},"positionId":{"type":"string"}},"required":["draftId","expectedTargetStateHash","resolutions","reason","positionId"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","positionId":"positions:lead","expectedTargetStateHash":"54e075af8d48f5011aac40fe3b352481e236f7a6437546ef8ffd89023016b169","resolutions":[],"reason":"Reorganizing"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/positions/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"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"},"positionId":{"type":"string"}},"required":["draftId","expectedTargetStateHash","resolutions","reason","positionId"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","positionId":"positions:lead","expectedTargetStateHash":"54e075af8d48f5011aac40fe3b352481e236f7a6437546ef8ffd89023016b169","resolutions":[],"reason":"Reorganizing"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/positions/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"positionId":{"type":"string"}},"required":["draftId","positionId"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","positionId":"positions:lead"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/org-units/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"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"},"id":{"type":"string"}},"required":["draftId","expectedTargetStateHash","resolutions","reason","id"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","id":"orgUnits:A","expectedTargetStateHash":"2bb7cf06f82788fc00c1853256801a2c35389628e5a7929facfaccfb1c545a84","resolutions":[],"reason":"Reorganizing"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/org-units/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"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"},"id":{"type":"string"}},"required":["draftId","expectedTargetStateHash","resolutions","reason","id"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","id":"orgUnits:A","expectedTargetStateHash":"2bb7cf06f82788fc00c1853256801a2c35389628e5a7929facfaccfb1c545a84","resolutions":[],"reason":"Reorganizing"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/org-units/remove":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"draftId":{"type":"string"}},"required":["orgUnitId","draftId"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","orgUnitId":"orgUnits:A"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/capital-partners/add":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"code":{"type":"string"},"reason":{"type":"string"}},"required":["draftId","name","code","reason"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","name":"Acme Capital","code":"cp_acme","reason":"New partner"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/structure-types/create":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/memberships/by-member":{"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.","parameters":[{"name":"memberType","in":"query","required":true,"schema":{"anyOf":[{"type":"string","const":"position"},{"type":"string","const":"worker"}]},"example":"worker"},{"name":"memberId","in":"query","required":true,"schema":{"type":"string"},"example":"workers: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}}],"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"}},"/api/v2/org-units/admin/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.","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 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}}],"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"}},"/api/v2/org-units/admin/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.","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}}],"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"}},"/api/v2/org-units/admin/structure-types/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","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-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/org-units/admin/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.","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}}],"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"}},"/api/v2/org-units/admin/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.","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}}],"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"}},"/api/v2/org-units/admin/drafts/positions/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"positionId":{"type":"string"},"newOrgUnitId":{"type":"string"}},"required":["draftId","positionId","newOrgUnitId"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","positionId":"positions:lead","newOrgUnitId":"orgUnits:A"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/dependencies/org-unit":{"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.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"example":"orgUnits:tiger"}],"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"}},"/api/v2/org-units/admin/dependencies/position":{"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.","parameters":[{"name":"positionId","in":"query","required":true,"schema":{"type":"string"},"example":"positions:lead"}],"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"}},"/api/v2/org-units/admin/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`.","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"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/structure-types/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"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"}]}},"required":["id"],"additionalProperties":false},"example":{"id":"orgStructureTypes:team","name":"Squad"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/org-units/update":{"post":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"draftId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"structureTypeKey":{"type":"string"},"code":{"type":"string"}},"required":["orgUnitId","draftId"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","orgUnitId":"orgUnits:A","name":"Renamed"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/positions/add":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"draftId":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"workerRoleId":{"type":"string"},"isManager":{"type":"boolean"}},"required":["orgUnitId","draftId","title"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","orgUnitId":"orgUnits:tiger","title":"Producer"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/org-units/add":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"name":{"type":"string"},"structureTypeKey":{"type":"string"},"parentUnitId":{"type":"string"},"description":{"type":"string"},"code":{"type":"string"}},"required":["draftId","name","structureTypeKey"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","name":"New Studio","structureTypeKey":"team"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/positions/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"},"positionId":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"workerRoleId":{"anyOf":[{"type":"string"},{"type":"null"}]},"isManager":{"type":"boolean"}},"required":["draftId","positionId"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one","positionId":"positions:lead","title":"Lead Producer"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/active":{"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"}},"/api/v2/org-units/admin/drafts/create":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/org-units/admin/drafts/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"draftId":{"type":"string"}},"required":["draftId"],"additionalProperties":false},"example":{"draftId":"orgchartdraft_one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/people/admin/memberships/add":{"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"memberType":{"anyOf":[{"type":"string","const":"position"},{"type":"string","const":"worker"}]},"memberId":{"type":"string"},"role":{"type":"string"}},"required":["orgUnitId","memberType","memberId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","memberType":"worker","memberId":"workers:w1"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/people/admin/integrity/repairs/apply":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"repairRunId":{"type":"string"},"expectedPlanHash":{"type":"string"}},"required":["repairRunId","expectedPlanHash"],"additionalProperties":false},"example":{"repairRunId":"workforce_integrity_repair","expectedPlanHash":"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/people/admin/memberships/update-role":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"membershipId":{"type":"string"},"role":{"type":"string"}},"required":["membershipId"],"additionalProperties":false},"example":{"membershipId":"orgUnitMemberships:m1","role":"Chair"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/people/admin/workers/create":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/people/admin/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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/people/admin/workers/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workerId":{"type":"string"}},"required":["workerId"],"additionalProperties":false},"example":{"workerId":"workers:w1"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/people/admin/integrity/person-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"}},"/api/v2/people/admin/workers/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.","parameters":[{"name":"workerId","in":"query","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}}],"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"}},"/api/v2/people/admin/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.","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}}],"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"}},"/api/v2/people/admin/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.","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}}],"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"}},"/api/v2/people/admin/integrity/repairs/preview":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"auditRunId":{"type":"string"},"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":["auditRunId","dispositions"],"additionalProperties":false},"example":{"auditRunId":"workforce_integrity_audit","dispositions":[{"findingId":"wf_dxFq_UcaIxTtiUxZ8QiAgA","decision":"DISMISS","reason":"Free text a person wrote."}]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/people/admin/integrity/runs/get":{"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.","parameters":[{"name":"runId","in":"query","required":false,"schema":{"type":"string"},"example":"workforce_integrity_audit"}],"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"}},"/api/v2/people/admin/integrity/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.","parameters":[{"name":"runId","in":"query","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}}],"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"}},"/api/v2/people/admin/memberships/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"membershipId":{"type":"string"}},"required":["membershipId"],"additionalProperties":false},"example":{"membershipId":"orgUnitMemberships:m1"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/people/admin/workers/expertise-tags/set":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workerId":{"type":"string"},"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":["workerId","expertiseTagId","level","source"],"additionalProperties":false},"example":{"workerId":"workers:w1","expertiseTagId":"expertiseTags:ts","level":"expert","source":"manual"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/people/admin/integrity/audits/start":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/projects/admin/requests/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.","parameters":[{"name":"requestId","in":"query","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}}],"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"}},"/api/v2/projects/admin/requests/get":{"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.","parameters":[{"name":"requestId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"requests:intake"}],"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"}},"/api/v2/projects/admin/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.","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}}],"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"}},"/api/v2/projects/admin/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.","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}}],"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"}},"/api/v2/runs/admin/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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"runId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:delegatedAtA"},{"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}}],"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"}},"/api/v2/runs/admin/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","id":"workflowRuns:delegatedAtA"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/runs/admin/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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgUnitId":{"type":"string"},"runId":{"type":"string","minLength":1},"checkpointId":{"type":"string","minLength":1}},"required":["runId","checkpointId"],"additionalProperties":false},"example":{"orgUnitId":"orgUnits:A","runId":"workflowRuns:delegatedAtA","checkpointId":"workflowCheckpoints:lookupAtA"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/runs/admin/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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"},"example":"orgUnits:A"},{"name":"runId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"workflowRuns:delegatedAtA"},{"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}}],"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"}},"/api/v2/skills/admin/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"permanent":{"type":"boolean"}},"required":["id"],"additionalProperties":false},"example":{"id":"skilldef_one","permanent":true}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/skills/admin/catalogs/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,"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-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/skills/admin/catalogs/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"type":"string"}},"required":["providerId"],"additionalProperties":false},"example":{"providerId":"clawhub"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/skills/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"originSkillId":{"type":"string"},"newSkillId":{"type":"string"}},"required":["originSkillId","newSkillId"],"additionalProperties":false},"example":{"originSkillId":"skilldef_catalog","newSkillId":"translate-copy"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/skills/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","enabled"],"additionalProperties":false},"example":{"id":"skilldef_one","enabled":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/skills/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string"},"skillId":{"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","skillId","name","description"],"additionalProperties":false},"example":{"fileId":"files:skill_upload","skillId":"acme-skill","name":"Acme","description":"Does acme things."}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/skills/admin/catalogs/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"type":"string"},"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":["providerId","skills"],"additionalProperties":false},"example":{"providerId":"clawhub","skills":[{"skillKey":"acme/alpha","name":"Alpha","description":"The alpha skill."}]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/skills/admin/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.","parameters":[{"name":"skillId","in":"query","required":true,"schema":{"type":"string"},"example":"summarize"}],"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"}},"/api/v2/skills/admin/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.","parameters":[{"name":"skillId","in":"query","required":true,"schema":{"type":"string"},"example":"summarize"}],"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"}},"/api/v2/skills/admin/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.","parameters":[{"name":"skillId","in":"query","required":true,"schema":{"type":"string"},"example":"extract"}],"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"}},"/api/v2/skills/admin/versions/reinstate":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"string"},"reason":{"type":"string"}},"required":["id","version"],"additionalProperties":false},"example":{"id":"skilldef_one","version":"1.0.0"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/skills/admin/exemplars/replace":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"exemplars":{"type":"array","items":{"type":"object","properties":{"input":{},"expectedOutput":{},"notes":{"type":"string"}},"required":["input","expectedOutput"],"additionalProperties":false}}},"required":["id","exemplars"],"additionalProperties":false},"example":{"id":"skilldef_one","exemplars":[{"input":"Summarize the Q3 report.","expectedOutput":"Three bullet points."},{"input":"Summarize the board minutes.","expectedOutput":"One paragraph."}]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/skills/admin/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.","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}}],"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"}},"/api/v2/tools/admin/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false},"example":{"id":"tooldef_one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/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.","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"}}],"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"}},"/api/v2/tools/admin/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`.","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."}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/create":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"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":["id","patch"],"additionalProperties":false},"example":{"id":"tooldef_one","patch":{"riskLevel":"write"}}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"enabled":{"type":"boolean"}},"required":["id","enabled"],"additionalProperties":false},"example":{"id":"tooldef_one","enabled":false}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/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.","parameters":[{"name":"sourceTypes","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}}],"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"}},"/api/v2/tools/admin/commands/get":{"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.","parameters":[{"name":"commandId","in":"query","required":true,"schema":{"type":"string"},"example":"git.status"}],"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"}},"/api/v2/tools/admin/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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/commands/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.","parameters":[{"name":"commandId","in":"query","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}}],"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"}},"/api/v2/tools/admin/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.","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}}],"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"}},"/api/v2/tools/admin/commands/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.","parameters":[{"name":"commandId","in":"query","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}}],"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"}},"/api/v2/tools/admin/versions/reinstate":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"string"},"reason":{"type":"string"}},"required":["id","version"],"additionalProperties":false},"example":{"id":"tooldef_one","version":"1.0.0"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"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":["id","sandboxCommands"],"additionalProperties":false},"example":{"id":"tooldef_sandbox","sandboxCommands":[{"pattern":"git status","matchKind":"literal"}]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/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.","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"]}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/tools/admin/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"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":["id","patch"],"additionalProperties":false},"example":{"id":"tooldef_one","patch":{"description":"Looks up a contact."}}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/trust-fabric/admin/kill/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}},"required":["reason"],"additionalProperties":false},"example":{"reason":"Incident 42: halt every run"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/trust-fabric/admin/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.","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}}],"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"}},"/api/v2/trust-fabric/admin/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.","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`."}],"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"}},"/api/v2/trust-fabric/admin/command-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.","parameters":[{"name":"commandId","in":"query","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}}],"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"}},"/api/v2/trust-fabric/admin/chat-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.","parameters":[{"name":"orgUnitId","in":"query","required":false,"schema":{"type":"string"}},{"name":"sessionId","in":"query","required":true,"schema":{"type":"string","minLength":1},"example":"channelSessions:tf_chat"},{"name":"promptMessageId","in":"query","required":true,"schema":{"type":"string"},"example":"tf_prompt_message"}],"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"}},"/api/v2/trust-fabric/admin/run-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.","parameters":[{"name":"runId","in":"query","required":true,"schema":{"type":"string"},"example":"workflowRuns:tf_r1"}],"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"}},"/api/v2/trust-fabric/admin/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.","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}}],"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"}},"/api/v2/trust-fabric/admin/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"}},"/api/v2/trust-fabric/admin/posture/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","const":"workflow_publish_judge_gate"},"mode":{"type":"string","const":"enforce"},"reason":{"type":"string"}},"required":["key","mode","reason"],"additionalProperties":false},"example":{"key":"workflow_publish_judge_gate","mode":"enforce","reason":"Incident 42: judge every publish"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/trust-fabric/admin/doors/agents":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"door":{"type":"string","const":"agents"},"stopped":{"type":"boolean"},"reason":{"type":"string"}},"required":["door","stopped","reason"],"additionalProperties":false},"example":{"door":"agents","stopped":true,"reason":"Incident 42: stop agent writes"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/trust-fabric/admin/kill/state":{"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"}},"/api/v2/trust-fabric/admin/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.","parameters":[{"name":"agentDefinitionId","in":"query","required":true,"schema":{"type":"string"},"example":"agentdef_tf_a1"}],"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"}},"/api/v2/vendors/admin/notes/add":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"toolId":{"type":"string"},"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":["toolId","toolName","schemaHash","disposition","riskLevel"],"additionalProperties":false},"example":{"toolId":"splunk_mcp","toolName":"export","schemaHash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","disposition":"approved","riskLevel":"read"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/specs/attach":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/create":{"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`.","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"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendorId":{"type":"string"},"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"}}},"required":["vendorId"],"additionalProperties":false},"example":{"vendorId":"vendors:acme","name":"Acme Corp"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/specs/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"apiSpecId":{"type":"string"},"title":{"type":"string"},"sourceUrl":{"type":"string"},"notes":{"type":"string"},"version":{"type":"string"},"connectionName":{"type":"string"}},"required":["apiSpecId"],"additionalProperties":false},"example":{"apiSpecId":"vendorApiSpecs:one","title":"Acme REST v2"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/notes/update":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lessonId":{"type":"string"},"content":{"type":"string"},"connectionName":{"type":"string"}},"required":["lessonId"],"additionalProperties":false},"example":{"lessonId":"vendorLessons:one","content":"Rate limited to 20 requests a second"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/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.","parameters":[{"name":"vendorKey","in":"query","required":true,"schema":{"type":"string"},"example":"acme"}],"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"}},"/api/v2/vendors/admin/links/add":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendorId":{"type":"string"},"primitiveType":{"anyOf":[{"type":"string","const":"tool"},{"type":"string","const":"procedure"}]},"primitiveId":{"type":"string"},"primitiveLabel":{"type":"string"}},"required":["vendorId","primitiveType","primitiveId"],"additionalProperties":false},"example":{"vendorId":"vendors:acme","primitiveType":"procedure","primitiveId":"acme_sync"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/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.","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}}],"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"}},"/api/v2/vendors/admin/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).","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}}],"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"}},"/api/v2/vendors/admin/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.","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}}],"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"}},"/api/v2/vendors/admin/list":{"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.","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}}],"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"}},"/api/v2/vendors/admin/connections/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.","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"}}}}],"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"}},"/api/v2/vendors/admin/connections/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.","parameters":[{"name":"vendorKey","in":"query","required":true,"schema":{"type":"string"},"example":"splunk"},{"name":"connectionName","in":"query","required":true,"schema":{"type":"string"},"example":"mcp"}],"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"}},"/api/v2/vendors/admin/specs/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"apiSpecId":{"type":"string"}},"required":["apiSpecId"],"additionalProperties":false},"example":{"apiSpecId":"vendorApiSpecs:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/notes/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lessonId":{"type":"string"}},"required":["lessonId"],"additionalProperties":false},"example":{"lessonId":"vendorLessons:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/approval-status/set":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vendorId":{"type":"string"},"approvalStatus":{"anyOf":[{"type":"string","const":"approved"},{"type":"string","const":"under_review"},{"type":"string","const":"not_approved"},{"type":"string","const":"deprecated"}]}},"required":["vendorId","approvalStatus"],"additionalProperties":false},"example":{"vendorId":"vendors:acme","approvalStatus":"under_review"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/vendors/admin/links/remove":{"post":{"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"linkId":{"type":"string"}},"required":["linkId"],"additionalProperties":false},"example":{"linkId":"vendorLinks:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/admin/update":{"post":{"operationId":"updateWebhookAdmin","tags":["Webhooks"],"summary":"Update a webhook subscription's URL, events, label or auth token (null clears the token); an id that names no subscription changes nothing.","description":"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"label":{"type":"string"},"authToken":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id"],"additionalProperties":false},"example":{"id":"whsub_one","label":"Receiver v2","authToken":"WEBHOOK-AUTH-TOKEN-SENTINEL"}}}},"responses":{"200":{"description":"Update a webhook subscription's URL, events, label or auth token (null clears the token); 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; `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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse400Keyed"}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse401"}}},"headers":{"X-Request-Id":{"$ref":"#/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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/admin/deliveries":{"get":{"operationId":"listWebhookDeliveriesAdmin","tags":["Webhooks"],"summary":"List a page of a webhook subscription's deliveries, newest first.","description":"Requires permission `webhooks:read`.\n\nList a page of a webhook subscription's deliveries, newest first.","parameters":[{"name":"subscriptionId","in":"query","required":true,"schema":{"type":"string"},"example":"whsub_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":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}}],"responses":{"200":{"description":"List a page of a webhook subscription's deliveries, newest first.","content":{"application/json":{"schema":{"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"]},"example":{"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}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/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: `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":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/webhooks/admin/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.","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}}],"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"}},"/api/v2/webhooks/admin/pause":{"post":{"operationId":"pauseWebhookAdmin","tags":["Webhooks"],"summary":"Pause a webhook subscription; an id that names no subscription changes nothing.","description":"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false},"example":{"id":"whsub_one"}}}},"responses":{"200":{"description":"Pause 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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/admin/resume":{"post":{"operationId":"resumeWebhookAdmin","tags":["Webhooks"],"summary":"Resume a webhook subscription and clear its failure count; an id that names no subscription changes nothing.","description":"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false},"example":{"id":"whsub_one"}}}},"responses":{"200":{"description":"Resume a webhook subscription and clear its failure count; 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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/admin/dead-letters/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"}},"/api/v2/webhooks/admin/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.","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`."}],"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"}},"/api/v2/webhooks/admin/test":{"post":{"operationId":"sendTestWebhookAdmin","tags":["Webhooks"],"summary":"Send a test delivery to a webhook subscription and answer its delivery id.","description":"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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subscriptionId":{"type":"string"}},"required":["subscriptionId"],"additionalProperties":false},"example":{"subscriptionId":"whsub_one"}}}},"responses":{"200":{"description":"Send a test delivery to a webhook subscription and answer its delivery id.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"},"meta":{"$ref":"#/components/schemas/PlatformMeta"}},"required":["data","meta"]},"example":{"data":"webhookdelivery_00523d09-7964-4755-abb5-1f08b2c37ace","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 active webhook subscription 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":"webhooks","x-forge-irreversible":"delivered","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/admin/list":{"get":{"operationId":"listWebhooksAdmin","tags":["Webhooks"],"summary":"List a page of every webhook subscription, admin-owned and app-owned, newest first; no signing secret or auth token is answered.","description":"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,"description":"The opaque `meta.nextCursor` from the previous page, with the same other parameters.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"List a page of every webhook subscription, admin-owned and app-owned, newest first; no signing secret or auth token is answered.","content":{"application/json":{"schema":{"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"]},"example":{"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}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"RateLimit-Limit":{"$ref":"#/components/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: `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":"database","x-forge-actor-kinds":["platform_key","personal_key"],"security":[{"PlatformApiKey":[]},{"PersonalKey":[]}],"x-forge-rate-limit":"read"}},"/api/v2/webhooks/admin/dead-letters/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1}},"required":["id"],"additionalProperties":false},"example":{"id":"deadLetterQueue:one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/webhooks/admin/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`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false},"example":{"id":"whsub_one"}}}},"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":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"x-forge-rate-limit":"write"}},"/api/v2/workflows/admin/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.","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"}}],"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"}}},"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."}}}}}}
