List role grants held by API keys, External Apps and agents. Requires permissions grants:read, policies:read and audit:read; each grant is decided at its own scope.
GET
/
api
/
v3
/
governance-grants
List role grants held by API keys, External Apps and agents
Returns the grants held by API keys, External Apps and agents that you may see, and people’s grants when you pass includePersonGrants=true (or actorKind=person for people alone): grants:read at the grant’s scope, a role that is not a compatibility role, and, for an agent’s grant, agents:read at the agent’s home and in your credential’s scopes. People’s grants are returned by the person’s id; no grant says who gave it or why, or carries a name. A page may be short or empty while meta.hasMore is true; follow meta.nextCursor. To give or revoke a role, call giveRole or revokeRole, which need grants:manage. See Roles and grants.
Authorizations
BearerAuthPlatformApiKeyPersonalKey
Authorization
string
header
required
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.
Query Parameters
cursor
string
The previous page's meta.nextCursor; any other value is 400.
Minimum string length: 1
limit
integer
default:50
Grants read per page, 1 to 50 (default 50); a larger value is 400too_big.
Required range: 1 <= x <= 50
actorKind
enum<string>
Only grants held by this kind of actor. person lists people's grants alone.
Available options:
api_key,
external_app,
agent,
person
includePersonGrants
enum<string>
true also returns people's grants. Without it (or actorKind=person) the page holds no person grant, as before.
Available options:
true
Response
One page of role grants
data
object[]
required
Show child attributes
meta
object
required
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.
Option 1
Option 2
Show child attributes
⌘I
List role grants held by API keys, External Apps and agents
{"docsConfig":{"theme":"maple","$schema":"https://mintlify.com/docs.json","name":"Gloo","colors":{"primary":"#00C980","light":"#33D89A","dark":"#007A4E"},"logo":{"light":"https://mintcdn.com/gloo-b243725a/6UEVtMrmK4zuVXLK/logo/logo-gloo-studio_dark.png?fit=max\u0026auto=format\u0026n=6UEVtMrmK4zuVXLK\u0026q=85\u0026s=e55c999bcee79d2a8c71201276d7ac04","dark":"https://mintcdn.com/gloo-b243725a/6UEVtMrmK4zuVXLK/logo/logo-gloo-studio_light.png?fit=max\u0026auto=format\u0026n=6UEVtMrmK4zuVXLK\u0026q=85\u0026s=d694bd564bd25770372866144835907f"},"favicon":"https://mintcdn.com/gloo-b243725a/kKkk4V16R7WUzhYp/images/favicon.png?fit=max\u0026auto=format\u0026n=kKkk4V16R7WUzhYp\u0026q=85\u0026s=44f053bd96986ec1e7eb58d2c05b2f70","api":{"playground":{"proxy":false}},"navbar":{"links":[{"href":"/getting-started/support","label":"Get help"}],"primary":{"type":"button","label":"Gloo AI Studio","href":"https://studio.ai.gloo.com/"}},"fonts":{"heading":{"family":"F37 Jan","weight":700,"source":"fonts/f37jan/F37Jan-Bold.woff2","format":"woff2"},"body":{"family":"F37 Jan","weight":400,"source":"fonts/f37jan/F37Jan-Regular.woff2","format":"woff2"}},"contextual":{"options":["copy","claude","chatgpt"],"display":"header"},"styling":{"latex":true},"navigation":{"global":{"anchors":[{"anchor":"Status","icon":"heart-pulse","href":"https://status.ai.gloo.com"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"gloo-b243725a","hasAudioNarration":false,"actualSubdomain":"gloo-b243725a","customDomains":["docs.gloo.com"],"gitSource":{"type":"github","owner":"tangogroup","repo":"gloo","deployBranch":"main","contentDirectory":"apps/docs","isPrivate":true,"mountPath":"","label":"","_id":"6aeb9b92936e725d0bbcad36"},"feedback":{"thumbs":false},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"REMOVE_BRANDING":{"status":"DISABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6af742c93e3caf0ce37022de","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Documentation","count":67},{"language":"default","tag":"API Reference","count":48},{"language":"default","tag":"Learning Center","count":43},{"language":"default","tag":"Legacy","count":29},{"language":"default","tag":"Tutorials","count":28},{"language":"default","tag":"Responses \u0026 Completions","count":18},{"language":"default","tag":"Best Practices","count":17},{"language":"default","tag":"Inference and APIs","count":16},{"language":"default","tag":"Content","count":15},{"language":"default","tag":"Data Engine","count":13}]},"assistantConfig":{},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"snippets/forge-palette.css","content":":root{--forge-purple: #9b8ab8;--forge-blue: #7a9ab8;--forge-red: #c46060;--forge-gold: #b8a87a;--forge-green: #6aab78;--forge-orange: #d4915a;--forge-bg-page: #0a0907;--forge-bg-panel: #110f0c;--forge-bg-panel-emph: #1a1715;--forge-border: #2a2520;--forge-text-muted: #5c5450;--forge-text-body: #8a8078;--forge-text-emph: #e8e2da}.forge-diagram{color-scheme:light dark;max-width:100%;overflow:hidden}.forge-diagram-scroll{overflow-x:auto;overscroll-behavior-inline:contain}.forge-diagram__title{color:#0f172a;font-weight:700}.forge-diagram__summary{color:#334155;font-size:0.875rem;line-height:1.5rem;margin-top:0.25rem}.forge-flow{display:flex;gap:1.75rem;list-style:none;margin:1rem 0 0;min-width:max-content;overflow-x:auto;padding:0 0 0.5rem}.forge-flow__step{background:#fff;border:1px solid #cbd5e1;border-top:4px solid var(--forge-blue);border-radius:0.75rem;display:grid;gap:0.25rem;min-width:11rem;padding:1rem;position:relative}.forge-flow__step+.forge-flow__step::before{color:#64748b;content:\"→\";font-size:1.25rem;left:-1.15rem;position:absolute;top:50%;transform:translate(-50%, -50%)}.forge-flow__step strong{color:#0f172a}.forge-flow__step span{color:#334155;font-size:0.875rem}.forge-flow__step small{color:#475569}.forge-tone-workforce{border-top-color:var(--forge-purple)}.forge-tone-substrate{border-top-color:var(--forge-blue)}.forge-tone-governance{border-top-color:var(--forge-red)}.forge-tone-observability{border-top-color:var(--forge-gold)}.forge-tone-production{border-top-color:var(--forge-green)}.forge-tone-operations{border-top-color:var(--forge-orange)}html.dark .forge-diagram__title,html.dark .forge-flow__step strong{color:#fafaf9}html.dark .forge-diagram__summary,html.dark .forge-flow__step span{color:#d6d3d1}html.dark .forge-flow__step small{color:#a8a29e}html.dark .forge-flow__step{background:#151310;border-color:#57534e}@media (max-width: 640px){.forge-diagram-responsive{display:flex;min-width:max-content}}@media (forced-colors: active){.forge-diagram *{forced-color-adjust:auto}}@media (prefers-reduced-motion: reduce){.forge-diagram *,.forge-diagram *::before,.forge-diagram *::after{scroll-behavior:auto;transition:none}}"},{"filePath":"forge-api-layout.css","content":"@media (max-width: 400px){body:has(#sidebar a[aria-current=\"page\"][href^=\"/forge/\"]) .api-section-heading>div:first-child{flex-wrap:wrap;gap:0.5rem}}"}]}
{"page":{"pagePath":"forge/reference/http-api/governance/listgrants","slug":"/forge/reference/http-api/governance/listgrants","pageMetadata":{"title":"List role grants","description":"List role grants held by API keys, External Apps and agents. Requires permissions `grants:read`, `policies:read` and `audit:read`; each grant is decided at its own scope.","deprecated":null,"version":null,"sidebarTitle":"List role grants","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-grants","href":"/forge/reference/http-api/governance/listgrants","autogeneratedByOpenApi":true,"hidden":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"List role grants held by API keys, External Apps and agents. Requires permissions \", _jsx(_components.code, {\n children: \"grants:read\"\n }), \", \", _jsx(_components.code, {\n children: \"policies:read\"\n }), \" and \", _jsx(_components.code, {\n children: \"audit:read\"\n }), \"; each grant is decided at its own scope.\"]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,..._provideComponents(),...props.components};return _jsxs(_components.p,{children:[`Returns the grants held by API keys, External Apps and agents that you may see, and people’s grants when you pass `,_jsx(_components.code,{children:`includePersonGrants=true`}),` (or `,_jsx(_components.code,{children:`actorKind=person`}),` for people alone): `,_jsx(_components.code,{children:`grants:read`}),` at the grant’s scope, a role that is not a compatibility role, and, for an agent’s grant, `,_jsx(_components.code,{children:`agents:read`}),` at the agent’s home and in your credential’s scopes. People’s grants are returned by the person’s id; no grant says who gave it or why, or carries a name. A page may be short or empty while `,_jsx(_components.code,{children:`meta.hasMore`}),` is `,_jsx(_components.code,{children:`true`}),`; follow `,_jsx(_components.code,{children:`meta.nextCursor`}),`. To give or revoke a role, call `,_jsx(_components.a,{href:`/forge/reference/http-api/governance/giveRole`,children:`giveRole`}),` or `,_jsx(_components.a,{href:`/forge/reference/http-api/governance/revokeRole`,children:`revokeRole`}),`, which need `,_jsx(_components.code,{children:`grants:manage`}),`. See `,_jsx(_components.a,{href:`/forge/reference/http-api/governance#roles-and-grants`,children:`Roles and grants`}),`.`]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"List role grants","description":"List role grants held by API keys, External Apps and agents. Requires permissions `grants:read`, `policies:read` and `audit:read`; each grant is decided at its own scope.","deprecated":null,"version":null,"sidebarTitle":"List role grants","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-grants","href":"/forge/reference/http-api/governance/listgrants","autogeneratedByOpenApi":true,"hidden":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"listGrants","tags":["Governance"],"summary":"List role grants held by API keys, External Apps and agents","description":"List role grants held by API keys, External Apps and agents. Requires permissions `grants:read`, `policies:read` and `audit:read`; each grant is decided at its own scope.","responses":{"200":"b9e7e5cf-1f9c-4e4f-a584-6610fb0d9c88","400":"e663c337-0d80-4445-971d-cc6432522746","401":"6e9c2acc-c1d8-42cf-ac87-36bd9cc7768c","403":"35f83e92-7f42-4b34-8037-24c94be5626c","404":"49d61ecf-8995-47d2-aa95-df89ddf6ff01","429":"bc2ba6b6-d207-42f4-939a-6ee28991cc1c","500":"6c39b8b5-b430-45a0-a220-c64c271ac01c","503":"44c4045d-63a7-4baa-bd65-d28b78c5989a"},"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":["7a214af9-78dd-49f6-9f9d-6fe40b92a737","6846a0a1-8b63-4ad9-9237-a7081efeacaa","2a049d91-d2e7-4375-8818-5088c21b9f01"],"x-forge-rate-limit":"read","parameters":["d581a474-3f57-4773-b515-3b23a5ad71cd","c66c152e-2b18-413a-8f15-093d9233299e","da4859ed-9af2-4027-95e2-1d8a743ff9b0","b97a48ce-85fa-4c19-ae6a-cec7e0a7bc94"],"x-mint":{"href":"/forge/reference/http-api/governance/listGrants","metadata":{"title":"List role grants","sidebarTitle":"List role grants","description":"List role grants held by API keys, External Apps and agents. Requires permissions `grants:read`, `policies:read` and `audit:read`; each grant is decided at its own scope."},"content":"Returns the grants held by API keys, External Apps and agents that you may see, and people's grants when you pass `includePersonGrants=true` (or `actorKind=person` for people alone): `grants:read` at the grant's scope, a role that is not a compatibility role, and, for an agent's grant, `agents:read` at the agent's home and in your credential's scopes. People's grants are returned by the person's id; no grant says who gave it or why, or carries a name. A page may be short or empty while `meta.hasMore` is `true`; follow `meta.nextCursor`. To give or revoke a role, call [giveRole](/forge/reference/http-api/governance/giveRole) or [revokeRole](/forge/reference/http-api/governance/revokeRole), which need `grants:manage`. See [Roles and grants](/forge/reference/http-api/governance#roles-and-grants)."},"method":"get","type":"path","servers":["f5796cee-a3a5-412c-be42-6a82a3536598"],"path":"/api/v3/governance-grants","baseUrlOptions":["https://api.forge.gloo.com"],"title":"List role grants held by API keys, External Apps and agents","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated","disableProxy":true},"dependencies":{"parameters":{"d581a474-3f57-4773-b515-3b23a5ad71cd":{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"isRequired":false,"description":"The previous page's `meta.nextCursor`; any other value is `400`.","uniqueKey":"","typeLabel":"string"},"description":"The previous page's `meta.nextCursor`; any other value is `400`."},"c66c152e-2b18-413a-8f15-093d9233299e":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":50,"isRequired":false,"description":"Grants read per page, 1 to 50 (default 50); a larger value is `400` `too_big`.","uniqueKey":"","typeLabel":"integer"},"description":"Grants read per page, 1 to 50 (default 50); a larger value is `400` `too_big`."},"da4859ed-9af2-4027-95e2-1d8a743ff9b0":{"name":"actorKind","in":"query","required":false,"schema":{"type":"string","enum":["api_key","external_app","agent","person"],"isRequired":false,"description":"Only grants held by this kind of actor. `person` lists people's grants alone.","uniqueKey":"","typeLabel":"enum\u003cstring>"},"description":"Only grants held by this kind of actor. `person` lists people's grants alone."},"b97a48ce-85fa-4c19-ae6a-cec7e0a7bc94":{"name":"includePersonGrants","in":"query","required":false,"schema":{"type":"string","enum":["true"],"isRequired":false,"description":"`true` also returns people's grants. Without it (or `actorKind=person`) the page holds no person grant, as before.","uniqueKey":"","typeLabel":"enum\u003cstring>"},"description":"`true` also returns people's grants. Without it (or `actorKind=person`) the page holds no person grant, as before."}},"responses":{"b9e7e5cf-1f9c-4e4f-a584-6610fb0d9c88":{"description":"One page of role grants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"isRequired":true,"uniqueKey":"data.items.[INDEX].id","typeLabel":"string"},"actorKind":{"type":"string","enum":["api_key","external_app","agent","person"],"isRequired":true,"uniqueKey":"data.items.[INDEX].actorKind","typeLabel":"enum\u003cstring>"},"actorId":{"type":"string","isRequired":true,"uniqueKey":"data.items.[INDEX].actorId","typeLabel":"string"},"roleKey":{"type":"string","minLength":1,"isRequired":true,"uniqueKey":"data.items.[INDEX].roleKey","typeLabel":"string"},"scope":{"oneOf":[{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","const":"platform","isRequired":true,"uniqueKey":"data.items.[INDEX].scope.oneOf.0.kind","typeLabel":"string"}},"additionalProperties":false,"isRequired":true,"uniqueKey":"data.items.[INDEX].scope.oneOf.0","typeLabel":"object"},{"type":"object","required":["kind","orgUnitId"],"properties":{"kind":{"type":"string","const":"org_unit","isRequired":true,"uniqueKey":"data.items.[INDEX].scope.oneOf.1.kind","typeLabel":"string"},"orgUnitId":{"type":"string","minLength":1,"isRequired":true,"uniqueKey":"data.items.[INDEX].scope.oneOf.1.orgUnitId","typeLabel":"string"}},"additionalProperties":false,"isRequired":true,"uniqueKey":"data.items.[INDEX].scope.oneOf.1","typeLabel":"object"}],"isRequired":true,"uniqueKey":"data.items.[INDEX].scope","typeLabel":"object"},"enabled":{"type":"boolean","isRequired":true,"uniqueKey":"data.items.[INDEX].enabled","typeLabel":"boolean"},"grantedAt":{"type":"number","isRequired":true,"uniqueKey":"data.items.[INDEX].grantedAt","typeLabel":"number"},"expiresAt":{"oneOf":[{"type":"number","isRequired":true,"uniqueKey":"data.items.[INDEX].expiresAt.oneOf.0","typeLabel":"number"},{"type":"null","isRequired":true,"uniqueKey":"data.items.[INDEX].expiresAt.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.items.[INDEX].expiresAt","typeLabel":"number | 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.","uniqueKey":"data.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"data","typeLabel":"object[]"},"meta":{"oneOf":[{"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.","required":["hasMore","nextCursor","partial","requestId"],"properties":{"requestId":{"type":"string","isRequired":true,"uniqueKey":"meta.oneOf.0.requestId","typeLabel":"string"},"hasMore":{"type":"boolean","const":false,"isRequired":true,"uniqueKey":"meta.oneOf.0.hasMore","typeLabel":"boolean"},"nextCursor":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"meta.oneOf.0.nextCursor.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"meta.oneOf.0.nextCursor.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"meta.oneOf.0.nextCursor","typeLabel":"string | null"},"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.","isRequired":true,"uniqueKey":"meta.oneOf.0.partial","typeLabel":"boolean"},"asOf":{"oneOf":[{"type":"integer","uniqueKey":"meta.oneOf.0.asOf.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"meta.oneOf.0.asOf.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.oneOf.0.asOf","typeLabel":"integer | 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.","uniqueKey":"meta.oneOf.0.truncated","typeLabel":"boolean"}},"additionalProperties":true,"isRequired":true,"uniqueKey":"meta.oneOf.0","typeLabel":"object"},{"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.","required":["hasMore","nextCursor","partial","requestId"],"properties":{"requestId":{"type":"string","isRequired":true,"uniqueKey":"meta.oneOf.1.requestId","typeLabel":"string"},"hasMore":{"type":"boolean","isRequired":true,"uniqueKey":"meta.oneOf.1.hasMore","typeLabel":"boolean"},"nextCursor":{"type":"string","isRequired":true,"uniqueKey":"meta.oneOf.1.nextCursor","typeLabel":"string"},"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.","isRequired":true,"uniqueKey":"meta.oneOf.1.partial","typeLabel":"boolean"},"asOf":{"oneOf":[{"type":"integer","uniqueKey":"meta.oneOf.1.asOf.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"meta.oneOf.1.asOf.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.oneOf.1.asOf","typeLabel":"integer | 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.","uniqueKey":"meta.oneOf.1.truncated","typeLabel":"boolean"}},"additionalProperties":true,"isRequired":true,"uniqueKey":"meta.oneOf.1","typeLabel":"object"}],"isRequired":true,"uniqueKey":"meta","typeLabel":"object"}},"required":["data","meta"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"data":[{"id":"\u003cstring>","actorKind":"api_key","actorId":"\u003cstring>","roleKey":"\u003cstring>","scope":{"kind":"platform"},"enabled":true,"grantedAt":123,"expiresAt":123}],"meta":{"requestId":"\u003cstring>","hasMore":false,"nextCursor":"\u003cstring>","partial":true,"asOf":123,"truncated":true}}}},"exampleType":"generated"}},"headers":{"X-Request-Id":{"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"}},"RateLimit-Limit":{"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}},"RateLimit-Remaining":{"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}},"RateLimit-Reset":{"description":"Seconds until the bucket this request spent from is full again.","schema":{"type":"integer","minimum":0}}},"exampleType":"generated"},"e663c337-0d80-4445-971d-cc6432522746":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["bad_request","allowed_scopes_removed"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"docUrl":{"type":"string","format":"uri","uniqueKey":"error.docUrl","typeLabel":"string\u003curi>"},"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"],"uniqueKey":"error.reason","typeLabel":"enum\u003cstring>"},"requiredPermission":{"oneOf":[{"type":"string","uniqueKey":"error.requiredPermission.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"error.requiredPermission.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.requiredPermission","typeLabel":"string | null"},"personRequired":{"type":"boolean","uniqueKey":"error.personRequired","typeLabel":"boolean"},"decisionId":{"type":"string","uniqueKey":"error.decisionId","typeLabel":"string"},"capHeadroom":{"type":"object","properties":{"remainingCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.remainingCents","typeLabel":"number"},"capCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.capCents","typeLabel":"number"},"consumedCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.consumedCents","typeLabel":"number"},"estimateCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.estimateCents","typeLabel":"number"}},"required":["remainingCents","capCents","consumedCents","estimateCents"],"additionalProperties":false,"uniqueKey":"error.capHeadroom","typeLabel":"object"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].path","typeLabel":"string"},"param":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].param","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].message","typeLabel":"string"},"code":{"type":"string","enum":["required","invalid_type","invalid_value","invalid_format","too_small","too_big","unknown_field","invalid_json","invalid"],"isRequired":true,"uniqueKey":"error.details.items.[INDEX].code","typeLabel":"enum\u003cstring>"}},"required":["path","param","message","code"],"additionalProperties":false,"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"maxItems":50,"uniqueKey":"error.details","typeLabel":"object[]"}},"additionalProperties":true,"isRequired":true,"uniqueKey":"error","typeLabel":"object"},"meta":{"type":"object","properties":{"requestId":{"type":"string","isRequired":true,"uniqueKey":"meta.requestId","typeLabel":"string"},"hasMore":{"type":"boolean","uniqueKey":"meta.hasMore","typeLabel":"boolean"},"nextCursor":{"oneOf":[{"type":"string","uniqueKey":"meta.nextCursor.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"meta.nextCursor.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.nextCursor","typeLabel":"string | null"},"asOf":{"oneOf":[{"type":"integer","uniqueKey":"meta.asOf.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"meta.asOf.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.asOf","typeLabel":"integer | null"}},"required":["requestId"],"additionalProperties":true,"isRequired":true,"uniqueKey":"meta","typeLabel":"object"}},"additionalProperties":true,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"bad_request","message":"\u003cstring>","docUrl":"\u003cstring>","reason":"requester_unavailable","requiredPermission":"\u003cstring>","personRequired":true,"decisionId":"\u003cstring>","capHeadroom":{"remainingCents":123,"capCents":123,"consumedCents":123,"estimateCents":123},"details":[{"path":"\u003cstring>","param":"\u003cstring>","message":"\u003cstring>","code":"required"}]},"meta":{"requestId":"\u003cstring>","hasMore":true,"nextCursor":"\u003cstring>","asOf":123}}}},"exampleType":"generated"}},"headers":{"X-Request-Id":{"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"}},"RateLimit-Limit":{"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}},"RateLimit-Remaining":{"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}},"RateLimit-Reset":{"description":"Seconds until the bucket this request spent from is full again.","schema":{"type":"integer","minimum":0}}},"exampleType":"generated"},"6e9c2acc-c1d8-42cf-ac87-36bd9cc7768c":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthorized"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"docUrl":{"type":"string","format":"uri","uniqueKey":"error.docUrl","typeLabel":"string\u003curi>"},"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"],"uniqueKey":"error.reason","typeLabel":"enum\u003cstring>"},"requiredPermission":{"oneOf":[{"type":"string","uniqueKey":"error.requiredPermission.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"error.requiredPermission.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.requiredPermission","typeLabel":"string | null"},"personRequired":{"type":"boolean","uniqueKey":"error.personRequired","typeLabel":"boolean"},"decisionId":{"type":"string","uniqueKey":"error.decisionId","typeLabel":"string"},"capHeadroom":{"type":"object","properties":{"remainingCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.remainingCents","typeLabel":"number"},"capCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.capCents","typeLabel":"number"},"consumedCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.consumedCents","typeLabel":"number"},"estimateCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.estimateCents","typeLabel":"number"}},"required":["remainingCents","capCents","consumedCents","estimateCents"],"additionalProperties":false,"uniqueKey":"error.capHeadroom","typeLabel":"object"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].path","typeLabel":"string"},"param":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].param","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].message","typeLabel":"string"},"code":{"type":"string","enum":["required","invalid_type","invalid_value","invalid_format","too_small","too_big","unknown_field","invalid_json","invalid"],"isRequired":true,"uniqueKey":"error.details.items.[INDEX].code","typeLabel":"enum\u003cstring>"}},"required":["path","param","message","code"],"additionalProperties":false,"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"maxItems":50,"uniqueKey":"error.details","typeLabel":"object[]"}},"additionalProperties":true,"isRequired":true,"uniqueKey":"error","typeLabel":"object"},"meta":{"type":"object","properties":{"requestId":{"type":"string","isRequired":true,"uniqueKey":"meta.requestId","typeLabel":"string"},"hasMore":{"type":"boolean","uniqueKey":"meta.hasMore","typeLabel":"boolean"},"nextCursor":{"oneOf":[{"type":"string","uniqueKey":"meta.nextCursor.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"meta.nextCursor.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.nextCursor","typeLabel":"string | null"},"asOf":{"oneOf":[{"type":"integer","uniqueKey":"meta.asOf.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"meta.asOf.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.asOf","typeLabel":"integer | null"}},"required":["requestId"],"additionalProperties":true,"isRequired":true,"uniqueKey":"meta","typeLabel":"object"}},"additionalProperties":true,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthorized","message":"\u003cstring>","docUrl":"\u003cstring>","reason":"requester_unavailable","requiredPermission":"\u003cstring>","personRequired":true,"decisionId":"\u003cstring>","capHeadroom":{"remainingCents":123,"capCents":123,"consumedCents":123,"estimateCents":123},"details":[{"path":"\u003cstring>","param":"\u003cstring>","message":"\u003cstring>","code":"required"}]},"meta":{"requestId":"\u003cstring>","hasMore":true,"nextCursor":"\u003cstring>","asOf":123}}}},"exampleType":"generated"}},"headers":{"X-Request-Id":{"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"}},"RateLimit-Limit":{"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}},"RateLimit-Remaining":{"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}},"RateLimit-Reset":{"description":"Seconds until the bucket this request spent from is full again.","schema":{"type":"integer","minimum":0}}},"exampleType":"generated"},"35f83e92-7f42-4b34-8037-24c94be5626c":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["forbidden","permission_denied","operator_stopped"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"docUrl":{"type":"string","format":"uri","uniqueKey":"error.docUrl","typeLabel":"string\u003curi>"},"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"],"uniqueKey":"error.reason","typeLabel":"enum\u003cstring>"},"requiredPermission":{"oneOf":[{"type":"string","uniqueKey":"error.requiredPermission.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"error.requiredPermission.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.requiredPermission","typeLabel":"string | null"},"personRequired":{"type":"boolean","uniqueKey":"error.personRequired","typeLabel":"boolean"},"decisionId":{"type":"string","uniqueKey":"error.decisionId","typeLabel":"string"},"capHeadroom":{"type":"object","properties":{"remainingCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.remainingCents","typeLabel":"number"},"capCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.capCents","typeLabel":"number"},"consumedCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.consumedCents","typeLabel":"number"},"estimateCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.estimateCents","typeLabel":"number"}},"required":["remainingCents","capCents","consumedCents","estimateCents"],"additionalProperties":false,"uniqueKey":"error.capHeadroom","typeLabel":"object"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].path","typeLabel":"string"},"param":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].param","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].message","typeLabel":"string"},"code":{"type":"string","enum":["required","invalid_type","invalid_value","invalid_format","too_small","too_big","unknown_field","invalid_json","invalid"],"isRequired":true,"uniqueKey":"error.details.items.[INDEX].code","typeLabel":"enum\u003cstring>"}},"required":["path","param","message","code"],"additionalProperties":false,"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"maxItems":50,"uniqueKey":"error.details","typeLabel":"object[]"}},"additionalProperties":true,"isRequired":true,"uniqueKey":"error","typeLabel":"object"},"meta":{"type":"object","properties":{"requestId":{"type":"string","isRequired":true,"uniqueKey":"meta.requestId","typeLabel":"string"},"hasMore":{"type":"boolean","uniqueKey":"meta.hasMore","typeLabel":"boolean"},"nextCursor":{"oneOf":[{"type":"string","uniqueKey":"meta.nextCursor.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"meta.nextCursor.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.nextCursor","typeLabel":"string | null"},"asOf":{"oneOf":[{"type":"integer","uniqueKey":"meta.asOf.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"meta.asOf.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.asOf","typeLabel":"integer | null"}},"required":["requestId"],"additionalProperties":true,"isRequired":true,"uniqueKey":"meta","typeLabel":"object"}},"additionalProperties":true,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"forbidden","message":"\u003cstring>","docUrl":"\u003cstring>","reason":"requester_unavailable","requiredPermission":"\u003cstring>","personRequired":true,"decisionId":"\u003cstring>","capHeadroom":{"remainingCents":123,"capCents":123,"consumedCents":123,"estimateCents":123},"details":[{"path":"\u003cstring>","param":"\u003cstring>","message":"\u003cstring>","code":"required"}]},"meta":{"requestId":"\u003cstring>","hasMore":true,"nextCursor":"\u003cstring>","asOf":123}}}},"exampleType":"generated"}},"headers":{"X-Request-Id":{"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"}},"RateLimit-Limit":{"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}},"RateLimit-Remaining":{"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}},"RateLimit-Reset":{"description":"Seconds until the bucket this request spent from is full again.","schema":{"type":"integer","minimum":0}}},"exampleType":"generated"},"49d61ecf-8995-47d2-aa95-df89ddf6ff01":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["resource_missing"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"docUrl":{"type":"string","format":"uri","uniqueKey":"error.docUrl","typeLabel":"string\u003curi>"},"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"],"uniqueKey":"error.reason","typeLabel":"enum\u003cstring>"},"requiredPermission":{"oneOf":[{"type":"string","uniqueKey":"error.requiredPermission.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"error.requiredPermission.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.requiredPermission","typeLabel":"string | null"},"personRequired":{"type":"boolean","uniqueKey":"error.personRequired","typeLabel":"boolean"},"decisionId":{"type":"string","uniqueKey":"error.decisionId","typeLabel":"string"},"capHeadroom":{"type":"object","properties":{"remainingCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.remainingCents","typeLabel":"number"},"capCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.capCents","typeLabel":"number"},"consumedCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.consumedCents","typeLabel":"number"},"estimateCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.estimateCents","typeLabel":"number"}},"required":["remainingCents","capCents","consumedCents","estimateCents"],"additionalProperties":false,"uniqueKey":"error.capHeadroom","typeLabel":"object"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].path","typeLabel":"string"},"param":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].param","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].message","typeLabel":"string"},"code":{"type":"string","enum":["required","invalid_type","invalid_value","invalid_format","too_small","too_big","unknown_field","invalid_json","invalid"],"isRequired":true,"uniqueKey":"error.details.items.[INDEX].code","typeLabel":"enum\u003cstring>"}},"required":["path","param","message","code"],"additionalProperties":false,"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"maxItems":50,"uniqueKey":"error.details","typeLabel":"object[]"}},"additionalProperties":true,"isRequired":true,"uniqueKey":"error","typeLabel":"object"},"meta":{"type":"object","properties":{"requestId":{"type":"string","isRequired":true,"uniqueKey":"meta.requestId","typeLabel":"string"},"hasMore":{"type":"boolean","uniqueKey":"meta.hasMore","typeLabel":"boolean"},"nextCursor":{"oneOf":[{"type":"string","uniqueKey":"meta.nextCursor.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"meta.nextCursor.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.nextCursor","typeLabel":"string | null"},"asOf":{"oneOf":[{"type":"integer","uniqueKey":"meta.asOf.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"meta.asOf.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.asOf","typeLabel":"integer | null"}},"required":["requestId"],"additionalProperties":true,"isRequired":true,"uniqueKey":"meta","typeLabel":"object"}},"additionalProperties":true,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"resource_missing","message":"\u003cstring>","docUrl":"\u003cstring>","reason":"requester_unavailable","requiredPermission":"\u003cstring>","personRequired":true,"decisionId":"\u003cstring>","capHeadroom":{"remainingCents":123,"capCents":123,"consumedCents":123,"estimateCents":123},"details":[{"path":"\u003cstring>","param":"\u003cstring>","message":"\u003cstring>","code":"required"}]},"meta":{"requestId":"\u003cstring>","hasMore":true,"nextCursor":"\u003cstring>","asOf":123}}}},"exampleType":"generated"}},"headers":{"X-Request-Id":{"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"}},"RateLimit-Limit":{"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}},"RateLimit-Remaining":{"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}},"RateLimit-Reset":{"description":"Seconds until the bucket this request spent from is full again.","schema":{"type":"integer","minimum":0}}},"exampleType":"generated"},"bc2ba6b6-d207-42f4-939a-6ee28991cc1c":{"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":{"description":"Seconds to wait before sending the request again. Sent on a 429 and on a transient 503.","schema":{"type":"integer","minimum":1}},"RateLimit-Limit":{"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}},"RateLimit-Remaining":{"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}},"RateLimit-Reset":{"description":"Seconds until the bucket this request spent from is full again.","schema":{"type":"integer","minimum":0}},"X-Request-Id":{"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"}}},"content":{"application/json":{"schema":{"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"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"docUrl":{"type":"string","format":"uri","uniqueKey":"error.docUrl","typeLabel":"string\u003curi>"},"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"],"uniqueKey":"error.reason","typeLabel":"enum\u003cstring>"},"requiredPermission":{"oneOf":[{"type":"string","uniqueKey":"error.requiredPermission.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"error.requiredPermission.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.requiredPermission","typeLabel":"string | null"},"personRequired":{"type":"boolean","uniqueKey":"error.personRequired","typeLabel":"boolean"},"decisionId":{"type":"string","uniqueKey":"error.decisionId","typeLabel":"string"},"capHeadroom":{"type":"object","properties":{"remainingCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.remainingCents","typeLabel":"number"},"capCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.capCents","typeLabel":"number"},"consumedCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.consumedCents","typeLabel":"number"},"estimateCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.estimateCents","typeLabel":"number"}},"required":["remainingCents","capCents","consumedCents","estimateCents"],"additionalProperties":false,"uniqueKey":"error.capHeadroom","typeLabel":"object"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].path","typeLabel":"string"},"param":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].param","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].message","typeLabel":"string"},"code":{"type":"string","enum":["required","invalid_type","invalid_value","invalid_format","too_small","too_big","unknown_field","invalid_json","invalid"],"isRequired":true,"uniqueKey":"error.details.items.[INDEX].code","typeLabel":"enum\u003cstring>"}},"required":["path","param","message","code"],"additionalProperties":false,"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"maxItems":50,"uniqueKey":"error.details","typeLabel":"object[]"}},"required":["code","message"],"additionalProperties":true,"isRequired":true,"uniqueKey":"error","typeLabel":"object"},"meta":{"type":"object","properties":{"requestId":{"type":"string","isRequired":true,"uniqueKey":"meta.requestId","typeLabel":"string"},"hasMore":{"type":"boolean","uniqueKey":"meta.hasMore","typeLabel":"boolean"},"nextCursor":{"oneOf":[{"type":"string","uniqueKey":"meta.nextCursor.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"meta.nextCursor.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.nextCursor","typeLabel":"string | null"},"asOf":{"oneOf":[{"type":"integer","uniqueKey":"meta.asOf.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"meta.asOf.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.asOf","typeLabel":"integer | null"}},"required":["requestId"],"additionalProperties":true,"isRequired":true,"uniqueKey":"meta","typeLabel":"object"}},"required":["error","meta"],"additionalProperties":true,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthorized","message":"\u003cstring>","docUrl":"\u003cstring>","reason":"requester_unavailable","requiredPermission":"\u003cstring>","personRequired":true,"decisionId":"\u003cstring>","capHeadroom":{"remainingCents":123,"capCents":123,"consumedCents":123,"estimateCents":123},"details":[{"path":"\u003cstring>","param":"\u003cstring>","message":"\u003cstring>","code":"required"}]},"meta":{"requestId":"\u003cstring>","hasMore":true,"nextCursor":"\u003cstring>","asOf":123}}}},"exampleType":"generated"}},"exampleType":"generated"},"6c39b8b5-b430-45a0-a220-c64c271ac01c":{"description":"Unexpected error","content":{"application/json":{"schema":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["internal_error"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"docUrl":{"type":"string","format":"uri","uniqueKey":"error.docUrl","typeLabel":"string\u003curi>"},"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"],"uniqueKey":"error.reason","typeLabel":"enum\u003cstring>"},"requiredPermission":{"oneOf":[{"type":"string","uniqueKey":"error.requiredPermission.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"error.requiredPermission.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.requiredPermission","typeLabel":"string | null"},"personRequired":{"type":"boolean","uniqueKey":"error.personRequired","typeLabel":"boolean"},"decisionId":{"type":"string","uniqueKey":"error.decisionId","typeLabel":"string"},"capHeadroom":{"type":"object","properties":{"remainingCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.remainingCents","typeLabel":"number"},"capCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.capCents","typeLabel":"number"},"consumedCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.consumedCents","typeLabel":"number"},"estimateCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.estimateCents","typeLabel":"number"}},"required":["remainingCents","capCents","consumedCents","estimateCents"],"additionalProperties":false,"uniqueKey":"error.capHeadroom","typeLabel":"object"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].path","typeLabel":"string"},"param":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].param","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].message","typeLabel":"string"},"code":{"type":"string","enum":["required","invalid_type","invalid_value","invalid_format","too_small","too_big","unknown_field","invalid_json","invalid"],"isRequired":true,"uniqueKey":"error.details.items.[INDEX].code","typeLabel":"enum\u003cstring>"}},"required":["path","param","message","code"],"additionalProperties":false,"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"maxItems":50,"uniqueKey":"error.details","typeLabel":"object[]"}},"additionalProperties":true,"isRequired":true,"uniqueKey":"error","typeLabel":"object"},"meta":{"type":"object","properties":{"requestId":{"type":"string","isRequired":true,"uniqueKey":"meta.requestId","typeLabel":"string"},"hasMore":{"type":"boolean","uniqueKey":"meta.hasMore","typeLabel":"boolean"},"nextCursor":{"oneOf":[{"type":"string","uniqueKey":"meta.nextCursor.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"meta.nextCursor.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.nextCursor","typeLabel":"string | null"},"asOf":{"oneOf":[{"type":"integer","uniqueKey":"meta.asOf.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"meta.asOf.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.asOf","typeLabel":"integer | null"}},"required":["requestId"],"additionalProperties":true,"isRequired":true,"uniqueKey":"meta","typeLabel":"object"}},"additionalProperties":true,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"internal_error","message":"\u003cstring>","docUrl":"\u003cstring>","reason":"requester_unavailable","requiredPermission":"\u003cstring>","personRequired":true,"decisionId":"\u003cstring>","capHeadroom":{"remainingCents":123,"capCents":123,"consumedCents":123,"estimateCents":123},"details":[{"path":"\u003cstring>","param":"\u003cstring>","message":"\u003cstring>","code":"required"}]},"meta":{"requestId":"\u003cstring>","hasMore":true,"nextCursor":"\u003cstring>","asOf":123}}}},"exampleType":"generated"}},"headers":{"X-Request-Id":{"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"}},"RateLimit-Limit":{"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}},"RateLimit-Remaining":{"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}},"RateLimit-Reset":{"description":"Seconds until the bucket this request spent from is full again.","schema":{"type":"integer","minimum":0}}},"exampleType":"generated"},"44c4045d-63a7-4baa-bd65-d28b78c5989a":{"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":{"description":"Seconds to wait before sending the request again. Sent on a 429 and on a transient 503.","schema":{"type":"integer","minimum":1}},"RateLimit-Limit":{"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}},"RateLimit-Remaining":{"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}},"RateLimit-Reset":{"description":"Seconds until the bucket this request spent from is full again.","schema":{"type":"integer","minimum":0}},"X-Request-Id":{"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"}}},"content":{"application/json":{"schema":{"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"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"docUrl":{"type":"string","format":"uri","uniqueKey":"error.docUrl","typeLabel":"string\u003curi>"},"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"],"uniqueKey":"error.reason","typeLabel":"enum\u003cstring>"},"requiredPermission":{"oneOf":[{"type":"string","uniqueKey":"error.requiredPermission.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"error.requiredPermission.oneOf.1","typeLabel":"null"}],"uniqueKey":"error.requiredPermission","typeLabel":"string | null"},"personRequired":{"type":"boolean","uniqueKey":"error.personRequired","typeLabel":"boolean"},"decisionId":{"type":"string","uniqueKey":"error.decisionId","typeLabel":"string"},"capHeadroom":{"type":"object","properties":{"remainingCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.remainingCents","typeLabel":"number"},"capCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.capCents","typeLabel":"number"},"consumedCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.consumedCents","typeLabel":"number"},"estimateCents":{"type":"number","isRequired":true,"uniqueKey":"error.capHeadroom.estimateCents","typeLabel":"number"}},"required":["remainingCents","capCents","consumedCents","estimateCents"],"additionalProperties":false,"uniqueKey":"error.capHeadroom","typeLabel":"object"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].path","typeLabel":"string"},"param":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].param","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.details.items.[INDEX].message","typeLabel":"string"},"code":{"type":"string","enum":["required","invalid_type","invalid_value","invalid_format","too_small","too_big","unknown_field","invalid_json","invalid"],"isRequired":true,"uniqueKey":"error.details.items.[INDEX].code","typeLabel":"enum\u003cstring>"}},"required":["path","param","message","code"],"additionalProperties":false,"uniqueKey":"error.details.items.[INDEX]","typeLabel":"object"},"maxItems":50,"uniqueKey":"error.details","typeLabel":"object[]"}},"required":["code","message"],"additionalProperties":true,"isRequired":true,"uniqueKey":"error","typeLabel":"object"},"meta":{"type":"object","properties":{"requestId":{"type":"string","isRequired":true,"uniqueKey":"meta.requestId","typeLabel":"string"},"hasMore":{"type":"boolean","uniqueKey":"meta.hasMore","typeLabel":"boolean"},"nextCursor":{"oneOf":[{"type":"string","uniqueKey":"meta.nextCursor.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"meta.nextCursor.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.nextCursor","typeLabel":"string | null"},"asOf":{"oneOf":[{"type":"integer","uniqueKey":"meta.asOf.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"meta.asOf.oneOf.1","typeLabel":"null"}],"uniqueKey":"meta.asOf","typeLabel":"integer | null"}},"required":["requestId"],"additionalProperties":true,"isRequired":true,"uniqueKey":"meta","typeLabel":"object"}},"required":["error","meta"],"additionalProperties":true,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthorized","message":"\u003cstring>","docUrl":"\u003cstring>","reason":"requester_unavailable","requiredPermission":"\u003cstring>","personRequired":true,"decisionId":"\u003cstring>","capHeadroom":{"remainingCents":123,"capCents":123,"consumedCents":123,"estimateCents":123},"details":[{"path":"\u003cstring>","param":"\u003cstring>","message":"\u003cstring>","code":"required"}]},"meta":{"requestId":"\u003cstring>","hasMore":true,"nextCursor":"\u003cstring>","asOf":123}}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"7a214af9-78dd-49f6-9f9d-6fe40b92a737":{"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 \u003cjwt>`. An app's static companion key also authenticates as the app, but is deprecated and is not protected by `Idempotency-Key`.","scopes":[],"schemeName":"BearerAuth"}},"6846a0a1-8b63-4ad9-9237-a7081efeacaa":{"PlatformApiKey":{"type":"http","scheme":"bearer","description":"A platform API key, created in the Console under Developers. Pass as `Authorization: Bearer \u003ckey>`. It acts as itself, under its role grants narrowed by its scopes.","scopes":[],"schemeName":"PlatformApiKey"}},"2a049d91-d2e7-4375-8818-5088c21b9f01":{"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 \u003ckey>`. It acts for that person, under their role grants narrowed by its scopes; an operation that acts for a person admits only this kind.","scopes":[],"schemeName":"PersonalKey"}}},"servers":{"f5796cee-a3a5-412c-be42-6a82a3536598":{"url":"https://api.forge.gloo.com","description":"Production"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"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 \u003cjwt>`. An app's static companion key also authenticates as the app, but is deprecated and is not protected by `Idempotency-Key`.","scopes":[],"schemeName":"BearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"An External App: the JWT it obtains from `POST /oauth/token` with OAuth2 client_credentials. Pass as `Authorization: Bearer \u003cjwt>`. An app's static companion key also authenticates as the app, but is deprecated and is not protected by `Idempotency-Key`.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"BearerAuth","name":"Authorization"}],"title":"BearerAuth"},{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"A platform API key, created in the Console under Developers. Pass as `Authorization: Bearer \u003ckey>`. It acts as itself, under its role grants narrowed by its scopes.","scopes":[],"schemeName":"PlatformApiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"A platform API key, created in the Console under Developers. Pass as `Authorization: Bearer \u003ckey>`. It acts as itself, under its role grants narrowed by its scopes.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"PlatformApiKey","name":"Authorization"}],"title":"PlatformApiKey"},{"schemes":[{"scheme":{"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 \u003ckey>`. It acts for that person, under their role grants narrowed by its scopes; an operation that acts for a person admits only this kind.","scopes":[],"schemeName":"PersonalKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"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 \u003ckey>`. It acts for that person, under their role grants narrowed by its scopes; an operation that acts for a person admits only this kind.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"PersonalKey","name":"Authorization"}],"title":"PersonalKey"}]},"originalFileLocation":"forge/reference/openapi-v3.json"},"subdomain":"gloo-b243725a","siteName":"Gloo","title":"List role grants - Gloo","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-09T03:20:36.249Z","originalFileLocation":"forge/reference/http-api/governance/listgrants.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"List role grants held by API keys, External Apps and agents. Requires permissions grants:read, policies:read and audit:read; each grant is decided at its own scope.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Gloo\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003cmeta data-mint-head name=\"robots\" content=\"noindex\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/gloo-b243725a/E9tcQ27KykgznjKS/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/gloo-b243725a/E9tcQ27KykgznjKS/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/gloo-b243725a/E9tcQ27KykgznjKS/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/gloo-b243725a/E9tcQ27KykgznjKS/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/gloo-b243725a/E9tcQ27KykgznjKS/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/gloo-b243725a/E9tcQ27KykgznjKS/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/gloo-b243725a/E9tcQ27KykgznjKS/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/gloo-b243725a/E9tcQ27KykgznjKS/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/gloo-b243725a/E9tcQ27KykgznjKS/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"List role grants - Gloo\">\u003cmeta data-mint-head property=\"og:description\" content=\"List role grants held by API keys, External Apps and agents. Requires permissions grants:read, policies:read and audit:read; each grant is decided at its own scope.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Gloo\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.gloo.com/forge/reference/http-api/governance/listgrants\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://gloo-b243725a.mintlify.site/_mintlify/api/og/v2?division=Governance\u0026amp;title=List+role+grants\u0026amp;description=List+role+grants+held+by+API+keys%2C+External+Apps+and+agents.+Requires+permissions+%60grants%3Aread%60%2C+%60policies%3Aread%60+and+%60audit%3Aread%60%3B+each+grant+is+decided+at+its+\u0026amp;theme=497206027fd8620dc19fa877\u0026amp;signature=24e30dacdc228bb275459e74b75fff035f01b11624d7c3fa8566f386cbe1d61e\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"List role grants - Gloo\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"List role grants held by API keys, External Apps and agents. Requires permissions grants:read, policies:read and audit:read; each grant is decided at its own scope.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://gloo-b243725a.mintlify.site/_mintlify/api/og/v2?division=Governance\u0026amp;title=List+role+grants\u0026amp;description=List+role+grants+held+by+API+keys%2C+External+Apps+and+agents.+Requires+permissions+%60grants%3Aread%60%2C+%60policies%3Aread%60+and+%60audit%3Aread%60%3B+each+grant+is+decided+at+its+\u0026amp;theme=497206027fd8620dc19fa877\u0026amp;signature=24e30dacdc228bb275459e74b75fff035f01b11624d7c3fa8566f386cbe1d61e\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/gloo-b243725a/E9tcQ27KykgznjKS/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Gloo\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#00C980\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.gloo.com/forge/reference/http-api/governance/listgrants\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/forge/reference/http-api/governance/listgrants.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.gloo.com/#organization\",\"name\":\"Gloo\",\"url\":\"https://docs.gloo.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/gloo-b243725a/6UEVtMrmK4zuVXLK/logo/logo-gloo-studio_dark.png?fit=max\u0026auto=format\u0026n=6UEVtMrmK4zuVXLK\u0026q=85\u0026s=e55c999bcee79d2a8c71201276d7ac04\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.gloo.com#website\",\"name\":\"Gloo\",\"url\":\"https://docs.gloo.com\",\"publisher\":{\"@id\":\"https://docs.gloo.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.gloo.com/forge/reference/http-api/governance/listgrants#webpage\",\"url\":\"https://docs.gloo.com/forge/reference/http-api/governance/listgrants\",\"name\":\"List role grants\",\"description\":\"List role grants held by API keys, External Apps and agents. Requires permissions grants:read, policies:read and audit:read; each grant is decided at its own scope.\",\"dateModified\":\"2026-11-09T03:20:36.249Z\",\"isPartOf\":{\"@id\":\"https://docs.gloo.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.gloo.com/forge/reference/http-api/governance/listgrants#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.gloo.com/forge/reference/http-api/governance/listgrants#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"HTTP API\",\"item\":\"https://docs.gloo.com/forge/reference/http-api\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Governance\",\"item\":\"https://docs.gloo.com/forge/reference/http-api/families/governance\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Governance\",\"item\":\"https://docs.gloo.com/forge/reference/http-api/governance\"},{\"@type\":\"ListItem\",\"position\":4,\"name\":\"List role grants\",\"item\":\"https://docs.gloo.com/forge/reference/http-api/governance/listgrants\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.gloo.com/forge/reference/http-api/governance/listgrants#apireference\",\"headline\":\"List role grants\",\"name\":\"List role grants\",\"description\":\"List role grants held by API keys, External Apps and agents. Requires permissions grants:read, policies:read and audit:read; each grant is decided at its own scope.\",\"url\":\"https://docs.gloo.com/forge/reference/http-api/governance/listgrants\",\"mainEntityOfPage\":{\"@id\":\"https://docs.gloo.com/forge/reference/http-api/governance/listgrants#webpage\"},\"dateModified\":\"2026-11-09T03:20:36.249Z\",\"publisher\":{\"@id\":\"https://docs.gloo.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.gloo.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Gloo\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Gloo\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/forge/reference/http-api/governance/listgrants.md","siteName":"Gloo","nav":{"global":{"anchors":[{"anchor":"Status","icon":"heart-pulse","href":"https://status.ai.gloo.com"}]},"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/getting-started/overview"}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/api-reference/general/overview"}]},{"tab":"Tutorials","pages":[{"title":"Tutorials","href":"/tutorials/overview"}]},{"tab":"Best Practices","pages":[{"title":"Best Practices","href":"/best-practices/overview"}]},{"tab":"Learning Center","pages":[{"title":"Learning Center","href":"/ai-learning-center/gloo-ai-101/ai-overview"}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]},{"tab":"Forge Platform","icon":"layer-group","hidden":true,"pages":[{"title":"Forge Platform","href":"/forge"}]},{"tab":"Forge API","icon":"code","hidden":true,"groups":[{"group":"API guides","icon":"book-open","pages":[{"title":"Forge integration reference","sidebarTitle":"Reference overview","icon":"book-open","description":"Authentication, API conventions, OpenAPI, MCP, client choices, errors, and operation reference.","href":"/forge/reference"},{"title":"Conventions","sidebarTitle":"Conventions","icon":"book-open","description":"The Platform API base URL, response envelopes, operation and path naming, how role grants and scopes decide access, the scope-to-permission catalog, pagination and rate limits.","href":"/forge/reference/conventions"},{"group":"Authentication and permissions","icon":"key","root":{"title":"Permission reference","sidebarTitle":"Permissions","icon":"key","description":"Every Forge permission: its key, what it lets someone do, whether giving it needs an opt-in, and which roles include it. Generated from the permission catalog.","href":"/forge/reference/permissions"},"pages":[{"title":"Credential kinds reference","sidebarTitle":"Credential kinds","icon":"id-card","description":"Which kinds of credential each Forge Platform API operation admits: an External App, a platform API key or a Personal key. Generated from the OpenAPI document.","href":"/forge/reference/credential-kinds"}]},{"title":"Idempotency","sidebarTitle":"Idempotency","icon":"repeat","description":"How the Idempotency-Key header makes mutating /api/v3 and /api/v2 requests safe to retry: key format, scope, replay, the five idempotency error codes, retention and client behavior.","href":"/forge/reference/idempotency"},{"title":"Errors","sidebarTitle":"Errors","icon":"circle-xmark","description":"Platform API error codes: when each fires and how to handle it, plus troubleshooting by symptom for authentication, access, validation, conflicts, unknown writes and holds.","href":"/forge/reference/errors"},{"title":"Forge MCP server","sidebarTitle":"MCP server","icon":"plug","description":"Hosted and stdio MCP connection modes, tool discovery, calls, confirmations, paging, resources, and prompts.","href":"/forge/reference/mcp-server"},{"group":"Procedure SDK","icon":"cube","pages":[{"title":"Procedure SDK for Node","sidebarTitle":"Procedure SDK (Node)","icon":"node-js","iconType":"brands","description":"Current @gloo/procedure-sdk-node exports and procedure-sandbox usage.","href":"/forge/reference/procedure-sdk-node"},{"title":"Procedure SDK for Python","sidebarTitle":"Procedure SDK (Python)","icon":"python","iconType":"brands","description":"Current gloo_procedure_sdk exports and procedure-sandbox usage.","href":"/forge/reference/procedure-sdk-python"}]},{"title":"Inference Carve-Out","sidebarTitle":"Inference carve-out","icon":"brain","description":"Two OpenAI-compatible surfaces. /api/inference/v1/* is the External-App carve-out (JWKS-signed JWT). /api/llm/v1/* is the LLM proxy (virtual-key auth) backed by the routing tier abstraction.","href":"/forge/reference/inference"}]},{"group":"HTTP API","icon":"sitemap","pages":[{"title":"HTTP API reference","sidebarTitle":"HTTP API overview","icon":"sitemap","description":"How the HTTP API reference is organized, what each operation page tells you, and which family holds the operations you need.","href":"/forge/reference/http-api/index"},{"group":"Identity and access","icon":"id-badge","root":{"title":"Identity and access API","sidebarTitle":"Identity and access","icon":"id-badge","description":"HTTP API operations for the calling credential, Personal keys, External Apps and job roles: who you are, what you may do, and the credentials that act.","href":"/forge/reference/http-api/families/identity-and-access"},"pages":[{"group":"Current actor","icon":"id-badge","pages":[{"title":"Discover your current actor","description":"Self-discovery for any Platform API credential — the verified actor, its current narrowed permissions and the advisory prerequisites of each documented operation that requires a permission. Requires no permission.","deprecated":null,"version":null,"sidebarTitle":"Current actor","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/actor","href":"/forge/reference/http-api/actor"},{"title":"List your effective permissions","description":"Self-discovery for any Platform API credential — the permissions this request holds after its scopes narrow them, and the operations they satisfy. Requires no permission.","deprecated":null,"version":null,"sidebarTitle":"My permissions","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/permissions","href":"/forge/reference/http-api/actor/my-permissions"},{"title":"Explain one of your refusals","description":"A Platform API credential explains a 403 it received, by the decisionId the refusal named, without the governance evidence permissions. Requires no permission.","deprecated":null,"version":null,"sidebarTitle":"Explain my refusal","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/denials/{decisionId}","href":"/forge/reference/http-api/actor/my-denials"},{"title":"Get your rate limits","description":"The calling credential's own read, write and expensive rate-limit buckets — capacity, requests left, seconds to full and refill rate. Requires no permission.","deprecated":null,"version":null,"sidebarTitle":"Your rate limits","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/limits","href":"/forge/reference/http-api/me-limits"},{"title":"Look up one of your requests","description":"One request your credential made in the last 30 days, by the request id its response carried — route, status, duration, trace id and, for a refusal, its error code and message. Requires no permission.","deprecated":null,"version":null,"sidebarTitle":"Your requests","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/requests/{requestId}","href":"/forge/reference/http-api/me-request"},{"title":"Count your requests","description":"Your credential's requests over the last 7 days, counted by day, route and status class. Requires no permission.","deprecated":null,"version":null,"sidebarTitle":"Your usage","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/usage","href":"/forge/reference/http-api/me-usage"},{"title":"Request a confirmation","description":"Ask the credential's owner to confirm one exact destructive call before the credential makes it.","deprecated":null,"version":null,"sidebarTitle":"Request a confirmation","openapi":"/forge/reference/openapi-v3.json post /api/v3/me/confirmations","href":"/forge/reference/http-api/actor/request-confirmation"},{"title":"Get a confirmation","description":"Read a confirmation the calling credential asked for, and whether its owner approved it.","deprecated":null,"version":null,"sidebarTitle":"Get a confirmation","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/confirmations/{confirmationId}","href":"/forge/reference/http-api/actor/get-confirmation"},{"title":"Use a confirmation","description":"Spend an approved confirmation, once, for the identical call it confirms.","deprecated":null,"version":null,"sidebarTitle":"Use a confirmation","openapi":"/forge/reference/openapi-v3.json post /api/v3/me/confirmations/{confirmationId}/consume","href":"/forge/reference/http-api/actor/consume-confirmation"}]},{"group":"API keys","icon":"key","root":{"title":"API keys administration","sidebarTitle":"API keys","icon":"key","description":"List every Personal key and host sign-in in the deployment and revoke any of them with a platform API key, or manage your own with your Personal key.","href":"/forge/reference/http-api/api-keys"},"pages":[{"title":"Delete one of the Personal key owner's own revoked keys and disable its role grants","description":"Delete one of the Personal key owner's own revoked keys and disable its role grants. A Personal key acts as its owner, only on its owner's own records; the key's scopes must reach `apikeys:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete one of the Personal key owner's own revoked keys and disable its role grants","openapi":"/forge/reference/openapi-v3.json delete /api/v3/me/api-keys/{keyId}","href":"/forge/reference/http-api/api-keys/admin/own-keys-delete"},{"title":"List a page of every Personal key and host sign-in in the deployment, active then revoked, newest first, without naming its owner","description":"List a page of every Personal key and host sign-in in the deployment, active then revoked, newest first, without naming its owner. Requires permission `apikeys:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of every Personal key and host sign-in in the deployment, active then revoked, newest first, without naming its owner","openapi":"/forge/reference/openapi-v3.json get /api/v3/personal-keys","href":"/forge/reference/http-api/api-keys/admin/personal-keys"},{"title":"List a page of the Personal key owner's own Personal keys and host sign-ins, active then revoked, newest first","description":"List a page of the Personal key owner's own Personal keys and host sign-ins, active then revoked, newest first. A Personal key acts as its owner, only on its owner's own records; the key's scopes must reach `apikeys:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the Personal key owner's own Personal keys and host sign-ins, active then revoked, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/api-keys","href":"/forge/reference/http-api/api-keys/admin/own-keys"},{"title":"Revoke one of the Personal key owner's own keys or host sign-ins","description":"Revoke one of the Personal key owner's own keys or host sign-ins. A Personal key acts as its owner, only on its owner's own records; the key's scopes must reach `apikeys:manage`.","deprecated":null,"version":null,"sidebarTitle":"Revoke one of the Personal key owner's own keys or host sign-ins","openapi":"/forge/reference/openapi-v3.json post /api/v3/me/api-keys/{keyId}/revoke","href":"/forge/reference/http-api/api-keys/admin/own-keys-revoke"},{"title":"Revoke any person's Personal key or host sign-in","description":"Revoke any person's Personal key or host sign-in; its owner is told. Requires permission `apikeys:manage`.","deprecated":null,"version":null,"sidebarTitle":"Revoke any person's Personal key or host sign-in","openapi":"/forge/reference/openapi-v3.json post /api/v3/personal-keys/{keyId}/revoke","href":"/forge/reference/http-api/api-keys/admin/personal-keys-revoke"}]},{"group":"External apps","icon":"plug","root":{"title":"External Apps","sidebarTitle":"External Apps","icon":"window-maximize","description":"OAuth2 client management for integrating systems: explicit ExternalApp responses and one-time secrets that are never stored.","href":"/forge/reference/http-api/externalApps"},"pages":[{"title":"Get your own External Application record","description":"Self-introspection — an External Application reads its own record, including the catalog permissions its role grants hold. Requires no permission, only an External Application credential.","deprecated":null,"version":null,"sidebarTitle":"Get your own record","openapi":"/forge/reference/openapi-v3.json get /api/v3/me","href":"/forge/reference/http-api/externalapps/me"},{"title":"List External Apps","description":"Returns ExternalApp rows — an explicit allowlist, with null for an absent optional value. Requires permission `apps:manage`.","deprecated":null,"version":null,"sidebarTitle":"List External Apps","openapi":"/forge/reference/openapi-v3.json get /api/v3/external-apps","href":"/forge/reference/http-api/externalapps/list"},{"title":"Get an External Application by ID","description":"Returns one ExternalApp plus its computed, read-only allowedScopes. Requires permission `apps:manage`.","deprecated":null,"version":null,"sidebarTitle":"Get an External Application by ID","openapi":"/forge/reference/openapi-v3.json get /api/v3/external-apps/{externalAppId}","href":"/forge/reference/http-api/externalapps/get"},{"title":"Create an External Application","description":"Mints OAuth2 client credentials for a new External App. The client secret is returned once, stored only as a hash, and never cached for Idempotency-Key replay. Requires permission `apps:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create an External Application","openapi":"/forge/reference/openapi-v3.json post /api/v3/external-apps","href":"/forge/reference/http-api/externalapps/create"},{"title":"Update an External Application","description":"Patches the supplied fields and returns the ExternalApp with its computed allowedScopes. Requires permission `apps:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update an External Application","openapi":"/forge/reference/openapi-v3.json patch /api/v3/external-apps/{externalAppId}","href":"/forge/reference/http-api/externalapps/update"},{"title":"Deactivate (soft-delete) an External Application","description":"Marks the App as inactive, revokes its companion key and purges the resources it owns. Requires permission `apps:manage`.","deprecated":null,"version":null,"sidebarTitle":"Deactivate (soft-delete) an External Application","openapi":"/forge/reference/openapi-v3.json delete /api/v3/external-apps/{externalAppId}","href":"/forge/reference/http-api/externalapps/deactivate"},{"title":"Rotate the client_secret for an External Application","description":"Issues a new client secret and invalidates the previous one. The new secret is returned once, stored only as a hash, and never cached for Idempotency-Key replay. Requires permission `apps:manage`.","deprecated":null,"version":null,"sidebarTitle":"Rotate the client_secret for an External Application","openapi":"/forge/reference/openapi-v3.json post /api/v3/external-apps/{externalAppId}/rotate-secret","href":"/forge/reference/http-api/externalapps/rotatesecret"},{"title":"Rotate the callback signing secret for an External Application","description":"Rotate the app-level key that workflow dispatch callbacks are signed with. Distinct from the client secret. Returned once, stored only encrypted, and never cached for Idempotency-Key replay. Requires permission `apps:manage`.","deprecated":null,"version":null,"sidebarTitle":"Rotate the callback signing secret","openapi":"/forge/reference/openapi-v3.json post /api/v3/external-apps/{externalAppId}/rotate-callback-secret","href":"/forge/reference/http-api/externalapps/rotatecallbacksecret"},{"title":"List the agents an External App owns, one page at a time in creation order, leaving its users' Personal Agents out — each agent's id, slug, name, description, status and timestamps","description":"List the agents an External App owns, one page at a time in creation order, leaving its users' Personal Agents out — each agent's id, slug, name, description, status and timestamps. Requires permission `apps:read`.","deprecated":null,"version":null,"sidebarTitle":"List the agents an External App owns, one page at a time in creation order, leaving its users' Personal Agents out — each agent's id, slug, name, description, status and timestamps","openapi":"/forge/reference/openapi-v3.json get /api/v3/external-apps/{externalAppId}/owned-agents","href":"/forge/reference/http-api/external-apps/admin/owned-agents"},{"title":"External App API","sidebarTitle":"External App API","icon":"plug-circle-bolt","description":"The External App API — endpoints called by external apps to manage their own agents and customers and discover available models. Distinct from the management API and the inference carve-out.","href":"/forge/reference/http-api/external"},{"title":"Find or create a personal agent","description":"Idempotently provision a PERSONAL agent for a user. Returns the existing agent if one already exists for the (app, user) pair. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"findOrCreateAgent","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/find-or-create","href":"/forge/reference/http-api/external/findorcreateagent"},{"title":"List available models for an agent","description":"Returns the OpenAI-compatible model list for a specific agent. Resolves by explicit agentId, user JWT, or app default. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"listAvailableModelsForAgent","openapi":"/forge/reference/openapi-v3.json get /api/v3/agent-available-models","href":"/forge/reference/http-api/external/listavailablemodelsforagent"}]},{"group":"Roles and grants","icon":"user-shield","root":{"title":"Roles and grants administration","sidebarTitle":"Role administration","icon":"id-badge","description":"Create, change and delete job roles, and manage the tools and skills each role grants, with a platform API key.","href":"/forge/reference/http-api/grants-roles"},"pages":[{"title":"Grant, deny or revoke tools, skills, tool sets and skill sets on a job role, all or nothing","description":"Grant, deny or revoke tools, skills, tool sets and skill sets on a job role, all or nothing. Requires permission `roles:manage`.","deprecated":null,"version":null,"sidebarTitle":"Grant, deny or revoke tools, skills, tool sets and skill sets on a job role, all or nothing","openapi":"/forge/reference/openapi-v3.json post /api/v3/roles/{roleId}/capabilities/save","href":"/forge/reference/http-api/grants-roles/admin/capabilities-save"},{"title":"Create a job role and answer its id","description":"Create a job role and answer its id. Requires permission `roles:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create a job role and answer its id","openapi":"/forge/reference/openapi-v3.json post /api/v3/roles","href":"/forge/reference/http-api/grants-roles/admin/create"},{"title":"Start drafting a job role's job description, system prompt or responsibilities with AI, and answer the request id its status is read by","description":"Start drafting a job role's job description, system prompt or responsibilities with AI, and answer the request id its status is read by. Requires permission `roles:manage`.","deprecated":null,"version":null,"sidebarTitle":"Start drafting a job role's job description, system prompt or responsibilities with AI, and answer the request id its status is read by","openapi":"/forge/reference/openapi-v3.json post /api/v3/roles/{roleId}/content/generate","href":"/forge/reference/http-api/grants-roles/admin/content-generate"},{"title":"List the tools, skills, tool sets and skill sets a job role grants or denies","description":"List the tools, skills, tool sets and skill sets a job role grants or denies. Requires permission `roles:read`.","deprecated":null,"version":null,"sidebarTitle":"List the tools, skills, tool sets and skill sets a job role grants or denies","openapi":"/forge/reference/openapi-v3.json get /api/v3/roles/{roleId}/capabilities","href":"/forge/reference/http-api/grants-roles/admin/capabilities"},{"title":"Delete a job role that no position holds","description":"Delete a job role that no position holds. Requires permission `roles:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete a job role that no position holds","openapi":"/forge/reference/openapi-v3.json delete /api/v3/roles/{roleId}","href":"/forge/reference/http-api/grants-roles/admin/remove"},{"title":"Change a job role's fields","description":"Change a job role's fields. Requires permission `roles:manage`.","deprecated":null,"version":null,"sidebarTitle":"Change a job role's fields","openapi":"/forge/reference/openapi-v3.json patch /api/v3/roles/{roleId}","href":"/forge/reference/http-api/grants-roles/admin/update"},{"title":"List a page of one holder's role grants the key may read — a person's, an agent's, an API key's or an External App's, each with its role, scope, whether it is enabled, and when it was given and expires","description":"List a page of one holder's role grants the key may read — a person's, an agent's, an API key's or an External App's, each with its role, scope, whether it is enabled, and when it was given and expires. Requires permission `grants:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of one holder's role grants the key may read — a person's, an agent's, an API key's or an External App's, each with its role, scope, whether it is enabled, and when it was given and expires","openapi":"/forge/reference/openapi-v3.json get /api/v3/role-grant-holder","href":"/forge/reference/http-api/grants-roles/admin/grants-holder"},{"title":"Get an AI role content request's status — pending, failed with its reason, or completed with the drafted text. An unknown request id answers null","description":"Get an AI role content request's status — pending, failed with its reason, or completed with the drafted text. An unknown request id answers null. Requires permission `roles:manage`.","deprecated":null,"version":null,"sidebarTitle":"Get an AI role content request's status — pending, failed with its reason, or completed with the drafted text. An unknown request id answers null","openapi":"/forge/reference/openapi-v3.json get /api/v3/role-content-generations/{requestId}","href":"/forge/reference/http-api/grants-roles/admin/content-generation"}]}]},{"group":"Workforce","icon":"users","root":{"title":"Workforce API","sidebarTitle":"Workforce","icon":"users","description":"HTTP API operations for org units, positions, pods, people, workers, identity and the customer directory.","href":"/forge/reference/http-api/families/workforce"},"pages":[{"group":"Workforce","icon":"users","root":{"title":"Workforce","sidebarTitle":"Workforce","icon":"users","description":"Read org units, positions, pods, people and workers; manage pods, people and identity links, and, at the platform scope, position assignments.","href":"/forge/reference/http-api/workforce"},"pages":[{"title":"List org units","description":"Lists workforce rows within the caller's current workforce scope closure in legacy ID order. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List org units","openapi":"/forge/reference/openapi-v3.json get /api/v3/org-units","href":"/forge/reference/http-api/workforce/listorgunits"},{"title":"Get org unit","description":"Returns a visible workforce row using legacy IDs. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get org unit","openapi":"/forge/reference/openapi-v3.json get /api/v3/org-units/{orgUnitId}","href":"/forge/reference/http-api/workforce/getorgunit"},{"title":"List positions","description":"Lists workforce rows within the caller's current workforce scope closure in legacy ID order. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List positions","openapi":"/forge/reference/openapi-v3.json get /api/v3/positions","href":"/forge/reference/http-api/workforce/listpositions"},{"title":"Get position","description":"Returns a visible workforce row using legacy IDs. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get position","openapi":"/forge/reference/openapi-v3.json get /api/v3/positions/{positionId}","href":"/forge/reference/http-api/workforce/getposition"},{"title":"Create org unit","description":"Creates an active org unit of an active structure type, under an active parent or as a new root. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create org unit","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-units","href":"/forge/reference/http-api/workforce/createorgunit"},{"title":"Move org unit","description":"Moves an org unit and its subtree under an active new parent, or to the root. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Move org unit","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-units/{orgUnitId}/move","href":"/forge/reference/http-api/workforce/moveorgunit"},{"title":"Create position","description":"Creates an OPEN position in an org unit. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create position","openapi":"/forge/reference/openapi-v3.json post /api/v3/positions","href":"/forge/reference/http-api/workforce/createposition"},{"title":"Update position","description":"Sets whether an agent may be assigned to the position. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update position","openapi":"/forge/reference/openapi-v3.json patch /api/v3/positions/{positionId}","href":"/forge/reference/http-api/workforce/updateposition"},{"title":"Set position reporting","description":"Sets or clears the position this one reports to, with an audited reason. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set position reporting","openapi":"/forge/reference/openapi-v3.json post /api/v3/positions/{positionId}/set-reporting","href":"/forge/reference/http-api/workforce/setpositionreporting"},{"title":"List pods","description":"Lists pods in podKey order with effective lead and member counts at `at`. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List pods","openapi":"/forge/reference/openapi-v3.json get /api/v3/pods","href":"/forge/reference/http-api/workforce/listpods"},{"title":"Get pod","description":"Returns one pod with its roster effective at `at` (up to 100 entries; rosterTruncated reports more). Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get pod","openapi":"/forge/reference/openapi-v3.json get /api/v3/pods/{podId}","href":"/forge/reference/http-api/workforce/getpod"},{"title":"List pod membership history","description":"Lists a pod's membership history in sequence order. meta.nextCursor is the decimal sequence to continue after; any other cursor is 400. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List pod membership history","openapi":"/forge/reference/openapi-v3.json get /api/v3/pods/{podId}/membership-history","href":"/forge/reference/http-api/workforce/listpodmembershiphistory"},{"title":"Preview pod membership","description":"Previews one pod membership change (add, change-effective, update-future or end) exactly as the Console does, and changes nothing. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview pod membership","openapi":"/forge/reference/openapi-v3.json post /api/v3/pods/preview-membership","href":"/forge/reference/http-api/workforce/previewpodmembership"},{"title":"List assignment history","description":"List assignment history. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List assignment history","openapi":"/forge/reference/openapi-v3.json get /api/v3/position-assignment-history","href":"/forge/reference/http-api/workforce/listassignmenthistory"},{"title":"Create position assignment","description":"Seats a worker in a position from `startDate` (until `endDate`, when given) as a PRIMARY or SECONDARY assignment, with an audited reason. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create position assignment","openapi":"/forge/reference/openapi-v3.json post /api/v3/positions/{positionId}/assignments","href":"/forge/reference/http-api/workforce/createpositionassignment"},{"title":"Update position assignment","description":"Changes an assignment's kind, start or end (a null `endDate` reopens it), with an audited reason. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update position assignment","openapi":"/forge/reference/openapi-v3.json patch /api/v3/position-assignments/{positionAssignmentId}","href":"/forge/reference/http-api/workforce/updatepositionassignment"},{"title":"End position assignment","description":"Ends an open assignment at `endDate`, with an audited reason. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"End position assignment","openapi":"/forge/reference/openapi-v3.json post /api/v3/position-assignments/{positionAssignmentId}/end","href":"/forge/reference/http-api/workforce/endpositionassignment"},{"title":"Reassign primary position","description":"Moves a worker's primary position in one transaction — the primary effective at `startDate` ends then, and an open PRIMARY assignment in `newPositionId` starts. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Reassign primary position","openapi":"/forge/reference/openapi-v3.json post /api/v3/workers/{workerId}/reassign-primary-position","href":"/forge/reference/http-api/workforce/reassignprimaryposition"},{"title":"List worker roles","description":"Returns every worker role (Job) a position can carry, oldest first, in one response without `limit`, or in pages of `limit` with `cursor`. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List worker roles","openapi":"/forge/reference/openapi-v3.json get /api/v3/worker-roles","href":"/forge/reference/http-api/workforce/listworkerroles"},{"title":"Add pod membership","description":"Adds an active Employee or Contractor worker seat to a pod as lead or member from `startsAt`, with an optional end, allocation (default 100) and delivery role. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Add pod membership","openapi":"/forge/reference/openapi-v3.json post /api/v3/pods/{podId}/memberships","href":"/forge/reference/http-api/workforce/addpodmembership"},{"title":"Change pod membership effective","description":"Ends the membership at `effectiveAt` and starts its successor with the new role, allocation, delivery role and end; returns both rows. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Change pod membership effective","openapi":"/forge/reference/openapi-v3.json post /api/v3/pods/{podId}/memberships/{membershipId}/change-effective","href":"/forge/reference/http-api/workforce/changepodmembershipeffective"},{"title":"Update future pod membership","description":"Replaces the role, allocation, delivery role, start and end of a membership that has not started. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update future pod membership","openapi":"/forge/reference/openapi-v3.json patch /api/v3/pods/{podId}/memberships/{membershipId}","href":"/forge/reference/http-api/workforce/updatefuturepodmembership"},{"title":"End pod membership","description":"Sets the membership's end. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"End pod membership","openapi":"/forge/reference/openapi-v3.json post /api/v3/pods/{podId}/memberships/{membershipId}/end","href":"/forge/reference/http-api/workforce/endpodmembership"},{"title":"Delete future pod membership","description":"Deletes a membership that has not started and returns its `podId` and `membershipId` with `deleted` set to `true`. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete future pod membership","openapi":"/forge/reference/openapi-v3.json delete /api/v3/pods/{podId}/memberships/{membershipId}","href":"/forge/reference/http-api/workforce/deletefuturepodmembership"},{"title":"Confirm pod membership accuracy","description":"Records that the membership is still accurate, renewing its verification window. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Confirm pod membership accuracy","openapi":"/forge/reference/openapi-v3.json post /api/v3/pods/{podId}/memberships/{membershipId}/confirm-accuracy","href":"/forge/reference/http-api/workforce/confirmpodmembershipaccuracy"},{"title":"Create pod","description":"Creates an active pod managed by `managingOrgUnitId`. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create pod","openapi":"/forge/reference/openapi-v3.json post /api/v3/pods","href":"/forge/reference/http-api/workforce/createpod"},{"title":"Update pod","description":"Renames a pod, changes or clears (`null`) its description, or moves it to another managing org unit. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update pod","openapi":"/forge/reference/openapi-v3.json patch /api/v3/pods/{podId}","href":"/forge/reference/http-api/workforce/updatepod"},{"title":"Archive pod","description":"Archives an active pod and ends its open memberships, recording `reason` in the audit (the result does not carry it). Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Archive pod","openapi":"/forge/reference/openapi-v3.json delete /api/v3/pods/{podId}","href":"/forge/reference/http-api/workforce/archivepod"},{"title":"Assign pod owner","description":"Makes an active person the pod's owner from `startsAt`, with an optional end. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Assign pod owner","openapi":"/forge/reference/openapi-v3.json post /api/v3/pods/{podId}/owners","href":"/forge/reference/http-api/workforce/assignpodowner"},{"title":"Change pod owner effective","description":"Ends the owner assignment at `effectiveAt` and starts its successor with `personId` and the new end; at the assignment's own start it corrects the row in place. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Change pod owner effective","openapi":"/forge/reference/openapi-v3.json post /api/v3/pod-owners/{podOwnerId}/change-effective","href":"/forge/reference/http-api/workforce/changepodownereffective"},{"title":"End pod owner","description":"Sets the owner assignment's end. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"End pod owner","openapi":"/forge/reference/openapi-v3.json post /api/v3/pod-owners/{podOwnerId}/end","href":"/forge/reference/http-api/workforce/endpodowner"},{"title":"List pod owners","description":"Lists the pod's owner assignments that overlap the window, oldest first, each with the owner's display name and whether the person is current, inactive or unresolved. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List pod owners","openapi":"/forge/reference/openapi-v3.json get /api/v3/pods/{podId}/owners","href":"/forge/reference/http-api/workforce/listpodowners"},{"title":"Set pod internal profile","description":"Classifies the pod's internal (non-Customer) delivery from `effectiveAt` by delivery type and/or reporting category. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set pod internal profile","openapi":"/forge/reference/openapi-v3.json post /api/v3/pods/{podId}/set-internal-profile","href":"/forge/reference/http-api/workforce/setpodinternalprofile"},{"title":"End pod internal profile","description":"Sets the internal profile's end. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"End pod internal profile","openapi":"/forge/reference/openapi-v3.json post /api/v3/pod-internal-profiles/{podInternalProfileId}/end","href":"/forge/reference/http-api/workforce/endpodinternalprofile"},{"title":"List pod internal profiles","description":"Lists the pod's internal delivery profiles that overlap the window, oldest first. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List pod internal profiles","openapi":"/forge/reference/openapi-v3.json get /api/v3/pods/{podId}/internal-profiles","href":"/forge/reference/http-api/workforce/listpodinternalprofiles"},{"title":"Get worker","description":"Returns one worker seat — name, type, status, person link, current position and its team and department. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get worker","openapi":"/forge/reference/openapi-v3.json get /api/v3/workers/{workerId}","href":"/forge/reference/http-api/workforce/getworker"},{"title":"Create person","description":"Creates an active person (no sign-in and no role grant), optionally with an active worker seat (`createSeat`, EMPLOYEE or CONTRACTOR only). Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create person","openapi":"/forge/reference/openapi-v3.json post /api/v3/persons","href":"/forge/reference/http-api/workforce/createperson"},{"title":"Update person","description":"Changes a person's name, primary email, display name, time zone or type; `null` clears a nullable field. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update person","openapi":"/forge/reference/openapi-v3.json patch /api/v3/persons/{personId}","href":"/forge/reference/http-api/workforce/updateperson"},{"title":"Preview person merge","description":"Returns exactly what `POST /api/v2/workforce/mergePersons` would move for this pair — both people, the identity claim IDs, the rows per table, the counts, and any pod ownership conflict that would refuse the merge. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview person merge","openapi":"/forge/reference/openapi-v3.json post /api/v3/persons/preview-merge","href":"/forge/reference/http-api/workforce/previewpersonmerge"},{"title":"Merge persons","description":"Moves the loser's seats, identity claims, role grants and person-keyed rows to the winner and leaves the loser as an inactive redirect. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Merge persons","openapi":"/forge/reference/openapi-v3.json post /api/v3/persons/merge","href":"/forge/reference/http-api/workforce/mergepersons"},{"title":"Offboard person","description":"Offboard a person. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Offboard person","openapi":"/forge/reference/openapi-v3.json post /api/v3/persons/{personId}/offboard","href":"/forge/reference/http-api/workforce/offboardperson"},{"title":"Reactivate person","description":"Raises an inactive employee or contractor and one worker seat. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Reactivate person","openapi":"/forge/reference/openapi-v3.json post /api/v3/persons/{personId}/reactivate","href":"/forge/reference/http-api/workforce/reactivateperson"},{"title":"Get person","description":"Returns one person — name, display name, primary email, type, status and every human seat with its position, team, department, monthly budget and spend. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get person","openapi":"/forge/reference/openapi-v3.json get /api/v3/persons/{personId}","href":"/forge/reference/http-api/workforce/getperson"},{"title":"List workers","description":"List workers. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List workers","openapi":"/forge/reference/openapi-v3.json get /api/v3/workers","href":"/forge/reference/http-api/workforce/listworkers"},{"title":"Update worker seat","description":"Sets or clears (`null`) the monthly budget of an EMPLOYEE or CONTRACTOR seat and answers the seat as `GET /api/v2/workforce/getPerson` shows it; the change is audited on the person's history. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update worker seat","openapi":"/forge/reference/openapi-v3.json patch /api/v3/workers/{workerId}/seat","href":"/forge/reference/http-api/workforce/updateworkerseat"},{"title":"List person identities","description":"Lists every identity linked to the person, revoked ones included — provider, the provider's ID, status and times, never the identity's email. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"List person identities","openapi":"/forge/reference/openapi-v3.json get /api/v3/persons/{personId}/identities","href":"/forge/reference/http-api/workforce/listpersonidentities"},{"title":"Link person identity","description":"Links a Slack, email, GitHub, Google Workspace, Okta, Rippling, Microsoft Entra or Freshservice identity to an active person. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Link person identity","openapi":"/forge/reference/openapi-v3.json post /api/v3/persons/{personId}/identities","href":"/forge/reference/http-api/workforce/linkpersonidentity"},{"title":"Unlink person identity","description":"Revokes one of the person's identity links; messages from that identity no longer resolve to the person. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Unlink person identity","openapi":"/forge/reference/openapi-v3.json post /api/v3/persons/{personId}/identities/{identityId}/unlink","href":"/forge/reference/http-api/workforce/unlinkpersonidentity"},{"title":"List person email claims","description":"Lists the person's secondary email claims, revoked ones included, with how each was verified and where it came from. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"List person email claims","openapi":"/forge/reference/openapi-v3.json get /api/v3/persons/{personId}/email-claims","href":"/forge/reference/http-api/workforce/listpersonemailclaims"},{"title":"Add person email claim","description":"Claims a secondary email address for the person (verification `admin_assigned`, provider `api`), or answers the person's existing claim on it. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Add person email claim","openapi":"/forge/reference/openapi-v3.json post /api/v3/persons/{personId}/email-claims","href":"/forge/reference/http-api/workforce/upsertpersonemailclaim"},{"title":"Revoke person email claim","description":"Revokes one of the person's email claims, audited on the person's history with the reason. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Revoke person email claim","openapi":"/forge/reference/openapi-v3.json post /api/v3/persons/{personId}/email-claims/{claimId}/revoke","href":"/forge/reference/http-api/workforce/revokepersonemailclaim"},{"title":"Get person communication profile","description":"Returns the person's current communication profile (signature, tone, examples, writing instructions and automation authorization) with its revision, or `head` and `revision` both null before the first save. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Get person communication profile","openapi":"/forge/reference/openapi-v3.json get /api/v3/persons/{personId}/communication-profile","href":"/forge/reference/http-api/workforce/getpersoncommunicationprofile"},{"title":"Save person communication profile","description":"Saves a new revision of the person's communication profile. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Save person communication profile","openapi":"/forge/reference/openapi-v3.json patch /api/v3/persons/{personId}/communication-profile","href":"/forge/reference/http-api/workforce/savepersoncommunicationprofile"},{"title":"List person communication profile history","description":"Lists the person's communication profile revisions, newest first, without their editor. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"List person communication profile history","openapi":"/forge/reference/openapi-v3.json get /api/v3/persons/{personId}/communication-profile-history","href":"/forge/reference/http-api/workforce/listpersoncommunicationprofilehistory"},{"title":"List person audit events","description":"List a person's history. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List person audit events","openapi":"/forge/reference/openapi-v3.json get /api/v3/persons/{personId}/audit-events","href":"/forge/reference/http-api/workforce/listpersonauditevents"},{"title":"Assign pod customer","description":"Assigns an active Organization Customer to an active pod for `allocationPercent` of the pod's capacity from `startsAt`, with an optional end and optional delivery slices. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Assign pod customer","openapi":"/forge/reference/openapi-v3.json post /api/v3/pods/{podId}/customer-assignments","href":"/forge/reference/http-api/workforce/assignpodcustomer"},{"title":"Change pod customer assignment effective","description":"Change a Customer assignment from a date. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Change pod customer assignment effective","openapi":"/forge/reference/openapi-v3.json post /api/v3/pod-customer-assignments/{podCustomerAssignmentId}/change-effective","href":"/forge/reference/http-api/workforce/changepodcustomerassignmenteffective"},{"title":"Update future pod customer assignment","description":"Replaces the allocation, delivery slices, start and end of an assignment that has not started yet; the new start must also be in the future `(POD_CUSTOMER_FUTURE_ONLY)`. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update future pod customer assignment","openapi":"/forge/reference/openapi-v3.json patch /api/v3/pod-customer-assignments/{podCustomerAssignmentId}","href":"/forge/reference/http-api/workforce/updatefuturepodcustomerassignment"},{"title":"Delete future pod customer assignment","description":"Deletes an assignment that has not started yet `(POD_CUSTOMER_FUTURE_ONLY)` and returns its `podId` and `assignmentId` with `deleted` set to `true`. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete future pod customer assignment","openapi":"/forge/reference/openapi-v3.json delete /api/v3/pod-customer-assignments/{podCustomerAssignmentId}","href":"/forge/reference/http-api/workforce/deletefuturepodcustomerassignment"},{"title":"End pod customer assignment","description":"Sets the assignment's end, no later than its current end. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"End pod customer assignment","openapi":"/forge/reference/openapi-v3.json post /api/v3/pod-customer-assignments/{podCustomerAssignmentId}/end","href":"/forge/reference/http-api/workforce/endpodcustomerassignment"},{"title":"Confirm pod customer assignment accuracy","description":"Records that the assignment was reviewed now and moves its verification due date forward, whatever the pod's or Customer's current lifecycle. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Confirm pod customer assignment accuracy","openapi":"/forge/reference/openapi-v3.json post /api/v3/pod-customer-assignments/{podCustomerAssignmentId}/confirm-accuracy","href":"/forge/reference/http-api/workforce/confirmpodcustomerassignmentaccuracy"},{"title":"Preview pod customer assignment","description":"Preview a Customer assignment change. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview pod customer assignment","openapi":"/forge/reference/openapi-v3.json post /api/v3/pods/preview-customer-assignment","href":"/forge/reference/http-api/workforce/previewpodcustomerassignment"},{"title":"List pod customer assignments","description":"Lists the pod's Customer assignments that overlap the window, each with the pod, the Customer and whether its verification is current or stale. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List pod customer assignments","openapi":"/forge/reference/openapi-v3.json get /api/v3/pods/{podId}/customer-assignments","href":"/forge/reference/http-api/workforce/listpodcustomerassignments"},{"title":"List customer pod assignments","description":"Lists the Customer's pod assignments that overlap the window, each with its pod and verification state. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List customer pod assignments","openapi":"/forge/reference/openapi-v3.json get /api/v3/customers/{customerId}/pod-assignments","href":"/forge/reference/http-api/workforce/listcustomerpodassignments"},{"title":"List pod customer assignment history","description":"Pages through every Customer assignment the pod has had, latest effective end first. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List pod customer assignment history","openapi":"/forge/reference/openapi-v3.json get /api/v3/pods/{podId}/customer-assignment-history","href":"/forge/reference/http-api/workforce/listpodcustomerassignmenthistory"},{"title":"Get person allocation","description":"Get a person's allocation window. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get person allocation","openapi":"/forge/reference/openapi-v3.json get /api/v3/person-allocation","href":"/forge/reference/http-api/workforce/getpersonallocation"},{"title":"Get engineering scope","description":"Returns the engineering scope definition effective at `at` (the org units whose people form the engineering pool), or a null `data` when none is effective. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get engineering scope","openapi":"/forge/reference/openapi-v3.json get /api/v3/engineering-scope","href":"/forge/reference/http-api/workforce/getengineeringscope"},{"title":"Set engineering scope","description":"Sets the engineering scope from `startsAt`. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set engineering scope","openapi":"/forge/reference/openapi-v3.json patch /api/v3/engineering-scope","href":"/forge/reference/http-api/workforce/setengineeringscope"},{"title":"List reporting categories","description":"Returns every reporting category (at most 100, sorted by label then key), answered whole in one response — a create past 100 categories is refused. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List reporting categories","openapi":"/forge/reference/openapi-v3.json get /api/v3/reporting-categories","href":"/forge/reference/http-api/workforce/listreportingcategories"},{"title":"Create reporting category","description":"Creates an active reporting category with a unique `key`. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create reporting category","openapi":"/forge/reference/openapi-v3.json post /api/v3/reporting-categories","href":"/forge/reference/http-api/workforce/createreportingcategory"},{"title":"Update reporting category","description":"Replaces a category's label, description and retired flag; its key never changes. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update reporting category","openapi":"/forge/reference/openapi-v3.json patch /api/v3/reporting-categories/{reportingCategoryId}","href":"/forge/reference/http-api/workforce/updatereportingcategory"},{"title":"List bandwidth feedback","description":"Returns one worker's newest `limit` bandwidth reports, newest first, optionally for one week, answered whole in one response. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List bandwidth feedback","openapi":"/forge/reference/openapi-v3.json get /api/v3/workers/{workerId}/bandwidth-feedback","href":"/forge/reference/http-api/workforce/listbandwidthfeedback"},{"title":"Customer planning snapshot","description":"Read-only capacity planning by customer from one authorized snapshot, with workforce:read at platform scope.","deprecated":null,"version":null,"sidebarTitle":"Customer planning snapshot","openapi":"/forge/reference/openapi-v3.json get /api/v3/customer-planning","href":"/forge/reference/http-api/workforce/listcustomerplanning"},{"title":"Engineering capacity snapshot","description":"Read-only capacity planning by engineer from one authorized snapshot, with workforce:read at platform scope.","deprecated":null,"version":null,"sidebarTitle":"Engineering capacity snapshot","openapi":"/forge/reference/openapi-v3.json get /api/v3/engineers","href":"/forge/reference/http-api/workforce/listengineers"},{"title":"Pod planning snapshot","description":"Read-only capacity planning by Pod from one authorized snapshot, with workforce:read at platform scope.","deprecated":null,"version":null,"sidebarTitle":"Pod planning snapshot","openapi":"/forge/reference/openapi-v3.json get /api/v3/pod-planning","href":"/forge/reference/http-api/workforce/listpodplanning"}]},{"group":"Org units and positions","icon":"sitemap","root":{"title":"Org units and positions administration","sidebarTitle":"Org administration","icon":"sitemap","description":"Administer the organization's structure types and tier order, and read the org change schedule, with a platform API key.","href":"/forge/reference/http-api/org-units-positions"},"pages":[{"title":"Stage archiving a position in the active org chart draft, on its current dependency preview","description":"Stage archiving a position in the active org chart draft, on its current dependency preview. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage archiving a position in the active org chart draft, on its current dependency preview","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-drafts/{draftId}/positions/{positionId}/archive","href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-archive"},{"title":"Stage restoring a position in the active org chart draft, on its current dependency preview","description":"Stage restoring a position in the active org chart draft, on its current dependency preview. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage restoring a position in the active org chart draft, on its current dependency preview","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-drafts/{draftId}/positions/{positionId}/restore","href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-restore"},{"title":"Stage removing a position in the active org chart draft","description":"Stage removing a position in the active org chart draft. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage removing a position in the active org chart draft","openapi":"/forge/reference/openapi-v3.json delete /api/v3/org-unit-drafts/{draftId}/positions/{positionId}","href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-remove"},{"title":"Stage archiving an org unit in the active org chart draft, on its current dependency preview","description":"Stage archiving an org unit in the active org chart draft, on its current dependency preview. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage archiving an org unit in the active org chart draft, on its current dependency preview","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-drafts/{draftId}/org-units/{orgUnitId}/archive","href":"/forge/reference/http-api/org-units-positions/admin/drafts-org-units-archive"},{"title":"Stage restoring an org unit in the active org chart draft, on its current dependency preview","description":"Stage restoring an org unit in the active org chart draft, on its current dependency preview. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage restoring an org unit in the active org chart draft, on its current dependency preview","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-drafts/{draftId}/org-units/{orgUnitId}/restore","href":"/forge/reference/http-api/org-units-positions/admin/drafts-org-units-restore"},{"title":"Stage removing an org unit in the active org chart draft","description":"Stage removing an org unit in the active org chart draft. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage removing an org unit in the active org chart draft","openapi":"/forge/reference/openapi-v3.json delete /api/v3/org-unit-drafts/{draftId}/org-units/{orgUnitId}","href":"/forge/reference/http-api/org-units-positions/admin/drafts-org-units-remove"},{"title":"Stage a new capital-partner org unit in the active org chart draft","description":"Stage a new capital-partner org unit in the active org chart draft. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage a new capital-partner org unit in the active org chart draft","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-drafts/{draftId}/capital-partners","href":"/forge/reference/http-api/org-units-positions/admin/drafts-capital-partners-add"},{"title":"Create an org structure type (a tier or a cross-cutting group type) and answer its id","description":"Create an org structure type (a tier or a cross-cutting group type) and answer its id. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create an org structure type (a tier or a cross-cutting group type) and answer its id","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-structure-types","href":"/forge/reference/http-api/org-units-positions/admin/structure-types-create"},{"title":"List a page of a member's active org unit memberships, by createdAt, then id, with each unit's name","description":"List a page of a member's active org unit memberships, by createdAt, then id, with each unit's name. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a member's active org unit memberships, by createdAt, then id, with each unit's name","openapi":"/forge/reference/openapi-v3.json get /api/v3/org-unit-members/{memberId}/memberships","href":"/forge/reference/http-api/org-units-positions/admin/memberships-by-member"},{"title":"List an org unit's active memberships a page at a time, in the order they were created, each with its member's and unit's name","description":"List an org unit's active memberships a page at a time, in the order they were created, each with its member's and unit's name. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List an org unit's active memberships a page at a time, in the order they were created, each with its member's and unit's name","openapi":"/forge/reference/openapi-v3.json get /api/v3/org-units/{orgUnitId}/memberships","href":"/forge/reference/http-api/org-units-positions/admin/memberships"},{"title":"List a page of the active org structure types, optionally of one category, by createdAt, then id","description":"List a page of the active org structure types, optionally of one category, by createdAt, then id; createOrgUnit takes one's id as structureTypeId. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the active org structure types, optionally of one category, by createdAt, then id","openapi":"/forge/reference/openapi-v3.json get /api/v3/org-unit-structure-types","href":"/forge/reference/http-api/org-units-positions/admin/structure-types"},{"title":"List the tier structure types in tier order","description":"List the tier structure types in tier order. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List the tier structure types in tier order","openapi":"/forge/reference/openapi-v3.json get /api/v3/org-unit-structure-type-tiers","href":"/forge/reference/http-api/org-units-positions/admin/structure-types-tiers"},{"title":"List a page of the published org chart snapshots, newest first","description":"List a page of the published org chart snapshots, newest first. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the published org chart snapshots, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/org-unit-snapshots","href":"/forge/reference/http-api/org-units-positions/admin/snapshots"},{"title":"List a page of the scheduled org changes of one status (pending when none is given), in effective date order, optionally effective at or before a time","description":"List a page of the scheduled org changes of one status (pending when none is given), in effective date order, optionally effective at or before a time. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the scheduled org changes of one status (pending when none is given), in effective date order, optionally effective at or before a time","openapi":"/forge/reference/openapi-v3.json get /api/v3/org-unit-scheduled-changes","href":"/forge/reference/http-api/org-units-positions/admin/scheduled-changes"},{"title":"Stage moving a position to another org unit in the active org chart draft","description":"Stage moving a position to another org unit in the active org chart draft. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage moving a position to another org unit in the active org chart draft","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-drafts/{draftId}/positions/{positionId}/move","href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-move"},{"title":"Preview what depends on an org unit, and the hash an archive or restore of it is staged on","description":"Preview what depends on an org unit, and the hash an archive or restore of it is staged on. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview what depends on an org unit, and the hash an archive or restore of it is staged on","openapi":"/forge/reference/openapi-v3.json get /api/v3/org-units/{orgUnitId}/dependencies","href":"/forge/reference/http-api/org-units-positions/admin/dependencies-org-unit"},{"title":"Preview what depends on a position, and the hash an archive or restore of it is staged on","description":"Preview what depends on a position, and the hash an archive or restore of it is staged on. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview what depends on a position, and the hash an archive or restore of it is staged on","openapi":"/forge/reference/openapi-v3.json get /api/v3/positions/{positionId}/dependencies","href":"/forge/reference/http-api/org-units-positions/admin/dependencies-position"},{"title":"Set the tier order of the tier structure types, first to last","description":"Set the tier order of the tier structure types, first to last. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set the tier order of the tier structure types, first to last","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-structure-types/reorder-tiers","href":"/forge/reference/http-api/org-units-positions/admin/structure-types-reorder-tiers"},{"title":"Update an org structure type's names, tier order, nesting, icon, description or status","description":"Update an org structure type's names, tier order, nesting, icon, description or status. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update an org structure type's names, tier order, nesting, icon, description or status","openapi":"/forge/reference/openapi-v3.json patch /api/v3/org-unit-structure-types/{structureTypeId}","href":"/forge/reference/http-api/org-units-positions/admin/structure-types-update"},{"title":"Stage an org unit's name, description, structure type or code change in the active org chart draft","description":"Stage an org unit's name, description, structure type or code change in the active org chart draft. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage an org unit's name, description, structure type or code change in the active org chart draft","openapi":"/forge/reference/openapi-v3.json patch /api/v3/org-unit-drafts/{draftId}/org-units/{orgUnitId}","href":"/forge/reference/http-api/org-units-positions/admin/drafts-org-units-update"},{"title":"Stage a new position in the active org chart draft and answer its change id","description":"Stage a new position in the active org chart draft and answer its change id. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage a new position in the active org chart draft and answer its change id","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-drafts/{draftId}/positions","href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-add"},{"title":"Stage a new org unit in the active org chart draft and answer its change id","description":"Stage a new org unit in the active org chart draft and answer its change id. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage a new org unit in the active org chart draft and answer its change id","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-drafts/{draftId}/org-units","href":"/forge/reference/http-api/org-units-positions/admin/drafts-org-units-add"},{"title":"Stage a position's new title, description, role or manager flag in the active org chart draft","description":"Stage a position's new title, description, role or manager flag in the active org chart draft. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stage a position's new title, description, role or manager flag in the active org chart draft","openapi":"/forge/reference/openapi-v3.json patch /api/v3/org-unit-drafts/{draftId}/positions/{positionId}","href":"/forge/reference/http-api/org-units-positions/admin/drafts-positions-update"},{"title":"Get the active org chart draft, or null when none is open","description":"Get the active org chart draft, or null when none is open. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Get the active org chart draft, or null when none is open","openapi":"/forge/reference/openapi-v3.json get /api/v3/active-org-unit-draft","href":"/forge/reference/http-api/org-units-positions/admin/drafts-active"},{"title":"Open a new org chart draft and answer its id","description":"Open a new org chart draft and answer its id; one draft is active at a time. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Open a new org chart draft and answer its id","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-drafts","href":"/forge/reference/http-api/org-units-positions/admin/drafts-create"},{"title":"Publish the active org chart draft — apply its staged changes and answer the new snapshot id","description":"Publish the active org chart draft — apply its staged changes and answer the new snapshot id. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Publish the active org chart draft — apply its staged changes and answer the new snapshot id","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-unit-drafts/{draftId}/publish","href":"/forge/reference/http-api/org-units-positions/admin/drafts-publish"}]},{"group":"People and members","icon":"user-group","root":{"title":"People and members administration","sidebarTitle":"People administration","icon":"users","description":"Administer expertise tags and start workforce integrity audits, and read the deployment's person-identity check, with a platform API key.","href":"/forge/reference/http-api/people-members"},"pages":[{"title":"Add a worker or a position as a member of an org unit and answer the membership id","description":"Add a worker or a position as a member of an org unit and answer the membership id. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Add a worker or a position as a member of an org unit and answer the membership id","openapi":"/forge/reference/openapi-v3.json post /api/v3/org-units/{orgUnitId}/memberships","href":"/forge/reference/http-api/people-members/admin/memberships-add"},{"title":"Apply a previewed workforce repair run whose plan hash still matches","description":"Apply a previewed workforce repair run whose plan hash still matches. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Apply a previewed workforce repair run whose plan hash still matches","openapi":"/forge/reference/openapi-v3.json post /api/v3/workforce-integrity-runs/{runId}/apply-repair","href":"/forge/reference/http-api/people-members/admin/integrity-repairs-apply"},{"title":"Change an org unit member's role","description":"Change an org unit member's role. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Change an org unit member's role","openapi":"/forge/reference/openapi-v3.json patch /api/v3/org-unit-memberships/{orgUnitMembershipId}","href":"/forge/reference/http-api/people-members/admin/memberships-update-role"},{"title":"Create a person and their human worker seat","description":"Create a person and their human worker seat; an email a person in reach already holds answers 409. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create a person and their human worker seat","openapi":"/forge/reference/openapi-v3.json post /api/v3/workers","href":"/forge/reference/http-api/people-members/admin/workers-create"},{"title":"Create or update an expertise tag","description":"Create or update an expertise tag. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create or update an expertise tag","openapi":"/forge/reference/openapi-v3.json post /api/v3/expertise-tags/upsert","href":"/forge/reference/http-api/people-members/admin/expertise-tags-upsert"},{"title":"Deactivate a worker seat","description":"Deactivate a worker seat. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"Deactivate a worker seat","openapi":"/forge/reference/openapi-v3.json post /api/v3/workers/{workerId}/deactivate","href":"/forge/reference/http-api/people-members/admin/workers-deactivate"},{"title":"Get the deployment's person-identity integrity check — its status, counts and staleness","description":"Get the deployment's person-identity integrity check — its status, counts and staleness. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the deployment's person-identity integrity check — its status, counts and staleness","openapi":"/forge/reference/openapi-v3.json get /api/v3/person-integrity-status","href":"/forge/reference/http-api/people-members/admin/integrity-person-status"},{"title":"List a worker's expertise tags and levels","description":"List a worker's expertise tags and levels. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List a worker's expertise tags and levels","openapi":"/forge/reference/openapi-v3.json get /api/v3/workers/{workerId}/expertise-tags","href":"/forge/reference/http-api/people-members/admin/workers-expertise-tags"},{"title":"List a page of the expertise tags in creation order, optionally of one category","description":"List a page of the expertise tags in creation order, optionally of one category. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the expertise tags in creation order, optionally of one category","openapi":"/forge/reference/openapi-v3.json get /api/v3/expertise-tags","href":"/forge/reference/http-api/people-members/admin/expertise-tags"},{"title":"List members a page at a time, in the order people were created — each person's seats, emails and whether their sign-in is linked","description":"List members a page at a time, in the order people were created — each person's seats, emails and whether their sign-in is linked. Requires permission `grants:read`.","deprecated":null,"version":null,"sidebarTitle":"List members a page at a time, in the order people were created — each person's seats, emails and whether their sign-in is linked","openapi":"/forge/reference/openapi-v3.json get /api/v3/members","href":"/forge/reference/http-api/people-members/admin/members"},{"title":"Preview a workforce repair from an audit run's findings, named by their findingId","description":"Preview a workforce repair from an audit run's findings, named by their findingId; apply it with integrity/repairs/apply. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview a workforce repair from an audit run's findings, named by their findingId","openapi":"/forge/reference/openapi-v3.json post /api/v3/workforce-integrity-runs/{runId}/preview-repair","href":"/forge/reference/http-api/people-members/admin/integrity-repairs-preview"},{"title":"Get a workforce integrity audit or repair run","description":"Get a workforce integrity audit or repair run. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a workforce integrity audit or repair run","openapi":"/forge/reference/openapi-v3.json get /api/v3/workforce-integrity-run","href":"/forge/reference/http-api/people-members/admin/integrity-runs-get"},{"title":"List a workforce integrity run's findings a page at a time, optionally of one classification or status — each finding's findingId (it changes when the deployment's signing key rotates","description":"List a workforce integrity run's findings a page at a time, optionally of one classification or status — each finding's findingId (it changes when the deployment's signing key rotates; list again), invariant, classification and status, and the ids it affects. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"List a workforce integrity run's findings a page at a time, optionally of one classification or status — each finding's findingId (it changes when the deployment's signing key rotates","openapi":"/forge/reference/openapi-v3.json get /api/v3/workforce-integrity-runs/{runId}/findings","href":"/forge/reference/http-api/people-members/admin/integrity-findings"},{"title":"End an org unit member's membership","description":"End an org unit member's membership. Requires permission `org:manage`.","deprecated":null,"version":null,"sidebarTitle":"End an org unit member's membership","openapi":"/forge/reference/openapi-v3.json delete /api/v3/org-unit-memberships/{orgUnitMembershipId}","href":"/forge/reference/http-api/people-members/admin/memberships-remove"},{"title":"Set a worker's level for an expertise tag","description":"Set a worker's level for an expertise tag. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set a worker's level for an expertise tag","openapi":"/forge/reference/openapi-v3.json post /api/v3/workers/{workerId}/set-expertise-tag","href":"/forge/reference/http-api/people-members/admin/workers-expertise-tags-set"},{"title":"Start a workforce integrity audit (it reads and records findings)","description":"Start a workforce integrity audit (it reads and records findings). Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Start a workforce integrity audit (it reads and records findings)","openapi":"/forge/reference/openapi-v3.json post /api/v3/workforce-integrity-runs/start-audit","href":"/forge/reference/http-api/people-members/admin/integrity-audits-start"}]},{"group":"Identity","icon":"fingerprint","root":{"title":"Identity administration","sidebarTitle":"Identity administration","icon":"id-card","description":"List the sign-in attempts that matched no person and dismiss one, and read a person's profile or clear their avatar, with an API key.","href":"/forge/reference/http-api/identity-profile"},"pages":[{"title":"Dismiss an unmapped sign-in attempt, with a reason and an optional dismissal period in days (0 keeps it dismissed)","description":"Dismiss an unmapped sign-in attempt, with a reason and an optional dismissal period in days (0 keeps it dismissed). Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Dismiss an unmapped sign-in attempt, with a reason and an optional dismissal period in days (0 keeps it dismissed)","openapi":"/forge/reference/openapi-v3.json post /api/v3/identity-unmapped-attempts/{attemptId}/dismiss","href":"/forge/reference/http-api/identity-profile/admin/unmapped-attempts-dismiss"},{"title":"List a page of unmapped sign-in attempts, pending first, optionally with dismissed ones","description":"List a page of unmapped sign-in attempts, pending first, optionally with dismissed ones. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"List a page of unmapped sign-in attempts, pending first, optionally with dismissed ones","openapi":"/forge/reference/openapi-v3.json get /api/v3/identity-unmapped-attempts","href":"/forge/reference/http-api/identity-profile/admin/unmapped-attempts"},{"title":"Get the Personal key's owner's profile, or another person's by userId with workforce:manage","description":"Get the Personal key's owner's profile, or another person's by userId with workforce:manage. A Personal key acts as its owner; another person needs `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Get the Personal key's owner's profile, or another person's by userId with workforce:manage","openapi":"/forge/reference/openapi-v3.json get /api/v3/identity-profile","href":"/forge/reference/http-api/identity-profile/admin/profile"},{"title":"Clear the Personal key's owner's avatar, or another person's by userId with workforce:manage","description":"Clear the Personal key's owner's avatar, or another person's by userId with workforce:manage. A Personal key acts as its owner; another person needs `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Clear the Personal key's owner's avatar, or another person's by userId with workforce:manage","openapi":"/forge/reference/openapi-v3.json post /api/v3/identity-avatar/clear","href":"/forge/reference/http-api/identity-profile/admin/avatar-clear"}]},{"group":"Customers","icon":"building","root":{"title":"Customers","sidebarTitle":"Customers","icon":"building","description":"Read and manage the organization's customer directory over the Platform API.","href":"/forge/reference/http-api/customers"},"pages":[{"title":"List customers","description":"Returns one page of the whole customer directory, oldest customer first. Requires permission `customers:read`.","deprecated":null,"version":null,"sidebarTitle":"List customers","openapi":"/forge/reference/openapi-v3.json get /api/v3/customers","href":"/forge/reference/http-api/customers/list"},{"title":"Get customer","description":"Get a customer from the organization's directory. Requires permission `customers:read`.","deprecated":null,"version":null,"sidebarTitle":"Get customer","openapi":"/forge/reference/openapi-v3.json get /api/v3/customers/{customerId}","href":"/forge/reference/http-api/customers/get"},{"title":"List customer scopes","description":"Returns the org units, External Applications, projects and factories a customer is linked to, oldest link first, a page at a time — follow `meta.nextCursor` while `meta.hasMore` is true. Requires permission `customers:read`.","deprecated":null,"version":null,"sidebarTitle":"List customer scopes","openapi":"/forge/reference/openapi-v3.json get /api/v3/customers/{customerId}/scopes","href":"/forge/reference/http-api/customers/listscopes"},{"title":"Create customer","description":"Creates a customer exactly as the Console does. Requires permission `customers:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create customer","openapi":"/forge/reference/openapi-v3.json post /api/v3/customers","href":"/forge/reference/http-api/customers/create"},{"title":"Update customer","description":"Update a customer in the organization's directory. Requires permission `customers:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update customer","openapi":"/forge/reference/openapi-v3.json patch /api/v3/customers/{customerId}","href":"/forge/reference/http-api/customers/update"},{"title":"Archive customer","description":"Sets the customer's status to `archived`; archiving an archived customer succeeds — its status stays `archived` and its `updatedAt` advances. Requires permission `customers:manage`.","deprecated":null,"version":null,"sidebarTitle":"Archive customer","openapi":"/forge/reference/openapi-v3.json delete /api/v3/customers/{customerId}","href":"/forge/reference/http-api/customers/archive"},{"title":"Ensure an Organization customer has its organization home and answer that home","description":"Ensure an Organization customer has its organization home and answer that home. Requires permission `customers:manage`.","deprecated":null,"version":null,"sidebarTitle":"Ensure an Organization customer has its organization home and answer that home","openapi":"/forge/reference/openapi-v3.json post /api/v3/customers/{customerId}/organizations/ensure","href":"/forge/reference/http-api/customers/admin/organizations-ensure"},{"title":"Get a Freshservice department binding","description":"Read the customer that owns one Freshservice account, workspace and department. The display name never selects the owner.","deprecated":null,"version":null,"sidebarTitle":"Get a Freshservice department binding","openapi":"/forge/reference/openapi-v3.json get /api/v3/customer-freshservice-department-bindings","href":"/forge/reference/http-api/customers/get-freshservice-department-binding"},{"title":"Set a Freshservice department binding","description":"Create, revise or disable the customer that owns a Freshservice department, with a revision compare-and-set.","deprecated":null,"version":null,"sidebarTitle":"Set a Freshservice department binding","openapi":"/forge/reference/openapi-v3.json put /api/v3/customer-freshservice-department-bindings","href":"/forge/reference/http-api/customers/put-freshservice-department-binding"},{"title":"List the calling app's customers","description":"One page of the customers linked to the calling External App, optionally filtered by status.","deprecated":null,"version":null,"sidebarTitle":"List the calling app's customers","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/customers","href":"/forge/reference/http-api/customers/app-list"},{"title":"Create a customer for the calling app","description":"Find or create a customer and link it to the calling External App. Returns the customer.","deprecated":null,"version":null,"sidebarTitle":"Create a customer for the calling app","openapi":"/forge/reference/openapi-v3.json post /api/v3/me/customers","href":"/forge/reference/http-api/customers/app-create"},{"title":"Find or create a customer for the calling app","description":"Find a customer by its WorkOS id or create one, and link it to the calling External App. Says whether it created or linked.","deprecated":null,"version":null,"sidebarTitle":"Find or create a customer for the calling app","openapi":"/forge/reference/openapi-v3.json post /api/v3/me/customers/find-or-create","href":"/forge/reference/http-api/customers/app-find-or-create"},{"title":"Get one of the calling app's customers","description":"Read a customer linked to the calling External App. An unlinked customer answers 404, as an unknown one does.","deprecated":null,"version":null,"sidebarTitle":"Get one of the calling app's customers","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/customers/{customerId}","href":"/forge/reference/http-api/customers/app-get"},{"title":"Update one of the calling app's customers","description":"Change the supplied fields of a customer linked to the calling External App.","deprecated":null,"version":null,"sidebarTitle":"Update one of the calling app's customers","openapi":"/forge/reference/openapi-v3.json patch /api/v3/me/customers/{customerId}","href":"/forge/reference/http-api/customers/app-update"},{"title":"Unlink a customer from the calling app","description":"Remove only the calling External App's link to a customer. The shared customer and other apps' links are untouched.","deprecated":null,"version":null,"sidebarTitle":"Unlink a customer from the calling app","openapi":"/forge/reference/openapi-v3.json delete /api/v3/me/customers/{customerId}","href":"/forge/reference/http-api/customers/app-unlink"}]}]},{"group":"Agents","icon":"robot","root":{"title":"Agents API","sidebarTitle":"Agents","icon":"robot","description":"HTTP API operations for agents and what they are built from: skills, tools, models and memory, plus chat sessions and tool synthesis.","href":"/forge/reference/http-api/families/agents"},"pages":[{"group":"Agents","icon":"robot","root":{"title":"Agents","sidebarTitle":"Agents","icon":"users","description":"Author, fetch, and manage agent definitions through the Platform API.","href":"/forge/reference/http-api/agents"},"pages":[{"title":"List agents","description":"Returns the agents the caller may read — an agent is listed only when the caller holds `agents:read` at the agent's home org unit, and PERSONAL agents are never listed. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List agents","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents","href":"/forge/reference/http-api/agents/list"},{"title":"Get an agent by ID","description":"Returns one agent by its `agentId` or definition id. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get an agent by ID","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}","href":"/forge/reference/http-api/agents/get"},{"title":"Get the A2A AgentCard for an agent","description":"Returns the Agent-to-Agent (A2A) discovery card for one agent. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the A2A AgentCard for an agent","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/card","href":"/forge/reference/http-api/agents/getcard"},{"title":"Get an agent's configuration","description":"Get an agent's configuration. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get an agent's configuration","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/configuration","href":"/forge/reference/http-api/agents/getconfiguration"},{"title":"Get an agent's readiness","description":"Get an agent's readiness. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get an agent's readiness","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/readiness","href":"/forge/reference/http-api/agents/getreadiness"},{"title":"Get an agent's open setup request","description":"Get an agent's open setup request. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get an agent's open setup request","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/setup-request","href":"/forge/reference/http-api/agents/getsetuprequest"},{"title":"List agent templates","description":"List agent templates. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List agent templates","openapi":"/forge/reference/openapi-v3.json get /api/v3/agent-templates","href":"/forge/reference/http-api/agents/listtemplates"},{"title":"List an agent's procedure grants","description":"List an agent's procedure grants. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List an agent's procedure grants","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/procedure-grants","href":"/forge/reference/http-api/agents/listproceduregrants"},{"title":"List an agent's tool and capability grants","description":"List an agent's tool and capability grants. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List an agent's tool and capability grants","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/grants","href":"/forge/reference/http-api/agents/listgrants"},{"title":"Get an agent's relationships","description":"Get an agent's relationships. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get an agent's relationships","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/relationships","href":"/forge/reference/http-api/agents/getrelationships"},{"title":"List an agent's recent knowledge activity","description":"List an agent's recent knowledge activity. Requires permissions `agents:read` and `knowledge:read`.","deprecated":null,"version":null,"sidebarTitle":"List an agent's recent knowledge activity","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/knowledge-activity","href":"/forge/reference/http-api/agents/listknowledgeactivity"},{"title":"List the knowledge scopes an agent reads","description":"List the knowledge scopes an agent reads. Requires permissions `agents:read` and `knowledge:read`.","deprecated":null,"version":null,"sidebarTitle":"List the knowledge scopes an agent reads","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/readable-scopes","href":"/forge/reference/http-api/agents/listreadablescopes"},{"title":"Create an agent","description":"Creates an agent the calling External App owns, homed at its owning org unit. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Create an agent","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents","href":"/forge/reference/http-api/agents/create"},{"title":"Archive an agent","description":"Archives an agent the calling External App owns; deletePermanently then deletes an archived agent. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Archive an agent","openapi":"/forge/reference/openapi-v3.json delete /api/v3/agents/{agentId}","href":"/forge/reference/http-api/agents/delete"},{"title":"Permanently delete an archived agent","description":"Permanently deletes an archived agent the calling External App owns and purges its memory and knowledge. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete permanently","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/delete-permanently","href":"/forge/reference/http-api/agents/deletepermanently"},{"title":"Assign a tool set to an agent","description":"Grants one workspace tool set to an agent the calling External App owns; never a system tool set and never over an operator deny. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Assign a tool set","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/assign-tool-set","href":"/forge/reference/http-api/agents/assigntoolset"},{"title":"Unassign a tool set from an agent","description":"Revokes the calling External App's grant of one tool set on an agent it owns; an operator deny is left in place. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Unassign a tool set","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/unassign-tool-set","href":"/forge/reference/http-api/agents/unassigntoolset"},{"title":"Assign a skill to an agent","description":"Grants one workspace skill to an agent the calling External App owns, optionally overriding its activation mode; never a builtin or Anthropic skill and never over an operator deny. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Assign a skill","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/assign-skill","href":"/forge/reference/http-api/agents/assignskill"},{"title":"Unassign a skill from an agent","description":"Revokes the calling External App's grant of one skill on an agent it owns; an operator deny is left in place. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Unassign a skill","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/unassign-skill","href":"/forge/reference/http-api/agents/unassignskill"},{"title":"List an agent's versions","description":"Returns an agent's immutable versions, newest first, identity fields only. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List versions","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/versions","href":"/forge/reference/http-api/agents/listversions"},{"title":"List the published workflows that pin an agent","description":"Returns the published workflow versions that run an agent and the exact version each pins. Requires permission `agents:read`; the credential's scopes must also include `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List consumers","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/consumers","href":"/forge/reference/http-api/agents/listconsumers"},{"title":"Pause an agent","description":"Pauses an active agent — it takes no new work until resumed. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Pause an agent","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/pause","href":"/forge/reference/http-api/agents/pause"},{"title":"Resume a paused agent","description":"Resumes a paused agent. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Resume an agent","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/resume","href":"/forge/reference/http-api/agents/resume"},{"title":"Terminate an agent","description":"Terminates an agent (its `status` becomes `deprecated`); it can no longer be paused or resumed. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Terminate an agent","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/terminate","href":"/forge/reference/http-api/agents/terminate"},{"title":"Assign an agent's accountable owner","description":"Makes an active person the agent's accountable owner and starts a new 90-day review window. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Assign an owner","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/assign-owner","href":"/forge/reference/http-api/agents/assignowner"},{"title":"Acknowledge an agent's owner review","description":"Records that the agent's owner review was done — the next review is due in 90 days. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Acknowledge a review","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/acknowledge-review","href":"/forge/reference/http-api/agents/acknowledgereview"},{"title":"Attest an agent's identity","description":"Records that you, a person, attest the agent's current definition and accountable owner, until its next owner review. Requires permission `agents:manage`, as a person.","deprecated":null,"version":null,"sidebarTitle":"Attest an identity","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/attest-identity","href":"/forge/reference/http-api/agents/attestidentity"},{"title":"Ask for an agent's missing setup","description":"Opens one setup request for the agent's missing setup (connections, knowledge, approvals), asking the people who can provide each; a repeat while the same gaps are open reuses that request. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Request setup","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/request-setup","href":"/forge/reference/http-api/agents/requestsetup"},{"title":"Create an agent from a template","description":"Creates a draft agent from a template at the caller's home. Requires permissions `agents:manage` and `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Create from a template","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/create-from-template","href":"/forge/reference/http-api/agents/createfromtemplate"},{"title":"Assign a procedure to an agent","description":"Grants one procedure you can read to an agent as a tool. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Assign a procedure","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/assign-procedure","href":"/forge/reference/http-api/agents/assignprocedure"},{"title":"Unassign a procedure from an agent","description":"Revokes an agent's grant of one procedure. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Unassign a procedure","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/unassign-procedure","href":"/forge/reference/http-api/agents/unassignprocedure"},{"title":"Assign a tool to an agent","description":"Grants one active tool to an agent, with no overrides. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Assign a tool","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/assign-tool","href":"/forge/reference/http-api/agents/assigntool"},{"title":"Unassign a tool from an agent","description":"Revokes an agent's grant of one tool. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Unassign a tool","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/unassign-tool","href":"/forge/reference/http-api/agents/unassigntool"},{"title":"Replace an agent's exemplars","description":"Replaces a worker agent's exemplars with 2 to 5 entries. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Replace exemplars","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/replace-exemplars","href":"/forge/reference/http-api/agents/replaceexemplars"},{"title":"List agent task runs","description":"List agent task runs. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List agent task runs","openapi":"/forge/reference/openapi-v3.json get /api/v3/agent-task-runs","href":"/forge/reference/http-api/agents/listtaskruns"},{"title":"List agent consultations","description":"List agent consultations. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List agent consultations","openapi":"/forge/reference/openapi-v3.json get /api/v3/agent-consultations","href":"/forge/reference/http-api/agents/listconsultations"},{"title":"Get the agents' hourly, daily or weekly activity rollups (runs, tokens, cost) in a time window, oldest first, a page at a time","description":"Get the agents' hourly, daily or weekly activity rollups (runs, tokens, cost) in a time window, oldest first, a page at a time. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the agents' hourly, daily or weekly activity rollups (runs, tokens, cost) in a time window, oldest first, a page at a time","openapi":"/forge/reference/openapi-v3.json get /api/v3/agent-activity","href":"/forge/reference/http-api/agents/admin/activity"},{"title":"Archive an agent's active Agent Builder conversation by its slug, so its next turn starts clean","description":"Archive an agent's active Agent Builder conversation by its slug, so its next turn starts clean. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Archive an agent's active Agent Builder conversation by its slug, so its next turn starts clean","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/reset-builder","href":"/forge/reference/http-api/agents/admin/reset-builder"},{"title":"Send the Personal key's owner's message to an agent's Agent Builder by its slug and schedule its next turn","description":"Send the Personal key's owner's message to an agent's Agent Builder by its slug and schedule its next turn. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Send the Personal key's owner's message to an agent's Agent Builder by its slug and schedule its next turn","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/send-builder-message","href":"/forge/reference/http-api/agents/admin/send-builder-message"},{"title":"Start a new worker agent draft for the Personal key's owner in the Agent Builder","description":"Start a new worker agent draft for the Personal key's owner in the Agent Builder. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Start a new worker agent draft for the Personal key's owner in the Agent Builder","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/create-draft","href":"/forge/reference/http-api/agents/admin/create-draft"},{"title":"Grant skills to agents by their slugs","description":"Grant skills to agents by their slugs; an agent that already holds a skill keeps one grant. Requires permission `skills:manage`.","deprecated":null,"version":null,"sidebarTitle":"Grant skills to agents by their slugs","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/assign-skills","href":"/forge/reference/http-api/agents/admin/assign-skills"},{"title":"Create a draft agent for the Personal key's owner from the intake questionnaire","description":"Create a draft agent for the Personal key's owner from the intake questionnaire; a T3 or T4 risk tier opens an approval. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Create a draft agent for the Personal key's owner from the intake questionnaire","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/intake","href":"/forge/reference/http-api/agents/admin/intake"},{"title":"Replace an agent's core prompt or extension by its slug","description":"Replace an agent's core prompt or extension by its slug; the edit lapses its attestation. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Replace an agent's core prompt or extension by its slug","openapi":"/forge/reference/openapi-v3.json patch /api/v3/agents/{agentId}/prompt","href":"/forge/reference/http-api/agents/admin/update-prompt"},{"title":"Get the recent run count of up to 50 agents by their slugs","description":"Get the recent run count of up to 50 agents by their slugs. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the recent run count of up to 50 agents by their slugs","openapi":"/forge/reference/openapi-v3.json get /api/v3/agent-run-counts","href":"/forge/reference/http-api/agents/admin/run-counts"},{"title":"Make an exact prior version of an agent its active version again","description":"Make an exact prior version of an agent its active version again; never on a paused, terminated or archived agent. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Make an exact prior version of an agent its active version again","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/reinstate-version","href":"/forge/reference/http-api/agents/admin/reinstate-version"},{"title":"Replace an agent's granted skills or tool sets by its slug","description":"Replace an agent's granted skills or tool sets by its slug. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Replace an agent's granted skills or tool sets by its slug","openapi":"/forge/reference/openapi-v3.json patch /api/v3/agents/{agentId}/capabilities","href":"/forge/reference/http-api/agents/admin/update-capabilities"},{"title":"Update an agent's definition fields by its slug","description":"Update an agent's definition fields by its slug; a change to a canonical field lapses its attestation. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Update an agent's definition fields by its slug","openapi":"/forge/reference/openapi-v3.json patch /api/v3/agents/{agentId}","href":"/forge/reference/http-api/agents/admin/update"}]},{"group":"Skills","icon":"graduation-cap","root":{"title":"Skills","sidebarTitle":"Skills","icon":"graduation-cap","description":"Read and author packaged instruction sets that compose into agent prompts.","href":"/forge/reference/http-api/skills"},"pages":[{"title":"List skill definitions","description":"Pages the platform-global skill catalog, oldest first, behind a unique keyset cursor. Requires permission `skills:read`.","deprecated":null,"version":null,"sidebarTitle":"List skill definitions","openapi":"/forge/reference/openapi-v3.json get /api/v3/skills","href":"/forge/reference/http-api/skills/list"},{"title":"Get a skill by skillId","description":"Returns one skill with every version-defining field (`SkillDetail`). Requires permission `skills:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a skill by skillId","openapi":"/forge/reference/openapi-v3.json get /api/v3/skills/{skillId}","href":"/forge/reference/http-api/skills/get"},{"title":"List a skill's immutable versions","description":"Returns a skill's versions newest minted first, identity fields only. Requires permission `skills:read`.","deprecated":null,"version":null,"sidebarTitle":"List a skill's immutable versions","openapi":"/forge/reference/openapi-v3.json get /api/v3/skills/{skillId}/versions","href":"/forge/reference/http-api/skills/listversions"},{"title":"Create a workspace skill","description":"Creates a workspace skill in the platform-global catalog; any caller holding `skills:read` can then read it. Requires permission `skills:write`.","deprecated":null,"version":null,"sidebarTitle":"Create a workspace skill","openapi":"/forge/reference/openapi-v3.json post /api/v3/skills","href":"/forge/reference/http-api/skills/create"},{"title":"Update a workspace skill","description":"Patches the supplied fields of a workspace skill. Requires permission `skills:write`; also `skills:manage` when the patch carries a status.","deprecated":null,"version":null,"sidebarTitle":"Update a workspace skill","openapi":"/forge/reference/openapi-v3.json patch /api/v3/skills/{skillId}","href":"/forge/reference/http-api/skills/update"},{"title":"List skill sets","description":"List skill sets. Requires permission `skills:read` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"List skill sets","openapi":"/forge/reference/openapi-v3.json get /api/v3/skill-sets","href":"/forge/reference/http-api/skills/listsets"},{"title":"Create a skill set","description":"Creates a workspace skill set with optional starting members. Requires permission `skills:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Create a skill set","openapi":"/forge/reference/openapi-v3.json post /api/v3/skill-sets","href":"/forge/reference/http-api/skills/createset"},{"title":"Update a skill set","description":"Renames or redescribes a workspace skill set. Requires permission `skills:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Update a skill set","openapi":"/forge/reference/openapi-v3.json patch /api/v3/skill-sets/{setId}","href":"/forge/reference/http-api/skills/updateset"},{"title":"Delete a skill set","description":"Deprecates a workspace skill set — it leaves every list, and the agents holding it lose its skills at their next dispatch. Requires permission `skills:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Delete a skill set","openapi":"/forge/reference/openapi-v3.json delete /api/v3/skill-sets/{setId}","href":"/forge/reference/http-api/skills/deleteset"},{"title":"Add a skill to a skill set","description":"Adds a skill to a builtin or workspace skill set; `meta.changed` is false when it was already a member. Requires permission `skills:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Add a skill to a skill set","openapi":"/forge/reference/openapi-v3.json post /api/v3/skill-sets/{setId}/members","href":"/forge/reference/http-api/skills/addsetmember"},{"title":"Remove a skill from a skill set","description":"Removes a skill from a builtin or workspace skill set, including one whose skill was deleted; `meta.changed` is false when it was not a member. Requires permission `skills:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Remove a skill from a skill set","openapi":"/forge/reference/openapi-v3.json delete /api/v3/skill-sets/{setId}/members/{skillId}","href":"/forge/reference/http-api/skills/removesetmember"},{"title":"Archive a skill","description":"Archive a skill; a skill already archived, or any skill with permanent, is deleted and its agent grants revoked. Requires permission `skills:manage`.","deprecated":null,"version":null,"sidebarTitle":"Archive a skill","openapi":"/forge/reference/openapi-v3.json delete /api/v3/skills/{skillId}","href":"/forge/reference/http-api/skills/admin/remove"},{"title":"List the external skill catalogs Forge can browse and import from","description":"List the external skill catalogs Forge can browse and import from. Requires permission `skills:read`.","deprecated":null,"version":null,"sidebarTitle":"List the external skill catalogs Forge can browse and import from","openapi":"/forge/reference/openapi-v3.json get /api/v3/skill-catalog-providers","href":"/forge/reference/http-api/skills/admin/catalogs-providers"},{"title":"Browse one external skill catalog's skills","description":"Browse one external skill catalog's skills. Requires permission `skills:read`.","deprecated":null,"version":null,"sidebarTitle":"Browse one external skill catalog's skills","openapi":"/forge/reference/openapi-v3.json post /api/v3/skill-catalog-providers/{providerId}/browse","href":"/forge/reference/http-api/skills/admin/catalogs-browse"},{"title":"Clone a skill into a new workspace skill under a new skillId","description":"Clone a skill into a new workspace skill under a new skillId; answers the new skill's id. Requires permission `skills:write`.","deprecated":null,"version":null,"sidebarTitle":"Clone a skill into a new workspace skill under a new skillId","openapi":"/forge/reference/openapi-v3.json post /api/v3/skills/{skillId}/clone","href":"/forge/reference/http-api/skills/admin/clone"},{"title":"Enable or disable a skill for every agent","description":"Enable or disable a skill for every agent; a disabled skill is skipped at dispatch. Requires permission `skills:manage`.","deprecated":null,"version":null,"sidebarTitle":"Enable or disable a skill for every agent","openapi":"/forge/reference/openapi-v3.json post /api/v3/skills/{skillId}/set-enabled","href":"/forge/reference/http-api/skills/admin/set-enabled"},{"title":"Import an uploaded skill package (zip) as a draft workspace skill","description":"Import an uploaded skill package (zip) as a draft workspace skill; a package that fails the scan returns its findings. Requires permission `skills:write`.","deprecated":null,"version":null,"sidebarTitle":"Import an uploaded skill package (zip) as a draft workspace skill","openapi":"/forge/reference/openapi-v3.json post /api/v3/skills/{skillId}/packages/import","href":"/forge/reference/http-api/skills/admin/packages-import"},{"title":"Import skills from an external catalog","description":"Import skills from an external catalog; a skill whose key is already present is skipped. Requires permission `skills:write`.","deprecated":null,"version":null,"sidebarTitle":"Import skills from an external catalog","openapi":"/forge/reference/openapi-v3.json post /api/v3/skill-catalog-providers/{providerId}/import","href":"/forge/reference/http-api/skills/admin/catalogs-import"},{"title":"Resolve a skill's procedure references and list the assigned agents missing a grant for one","description":"Resolve a skill's procedure references and list the assigned agents missing a grant for one. Requires permission `skills:read`.","deprecated":null,"version":null,"sidebarTitle":"Resolve a skill's procedure references and list the assigned agents missing a grant for one","openapi":"/forge/reference/openapi-v3.json get /api/v3/skills/{skillId}/procedure-linkage","href":"/forge/reference/http-api/skills/admin/procedure-linkage"},{"title":"Get a skill's open script promotion proposal and the procedures its scripts were lifted into","description":"Get a skill's open script promotion proposal and the procedures its scripts were lifted into. Requires permission `skills:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a skill's open script promotion proposal and the procedures its scripts were lifted into","openapi":"/forge/reference/openapi-v3.json get /api/v3/skills/{skillId}/promotion-state","href":"/forge/reference/http-api/skills/admin/promotion-state"},{"title":"Get how often a skill's scripts ran in the promotion window, against the promotion thresholds","description":"Get how often a skill's scripts ran in the promotion window, against the promotion thresholds; null for a skill with no scripts. Requires permission `skills:read`.","deprecated":null,"version":null,"sidebarTitle":"Get how often a skill's scripts ran in the promotion window, against the promotion thresholds","openapi":"/forge/reference/openapi-v3.json get /api/v3/skills/{skillId}/script-telemetry","href":"/forge/reference/http-api/skills/admin/script-telemetry"},{"title":"Reinstate an immutable skill version as the skill's head","description":"Reinstate an immutable skill version as the skill's head. Requires permission `skills:manage`.","deprecated":null,"version":null,"sidebarTitle":"Reinstate an immutable skill version as the skill's head","openapi":"/forge/reference/openapi-v3.json post /api/v3/skills/{skillId}/reinstate-version","href":"/forge/reference/http-api/skills/admin/versions-reinstate"},{"title":"Replace a workspace skill's exemplars (two to five)","description":"Replace a workspace skill's exemplars (two to five); a catalog skill is refused. Requires permission `skills:manage`.","deprecated":null,"version":null,"sidebarTitle":"Replace a workspace skill's exemplars (two to five)","openapi":"/forge/reference/openapi-v3.json post /api/v3/skills/{skillId}/replace-exemplars","href":"/forge/reference/http-api/skills/admin/exemplars-replace"},{"title":"List skills a page at a time, filtered, sorted and grouped as the Console's skill list is, with each skill's agent usage","description":"List skills a page at a time, filtered, sorted and grouped as the Console's skill list is, with each skill's agent usage. Requires permission `skills:read`.","deprecated":null,"version":null,"sidebarTitle":"List skills a page at a time, filtered, sorted and grouped as the Console's skill list is, with each skill's agent usage","openapi":"/forge/reference/openapi-v3.json get /api/v3/skill-page","href":"/forge/reference/http-api/skills/admin/page"}]},{"group":"Tools","icon":"wrench","root":{"title":"Tools","sidebarTitle":"Tools","icon":"wrench","description":"Read safe metadata from the platform-global tool catalog.","href":"/forge/reference/http-api/tools"},"pages":[{"title":"List tools","description":"Pages the read-only tool catalog. Requires permission and scope `tools:read`.","deprecated":null,"version":null,"sidebarTitle":"List tools","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools","href":"/forge/reference/http-api/tools/list"},{"title":"Get a tool","description":"Returns safe tool metadata and schemas. Requires permission and scope `tools:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a tool","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools/{toolId}","href":"/forge/reference/http-api/tools/get"},{"title":"List tool sets","description":"Lists read-only tool sets. Requires permission and scope `tools:read`.","deprecated":null,"version":null,"sidebarTitle":"List tool sets","openapi":"/forge/reference/openapi-v3.json get /api/v3/tool-sets","href":"/forge/reference/http-api/tools/listsets"},{"title":"List a tool's versions","description":"Returns a tool's immutable versions, newest first, identity fields only. Requires permission and scope `tools:read`.","deprecated":null,"version":null,"sidebarTitle":"List tool versions","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools/{toolId}/versions","href":"/forge/reference/http-api/tools/listversions"},{"title":"List the agents holding a tool","description":"Returns the agents the tool is assigned to (`status=active`, the default) or was revoked from (`status=revoked`), with whether the assignment grants or denies it. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List the agents holding a tool","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools/{toolId}/agents","href":"/forge/reference/http-api/tools/listagents"},{"title":"List a tool's recent calls","description":"Returns the tool's newest calls — status, timing, cost and token usage, and the governance disposition. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List a tool's recent calls","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools/{toolId}/executions","href":"/forge/reference/http-api/tools/listexecutions"},{"title":"Get a tool's usage and cost","description":"Returns the tool's calls, failures, cost and tokens since `sinceMs`, and the agents that called it most among those you can read; calls from agents you cannot read are counted in `hiddenCallerCount`, never named. Requires permissions `agents:read` and `tools:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a tool's usage and cost","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools/{toolId}/usage","href":"/forge/reference/http-api/tools/getusage"},{"title":"List the most used tools","description":"Returns the tools called most in the last seven days, of any status, most calls first. Requires permission `tools:read`.","deprecated":null,"version":null,"sidebarTitle":"List the most used tools","openapi":"/forge/reference/openapi-v3.json get /api/v3/most-used-tools","href":"/forge/reference/http-api/tools/listmostused"},{"title":"List tools needing attention","description":"Returns the tools, of any status, whose input schema is invalid or that are disabled, and why, in catalog order. Requires permission `tools:read`.","deprecated":null,"version":null,"sidebarTitle":"List tools needing attention","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools-needing-attention","href":"/forge/reference/http-api/tools/listneedingattention"},{"title":"List a tool's history","description":"Returns the tool's history events, newest first — the event, its category, the kind of actor and when. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List a tool's history","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools/{toolId}/audit-histories","href":"/forge/reference/http-api/tools/listaudithistory"},{"title":"Count a tool's sandbox rejections","description":"Returns how many of the tool's sandbox commands were rejected since `sinceMs` — a count only, never a command. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Count a tool's sandbox rejections","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools/{toolId}/sandbox-rejections","href":"/forge/reference/http-api/tools/getsandboxrejections"},{"title":"Create a workspace tool set","description":"Creates a workspace tool set whose id is `ws_\u003cslug of the name>` (with a short suffix when taken). Requires permission `tools:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Create a workspace tool set","openapi":"/forge/reference/openapi-v3.json post /api/v3/tool-sets","href":"/forge/reference/http-api/tools/createset"},{"title":"Update a workspace tool set","description":"Update a workspace tool set. Requires permission `tools:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Update a workspace tool set","openapi":"/forge/reference/openapi-v3.json patch /api/v3/tool-sets/{setId}","href":"/forge/reference/http-api/tools/updateset"},{"title":"Delete a workspace tool set","description":"Deletes a workspace tool set and revokes every agent grant of it; the holding agents lose its tools at their next dispatch. Requires permission `tools:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Delete a workspace tool set","openapi":"/forge/reference/openapi-v3.json delete /api/v3/tool-sets/{setId}","href":"/forge/reference/http-api/tools/deleteset"},{"title":"Archive a tool","description":"Archive a tool; a tool already archived is deleted. Requires permission `tools:manage`.","deprecated":null,"version":null,"sidebarTitle":"Archive a tool","openapi":"/forge/reference/openapi-v3.json delete /api/v3/tools/{toolId}","href":"/forge/reference/http-api/tools/admin/remove"},{"title":"Search the cached Pipedream app catalog, a page at a time","description":"Search the cached Pipedream app catalog, a page at a time. Requires permission `tools:read`.","deprecated":null,"version":null,"sidebarTitle":"Search the cached Pipedream app catalog, a page at a time","openapi":"/forge/reference/openapi-v3.json get /api/v3/tool-pipedream-apps","href":"/forge/reference/http-api/tools/admin/pipedream-apps"},{"title":"Deprecate many tools by id and answer how many changed","description":"Deprecate many tools by id and answer how many changed. Requires permission `tools:manage`.","deprecated":null,"version":null,"sidebarTitle":"Deprecate many tools by id and answer how many changed","openapi":"/forge/reference/openapi-v3.json post /api/v3/tool-bulk/deprecate","href":"/forge/reference/http-api/tools/admin/bulk-deprecate"},{"title":"Set the risk level of many tools by id and answer how many changed","description":"Set the risk level of many tools by id and answer how many changed. Requires permission `tools:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set the risk level of many tools by id and answer how many changed","openapi":"/forge/reference/openapi-v3.json post /api/v3/tool-bulk/risk-level","href":"/forge/reference/http-api/tools/admin/bulk-risk-level"},{"title":"Add a tag to, or remove a tag from, many tools by id and answer how many changed","description":"Add a tag to, or remove a tag from, many tools by id and answer how many changed. Requires permission `tools:write`.","deprecated":null,"version":null,"sidebarTitle":"Add a tag to, or remove a tag from, many tools by id and answer how many changed","openapi":"/forge/reference/openapi-v3.json post /api/v3/tool-bulk/tags","href":"/forge/reference/http-api/tools/admin/bulk-tags"},{"title":"Create a draft tool definition and answer its id","description":"Create a draft tool definition and answer its id. Requires permission `tools:write`.","deprecated":null,"version":null,"sidebarTitle":"Create a draft tool definition and answer its id","openapi":"/forge/reference/openapi-v3.json post /api/v3/tools","href":"/forge/reference/http-api/tools/admin/create"},{"title":"Patch a tool's governance — risk level, approval, cost estimate, approval policy or declaration. A change that lowers it also needs tools:manage","description":"Patch a tool's governance — risk level, approval, cost estimate, approval policy or declaration. A change that lowers it also needs tools:manage. Requires permission `tools:write`.","deprecated":null,"version":null,"sidebarTitle":"Patch a tool's governance — risk level, approval, cost estimate, approval policy or declaration. A change that lowers it also needs tools:manage","openapi":"/forge/reference/openapi-v3.json post /api/v3/tools/{toolId}/governance","href":"/forge/reference/http-api/tools/admin/governance"},{"title":"Enable or disable a tool for every agent","description":"Enable or disable a tool for every agent. Requires permission `tools:manage`.","deprecated":null,"version":null,"sidebarTitle":"Enable or disable a tool for every agent","openapi":"/forge/reference/openapi-v3.json post /api/v3/tools/{toolId}/set-enabled","href":"/forge/reference/http-api/tools/admin/set-enabled"},{"title":"Export the workspace tool catalog as a version 1 manifest, with secret-bearing connection fields nulled","description":"Export the workspace tool catalog as a version 1 manifest, with secret-bearing connection fields nulled; code tools, input and output schemas and owner are left out. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Export the workspace tool catalog as a version 1 manifest, with secret-bearing connection fields nulled","openapi":"/forge/reference/openapi-v3.json get /api/v3/tool-catalog-export","href":"/forge/reference/http-api/tools/admin/catalog-export"},{"title":"Get a sandbox command definition by its commandId","description":"Get a sandbox command definition by its commandId. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a sandbox command definition by its commandId","openapi":"/forge/reference/openapi-v3.json get /api/v3/tool-commands/{commandId}","href":"/forge/reference/http-api/tools/admin/commands-get"},{"title":"Import a version 1 tool catalog manifest — skip, upsert or rename tools whose toolId already exists. Overwriting an existing tool also needs tools:manage","description":"Import a version 1 tool catalog manifest — skip, upsert or rename tools whose toolId already exists. Overwriting an existing tool also needs tools:manage; an upsert keeps stored schemas and owner the manifest leaves out. Requires permission `tools:write`.","deprecated":null,"version":null,"sidebarTitle":"Import a version 1 tool catalog manifest — skip, upsert or rename tools whose toolId already exists. Overwriting an existing tool also needs tools:manage","openapi":"/forge/reference/openapi-v3.json post /api/v3/tool-catalog/import","href":"/forge/reference/http-api/tools/admin/catalog-import"},{"title":"List a page of a command's newest invocations with status, timing and cost, without the call content","description":"List a page of a command's newest invocations with status, timing and cost, without the call content; an invocation names its agent only when the key may read that agent. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a command's newest invocations with status, timing and cost, without the call content","openapi":"/forge/reference/openapi-v3.json get /api/v3/tool-commands/{commandId}/recent-invocations","href":"/forge/reference/http-api/tools/admin/commands-recent-invocations"},{"title":"List the sandbox command definitions, newest first, a page at a time, by source, risk class or workspace","description":"List the sandbox command definitions, newest first, a page at a time, by source, risk class or workspace. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List the sandbox command definitions, newest first, a page at a time, by source, risk class or workspace","openapi":"/forge/reference/openapi-v3.json get /api/v3/tool-commands","href":"/forge/reference/http-api/tools/admin/commands"},{"title":"List the skills that grant a sandbox command, by its commandId, newest grant first, a page at a time","description":"List the skills that grant a sandbox command, by its commandId, newest grant first, a page at a time. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List the skills that grant a sandbox command, by its commandId, newest grant first, a page at a time","openapi":"/forge/reference/openapi-v3.json get /api/v3/tool-commands/{commandId}/grants","href":"/forge/reference/http-api/tools/admin/commands-grants"},{"title":"Reinstate an immutable tool version as the tool's head","description":"Reinstate an immutable tool version as the tool's head. Requires permission `tools:manage`.","deprecated":null,"version":null,"sidebarTitle":"Reinstate an immutable tool version as the tool's head","openapi":"/forge/reference/openapi-v3.json post /api/v3/tools/{toolId}/reinstate-version","href":"/forge/reference/http-api/tools/admin/versions-reinstate"},{"title":"Replace a sandbox tool's command whitelist. A stored command keeps who added it","description":"Replace a sandbox tool's command whitelist. A stored command keeps who added it; a new one is recorded as added by the key. Requires permission `tools:manage`.","deprecated":null,"version":null,"sidebarTitle":"Replace a sandbox tool's command whitelist. A stored command keeps who added it","openapi":"/forge/reference/openapi-v3.json post /api/v3/tools/{toolId}/sandbox-commands","href":"/forge/reference/http-api/tools/admin/sandbox-commands"},{"title":"Revoke one tool from many agents by assignment id. Assignments of another tool, already revoked, missing or outside the key's agents:manage reach are skipped","description":"Revoke one tool from many agents by assignment id. Assignments of another tool, already revoked, missing or outside the key's agents:manage reach are skipped. Requires permission `agents:manage`.","deprecated":null,"version":null,"sidebarTitle":"Revoke one tool from many agents by assignment id. Assignments of another tool, already revoked, missing or outside the key's agents:manage reach are skipped","openapi":"/forge/reference/openapi-v3.json post /api/v3/tool-bulk/revoke-from-agents","href":"/forge/reference/http-api/tools/admin/bulk-revoke-from-agents"},{"title":"Patch a tool definition's fields","description":"Patch a tool definition's fields. Requires permission `tools:manage`.","deprecated":null,"version":null,"sidebarTitle":"Patch a tool definition's fields","openapi":"/forge/reference/openapi-v3.json patch /api/v3/tools/{toolId}","href":"/forge/reference/http-api/tools/admin/update"}]},{"group":"Models","icon":"microchip","root":{"title":"Models","sidebarTitle":"Models","icon":"microchip","description":"Browse the global catalog of language models and their recorded catalog state.","href":"/forge/reference/http-api/models"},"pages":[{"title":"List model catalog entries","description":"Lists the model catalog. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List model catalog entries","openapi":"/forge/reference/openapi-v3.json get /api/v3/models","href":"/forge/reference/http-api/models/list"},{"title":"Get a model by ID","description":"Get a model by ID. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a model by ID","openapi":"/forge/reference/openapi-v3.json get /api/v3/models/{modelId}","href":"/forge/reference/http-api/models/get"},{"title":"Get a model's full metadata","description":"Get a model's full metadata. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a model's full metadata","openapi":"/forge/reference/openapi-v3.json get /api/v3/models/{modelId}/detail","href":"/forge/reference/http-api/models/getdetail"},{"title":"List fallback chains","description":"Returns the model fallback chains one page at a time, in the order they were created (a system chain is marked by `isSystem`) — each chain's models in priority order, whether it is active, its purpose and sync status. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List fallback chains","openapi":"/forge/reference/openapi-v3.json get /api/v3/model-fallback-chains","href":"/forge/reference/http-api/models/listfallbackchains"},{"title":"Activate or deactivate a catalog model by its modelId","description":"Activate or deactivate a catalog model by its modelId; answers its new state. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Activate or deactivate a catalog model by its modelId","openapi":"/forge/reference/openapi-v3.json post /api/v3/models/{modelId}/toggle-active","href":"/forge/reference/http-api/models/admin/catalog-toggle-active"},{"title":"Add a model to the catalog, without rates","description":"Add a model to the catalog, without rates; answers its modelId. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Add a model to the catalog, without rates","openapi":"/forge/reference/openapi-v3.json post /api/v3/models","href":"/forge/reference/http-api/models/admin/catalog-create"},{"title":"Create a model fallback chain and answer its id","description":"Create a model fallback chain and answer its id. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create a model fallback chain and answer its id","openapi":"/forge/reference/openapi-v3.json post /api/v3/model-fallback-chains","href":"/forge/reference/http-api/models/admin/fallback-chains-create"},{"title":"Create a model slot that resolves a slot name in one environment to a catalog model, and answer its id","description":"Create a model slot that resolves a slot name in one environment to a catalog model, and answer its id. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create a model slot that resolves a slot name in one environment to a catalog model, and answer its id","openapi":"/forge/reference/openapi-v3.json post /api/v3/model-slots","href":"/forge/reference/http-api/models/admin/slots-create"},{"title":"Delete a model fallback chain","description":"Delete a model fallback chain; a system chain is refused (disable it instead). Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete a model fallback chain","openapi":"/forge/reference/openapi-v3.json delete /api/v3/model-fallback-chains/{fallbackChainId}","href":"/forge/reference/http-api/models/admin/fallback-chains-remove"},{"title":"Delete an agent's model tier routing","description":"Delete an agent's model tier routing. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete an agent's model tier routing","openapi":"/forge/reference/openapi-v3.json delete /api/v3/agents/{agentId}/model-routing","href":"/forge/reference/http-api/models/admin/routing-agents-delete"},{"title":"Delete a model slot","description":"Delete a model slot; an id that names no slot changes nothing. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete a model slot","openapi":"/forge/reference/openapi-v3.json delete /api/v3/model-slots/{slotId}","href":"/forge/reference/http-api/models/admin/slots-delete"},{"title":"List a page of the model slots in creation order, optionally in one environment","description":"List a page of the model slots in creation order, optionally in one environment. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the model slots in creation order, optionally in one environment","openapi":"/forge/reference/openapi-v3.json get /api/v3/model-slots","href":"/forge/reference/http-api/models/admin/slots"},{"title":"Get one model slot by name, in one environment or the first match","description":"Get one model slot by name, in one environment or the first match. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get one model slot by name, in one environment or the first match","openapi":"/forge/reference/openapi-v3.json get /api/v3/model-slot-lookup","href":"/forge/reference/http-api/models/admin/slots-get"},{"title":"List a page of the catalog models whose deprecation date falls within the given days (default 30), in creation order","description":"List a page of the catalog models whose deprecation date falls within the given days (default 30), in creation order. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the catalog models whose deprecation date falls within the given days (default 30), in creation order","openapi":"/forge/reference/openapi-v3.json get /api/v3/models-approaching-deprecation","href":"/forge/reference/http-api/models/admin/approaching-deprecation"},{"title":"Get the organization's default model tier routing, or null when none is set","description":"Get the organization's default model tier routing, or null when none is set. Requires permission `workflows:use`.","deprecated":null,"version":null,"sidebarTitle":"Get the organization's default model tier routing, or null when none is set","openapi":"/forge/reference/openapi-v3.json get /api/v3/model-routing-org-default","href":"/forge/reference/http-api/models/admin/routing-org-default"},{"title":"Get an agent's model tier routing, or null when it has none","description":"Get an agent's model tier routing, or null when it has none. Requires permission `workflows:use`.","deprecated":null,"version":null,"sidebarTitle":"Get an agent's model tier routing, or null when it has none","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/model-routing","href":"/forge/reference/http-api/models/admin/routing-agents-get"},{"title":"List a page of the model tier routing configs, in creation order — the organization default and each readable agent's","description":"List a page of the model tier routing configs, in creation order — the organization default and each readable agent's. Requires permission `workflows:use`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the model tier routing configs, in creation order — the organization default and each readable agent's","openapi":"/forge/reference/openapi-v3.json get /api/v3/model-routing-configs","href":"/forge/reference/http-api/models/admin/routing-configs"},{"title":"Remove a model from the catalog by its modelId","description":"Remove a model from the catalog by its modelId. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Remove a model from the catalog by its modelId","openapi":"/forge/reference/openapi-v3.json delete /api/v3/models/{modelId}","href":"/forge/reference/http-api/models/admin/catalog-remove"},{"title":"Search catalog models by display name, one page at a time in model id order, each with the agents the key may read that use it","description":"Search catalog models by display name, one page at a time in model id order, each with the agents the key may read that use it. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Search catalog models by display name, one page at a time in model id order, each with the agents the key may read that use it","openapi":"/forge/reference/openapi-v3.json get /api/v3/models-with-usage-search","href":"/forge/reference/http-api/models/admin/catalog-search-with-usage"},{"title":"Set an agent's model tier routing","description":"Set an agent's model tier routing; answers the config. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set an agent's model tier routing","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/set-model-routing","href":"/forge/reference/http-api/models/admin/routing-agents-set"},{"title":"Set the organization's default model tier routing and answer the config id","description":"Set the organization's default model tier routing and answer the config id. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set the organization's default model tier routing and answer the config id","openapi":"/forge/reference/openapi-v3.json post /api/v3/model-routing-configs/set-org-default","href":"/forge/reference/http-api/models/admin/routing-org-default-set"},{"title":"Suggest an active replacement for a catalog model, with up to two alternatives","description":"Suggest an active replacement for a catalog model, with up to two alternatives. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Suggest an active replacement for a catalog model, with up to two alternatives","openapi":"/forge/reference/openapi-v3.json get /api/v3/models/{modelId}/replacement-suggestions","href":"/forge/reference/http-api/models/admin/catalog-suggest-replacement"},{"title":"Update a catalog model's metadata by its modelId","description":"Update a catalog model's metadata by its modelId; rates and approvalRequired stay Console-only. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update a catalog model's metadata by its modelId","openapi":"/forge/reference/openapi-v3.json patch /api/v3/models/{modelId}","href":"/forge/reference/http-api/models/admin/catalog-update"},{"title":"Update a model fallback chain's name, description, active flag or members","description":"Update a model fallback chain's name, description, active flag or members. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update a model fallback chain's name, description, active flag or members","openapi":"/forge/reference/openapi-v3.json patch /api/v3/model-fallback-chains/{fallbackChainId}","href":"/forge/reference/http-api/models/admin/fallback-chains-update"},{"title":"Point a model slot at another catalog model or change its description","description":"Point a model slot at another catalog model or change its description. Requires permission `gateway:manage`.","deprecated":null,"version":null,"sidebarTitle":"Point a model slot at another catalog model or change its description","openapi":"/forge/reference/openapi-v3.json patch /api/v3/model-slots/{slotId}","href":"/forge/reference/http-api/models/admin/slots-update"},{"title":"List catalog models a page at a time, filtered, sorted and optionally one group at a time, each with the agents the key may read that use it","description":"List catalog models a page at a time, filtered, sorted and optionally one group at a time, each with the agents the key may read that use it. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List catalog models a page at a time, filtered, sorted and optionally one group at a time, each with the agents the key may read that use it","openapi":"/forge/reference/openapi-v3.json get /api/v3/models-with-usage","href":"/forge/reference/http-api/models/admin/catalog-list-with-usage"}]},{"group":"Memory","icon":"brain","root":{"title":"Memory","sidebarTitle":"Memory","icon":"brain","description":"Read and write agent memory entries across the channel and long-term layers.","href":"/forge/reference/http-api/memory"},"pages":[{"title":"List memory entries","description":"List memory entries. Requires permission `memory:read`.","deprecated":null,"version":null,"sidebarTitle":"List memory entries","openapi":"/forge/reference/openapi-v3.json get /api/v3/memory","href":"/forge/reference/http-api/memory/list"},{"title":"Get a memory entry by ID","description":"Get a memory entry by ID. Requires permission `memory:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a memory entry by ID","openapi":"/forge/reference/openapi-v3.json get /api/v3/memory/{memoryId}","href":"/forge/reference/http-api/memory/get"},{"title":"Create a memory entry","description":"Create a memory entry. Requires permission `memory:write`.","deprecated":null,"version":null,"sidebarTitle":"Create a memory entry","openapi":"/forge/reference/openapi-v3.json post /api/v3/memory","href":"/forge/reference/http-api/memory/create"},{"title":"Update a memory entry","description":"Update a memory entry. Requires permission `memory:write`.","deprecated":null,"version":null,"sidebarTitle":"Update a memory entry","openapi":"/forge/reference/openapi-v3.json patch /api/v3/memory/{memoryId}","href":"/forge/reference/http-api/memory/update"},{"title":"Forget a long-term memory entry","description":"Forget one long-term memory entry. Requires permission `memory:write`.","deprecated":null,"version":null,"sidebarTitle":"Forget a long-term memory entry","openapi":"/forge/reference/openapi-v3.json delete /api/v3/memory/{memoryId}","href":"/forge/reference/http-api/memory/delete"},{"title":"Clear one batch of an agent's channel or long-term memory","description":"Clear one batch of an agent's channel or long-term memory; hasMore says to call again. Requires permission `memory:write`.","deprecated":null,"version":null,"sidebarTitle":"Clear one batch of an agent's channel or long-term memory","openapi":"/forge/reference/openapi-v3.json post /api/v3/memory/clear","href":"/forge/reference/http-api/memory/admin/clear"},{"title":"List an agent's facts and episodes, newest first, omitting those stamped with a company the key cannot read","description":"List an agent's facts and episodes, newest first, omitting those stamped with a company the key cannot read. Requires permission `memory:read`.","deprecated":null,"version":null,"sidebarTitle":"List an agent's facts and episodes, newest first, omitting those stamped with a company the key cannot read","openapi":"/forge/reference/openapi-v3.json get /api/v3/memory-facts","href":"/forge/reference/http-api/memory/admin/facts"}]},{"group":"Chat","icon":"comments","root":{"title":"Chat","sidebarTitle":"Chat","icon":"comments","description":"Drive Hybrid Workforce Chat — channels, sessions, and messages — from external systems.","href":"/forge/reference/http-api/chat"},"pages":[{"title":"List chat channels","description":"Lists the channels the caller holds `chat:read` for at each channel's home org unit, newest first. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List chat channels","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-channels","href":"/forge/reference/http-api/chat/listchannels"},{"title":"Get a chat session","description":"Returns one session in a channel the caller may read. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a chat session","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions/{sessionId}","href":"/forge/reference/http-api/chat/getsession"},{"title":"List messages in a session","description":"Lists a session's transcript, readable as in `getChatSession`. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List messages in a session","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions/{sessionId}/messages","href":"/forge/reference/http-api/chat/listmessages"},{"title":"Create a chat session in a channel","description":"Starts a session in a channel the caller holds `chat:manage` for at the channel's home. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create a chat session in a channel","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-channels/{channelId}/sessions","href":"/forge/reference/http-api/chat/createsession"},{"title":"Send a message to a session","description":"Records a message in a session whose channel the caller holds `chat:use` for at the channel's home. Requires permission `chat:use`.","deprecated":null,"version":null,"sidebarTitle":"Send a message to a session","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-sessions/{sessionId}/messages","href":"/forge/reference/http-api/chat/sendmessage"},{"title":"React to a chat message as the Personal key's owner","description":"React to a chat message as the Personal key's owner; a second reaction replaces the owner's first. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"React to a chat message as the Personal key's owner","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-messages/{messageId}/reactions","href":"/forge/reference/http-api/chat/admin/add-reaction"},{"title":"Remove the Personal key's owner's reaction on a chat message","description":"Remove the Personal key's owner's reaction on a chat message; a message the owner has not reacted to is left as it is. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Remove the Personal key's owner's reaction on a chat message","openapi":"/forge/reference/openapi-v3.json delete /api/v3/chat-messages/{messageId}/reaction","href":"/forge/reference/http-api/chat/admin/remove-reaction"},{"title":"Archive a chat session","description":"Archive a chat session; its blackboards end and its session memory closes. An archived session is left as it is. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Archive a chat session","openapi":"/forge/reference/openapi-v3.json delete /api/v3/chat-sessions/{sessionId}","href":"/forge/reference/http-api/chat/admin/archive"},{"title":"Put a shared agent on a channel as a participant, judge or observer","description":"Put a shared agent on a channel as a participant, judge or observer; answers the new assignment's id. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Put a shared agent on a channel as a participant, judge or observer","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-channels/{channelId}/agent-assignments","href":"/forge/reference/http-api/chat/admin/assign-agent"},{"title":"Take an agent off a channel by its assignment id (one already removed succeeds)","description":"Take an agent off a channel by its assignment id (one already removed succeeds). Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Take an agent off a channel by its assignment id (one already removed succeeds)","openapi":"/forge/reference/openapi-v3.json delete /api/v3/chat-agent-assignments/{assignmentId}","href":"/forge/reference/http-api/chat/admin/remove-agent"},{"title":"Capture one of the Personal key's owner's chat turns as a trace snapshot, as the owner, and answer its short id","description":"Capture one of the Personal key's owner's chat turns as a trace snapshot, as the owner, and answer its short id. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Capture one of the Personal key's owner's chat turns as a trace snapshot, as the owner, and answer its short id","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-turns/{turnId}/trace-snapshots","href":"/forge/reference/http-api/chat/admin/capture-turn-snapshot"},{"title":"Complete a chat session","description":"Complete a chat session; its blackboards end and its session memory closes. A completed or archived session is left as it is. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Complete a chat session","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-sessions/{sessionId}/complete","href":"/forge/reference/http-api/chat/admin/complete"},{"title":"List the chat channels the Personal key's owner can join, by the factory, org unit, group or project each belongs to, and whether the owner has joined each","description":"List the chat channels the Personal key's owner can join, by the factory, org unit, group or project each belongs to, and whether the owner has joined each. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List the chat channels the Personal key's owner can join, by the factory, org unit, group or project each belongs to, and whether the owner has joined each","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/discoverable-chat-channels","href":"/forge/reference/http-api/chat/admin/discoverable-channels"},{"title":"Export one of the Personal key's owner's agent turns as a trace — full and abbreviated markdown and JSON, optionally redacted, with the thread redacted as the key reads it","description":"Export one of the Personal key's owner's agent turns as a trace — full and abbreviated markdown and JSON, optionally redacted, with the thread redacted as the key reads it. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Export one of the Personal key's owner's agent turns as a trace — full and abbreviated markdown and JSON, optionally redacted, with the thread redacted as the key reads it","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-turns/{turnId}/trace","href":"/forge/reference/http-api/chat/admin/turn-trace"},{"title":"Get a chat channel — its name, emoji, scope, the entity it is scoped to, type and status","description":"Get a chat channel — its name, emoji, scope, the entity it is scoped to, type and status. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a chat channel — its name, emoji, scope, the entity it is scoped to, type and status","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-channels/{channelId}","href":"/forge/reference/http-api/chat/admin/channel"},{"title":"Get the messages of one of the Personal key's owner's agent turns — the anchor message and the steps the turn took, with tool output redacted as the key may read it","description":"Get the messages of one of the Personal key's owner's agent turns — the anchor message and the steps the turn took, with tool output redacted as the key may read it. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the messages of one of the Personal key's owner's agent turns — the anchor message and the steps the turn took, with tool output redacted as the key may read it","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-turns/{turnId}/messages","href":"/forge/reference/http-api/chat/admin/turn-messages"},{"title":"Get what one of the Personal key's owner's agent turns recalled — its cases, memories and facts ordered by kind then score, each restricted unless the owner reads it within the key's knowledge:read, and how narrowing changed its searches","description":"Get what one of the Personal key's owner's agent turns recalled — its cases, memories and facts ordered by kind then score, each restricted unless the owner reads it within the key's knowledge:read, and how narrowing changed its searches. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get what one of the Personal key's owner's agent turns recalled — its cases, memories and facts ordered by kind then score, each restricted unless the owner reads it within the key's knowledge:read, and how narrowing changed its searches","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-turns/{turnId}/context","href":"/forge/reference/http-api/chat/admin/turn-context"},{"title":"Resolve a knowledge citation in a chat session to the case it names, when the Personal key's owner reads that case within the key's knowledge:read","description":"Resolve a knowledge citation in a chat session to the case it names, when the Personal key's owner reads that case within the key's knowledge:read; null for an unknown or unreadable ref. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Resolve a knowledge citation in a chat session to the case it names, when the Personal key's owner reads that case within the key's knowledge:read","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions/{sessionId}/citation","href":"/forge/reference/http-api/chat/admin/citation"},{"title":"Join the Personal key's owner to the chat channel for a factory, project or team they belong to, provisioning it if none is active, and answer the channel and its active session","description":"Join the Personal key's owner to the chat channel for a factory, project or team they belong to, provisioning it if none is active, and answer the channel and its active session. Requires permission `chat:use`.","deprecated":null,"version":null,"sidebarTitle":"Join the Personal key's owner to the chat channel for a factory, project or team they belong to, provisioning it if none is active, and answer the channel and its active session","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-channels/join","href":"/forge/reference/http-api/chat/admin/join-channel"},{"title":"Link a chat channel to a Slack channel for syndication through an active Slack connection of the named org unit and workspace","description":"Link a chat channel to a Slack channel for syndication through an active Slack connection of the named org unit and workspace; an existing link is replaced. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Link a chat channel to a Slack channel for syndication through an active Slack connection of the named org unit and workspace","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-channels/{channelId}/set-slack-link","href":"/forge/reference/http-api/chat/admin/set-slack-link"},{"title":"Remove a chat channel's Slack link","description":"Remove a chat channel's Slack link; a channel with no link is left as it is. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Remove a chat channel's Slack link","openapi":"/forge/reference/openapi-v3.json delete /api/v3/chat-channels/{channelId}/slack-link","href":"/forge/reference/http-api/chat/admin/remove-slack-link"},{"title":"Get one of the Personal key's owner's agent turns — its model, timing, status, retries, tokens, cost and status hints","description":"Get one of the Personal key's owner's agent turns — its model, timing, status, retries, tokens, cost and status hints. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get one of the Personal key's owner's agent turns — its model, timing, status, retries, tokens, cost and status hints","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-turns/{turnId}","href":"/forge/reference/http-api/chat/admin/turn"},{"title":"List a page of the Personal key's owner's agent turns on a chat session's agent thread, by turn index, each with its status, index and anchor message order","description":"List a page of the Personal key's owner's agent turns on a chat session's agent thread, by turn index, each with its status, index and anchor message order. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the Personal key's owner's agent turns on a chat session's agent thread, by turn index, each with its status, index and anchor message order","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-threads/{threadId}/turns","href":"/forge/reference/http-api/chat/admin/thread-turns"},{"title":"Get the state of the latest agent turn on a chat session's agent thread when it ran for the Personal key's owner — running, completed or failed, and its error code","description":"Get the state of the latest agent turn on a chat session's agent thread when it ran for the Personal key's owner — running, completed or failed, and its error code. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the state of the latest agent turn on a chat session's agent thread when it ran for the Personal key's owner — running, completed or failed, and its error code","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-threads/{threadId}/latest-turn","href":"/forge/reference/http-api/chat/admin/thread-latest-turn"},{"title":"List a page of a chat session's agent turns on its primary thread, newest first — model, timing, status, tokens, cost and error","description":"List a page of a chat session's agent turns on its primary thread, newest first — model, timing, status, tokens, cost and error. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a chat session's agent turns on its primary thread, newest first — model, timing, status, tokens, cost and error","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions/{sessionId}/turns","href":"/forge/reference/http-api/chat/admin/session-turns"},{"title":"List a page of a chat channel's file attachments, newest first — file name, type, size and the message that carried each","description":"List a page of a chat channel's file attachments, newest first — file name, type, size and the message that carried each. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a chat channel's file attachments, newest first — file name, type, size and the message that carried each","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-channels/{channelId}/attachments","href":"/forge/reference/http-api/chat/admin/channel-attachments"},{"title":"List a page of a chat channel's active participants, people and agents, with each person's worker name and email","description":"List a page of a chat channel's active participants, people and agents, with each person's worker name and email; a Personal key's owner is marked as the current user. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a chat channel's active participants, people and agents, with each person's worker name and email","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-channels/{channelId}/participants","href":"/forge/reference/http-api/chat/admin/channel-participants"},{"title":"List a page of chat sessions across the key's org units, most recently active first, filtered by agent, channel, surface, status, model or activity since","description":"List a page of chat sessions across the key's org units, most recently active first, filtered by agent, channel, surface, status, model or activity since. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of chat sessions across the key's org units, most recently active first, filtered by agent, channel, surface, status, model or activity since","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions","href":"/forge/reference/http-api/chat/admin/sessions"},{"title":"List a page of the Personal key's owner's chat drafts the moderator held, oldest first, with its findings, optionally in one session","description":"List a page of the Personal key's owner's chat drafts the moderator held, oldest first, with its findings, optionally in one session. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the Personal key's owner's chat drafts the moderator held, oldest first, with its findings, optionally in one session","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/chat-pending-drafts","href":"/forge/reference/http-api/chat/admin/my-pending-drafts"},{"title":"List a page of a chat channel's sessions, most recently active first (one status's oldest first), with each one's message and participant counts","description":"List a page of a chat channel's sessions, most recently active first (one status's oldest first), with each one's message and participant counts. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a chat channel's sessions, most recently active first (one status's oldest first), with each one's message and participant counts","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-channels/{channelId}/sessions","href":"/forge/reference/http-api/chat/admin/channel-sessions"},{"title":"List a page of a chat channel's sessions as cards, most recently active first (one status's oldest first) — the channel's primary agent, agent count and each session's last-message preview","description":"List a page of a chat channel's sessions as cards, most recently active first (one status's oldest first) — the channel's primary agent, agent count and each session's last-message preview. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a chat channel's sessions as cards, most recently active first (one status's oldest first) — the channel's primary agent, agent count and each session's last-message preview","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-channels/{channelId}/session-cards","href":"/forge/reference/http-api/chat/admin/channel-session-cards"},{"title":"Pause an active chat session","description":"Pause an active chat session. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Pause an active chat session","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-sessions/{sessionId}/pause","href":"/forge/reference/http-api/chat/admin/pause"},{"title":"Get a chat channel's Slack link — the Slack channel, its connection and workspace, sync direction and status","description":"Get a chat channel's Slack link — the Slack channel, its connection and workspace, sync direction and status; null when it has none. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Get a chat channel's Slack link — the Slack channel, its connection and workspace, sync direction and status","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-channels/{channelId}/slack-link","href":"/forge/reference/http-api/chat/admin/slack-link"},{"title":"Open a captured trace snapshot by its short id — its metadata and short-lived URLs for its markdown and JSON, each withheld when the snapshot's session restricts it from the Personal key's owner","description":"Open a captured trace snapshot by its short id — its metadata and short-lived URLs for its markdown and JSON, each withheld when the snapshot's session restricts it from the Personal key's owner. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Open a captured trace snapshot by its short id — its metadata and short-lived URLs for its markdown and JSON, each withheld when the snapshot's session restricts it from the Personal key's owner","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-trace-snapshots/{shortId}/open","href":"/forge/reference/http-api/chat/admin/trace-snapshot"},{"title":"Get a channel's chat configuration — modality and its settings, assigned agents, judge and whether agents may react","description":"Get a channel's chat configuration — modality and its settings, assigned agents, judge and whether agents may react. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Get a channel's chat configuration — modality and its settings, assigned agents, judge and whether agents may react","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-channels/{channelId}/config","href":"/forge/reference/http-api/chat/admin/config"},{"title":"Get a chat message's reaction counts by emoji and its reaction value","description":"Get a chat message's reaction counts by emoji and its reaction value. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a chat message's reaction counts by emoji and its reaction value","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-messages/{messageId}/reactions","href":"/forge/reference/http-api/chat/admin/reactions"},{"title":"Resume a paused chat session","description":"Resume a paused chat session. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Resume a paused chat session","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-sessions/{sessionId}/resume","href":"/forge/reference/http-api/chat/admin/resume"},{"title":"Search a chat session's agent thread for the Personal key's owner — up to 100 matching messages, most relevant first, each with its role and text. A session whose agent text is withheld from the key is not searched","description":"Search a chat session's agent thread for the Personal key's owner — up to 100 matching messages, most relevant first, each with its role and text. A session whose agent text is withheld from the key is not searched. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Search a chat session's agent thread for the Personal key's owner — up to 100 matching messages, most relevant first, each with its role and text. A session whose agent text is withheld from the key is not searched","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-threads/{threadId}/search","href":"/forge/reference/http-api/chat/admin/thread-search"},{"title":"Set the judge agent that scores a channel's turns","description":"Set the judge agent that scores a channel's turns; the agent must be judge-capable. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set the judge agent that scores a channel's turns","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-channels/{channelId}/set-judge","href":"/forge/reference/http-api/chat/admin/set-judge"},{"title":"Remove a channel's judge agent","description":"Remove a channel's judge agent. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Remove a channel's judge agent","openapi":"/forge/reference/openapi-v3.json delete /api/v3/chat-channels/{channelId}/judge","href":"/forge/reference/http-api/chat/admin/remove-judge"},{"title":"Answer the direct message between the Personal key's owner and one other person, creating it when they have none. The owner must be participantA or participantB","description":"Answer the direct message between the Personal key's owner and one other person, creating it when they have none. The owner must be participantA or participantB. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Answer the direct message between the Personal key's owner and one other person, creating it when they have none. The owner must be participantA or participantB","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-direct-messages","href":"/forge/reference/http-api/chat/admin/direct-message"},{"title":"Answer the direct message between the Personal key's owner and a worker, and its active session, creating either when there is none","description":"Answer the direct message between the Personal key's owner and a worker, and its active session, creating either when there is none. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Answer the direct message between the Personal key's owner and a worker, and its active session, creating either when there is none","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-worker-direct-messages","href":"/forge/reference/http-api/chat/admin/worker-direct-message"},{"title":"Stop every agent in an active chat session","description":"Stop every agent in an active chat session; agents halt before their next model or tool call. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Stop every agent in an active chat session","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-sessions/{sessionId}/stop","href":"/forge/reference/http-api/chat/admin/stop"},{"title":"Ask a chat session's running turn to stop at its next checkpoint","description":"Ask a chat session's running turn to stop at its next checkpoint. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Ask a chat session's running turn to stop at its next checkpoint","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-sessions/{sessionId}/interrupt","href":"/forge/reference/http-api/chat/admin/interrupt"},{"title":"Set how a channel's agents take turns (directed, round robin, relevance gated or broadcast) and its turn settings","description":"Set how a channel's agents take turns (directed, round robin, relevance gated or broadcast) and its turn settings. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set how a channel's agents take turns (directed, round robin, relevance gated or broadcast) and its turn settings","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-channels/{channelId}/set-modality","href":"/forge/reference/http-api/chat/admin/modality"},{"title":"Allow or stop agents reacting to messages in a channel","description":"Allow or stop agents reacting to messages in a channel. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Allow or stop agents reacting to messages in a channel","openapi":"/forge/reference/openapi-v3.json post /api/v3/chat-channels/{channelId}/set-agent-reactions","href":"/forge/reference/http-api/chat/admin/agent-reactions"},{"title":"Update platform chat settings — how many channels the Console shows at first","description":"Update platform chat settings — how many channels the Console shows at first. Requires permission `chat:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update platform chat settings — how many channels the Console shows at first","openapi":"/forge/reference/openapi-v3.json patch /api/v3/chat-settings","href":"/forge/reference/http-api/chat/admin/settings"},{"title":"Get a chat session with its channel, linked entity and message count","description":"Get a chat session with its channel, linked entity and message count. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a chat session with its channel, linked entity and message count","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions/{sessionId}/overview","href":"/forge/reference/http-api/chat/admin/session"},{"title":"Get a chat session's board row — surface, opening line, participating agents and token rollup","description":"Get a chat session's board row — surface, opening line, participating agents and token rollup. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a chat session's board row — surface, opening line, participating agents and token rollup","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions/{sessionId}/board-row","href":"/forge/reference/http-api/chat/admin/session-detail"},{"title":"List a page of the active chat channels the Personal key's owner takes part in","description":"List a page of the active chat channels the Personal key's owner takes part in. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the active chat channels the Personal key's owner takes part in","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/chat-channels","href":"/forge/reference/http-api/chat/admin/my-channels"},{"title":"Search the chat channels the Personal key's owner can reach by name or context name (at least two characters), most recently active first","description":"Search the chat channels the Personal key's owner can reach by name or context name (at least two characters), most recently active first. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Search the chat channels the Personal key's owner can reach by name or context name (at least two characters), most recently active first","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-channel-search","href":"/forge/reference/http-api/chat/admin/channel-search"},{"title":"List a page of a chat session's messages, oldest first","description":"List a page of a chat session's messages, oldest first; knowledge the key may not read is redacted. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a chat session's messages, oldest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions/{sessionId}/redacted-messages","href":"/forge/reference/http-api/chat/admin/session-messages"},{"title":"Get a page of a multi-agent chat session's merged timeline — chat messages and agent-thread events in order","description":"Get a page of a multi-agent chat session's merged timeline — chat messages and agent-thread events in order. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a page of a multi-agent chat session's merged timeline — chat messages and agent-thread events in order","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions/{sessionId}/timeline","href":"/forge/reference/http-api/chat/admin/session-timeline"}]},{"group":"Synthesis","icon":"sparkles","root":{"title":"Synthesis","sidebarTitle":"Synthesis","icon":"sparkles","description":"Read the synthesis queue and Builder drafts, act on synthesis requests, work the Curator's queue, and manage synthesis templates, budget and the just-in-time default.","href":"/forge/reference/http-api/synthesis"},"pages":[{"title":"List synthesis requests","description":"Returns one page of synthesis requests, newest first within a status (`all` orders by status, then newest first), each with its workflow name, signature and possible duplicates. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"List synthesis requests","openapi":"/forge/reference/openapi-v3.json get /api/v3/synthesis-requests","href":"/forge/reference/http-api/synthesis/listrequests"},{"title":"List Builder holds","description":"Returns the draft procedures the Builder holds for operator review, one page at a time, newest hold first. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"List Builder holds","openapi":"/forge/reference/openapi-v3.json get /api/v3/synthesis-builder-holds","href":"/forge/reference/http-api/synthesis/listbuilderholds"},{"title":"Get synthesis request","description":"Returns one synthesis request. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"Get synthesis request","openapi":"/forge/reference/openapi-v3.json get /api/v3/synthesis-requests/{requestId}","href":"/forge/reference/http-api/synthesis/getrequest"},{"title":"Get Builder conversation","description":"Returns the first `limit` messages of the Builder conversation for one synthesis request, oldest first. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"Get Builder conversation","openapi":"/forge/reference/openapi-v3.json get /api/v3/synthesis-requests/{requestId}/builder-conversation","href":"/forge/reference/http-api/synthesis/getbuilderconversation"},{"title":"Promote synthesis requests","description":"Promotes each `provisional` request — the request completes and its primitive replaces the one it supersedes. Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"Promote synthesis requests","openapi":"/forge/reference/openapi-v3.json post /api/v3/synthesis/promote-requests","href":"/forge/reference/http-api/synthesis/promoterequests"},{"title":"Demote synthesis requests","description":"Demotes each `provisional` request with `reason` — the request is rejected, the rejection is recorded for future synthesis, and its cost is reconciled. Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"Demote synthesis requests","openapi":"/forge/reference/openapi-v3.json post /api/v3/synthesis/demote-requests","href":"/forge/reference/http-api/synthesis/demoterequests"},{"title":"Accept synthesis requests","description":"Moves each `awaiting_review` request to `provisional` despite its failing review verdict, and records the overridden verdict in an audit event per request. Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"Accept synthesis requests","openapi":"/forge/reference/openapi-v3.json post /api/v3/synthesis/accept-requests","href":"/forge/reference/http-api/synthesis/acceptrequests"},{"title":"Assign synthesis reviewer","description":"Assigns `reviewerSubject` as the reviewer of each request, or clears the assignment when it is null. Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"Assign synthesis reviewer","openapi":"/forge/reference/openapi-v3.json post /api/v3/synthesis/assign-reviewer","href":"/forge/reference/http-api/synthesis/assignreviewer"},{"title":"List curator recommendations","description":"Returns one page of the Curator's pending recommendations (pairs of skills, agents or procedures it judged to overlap), newest first, optionally of one `kind`. Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"List curator recommendations","openapi":"/forge/reference/openapi-v3.json get /api/v3/synthesis-curator-recommendations","href":"/forge/reference/http-api/synthesis/listcuratorrecommendations"},{"title":"Get curator recommendation","description":"Get a curator recommendation. Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"Get curator recommendation","openapi":"/forge/reference/openapi-v3.json get /api/v3/synthesis-curator-recommendations/{curatorRecommendationId}","href":"/forge/reference/http-api/synthesis/getcuratorrecommendation"},{"title":"Decide curator recommendation","description":"Decide a curator recommendation. Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"Decide curator recommendation","openapi":"/forge/reference/openapi-v3.json post /api/v3/synthesis-curator-recommendations/{curatorRecommendationId}/decide","href":"/forge/reference/http-api/synthesis/decidecuratorrecommendation"},{"title":"Close keep-both curator recommendations","description":"Closes each pending recommendation whose Curator recommendation is `keep_both` as `rejected` — the operator confirms the pair are distinct, and neither primitive changes. Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"Close keep-both curator recommendations","openapi":"/forge/reference/openapi-v3.json post /api/v3/synthesis/close-keep-both-curator-recommendations","href":"/forge/reference/http-api/synthesis/closekeepbothcuratorrecommendations"},{"title":"List synthesis templates","description":"Returns the workspace's synthesis templates — the constraints the Spec Linter checks every Builder draft against — a page at a time, in status and kind order. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"List synthesis templates","openapi":"/forge/reference/openapi-v3.json get /api/v3/synthesis-templates","href":"/forge/reference/http-api/synthesis/listtemplates"},{"title":"Create synthesis template","description":"Creates a template, stored trimmed and `active` unless `status` says otherwise, and answers 201 with it. Requires permission `synthesis:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create synthesis template","openapi":"/forge/reference/openapi-v3.json post /api/v3/synthesis-templates","href":"/forge/reference/http-api/synthesis/createtemplate"},{"title":"Update synthesis template","description":"Changes the fields sent (at least one) and answers 200 with the template. Requires permission `synthesis:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update synthesis template","openapi":"/forge/reference/openapi-v3.json patch /api/v3/synthesis-templates/{templateId}","href":"/forge/reference/http-api/synthesis/updatetemplate"},{"title":"Delete synthesis template","description":"Deletes the template; the Spec Linter stops checking it at the next dispatch. Requires permission `synthesis:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete synthesis template","openapi":"/forge/reference/openapi-v3.json delete /api/v3/synthesis-templates/{templateId}","href":"/forge/reference/http-api/synthesis/deletetemplate"},{"title":"Get synthesis budget","description":"Returns the workspace's synthesis spend budget and its current utilization, or a null `budget` before one is set, with the defaults Console offers for a new budget. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"Get synthesis budget","openapi":"/forge/reference/openapi-v3.json get /api/v3/synthesis-budget","href":"/forge/reference/http-api/synthesis/getbudget"},{"title":"Set synthesis budget","description":"Sets the monthly cap and, when sent, the alert threshold and the rolling window, keeping the others (a new budget takes the defaults); spend so far is unchanged. Requires permission `synthesis:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set synthesis budget","openapi":"/forge/reference/openapi-v3.json post /api/v3/synthesis/set-budget","href":"/forge/reference/http-api/synthesis/setbudget"},{"title":"Get JIT synthesis default","description":"Returns whether new Workflow Architect channels synthesize missing capabilities just in time (`off`, `on` or `ask`), or null when none is set, which channels treat as `off`. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"Get JIT synthesis default","openapi":"/forge/reference/openapi-v3.json get /api/v3/synthesis-jit-default","href":"/forge/reference/http-api/synthesis/getjitdefault"},{"title":"Set JIT synthesis default","description":"Sets the default for new Workflow Architect channels; existing channels keep theirs. Requires permission `synthesis:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set JIT synthesis default","openapi":"/forge/reference/openapi-v3.json post /api/v3/synthesis/set-jit-default","href":"/forge/reference/http-api/synthesis/setjitdefault"}]}]},{"group":"Workflows and runs","icon":"diagram-project","root":{"title":"Workflows and runs API","sidebarTitle":"Workflows and runs","icon":"diagram-project","description":"HTTP API operations to author and dispatch workflows, follow and control runs, read outcomes and files, and work with procedures and Factories.","href":"/forge/reference/http-api/families/workflows-and-runs"},"pages":[{"group":"Workflows","icon":"diagram-project","root":{"title":"Workflows","sidebarTitle":"Workflows","icon":"diagram-project","description":"Discover workflow definitions, read their input schema, publish and test-run drafts, dispatch new runs, and register a signed completion callback.","href":"/forge/reference/http-api/workflows"},"pages":[{"title":"List workflow definitions","description":"Page through the workflows the caller may read. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List workflow definitions","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows","href":"/forge/reference/http-api/workflows/list"},{"title":"Get a workflow definition by id","description":"Fetch one workflow by its document id. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a workflow definition by id","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}","href":"/forge/reference/http-api/workflows/get"},{"title":"Get workflow input schema","description":"Fetch the active (or a named published) version's input contract for typed UI rendering and pre-dispatch validation.","deprecated":null,"version":null,"sidebarTitle":"getInputSchema","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/input-schema","href":"/forge/reference/http-api/workflows/getinputschema"},{"title":"Get a workflow's editable draft","description":"Read a workflow's editable draft — its identity, name, description, factory and canonical typed input contract.","deprecated":null,"version":null,"sidebarTitle":"getDraft","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/draft","href":"/forge/reference/http-api/workflows/getdraft"},{"title":"Create an empty workflow draft","description":"Write the workflow draft shared with the Console builder.","deprecated":null,"version":null,"sidebarTitle":"create","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows","href":"/forge/reference/http-api/workflows/create"},{"title":"Update workflow draft metadata and inputs","description":"Write the workflow draft shared with the Console builder.","deprecated":null,"version":null,"sidebarTitle":"updateDraft","openapi":"/forge/reference/openapi-v3.json patch /api/v3/workflows/{workflowId}/draft","href":"/forge/reference/http-api/workflows/updatedraft"},{"title":"Get a workflow draft's nodes and edges","description":"Read the typed nodes and edges of a workflow's editable draft, bounded, without Console-only values.","deprecated":null,"version":null,"sidebarTitle":"getDraftGraph","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/draft-graph","href":"/forge/reference/http-api/workflows/getdraftgraph"},{"title":"Add a node to a workflow draft","description":"Add one typed node to a workflow's editable draft through the Console builder's checks.","deprecated":null,"version":null,"sidebarTitle":"createDraftNode","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/draft-nodes","href":"/forge/reference/http-api/workflows/createdraftnode"},{"title":"Edit a workflow draft node","description":"Change a draft node's name, description, position or machine-writable configuration.","deprecated":null,"version":null,"sidebarTitle":"updateDraftNode","openapi":"/forge/reference/openapi-v3.json patch /api/v3/workflows/{workflowId}/draft-nodes/{nodeId}","href":"/forge/reference/http-api/workflows/updatedraftnode"},{"title":"Delete a workflow draft node","description":"Delete a draft node and every edge of the draft that touches it.","deprecated":null,"version":null,"sidebarTitle":"deleteDraftNode","openapi":"/forge/reference/openapi-v3.json delete /api/v3/workflows/{workflowId}/draft-nodes/{nodeId}","href":"/forge/reference/http-api/workflows/deletedraftnode"},{"title":"Connect two workflow draft nodes","description":"Add one edge between two nodes of a workflow's editable draft through the Console builder's connection checks.","deprecated":null,"version":null,"sidebarTitle":"createDraftEdge","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/draft-edges","href":"/forge/reference/http-api/workflows/createdraftedge"},{"title":"Edit a workflow draft edge","description":"Change a draft edge's condition, label, error flag, description or gather group.","deprecated":null,"version":null,"sidebarTitle":"updateDraftEdge","openapi":"/forge/reference/openapi-v3.json patch /api/v3/workflows/{workflowId}/draft-edges/{edgeId}","href":"/forge/reference/http-api/workflows/updatedraftedge"},{"title":"Delete a workflow draft edge","description":"Delete one edge of a workflow's editable draft.","deprecated":null,"version":null,"sidebarTitle":"deleteDraftEdge","openapi":"/forge/reference/openapi-v3.json delete /api/v3/workflows/{workflowId}/draft-edges/{edgeId}","href":"/forge/reference/http-api/workflows/deletedraftedge"},{"title":"Validate a workflow draft","description":"Run the Forge Console's validator over a workflow draft and read its findings and publishability, without changing anything.","deprecated":null,"version":null,"sidebarTitle":"validateDraft","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/draft-validation","href":"/forge/reference/http-api/workflows/validatedraft"},{"title":"List a workflow's published versions","description":"Page a workflow's published versions newest first — number, status, publish time and note, and the frozen input contract.","deprecated":null,"version":null,"sidebarTitle":"listVersions","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/versions","href":"/forge/reference/http-api/workflows/listversions"},{"title":"Get a published workflow version","description":"Read one published workflow version — number, status, publish time and note, and the frozen input contract.","deprecated":null,"version":null,"sidebarTitle":"getVersion","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-versions/{versionId}","href":"/forge/reference/http-api/workflows/getversion"},{"title":"Get a published workflow version's nodes and edges","description":"Read the nodes and edges frozen into one published workflow version, bounded, without Console-only values.","deprecated":null,"version":null,"sidebarTitle":"getVersionGraph","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-versions/{versionId}/graph","href":"/forge/reference/http-api/workflows/getversiongraph"},{"title":"Get a workflow draft's Architect status","description":"See whether a workflow draft has a live Workflow Architect conversation and whether a person's decision is pending, with the Console link where the person decides.","deprecated":null,"version":null,"sidebarTitle":"getArchitectStatus","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/architect-status","href":"/forge/reference/http-api/workflows/getarchitectstatus"},{"title":"Get the Workflow Architect's pending plan","description":"Read the plan the Workflow Architect proposed for a workflow draft and is waiting on a person to confirm, with the human task the person decides it on.","deprecated":null,"version":null,"sidebarTitle":"getArchitectPlan","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/architect-plan","href":"/forge/reference/http-api/workflows/getarchitectplan"},{"title":"Get the Workflow Architect's build progress","description":"Read a workflow draft's build manifest and synthesis drive — each plan step's state and each primitive the Architect is building.","deprecated":null,"version":null,"sidebarTitle":"getArchitectProgress","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/architect-progress","href":"/forge/reference/http-api/workflows/getarchitectprogress"},{"title":"Get the pending synthesis confirmation","description":"Read the batch of primitives the Workflow Architect proposes to build for a workflow draft, waiting on a person, with specs, estimates and the coherence verdict.","deprecated":null,"version":null,"sidebarTitle":"getSynthesisConfirmation","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/synthesis-confirmation","href":"/forge/reference/http-api/workflows/getsynthesisconfirmation"},{"title":"Get the Workflow Architect's decisions ledger","description":"Read the plans and synthesis batches already resolved in a workflow draft's Architect conversation, newest first.","deprecated":null,"version":null,"sidebarTitle":"getArchitectDecisions","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/architect-decisions","href":"/forge/reference/http-api/workflows/getarchitectdecisions"},{"title":"Get the Workflow Architect's JIT synthesis mode","description":"Read whether a workflow draft's Architect conversation may synthesize missing primitives just in time, and the workspace default.","deprecated":null,"version":null,"sidebarTitle":"getArchitectJitMode","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/architect-jit-mode","href":"/forge/reference/http-api/workflows/getarchitectjitmode"},{"title":"Ask the Workflow Architect to fix a failed run","description":"Open a failed run's failure in a Workflow Architect conversation — clone a draft from the run's version, or add the failure to the draft's open conversation.","deprecated":null,"version":null,"sidebarTitle":"askArchitectToFixRun","openapi":"/forge/reference/openapi-v3.json post /api/v3/runs/{runId}/ask-architect-to-fix","href":"/forge/reference/http-api/workflows/askarchitecttofixrun"},{"title":"Save a chat task as a workflow","description":"Save a completed Personal Agent task from your own chat as a new workflow whose draft holds the task's steps.","deprecated":null,"version":null,"sidebarTitle":"createFromChatTask","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/create-from-chat-task","href":"/forge/reference/http-api/workflows/createfromchattask"},{"title":"Set the Workflow Architect's JIT synthesis mode","description":"Turn just-in-time synthesis on or off for a workflow draft's Architect conversation.","deprecated":null,"version":null,"sidebarTitle":"setArchitectJitMode","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/set-architect-jit-mode","href":"/forge/reference/http-api/workflows/setarchitectjitmode"},{"title":"Start a Workflow Architect conversation","description":"Create a workflow from a brief and start the Workflow Architect's first turn, acting for a Personal key's owner.","deprecated":null,"version":null,"sidebarTitle":"startArchitectConversation","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/start-architect-conversation","href":"/forge/reference/http-api/workflows/startarchitectconversation"},{"title":"Send the Workflow Architect a message","description":"Send the Workflow Architect the next message on a workflow's draft and start its turn, acting for a Personal key's owner.","deprecated":null,"version":null,"sidebarTitle":"sendArchitectMessage","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/architect-messages","href":"/forge/reference/http-api/workflows/sendarchitectmessage"},{"title":"List the Workflow Architect conversation","description":"Page a workflow draft's Workflow Architect conversation and read the turn's state to know when to read again.","deprecated":null,"version":null,"sidebarTitle":"listArchitectMessages","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/architect-messages","href":"/forge/reference/http-api/workflows/listarchitectmessages"},{"title":"Cancel the Workflow Architect's turn","description":"Ask a workflow draft's running Workflow Architect turn to stop at its next step.","deprecated":null,"version":null,"sidebarTitle":"cancelArchitectTurn","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/cancel-architect-turn","href":"/forge/reference/http-api/workflows/cancelarchitectturn"},{"title":"Reset the Workflow Architect conversation","description":"Archive a workflow draft's Architect conversation so the next message starts a fresh one.","deprecated":null,"version":null,"sidebarTitle":"resetArchitectConversation","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/reset-architect-conversation","href":"/forge/reference/http-api/workflows/resetarchitectconversation"},{"title":"Get a draft node's debug options","description":"Read a draft node and the production runs it can be debugged against.","deprecated":null,"version":null,"sidebarTitle":"getDebugOptions","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/debug-options","href":"/forge/reference/http-api/workflows/getdebugoptions"},{"title":"Prepare a debug attempt","description":"Freeze a draft node, resolve its inputs from a source run, and plan its side effects.","deprecated":null,"version":null,"sidebarTitle":"prepareDebugAttempt","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/debug-attempts","href":"/forge/reference/http-api/workflows/preparedebugattempt"},{"title":"Launch a debug attempt","description":"Run a prepared debug attempt with its plan hash.","deprecated":null,"version":null,"sidebarTitle":"launchDebugAttempt","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflow-debug-attempts/{attemptId}/launch","href":"/forge/reference/http-api/workflows/launchdebugattempt"},{"title":"Get a debug attempt","description":"Read one of your debug attempts.","deprecated":null,"version":null,"sidebarTitle":"getDebugAttempt","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-debug-attempts/{attemptId}","href":"/forge/reference/http-api/workflows/getdebugattempt"},{"title":"Cancel a debug attempt","description":"Stop a queued or running debug attempt.","deprecated":null,"version":null,"sidebarTitle":"cancelDebugAttempt","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflow-debug-attempts/{attemptId}/cancel","href":"/forge/reference/http-api/workflows/canceldebugattempt"},{"title":"List a debug attempt's history","description":"Read an attempt and your earlier attempts of the same node.","deprecated":null,"version":null,"sidebarTitle":"listDebugAttemptHistory","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-debug-attempts/{attemptId}/history","href":"/forge/reference/http-api/workflows/listdebugattempthistory"},{"title":"Compare two debug attempts","description":"Read an attempt beside an earlier finished attempt of the same node.","deprecated":null,"version":null,"sidebarTitle":"compareDebugAttempts","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-debug-attempts/{attemptId}/comparison","href":"/forge/reference/http-api/workflows/comparedebugattempts"},{"title":"List a debug attempt's files","description":"Read the files a debug attempt read and wrote.","deprecated":null,"version":null,"sidebarTitle":"listDebugFiles","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-debug-attempts/{attemptId}/files","href":"/forge/reference/http-api/workflows/listdebugfiles"},{"title":"Get a debug file's download link","description":"Get a download link for a file a debug attempt bound.","deprecated":null,"version":null,"sidebarTitle":"getDebugFileUrl","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-debug-attempts/{attemptId}/file-urls/{fileId}","href":"/forge/reference/http-api/workflows/getdebugfileurl"},{"title":"List a debug attempt's tool calls","description":"Read the tool calls a debug attempt made.","deprecated":null,"version":null,"sidebarTitle":"listDebugToolCalls","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-debug-attempts/{attemptId}/tool-calls","href":"/forge/reference/http-api/workflows/listdebugtoolcalls"},{"title":"Get a published version's preview options","description":"Read a published version's nodes and the production runs it can be previewed against.","deprecated":null,"version":null,"sidebarTitle":"getDebugPreviewOptions","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-versions/{versionId}/debug-preview-options","href":"/forge/reference/http-api/workflows/getdebugpreviewoptions"},{"title":"Preview a published slice's historical inputs","description":"Reconstruct the inputs a slice of a published version would read from a source run.","deprecated":null,"version":null,"sidebarTitle":"previewDebugSlice","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-versions/{versionId}/debug-slice-preview","href":"/forge/reference/http-api/workflows/previewdebugslice"},{"title":"Preview re-pinning a procedure's draft callers","description":"List a procedure's draft callers in workflows you can read, with what re-pinning each to a version changes.","deprecated":null,"version":null,"sidebarTitle":"previewProcedureRepin","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/repin-preview","href":"/forge/reference/http-api/workflows/previewprocedurerepin"},{"title":"Re-pin procedure nodes of a draft","description":"Re-pin the listed procedure nodes of one workflow's draft to a procedure version.","deprecated":null,"version":null,"sidebarTitle":"repinProcedure","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/repin-procedure","href":"/forge/reference/http-api/workflows/repinprocedure"},{"title":"Test a route condition","description":"Evaluate a router branch condition against a sample input.","deprecated":null,"version":null,"sidebarTitle":"testRouteCondition","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/test-route-condition","href":"/forge/reference/http-api/workflows/testroutecondition"},{"title":"List a workflow's triggers","description":"List a workflow's schedules and other triggers — kind, timing, version pin and next fire time.","deprecated":null,"version":null,"sidebarTitle":"listTriggers","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/triggers","href":"/forge/reference/http-api/workflows/listtriggers"},{"title":"Get a workflow trigger","description":"Read one workflow schedule or other trigger — kind, timing, version pin and next fire time.","deprecated":null,"version":null,"sidebarTitle":"getTrigger","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-triggers/{triggerId}","href":"/forge/reference/http-api/workflows/gettrigger"},{"title":"List the schedule roster","description":"List every trigger the caller may read across workflows, with its workflow, ingress config and latest run.","deprecated":null,"version":null,"sidebarTitle":"listScheduleRoster","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-triggers","href":"/forge/reference/http-api/workflows/listscheduleroster"},{"title":"Create a scheduled trigger","description":"Schedule a workflow — a cron trigger or a single one-shot fire.","deprecated":null,"version":null,"sidebarTitle":"createTrigger","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/triggers","href":"/forge/reference/http-api/workflows/createtrigger"},{"title":"Update a scheduled trigger","description":"Change a cron or one-shot trigger's schedule, backfill policy, inputs or enabled flag.","deprecated":null,"version":null,"sidebarTitle":"updateTrigger","openapi":"/forge/reference/openapi-v3.json patch /api/v3/workflow-triggers/{triggerId}","href":"/forge/reference/http-api/workflows/updatetrigger"},{"title":"Pause a scheduled trigger","description":"Stop a cron or one-shot trigger from firing.","deprecated":null,"version":null,"sidebarTitle":"pauseTrigger","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflow-triggers/{triggerId}/pause","href":"/forge/reference/http-api/workflows/pausetrigger"},{"title":"Resume a scheduled trigger","description":"Resume a paused cron or one-shot trigger from its next scheduled time.","deprecated":null,"version":null,"sidebarTitle":"resumeTrigger","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflow-triggers/{triggerId}/resume","href":"/forge/reference/http-api/workflows/resumetrigger"},{"title":"Delete a trigger","description":"Delete a trigger; an ingress trigger's URL stops with it.","deprecated":null,"version":null,"sidebarTitle":"deleteTrigger","openapi":"/forge/reference/openapi-v3.json delete /api/v3/workflow-triggers/{triggerId}","href":"/forge/reference/http-api/workflows/deletetrigger"},{"title":"Create an inbound URL (ingress) trigger","description":"Create a capability URL that starts the workflow on each POST.","deprecated":null,"version":null,"sidebarTitle":"createIngressTrigger","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/ingress-triggers","href":"/forge/reference/http-api/workflows/createingresstrigger"},{"title":"Pause or resume an ingress trigger","description":"Pause or resume an ingress trigger's URL.","deprecated":null,"version":null,"sidebarTitle":"setIngressStatus","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflow-triggers/{triggerId}/set-ingress-status","href":"/forge/reference/http-api/workflows/setingressstatus"},{"title":"Rotate an ingress trigger's token","description":"Mint a new ingress token; the old URL stops at once.","deprecated":null,"version":null,"sidebarTitle":"rotateIngressToken","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflow-triggers/{triggerId}/rotate-ingress-token","href":"/forge/reference/http-api/workflows/rotateingresstoken"},{"title":"Update an ingress trigger's config","description":"Change an ingress trigger's input mode, rate, dedupe header, signing or Customer attribution.","deprecated":null,"version":null,"sidebarTitle":"updateIngressConfig","openapi":"/forge/reference/openapi-v3.json patch /api/v3/workflow-triggers/{triggerId}/ingress-config","href":"/forge/reference/http-api/workflows/updateingressconfig"},{"title":"List fiscal calendars","description":"List the fiscal calendars available to workflow expressions and derived launch inputs.","deprecated":null,"version":null,"sidebarTitle":"listFiscalCalendars","openapi":"/forge/reference/openapi-v3.json get /api/v3/fiscal-calendars","href":"/forge/reference/http-api/workflows/listfiscalcalendars"},{"title":"Get a fiscal calendar","description":"Read one fiscal calendar by its lowercase slug.","deprecated":null,"version":null,"sidebarTitle":"getFiscalCalendar","openapi":"/forge/reference/openapi-v3.json get /api/v3/fiscal-calendars/{calendarName}","href":"/forge/reference/http-api/workflows/getfiscalcalendar"},{"title":"Create a fiscal calendar","description":"Create a fiscal-year calendar that fiscalPeriod() expressions can cite.","deprecated":null,"version":null,"sidebarTitle":"createFiscalCalendar","openapi":"/forge/reference/openapi-v3.json post /api/v3/fiscal-calendars","href":"/forge/reference/http-api/workflows/createfiscalcalendar"},{"title":"Update a fiscal calendar","description":"Change a fiscal calendar's label, description or start month.","deprecated":null,"version":null,"sidebarTitle":"updateFiscalCalendar","openapi":"/forge/reference/openapi-v3.json patch /api/v3/fiscal-calendars/{calendarName}","href":"/forge/reference/http-api/workflows/updatefiscalcalendar"},{"title":"Delete a fiscal calendar","description":"Delete a fiscal calendar no active published workflow version cites.","deprecated":null,"version":null,"sidebarTitle":"deleteFiscalCalendar","openapi":"/forge/reference/openapi-v3.json delete /api/v3/fiscal-calendars/{calendarName}","href":"/forge/reference/http-api/workflows/deletefiscalcalendar"},{"title":"Browse the step library","description":"List the step library, most recently changed first.","deprecated":null,"version":null,"sidebarTitle":"listSteps","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-steps","href":"/forge/reference/http-api/workflows/liststeps"},{"title":"Create a step library entry","description":"Add a reusable step to the step library.","deprecated":null,"version":null,"sidebarTitle":"createStep","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflow-steps","href":"/forge/reference/http-api/workflows/createstep"},{"title":"Update a step library entry","description":"Change the named fields of one step library entry.","deprecated":null,"version":null,"sidebarTitle":"updateStep","openapi":"/forge/reference/openapi-v3.json patch /api/v3/workflow-steps/{stepId}","href":"/forge/reference/http-api/workflows/updatestep"},{"title":"Delete a step library entry","description":"Remove a step from the step library.","deprecated":null,"version":null,"sidebarTitle":"deleteStep","openapi":"/forge/reference/openapi-v3.json delete /api/v3/workflow-steps/{stepId}","href":"/forge/reference/http-api/workflows/deletestep"},{"title":"List an ingress trigger's requests","description":"Read the requests to an ingress (inbound URL) trigger, newest first.","deprecated":null,"version":null,"sidebarTitle":"listIngressInvocations","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-triggers/{triggerId}/ingress-invocations","href":"/forge/reference/http-api/workflows/listingressinvocations"},{"title":"Publish a workflow draft","description":"Publish a workflow's draft as a new active version, through every Console publish gate.","deprecated":null,"version":null,"sidebarTitle":"publishDraft","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/publish-draft","href":"/forge/reference/http-api/workflows/publishdraft"},{"title":"Test-run a workflow draft","description":"Start a test run of a workflow's draft, as the Console's Test button does.","deprecated":null,"version":null,"sidebarTitle":"testRunDraft","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/test-run-draft","href":"/forge/reference/http-api/workflows/testrundraft"},{"title":"Roll back to a published version","description":"Make a superseded workflow version active again.","deprecated":null,"version":null,"sidebarTitle":"rollback","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflow-versions/{versionId}/activate","href":"/forge/reference/http-api/workflows/rollback"},{"title":"Reset a workflow draft to a version","description":"Replace a workflow's draft with a published version, discarding its unpublished edits.","deprecated":null,"version":null,"sidebarTitle":"resetDraft","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/reset-draft","href":"/forge/reference/http-api/workflows/resetdraft"},{"title":"Get a workflow's node capability readiness","description":"Whether each produce node's agent holds the skills, tool sets and external tools the node needs.","deprecated":null,"version":null,"sidebarTitle":"getCapabilityReadiness","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-capability-readiness","href":"/forge/reference/http-api/workflows/getcapabilityreadiness"},{"title":"Get a workflow's agent readiness","description":"Whether each Run-as-Agent node's agent can be dispatched, check by check.","deprecated":null,"version":null,"sidebarTitle":"getAgentReadiness","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/agent-readiness","href":"/forge/reference/http-api/workflows/getagentreadiness"},{"title":"Forecast a workflow run's cost","description":"The expected cost of the next run of a workflow's active version, from its recent completed runs.","deprecated":null,"version":null,"sidebarTitle":"getRunCostForecast","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/run-cost-forecast","href":"/forge/reference/http-api/workflows/getruncostforecast"},{"title":"Retire a workflow","description":"Stop a workflow from being launched.","deprecated":null,"version":null,"sidebarTitle":"retire","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/retire","href":"/forge/reference/http-api/workflows/retire"},{"title":"Unretire a workflow","description":"Allow a retired workflow to be launched again.","deprecated":null,"version":null,"sidebarTitle":"unretire","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/unretire","href":"/forge/reference/http-api/workflows/unretire"},{"title":"Move a workflow to the Trash","description":"Soft-delete a workflow.","deprecated":null,"version":null,"sidebarTitle":"trash","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/trash","href":"/forge/reference/http-api/workflows/trash"},{"title":"Restore a workflow from the Trash","description":"Undo a trash.","deprecated":null,"version":null,"sidebarTitle":"restore","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/restore","href":"/forge/reference/http-api/workflows/restore"},{"title":"Permanently delete a trashed workflow","description":"Delete a trashed workflow and everything it owns.","deprecated":null,"version":null,"sidebarTitle":"purge","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/purge","href":"/forge/reference/http-api/workflows/purge"},{"title":"Set a workflow's tags","description":"Replace a workflow's tags.","deprecated":null,"version":null,"sidebarTitle":"setTags","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/set-tags","href":"/forge/reference/http-api/workflows/settags"},{"title":"Set a workflow's owning org unit","description":"Move a workflow to another owning org unit.","deprecated":null,"version":null,"sidebarTitle":"setOwningOrgUnit","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/set-owning-org-unit","href":"/forge/reference/http-api/workflows/setowningorgunit"},{"title":"Bind a workflow asset file","description":"Bind a platform file to a workflow's asset input.","deprecated":null,"version":null,"sidebarTitle":"replaceAsset","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/{workflowId}/replace-asset","href":"/forge/reference/http-api/workflows/replaceasset"},{"title":"Create a workflow from a template","description":"Instantiate a workflow template.","deprecated":null,"version":null,"sidebarTitle":"createFromTemplate","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/create-from-template","href":"/forge/reference/http-api/workflows/createfromtemplate"},{"title":"List a workflow's asset bindings","description":"The files bound to a workflow's asset inputs.","deprecated":null,"version":null,"sidebarTitle":"listAssets","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/assets","href":"/forge/reference/http-api/workflows/listassets"},{"title":"List workflow templates","description":"The workflow templates.","deprecated":null,"version":null,"sidebarTitle":"listTemplates","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-templates","href":"/forge/reference/http-api/workflows/listtemplates"},{"title":"Find a workflow by name","description":"Look a workflow up by its name.","deprecated":null,"version":null,"sidebarTitle":"getByName","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-lookup","href":"/forge/reference/http-api/workflows/getbyname"},{"title":"Export a workflow as a bundle","description":"Export a workflow and its dependencies as a portable bundle.","deprecated":null,"version":null,"sidebarTitle":"exportBundle","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/bundle-export","href":"/forge/reference/http-api/workflows/exportbundle"},{"title":"Dispatch a workflow run","description":"Launch the active published version of a workflow by name or by id, or one of its published versions by id, and receive the run's durable identity. Requires permission `workflows:use`, plus `files:read` when an input references a staged file.","deprecated":null,"version":null,"sidebarTitle":"Dispatch a workflow run","openapi":"/forge/reference/openapi-v3.json post /api/v3/workflows/dispatch","href":"/forge/reference/http-api/workflows/dispatch"},{"title":"Get each workflow's run count, success rate, average duration and average cost in a time window","description":"Get each workflow's run count, success rate, average duration and average cost in a time window. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Get each workflow's run count, success rate, average duration and average cost in a time window","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflow-performance","href":"/forge/reference/http-api/workflows/admin/performance"}]},{"group":"Runs","icon":"play","root":{"title":"Runs","sidebarTitle":"Runs","icon":"play","description":"Inspect workflow runs and their steps, hand held runs to a person, and cancel, restart or otherwise control a run.","href":"/forge/reference/http-api/runs"},"pages":[{"title":"List workflow runs","description":"Returns the runs you may read, each decided at its home and companies, one page at a time. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"List workflow runs","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs","href":"/forge/reference/http-api/runs/list"},{"title":"Get run detail (with steps, human-step status and outputs)","description":"Get run detail (with steps, human-step status and outputs). Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get run detail","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}","href":"/forge/reference/http-api/runs/get"},{"title":"Get a run's governance hold status and person handoff","description":"Get a run's governance hold status and person handoff. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get run hold status","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/trust-status","href":"/forge/reference/http-api/runs/gettruststatus"},{"title":"List references to the files a run produced","description":"List references to the files a run produced. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"List run files","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/artifacts","href":"/forge/reference/http-api/runs/listartifacts"},{"title":"List a run's structural timeline","description":"List a run's structural timeline. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"List run timeline","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/events","href":"/forge/reference/http-api/runs/listevents"},{"title":"Get where a run came from","description":"Get where a run came from. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get run provenance","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/provenance","href":"/forge/reference/http-api/runs/getprovenance"},{"title":"Get one step of a run","description":"Get one step of a run with its outputs. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get run step","openapi":"/forge/reference/openapi-v3.json get /api/v3/run-steps/{stepId}","href":"/forge/reference/http-api/runs/getstep"},{"title":"Get a run's steps and audit timeline","description":"Get a run's steps and audit timeline. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get run timeline","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/timeline","href":"/forge/reference/http-api/runs/gettimeline"},{"title":"List the validator passes of a run step","description":"List the validator passes of a run step. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"List validator runs","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/validator-runs","href":"/forge/reference/http-api/runs/listvalidatorruns"},{"title":"List the context a run step recalled","description":"List the context a run step recalled. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"List step context","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/step-contexts","href":"/forge/reference/http-api/runs/liststepcontext"},{"title":"Resolve a run's knowledge citation","description":"Resolve a run's knowledge citation. Requires permission `runs:read` and `knowledge:read`.","deprecated":null,"version":null,"sidebarTitle":"Resolve run citation","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/citation-resolution","href":"/forge/reference/http-api/runs/resolvecitation"},{"title":"Find the tool call that produced a run's file","description":"Find the tool call that produced a run's file. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get artifact producer","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/artifact-producers/{fileId}","href":"/forge/reference/http-api/runs/getartifactproducer"},{"title":"List the notifications a run owes","description":"List the notifications a run owes. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"List notification obligations","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/notification-obligations","href":"/forge/reference/http-api/runs/listnotificationobligations"},{"title":"Get a run's debug bundle","description":"Get a run's debug bundle. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get run debug bundle","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/debug-bundle","href":"/forge/reference/http-api/runs/getdebugbundle"},{"title":"Export a run as Markdown","description":"Export a run as Markdown. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Export run as Markdown","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/markdown","href":"/forge/reference/http-api/runs/getmarkdown"},{"title":"List a run step's agent conversation","description":"List the agent conversation of a run step. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"List run step messages","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/step-messages","href":"/forge/reference/http-api/runs/liststepmessages"},{"title":"Get a run's diagnostic timeline","description":"Get a run's diagnostic timeline. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get run diagnostic timeline","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/diagnostic-timeline","href":"/forge/reference/http-api/runs/getdiagnostictimeline"},{"title":"List the runs that have an AI analysis","description":"List the runs that have an AI analysis. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List run analyses","openapi":"/forge/reference/openapi-v3.json get /api/v3/run-analyses","href":"/forge/reference/http-api/runs/listanalyses"},{"title":"Get a run's AI analysis","description":"Get a run's AI analysis. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"Get run analysis","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/analysis","href":"/forge/reference/http-api/runs/getanalysis"},{"title":"List the messages of a run's AI analysis","description":"List the messages of a run's AI analysis. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List run analysis messages","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/analysis-messages","href":"/forge/reference/http-api/runs/listanalysismessages"},{"title":"Request a run's cancellation","description":"Requests cancellation of a workflow run; effects already performed are not rolled back. Requires permission `runs:manage`.","deprecated":null,"version":null,"sidebarTitle":"Cancel a run","openapi":"/forge/reference/openapi-v3.json post /api/v3/runs/{runId}/cancel","href":"/forge/reference/http-api/runs/cancel"},{"title":"Restart a failed run from a step","description":"Restarts a failed run from one of its steps as a new attempt of the same run. Requires permission `runs:manage`.","deprecated":null,"version":null,"sidebarTitle":"Restart a run","openapi":"/forge/reference/openapi-v3.json post /api/v3/runs/{runId}/restart","href":"/forge/reference/http-api/runs/restart"},{"title":"Retry a run's failed notification","description":"Retries one of a run's notifications that needs attention, as a Personal key's owner. Requires permission `runs:manage`.","deprecated":null,"version":null,"sidebarTitle":"Retry a notification","openapi":"/forge/reference/openapi-v3.json post /api/v3/run-notification-obligations/{obligationId}/retry","href":"/forge/reference/http-api/runs/retrynotification"},{"title":"Start an AI analysis of a run","description":"Starts an agent's analysis of a run's root cause and recovery, once per run. Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"Start a run analysis","openapi":"/forge/reference/openapi-v3.json post /api/v3/runs/{runId}/start-analysis","href":"/forge/reference/http-api/runs/startanalysis"},{"title":"Set or clear a run's kill switch","description":"Halts or resumes a run's sandbox commands; it does not cancel the run. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Run kill switch","openapi":"/forge/reference/openapi-v3.json post /api/v3/runs/{runId}/set-kill-switch","href":"/forge/reference/http-api/runs/setkillswitch"},{"title":"List a page of a run's checkpoints, oldest first — the step each one follows, for rewind to name","description":"List a page of a run's checkpoints, oldest first — the step each one follows, for rewind to name. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a run's checkpoints, oldest first — the step each one follows, for rewind to name","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/checkpoints","href":"/forge/reference/http-api/runs/admin/checkpoints"},{"title":"Pause a running delegated run. A paused delegated run cannot be resumed","description":"Pause a running delegated run. A paused delegated run cannot be resumed; cancel it to end it. Requires permission `workflows:use`.","deprecated":null,"version":null,"sidebarTitle":"Pause a running delegated run. A paused delegated run cannot be resumed","openapi":"/forge/reference/openapi-v3.json post /api/v3/runs/{runId}/pause","href":"/forge/reference/http-api/runs/admin/pause"},{"title":"Rewind a run to one of its checkpoints — the checkpoint's state becomes the run's failure snapshot, which a restart resumes from","description":"Rewind a run to one of its checkpoints — the checkpoint's state becomes the run's failure snapshot, which a restart resumes from. Requires permission `workflows:use`.","deprecated":null,"version":null,"sidebarTitle":"Rewind a run to one of its checkpoints — the checkpoint's state becomes the run's failure snapshot, which a restart resumes from","openapi":"/forge/reference/openapi-v3.json post /api/v3/runs/{runId}/rewind","href":"/forge/reference/http-api/runs/admin/rewind"},{"title":"List a page of the knowledge searches one step of a run ran, newest first, one per call, each with the agent that ran it","description":"List a page of the knowledge searches one step of a run ran, newest first, one per call, each with the agent that ran it. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the knowledge searches one step of a run ran, newest first, one per call, each with the agent that ran it","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/step-searches","href":"/forge/reference/http-api/runs/admin/step-searches"}]},{"group":"Outcomes","icon":"flag-checkered","root":{"title":"Outcomes","sidebarTitle":"Outcomes","icon":"flag-checkered","description":"Read the governed outcome a workflow run produced, with its evidence references and pending states.","href":"/forge/reference/http-api/outcomes"},"pages":[{"title":"Get outcome","description":"Returns a ready outcome. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get outcome","openapi":"/forge/reference/openapi-v3.json get /api/v3/outcomes/{outcomeId}","href":"/forge/reference/http-api/outcomes/get"},{"title":"Get an outcome's dossier","description":"Get an outcome's dossier. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get outcome dossier","openapi":"/forge/reference/openapi-v3.json get /api/v3/outcomes/{outcomeId}/dossier","href":"/forge/reference/http-api/outcomes/getdossier"},{"title":"Get run outcome","description":"Returns the outcome state of one attempt (by default the run's current attempt) — running, pending, not_declared, not_applicable, invalid with its diagnostic, or ready with the outcome. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"Get run outcome","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/outcome","href":"/forge/reference/http-api/outcomes/getforrun"},{"title":"List outcomes","description":"Lists ready outcomes newest first, keeping those whose run the caller may read. Requires permission `runs:read`.","deprecated":null,"version":null,"sidebarTitle":"List outcomes","openapi":"/forge/reference/openapi-v3.json get /api/v3/outcomes","href":"/forge/reference/http-api/outcomes/list"},{"title":"List an objective's outcome contributions","description":"Lists the contributions governed outcomes made to an objective, newest first, with the project and objective names Console shows. Requires permission `objectives:read`.","deprecated":null,"version":null,"sidebarTitle":"List objective contributions","openapi":"/forge/reference/openapi-v3.json get /api/v3/outcomes/{outcomeId}/objective-contributions","href":"/forge/reference/http-api/outcomes/listobjectivecontributions"},{"title":"Rate an outcome","description":"Records a 1-5 rating, with optional notes, on an outcome, as Console's rating card does; a repeat overwrites it. Requires permission `workflows:use`.","deprecated":null,"version":null,"sidebarTitle":"Rate outcome","openapi":"/forge/reference/openapi-v3.json post /api/v3/outcomes/{outcomeId}/rate","href":"/forge/reference/http-api/outcomes/rate"}]},{"group":"Files","icon":"file","root":{"title":"Files","sidebarTitle":"Files","icon":"file","description":"Upload raw files and download your uploads and the outputs of runs you may read.","href":"/forge/reference/http-api/files"},"pages":[{"title":"Get a chat attachment's bytes, base64","description":"Get a chat attachment's bytes, base64; the read is recorded before a byte moves, and no URL is minted. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a chat attachment's bytes, base64","openapi":"/forge/reference/openapi-v3.json post /api/v3/files/{fileId}/chat-attachment-content","href":"/forge/reference/http-api/files/admin/chat-attachment-content"},{"title":"Upload a file","description":"Upload one file as the raw request body (not JSON or multipart). Content-Type is the file's media type.","deprecated":null,"version":null,"sidebarTitle":"Upload a file","openapi":"/forge/reference/openapi-v3.json post /api/v3/files","href":"/forge/reference/http-api/files/upload"},{"title":"Get a file's content","description":"Redirect to one file's bytes. The 302 Location is a bearer URL — anyone who holds it can download the file.","deprecated":null,"version":null,"sidebarTitle":"Get a file's content","openapi":"/forge/reference/openapi-v3.json get /api/v3/files/{fileId}/content","href":"/forge/reference/http-api/files/get-content"}]},{"group":"Procedures","icon":"list-check","root":{"title":"Procedures","sidebarTitle":"Procedures","icon":"list-check","description":"Read and administer the procedure catalog (references, callers, bindings, delete, deprecate, rename) and the sandbox endpoints a running procedure calls back through.","href":"/forge/reference/http-api/procedures"},"pages":[{"title":"List procedure families","description":"Returns one page of procedure families, ordered by `procedureId`; each is described by its highest-semver active version among the versions the caller may read, and a family with no visible active version is not listed. Requires permission `procedures:read`.","deprecated":null,"version":null,"sidebarTitle":"List procedure families","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures","href":"/forge/reference/http-api/procedures/list"},{"title":"Get a procedure version","description":"Returns one procedure version's catalog detail with its dispatch usage, hard-delete blockers, and whether any version of the family is used by a current workflow. Requires permission `procedures:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a procedure version","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}","href":"/forge/reference/http-api/procedures/get"},{"title":"List a procedure's versions","description":"Returns every version of one procedure family the caller may read, highest semver first, with status and dispatch usage, in one complete list (`meta.hasMore` is false). Requires permission `procedures:read`.","deprecated":null,"version":null,"sidebarTitle":"List a procedure's versions","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/versions","href":"/forge/reference/http-api/procedures/listversions"},{"title":"Get a procedure version's source","description":"Returns one procedure version's bundled source files exactly as stored, in stored order, each with its UTF-8 byte count. Requires permission `procedures:write`.","deprecated":null,"version":null,"sidebarTitle":"Get procedure source","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/source","href":"/forge/reference/http-api/procedures/getsource"},{"title":"List the published workflows that pin a procedure","description":"Returns the published workflow versions that run a procedure family and the exact version each pins. Requires permission `procedures:read`; the credential's scopes must also include `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List procedure consumers","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/consumers","href":"/forge/reference/http-api/procedures/listconsumers"},{"title":"List what references a procedure","description":"Returns the workflows whose drafts or published versions (superseded ones included — their replayed runs would break) reference any version of the procedure family, grouped by workflow and kind. Requires permission `procedures:manage`.","deprecated":null,"version":null,"sidebarTitle":"List procedure references","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/references","href":"/forge/reference/http-api/procedures/listreferences"},{"title":"List the workflows that pin a procedure version","description":"Returns one page of the published workflow versions whose graph pins this exact version, each once with its pinning node names — who depends on the version you are about to change. Requires permission `procedures:write`.","deprecated":null,"version":null,"sidebarTitle":"List version callers","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/version-callers","href":"/forge/reference/http-api/procedures/listversioncallers"},{"title":"Find procedures with a matching signature","description":"Returns versions of other procedures whose input and output field names match this version's (types are ignored) — candidates for consolidation. Requires permission `procedures:read`.","deprecated":null,"version":null,"sidebarTitle":"Find similar procedures","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/similar-procedures","href":"/forge/reference/http-api/procedures/findsimilar"},{"title":"Diagnose a procedure version's connection bindings","description":"Returns whether each of the version's connection bindings resolves a Credential, each vendor's connections to choose from, and the version's egress allowlist. Requires permission `procedures:manage`.","deprecated":null,"version":null,"sidebarTitle":"Get connection binding","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/connection-binding","href":"/forge/reference/http-api/procedures/getconnectionbinding"},{"title":"Delete procedure versions","description":"Delete procedure versions. Requires permission `procedures:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete procedures","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/delete-versions","href":"/forge/reference/http-api/procedures/delete"},{"title":"Deprecate a procedure version","description":"Deprecates an active version — workflows that pin it keep running, and authors are warned to upgrade. Requires permission `procedures:manage`.","deprecated":null,"version":null,"sidebarTitle":"Deprecate procedure","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/deprecate","href":"/forge/reference/http-api/procedures/deprecate"},{"title":"Rename a procedure","description":"Changes the family's display name by minting a new minor version carrying it (versions never change once minted). Requires permission `procedures:manage`.","deprecated":null,"version":null,"sidebarTitle":"Rename procedure","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/rename","href":"/forge/reference/http-api/procedures/rename"},{"title":"Set a procedure version's connections","description":"Replaces the version's connection bindings with the complete ordered list (`[]` clears them). Requires permission `procedures:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set procedure connections","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/set-connections","href":"/forge/reference/http-api/procedures/setconnections"},{"title":"Get a procedure version's latest validation run","description":"Returns the version's latest validation run as the Procedure Builder card shows it, or a null `run` when it was never validated. Requires permission `procedures:write`.","deprecated":null,"version":null,"sidebarTitle":"Get latest validation run","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/latest-validation-run","href":"/forge/reference/http-api/procedures/getlatestvalidationrun"},{"title":"Cancel a validation run","description":"Marks a running validation run canceled so its sandbox is reclaimed (the running action is not interrupted). Requires permission `procedures:write`.","deprecated":null,"version":null,"sidebarTitle":"Cancel validation run","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedure-validation-runs/{validationRunId}/cancel","href":"/forge/reference/http-api/procedures/cancelvalidationrun"},{"title":"Clone a procedure to the workspace","description":"Drafts a workspace copy of a built-in or marketplace procedure's latest active version under a new family (`\u003corigin>-copy`, `-copy-2`, …), for the Procedure Builder to refine. Requires permission `procedures:write`.","deprecated":null,"version":null,"sidebarTitle":"Clone procedure","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/clone","href":"/forge/reference/http-api/procedures/clone"},{"title":"Dismiss a script-promotion proposal","description":"Dismisses a proposal to promote a skill's script to a procedure. Requires permission `workflows:write`.","deprecated":null,"version":null,"sidebarTitle":"Dismiss script promotion","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedure-script-promotions/{proposalId}/dismiss","href":"/forge/reference/http-api/procedures/dismissscriptpromotion"},{"title":"Promote a procedure version","description":"Promotes a provisional version (active, not yet approved) to approved, and completes its synthesis request. Requires permission `procedures:approve`.","deprecated":null,"version":null,"sidebarTitle":"Promote procedure","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/promote","href":"/forge/reference/http-api/procedures/promote"},{"title":"Request repository review of a procedure version","description":"Opens a pull request in the procedure repository for a provisional version with draft source files, for people to review — an effect outside Forge. Requires permission `procedures:approve`.","deprecated":null,"version":null,"sidebarTitle":"Request procedure review","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/request-review","href":"/forge/reference/http-api/procedures/requestreview"},{"title":"Resolve a procedure's review hold","description":"Resolve a procedure's review hold. Requires permission `approvals:approve`.","deprecated":null,"version":null,"sidebarTitle":"Resolve review hold","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/resolve-review-hold","href":"/forge/reference/http-api/procedures/resolvereviewhold"},{"title":"Start a procedure with the Procedure Builder","description":"Creates a new workspace procedure draft (version 1.0.0) homed at `owningOrgUnitId`, where the caller must hold `procedures:write` (otherwise `403` naming it), and starts the Procedure Builder's first turn. Requires permission `procedures:write`, through a Personal key.","deprecated":null,"version":null,"sidebarTitle":"Start Builder","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/start-builder","href":"/forge/reference/http-api/procedures/startbuilder"},{"title":"Open a procedure in the Procedure Builder","description":"Open a procedure in the Procedure Builder. Requires permission `procedures:write`, through a Personal key.","deprecated":null,"version":null,"sidebarTitle":"Open in Builder","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/open-in-builder","href":"/forge/reference/http-api/procedures/openinbuilder"},{"title":"Send a message to the Procedure Builder","description":"Sends the person's message on the version's Builder conversation and starts the next turn. Requires permission `procedures:write`, through a Personal key.","deprecated":null,"version":null,"sidebarTitle":"Send Builder message","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/builder-messages","href":"/forge/reference/http-api/procedures/sendbuildermessage"},{"title":"Retry the Procedure Builder's failed turn","description":"Runs the turn that just failed again, writing no message. Requires permission `procedures:write`, through a Personal key.","deprecated":null,"version":null,"sidebarTitle":"Retry Builder turn","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/retry-builder-turn","href":"/forge/reference/http-api/procedures/retrybuilderturn"},{"title":"Reset the Procedure Builder conversation","description":"Archives the version's current Builder conversation, so the next message or open starts a fresh one. Requires permission `procedures:write`.","deprecated":null,"version":null,"sidebarTitle":"Reset Builder","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/reset-builder","href":"/forge/reference/http-api/procedures/resetbuilder"},{"title":"Stop the Procedure Builder's running turn","description":"Asks the version's running turn to stop after its current step (a tool already running finishes it). Requires permission `procedures:write`.","deprecated":null,"version":null,"sidebarTitle":"Stop Builder turn","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/stop-builder-turn","href":"/forge/reference/http-api/procedures/stopbuilderturn"},{"title":"List the Procedure Builder conversation","description":"List the Procedure Builder conversation. Requires permission `procedures:write`.","deprecated":null,"version":null,"sidebarTitle":"List Builder messages","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/builder-messages","href":"/forge/reference/http-api/procedures/listbuildermessages"},{"title":"Accept a script-promotion proposal","description":"Accepts a proposal to promote a skill's script to a procedure — the script's procedure is synthesized through the same intake the Workflow Architect uses, for the key's owner under the key's scopes. Requires permission `workflows:write`, through a Personal key.","deprecated":null,"version":null,"sidebarTitle":"Accept script promotion","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedure-script-promotions/{proposalId}/accept","href":"/forge/reference/http-api/procedures/acceptscriptpromotion"},{"title":"Invoke a capability","sidebarTitle":"invokeCapability","icon":"code","description":"Proxy a Convex-side capability provider call from inside a running Procedure sandbox. Authenticated by per-dispatch session token.","href":"/forge/reference/http-api/procedures/invokeCapability"},{"title":"Put a file","sidebarTitle":"putFile","icon":"code","description":"Persist file bytes produced inside a Procedure sandbox via the unified files/bindings model. Same schema as the agent-side putFile tool.","href":"/forge/reference/http-api/procedures/putFile"},{"title":"Get a file","sidebarTitle":"getFile","icon":"code","description":"Read a file the dispatch has access to from inside a Procedure sandbox. Four modes: text, bytes, stream, sandbox.","href":"/forge/reference/http-api/procedures/getFile"}]},{"group":"Factories","icon":"industry","root":{"title":"Factories","sidebarTitle":"Factories","icon":"industry","description":"Inspect factories, their workers, tasks, milestones, spend and catalogs; maintain tasks; message the manager agent; pause, resume or archive a factory.","href":"/forge/reference/http-api/factories"},"pages":[{"title":"List factories","description":"Lists the factories the caller holds `factories:read` for at each factory's home org unit, newest first. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"List factories","openapi":"/forge/reference/openapi-v3.json get /api/v3/factories","href":"/forge/reference/http-api/factories/list"},{"title":"Get a factory by ID","description":"Returns one factory with its first 50 active team members (`teamPartial` is true when more exist) and up to 20 of its tasks in index order. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a factory by ID","openapi":"/forge/reference/openapi-v3.json get /api/v3/factories/{factoryId}","href":"/forge/reference/http-api/factories/get"},{"title":"List workers assigned to a factory","description":"Lists a factory's active team members. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"List workers assigned to a factory","openapi":"/forge/reference/openapi-v3.json get /api/v3/factories/{factoryId}/workers","href":"/forge/reference/http-api/factories/listworkers"},{"title":"Get a factory's token spend over a window","description":"Returns one factory's token spend between `startTime` and `endTime` (epoch ms, inclusive) — totals, and breakdowns by source, model, agent worker and task. Requires permission `factories:read` and `cost:read`, both at the factory's home.","deprecated":null,"version":null,"sidebarTitle":"Get a factory's token spend","openapi":"/forge/reference/openapi-v3.json get /api/v3/factories/{factoryId}/spend","href":"/forge/reference/http-api/factories/getspend"},{"title":"Get a task's factory token spend over a window","description":"Returns one task's factory token spend between `startTime` and `endTime` (epoch ms, inclusive) — totals, and breakdowns by source and model. Requires permission `factories:read` and `cost:read`, both at the home of the task's factory.","deprecated":null,"version":null,"sidebarTitle":"Get a task's token spend","openapi":"/forge/reference/openapi-v3.json get /api/v3/factory-tasks/{taskId}/spend","href":"/forge/reference/http-api/factories/gettaskspend"},{"title":"Get a project's factory token spend over a window","description":"Returns one project's factory token spend between `startTime` and `endTime` (epoch ms, inclusive) — totals, and breakdowns by source and model. Requires permission `factories:read` and `cost:read`, both at the project's home.","deprecated":null,"version":null,"sidebarTitle":"Get a project's token spend","openapi":"/forge/reference/openapi-v3.json get /api/v3/projects/{projectId}/spend","href":"/forge/reference/http-api/factories/getprojectspend"},{"title":"Get a worker's factory token spend over a window","description":"Returns one worker's factory token spend between `startTime` and `endTime` (epoch ms, inclusive) — totals, and breakdowns by source and model. Requires permission `factories:read` and `cost:read`, both at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Get a worker's token spend","openapi":"/forge/reference/openapi-v3.json get /api/v3/factory-workers/{workerId}/spend","href":"/forge/reference/http-api/factories/getworkerspend"},{"title":"List factory tasks","description":"List factory tasks. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"List factory tasks","openapi":"/forge/reference/openapi-v3.json get /api/v3/factory-tasks","href":"/forge/reference/http-api/factories/listtasks"},{"title":"Get a factory task by ID","description":"Returns one task with its description, `assigneeName`, `createdBy` and `github` links when the caller holds `factories:read` at its factory's home org unit. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a factory task by ID","openapi":"/forge/reference/openapi-v3.json get /api/v3/factory-tasks/{taskId}","href":"/forge/reference/http-api/factories/gettask"},{"title":"List a factory's assignments","description":"Lists the projects, workflows and tasks assigned to one factory — `ACTIVE` assignments by default, or those in `status`. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"List a factory's assignments","openapi":"/forge/reference/openapi-v3.json get /api/v3/factories/{factoryId}/assignments","href":"/forge/reference/http-api/factories/listassignments"},{"title":"List a factory's release milestones","description":"Returns one page of the release milestones of one factory, most recently updated first — the milestones its tasks point at, and those the tasks of its projects point at. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"List a factory's releases","openapi":"/forge/reference/openapi-v3.json get /api/v3/factories/{factoryId}/releases","href":"/forge/reference/http-api/factories/listreleases"},{"title":"Create a task on a factory","description":"Creates a `software` task in `BACKLOG` on a factory you may read, filed under the legacy software project exactly as Console does. Requires permission `factories:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create a factory task","openapi":"/forge/reference/openapi-v3.json post /api/v3/factories/{factoryId}/tasks","href":"/forge/reference/http-api/factories/createtask"},{"title":"Edit a factory task","description":"Changes a task's title, description (null clears it), priority or tags; send at least one. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Edit a factory task","openapi":"/forge/reference/openapi-v3.json patch /api/v3/factory-tasks/{taskId}","href":"/forge/reference/http-api/factories/updatetask"},{"title":"Assign a factory task","description":"Assigns the task to an agent by its `workerId` (as `listWorkers` returns it), which must be an active agent member of the task's own factory, else `400 bad_request`; `null` unassigns it. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Assign a factory task","openapi":"/forge/reference/openapi-v3.json post /api/v3/factory-tasks/{taskId}/assign","href":"/forge/reference/http-api/factories/assigntask"},{"title":"Move a factory task to another status","description":"Moves the task to `to` along the task state machine Console uses; a move it does not allow is `400 bad_request`. Requires permission `factories:manage`.","deprecated":null,"version":null,"sidebarTitle":"Move a factory task","openapi":"/forge/reference/openapi-v3.json post /api/v3/factory-tasks/{taskId}/transition","href":"/forge/reference/http-api/factories/transitiontask"},{"title":"Message a factory's manager agent","description":"Stores `content` as your message in one of the factory's chat sessions and schedules the factory's manager agent to answer. Requires permission `factories:manage`.","deprecated":null,"version":null,"sidebarTitle":"Message a factory's manager","openapi":"/forge/reference/openapi-v3.json post /api/v3/factories/{factoryId}/send-message","href":"/forge/reference/http-api/factories/sendmessage"},{"title":"Pause a factory","description":"Pauses an active factory — new work through it is blocked until it is resumed; steps already running finish. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Pause a factory","openapi":"/forge/reference/openapi-v3.json post /api/v3/factories/{factoryId}/pause","href":"/forge/reference/http-api/factories/pause"},{"title":"Resume a factory","description":"Resumes a paused factory to the status it had when it was paused (ACTIVE when none was recorded). Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Resume a factory","openapi":"/forge/reference/openapi-v3.json post /api/v3/factories/{factoryId}/resume","href":"/forge/reference/http-api/factories/resume"},{"title":"Archive a factory","description":"Archives the factory permanently — it cannot be paused, resumed or reactivated afterwards. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Archive a factory","openapi":"/forge/reference/openapi-v3.json delete /api/v3/factories/{factoryId}","href":"/forge/reference/http-api/factories/archive"},{"title":"List factory blueprints","description":"Lists the deployment's factory blueprints, newest first — ACTIVE ones, or every blueprint with `includeDeprecated=true`, optionally of one `factoryTypeId`. Requires permission `factories:read`, held at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List factory blueprints","openapi":"/forge/reference/openapi-v3.json get /api/v3/factory-blueprints","href":"/forge/reference/http-api/factories/listblueprints"},{"title":"Get a factory blueprint by ID","description":"Returns one blueprint from the deployment's catalog. Requires permission `factories:read`, held at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Get a factory blueprint","openapi":"/forge/reference/openapi-v3.json get /api/v3/factory-blueprints/{blueprintId}","href":"/forge/reference/http-api/factories/getblueprint"},{"title":"Get a factory type by ID","description":"Returns one factory type from the deployment's catalog by its type ID. Requires permission `factories:read`, held at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Get a factory type","openapi":"/forge/reference/openapi-v3.json get /api/v3/factory-types/{typeId}","href":"/forge/reference/http-api/factories/gettype"},{"title":"List the indexed codebase's files","description":"Returns one page of the files in the deployment's indexed codebase, in path order, each once with its whole chunk count. Requires permission `factories:read`, held at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List codebase files","openapi":"/forge/reference/openapi-v3.json get /api/v3/factory-codebase-files","href":"/forge/reference/http-api/factories/listcodebasefiles"},{"title":"Search the indexed codebase","description":"Returns up to `limit` chunks of the deployment's indexed codebase whose text matches `query`, a text match over chunk text. Requires permission `factories:read`, held at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Search the codebase","openapi":"/forge/reference/openapi-v3.json get /api/v3/factory-codebase-search","href":"/forge/reference/http-api/factories/searchcodebase"}]}]},{"group":"Planning","icon":"bullseye","root":{"title":"Planning API","sidebarTitle":"Planning","icon":"bullseye","description":"HTTP API operations for objectives and key results, roadmaps, workstreams and milestones, planning projections and projects.","href":"/forge/reference/http-api/families/planning"},"pages":[{"group":"Objectives","icon":"bullseye","root":{"title":"Objectives","sidebarTitle":"Objectives","icon":"bullseye","description":"Read and write objectives and key-result progress over the Platform API.","href":"/forge/reference/http-api/objectives"},"pages":[{"title":"List objectives","description":"Page objectives with optional owner and status filters.","deprecated":null,"version":null,"sidebarTitle":"List","openapi":"/forge/reference/openapi-v3.json get /api/v3/objectives","href":"/forge/reference/http-api/objectives/list"},{"title":"Get objective","description":"Read one objective by id.","deprecated":null,"version":null,"sidebarTitle":"Get","openapi":"/forge/reference/openapi-v3.json get /api/v3/objectives/{objectiveId}","href":"/forge/reference/http-api/objectives/get"},{"title":"List objective key results","description":"Read key-result progress for one objective.","deprecated":null,"version":null,"sidebarTitle":"Listkeyresults","openapi":"/forge/reference/openapi-v3.json get /api/v3/objectives/{objectiveId}/key-results","href":"/forge/reference/http-api/objectives/listkeyresults"},{"title":"Create objective","description":"Creates a DRAFT objective owned by the company or an org unit; `ownerRefId` is recorded as sent. Requires permission `objectives:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create objective","openapi":"/forge/reference/openapi-v3.json post /api/v3/objectives","href":"/forge/reference/http-api/objectives/create"},{"title":"Update objective","description":"Changes an objective's title, description, owner, status or target date. Requires permission `objectives:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update objective","openapi":"/forge/reference/openapi-v3.json patch /api/v3/objectives/{objectiveId}","href":"/forge/reference/http-api/objectives/update"},{"title":"Archive objective","description":"Archives an objective by setting its status to CANCELLED. Requires permission `objectives:manage`.","deprecated":null,"version":null,"sidebarTitle":"Archive objective","openapi":"/forge/reference/openapi-v3.json delete /api/v3/objectives/{objectiveId}","href":"/forge/reference/http-api/objectives/archive"},{"title":"Add key result","description":"Adds a key result to an existing objective, starting at currentValue 0 and ON_TRACK. Requires permission `objectives:manage`.","deprecated":null,"version":null,"sidebarTitle":"Add key result","openapi":"/forge/reference/openapi-v3.json post /api/v3/objectives/{objectiveId}/key-results","href":"/forge/reference/http-api/objectives/addkeyresult"},{"title":"Update key result","description":"Changes a key result's title, target, progress, unit or status. Requires permission `objectives:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update key result","openapi":"/forge/reference/openapi-v3.json patch /api/v3/objective-key-results/{keyResultId}","href":"/forge/reference/http-api/objectives/updatekeyresult"},{"title":"Remove key result","description":"Deletes a key result permanently, as the Console does. Requires permission `objectives:manage`.","deprecated":null,"version":null,"sidebarTitle":"Remove key result","openapi":"/forge/reference/openapi-v3.json delete /api/v3/objective-key-results/{keyResultId}","href":"/forge/reference/http-api/objectives/removekeyresult"}]},{"group":"Roadmaps and planning","icon":"road","root":{"title":"Planning projections","sidebarTitle":"Planning projections","icon":"route","description":"Read the Blueprint critical path and blocked tasks over the Platform API.","href":"/forge/reference/http-api/planning"},"pages":[{"title":"Roadmaps","sidebarTitle":"Roadmaps","icon":"road","description":"Read and maintain Blueprint roadmaps over the Platform API.","href":"/forge/reference/http-api/roadmaps"},{"title":"List roadmaps","description":"Page roadmaps with optional owner and status filters.","deprecated":null,"version":null,"sidebarTitle":"List roadmaps","openapi":"/forge/reference/openapi-v3.json get /api/v3/roadmaps","href":"/forge/reference/http-api/roadmaps/list"},{"title":"Get roadmap","description":"Read one roadmap by id.","deprecated":null,"version":null,"sidebarTitle":"Get roadmap","openapi":"/forge/reference/openapi-v3.json get /api/v3/roadmaps/{roadmapId}","href":"/forge/reference/http-api/roadmaps/get"},{"title":"Create roadmap","description":"Creates a roadmap owned by the company, a department or a team, DRAFT unless a status is given; `ownerRefId` is recorded as sent. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create roadmap","openapi":"/forge/reference/openapi-v3.json post /api/v3/roadmaps","href":"/forge/reference/http-api/roadmaps/create"},{"title":"Update roadmap","description":"Changes a roadmap's name, description, owner or status; status ARCHIVED archives it. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update roadmap","openapi":"/forge/reference/openapi-v3.json patch /api/v3/roadmaps/{roadmapId}","href":"/forge/reference/http-api/roadmaps/update"},{"title":"Workstreams","sidebarTitle":"Workstreams","icon":"layer-group","description":"Read and maintain Blueprint workstreams over the Platform API.","href":"/forge/reference/http-api/workstreams"},{"title":"List workstreams","description":"Page workstreams with optional owner and status filters.","deprecated":null,"version":null,"sidebarTitle":"List workstreams","openapi":"/forge/reference/openapi-v3.json get /api/v3/workstreams","href":"/forge/reference/http-api/workstreams/list"},{"title":"Get workstream","description":"Read one workstream by id.","deprecated":null,"version":null,"sidebarTitle":"Get workstream","openapi":"/forge/reference/openapi-v3.json get /api/v3/workstreams/{workstreamId}","href":"/forge/reference/http-api/workstreams/get"},{"title":"Create workstream","description":"Creates an ACTIVE workstream owned by the company, a department or a team. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create workstream","openapi":"/forge/reference/openapi-v3.json post /api/v3/workstreams","href":"/forge/reference/http-api/workstreams/create"},{"title":"Update workstream","description":"Changes a workstream's name, description, owner or status; status ARCHIVED archives it. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update workstream","openapi":"/forge/reference/openapi-v3.json patch /api/v3/workstreams/{workstreamId}","href":"/forge/reference/http-api/workstreams/update"},{"title":"Milestones","sidebarTitle":"Milestones","icon":"flag","description":"Read, maintain and rerank Blueprint milestones over the Platform API.","href":"/forge/reference/http-api/milestones"},{"title":"List milestones","description":"Page milestones of a roadmap, a workstream or a release flag.","deprecated":null,"version":null,"sidebarTitle":"List milestones","openapi":"/forge/reference/openapi-v3.json get /api/v3/milestones","href":"/forge/reference/http-api/milestones/list"},{"title":"Get milestone","description":"Read one milestone by id.","deprecated":null,"version":null,"sidebarTitle":"Get milestone","openapi":"/forge/reference/openapi-v3.json get /api/v3/milestones/{milestoneId}","href":"/forge/reference/http-api/milestones/get"},{"title":"Create milestone","description":"Creates a milestone on an existing roadmap and workstream (otherwise `404`), PLANNED and at the end of its roadmap quarter unless given. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create milestone","openapi":"/forge/reference/openapi-v3.json post /api/v3/milestones","href":"/forge/reference/http-api/milestones/create"},{"title":"Update milestone","description":"Changes a milestone; status CANCELLED archives it. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update milestone","openapi":"/forge/reference/openapi-v3.json patch /api/v3/milestones/{milestoneId}","href":"/forge/reference/http-api/milestones/update"},{"title":"Rerank milestones","description":"Gives the listed milestones ranks 0, 1, 2, … in order and answers them in that order. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Rerank milestones","openapi":"/forge/reference/openapi-v3.json post /api/v3/milestones/rerank","href":"/forge/reference/http-api/milestones/rerank"},{"title":"Get critical path","description":"A roadmap's critical path, limited to tasks you may read.","deprecated":null,"version":null,"sidebarTitle":"Get critical path","openapi":"/forge/reference/openapi-v3.json get /api/v3/roadmaps/{roadmapId}/critical-path","href":"/forge/reference/http-api/planning/getcriticalpath"},{"title":"List blocked tasks","description":"Blocked tasks, limited to tasks you may read.","deprecated":null,"version":null,"sidebarTitle":"List blocked tasks","openapi":"/forge/reference/openapi-v3.json get /api/v3/planning-blocked-tasks","href":"/forge/reference/http-api/planning/listblockedtasks"},{"title":"List the blocked tasks the Personal key's owner could help with, newest first — only ordinary project tasks the key may read, never an assignee","description":"List the blocked tasks the Personal key's owner could help with, newest first — only ordinary project tasks the key may read, never an assignee. Requires permission `objectives:read`.","deprecated":null,"version":null,"sidebarTitle":"List the blocked tasks the Personal key's owner could help with, newest first — only ordinary project tasks the key may read, never an assignee","openapi":"/forge/reference/openapi-v3.json get /api/v3/planning-could-help","href":"/forge/reference/http-api/objectives-planning/admin/could-help"},{"title":"List the Personal key's owner's own tasks that wait on a blocker — only ordinary project tasks the key may read","description":"List the Personal key's owner's own tasks that wait on a blocker — only ordinary project tasks the key may read. Requires permission `objectives:read`.","deprecated":null,"version":null,"sidebarTitle":"List the Personal key's owner's own tasks that wait on a blocker — only ordinary project tasks the key may read","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/blockers","href":"/forge/reference/http-api/objectives-planning/admin/my-blockers"}]},{"group":"Projects","icon":"diagram-project","root":{"title":"Projects","sidebarTitle":"Projects","icon":"diagram-project","description":"Read, create, update, transition and transfer projects, change their objective links, manage their ordinary tasks, and staff them directly or through pods through the Platform API.","href":"/forge/reference/http-api/projects"},"pages":[{"title":"List projects","description":"Lists projects the caller may read at each project's home. Requires permission `projects:read`.","deprecated":null,"version":null,"sidebarTitle":"List projects","openapi":"/forge/reference/openapi-v3.json get /api/v3/projects","href":"/forge/reference/http-api/projects/list"},{"title":"Get project","description":"Returns a visible project and its customer relationship. Requires permission `projects:read`.","deprecated":null,"version":null,"sidebarTitle":"Get project","openapi":"/forge/reference/openapi-v3.json get /api/v3/projects/{projectId}","href":"/forge/reference/http-api/projects/get"},{"title":"List project objectives","description":"Returns a visible project's objective links without administrative join-row handles, a page at a time — its `projectObjectives` links in creation order, then its primary link unless one of them names the same objective. Requires permission `projects:read`.","deprecated":null,"version":null,"sidebarTitle":"List objectives","openapi":"/forge/reference/openapi-v3.json get /api/v3/projects/{projectId}/objectives","href":"/forge/reference/http-api/projects/listobjectives"},{"title":"List projects for planning","description":"Lists projects the caller may read at each project's home, each with its customer and task counts (the Console's planning view). Requires permission `projects:read`.","deprecated":null,"version":null,"sidebarTitle":"List projects for planning","openapi":"/forge/reference/openapi-v3.json get /api/v3/projects-for-planning","href":"/forge/reference/http-api/projects/listforplanning"},{"title":"Create project","description":"Creates a PLANNING project owned by an org unit. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create project","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects","href":"/forge/reference/http-api/projects/create"},{"title":"Update project","description":"Changes a project's name, description, start date, target date or purpose statement. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update project","openapi":"/forge/reference/openapi-v3.json patch /api/v3/projects/{projectId}","href":"/forge/reference/http-api/projects/update"},{"title":"Transition project","description":"Moves a project through the canonical status machine; ARCHIVED archives it and ARCHIVED→PLANNING revives it. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Transition project","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/transition","href":"/forge/reference/http-api/projects/transition"},{"title":"Link project objective","description":"Records that a project contributes to an objective with a weight and an optional note. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Link project objective","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/objectives","href":"/forge/reference/http-api/projects/linkobjective"},{"title":"Unlink project objective","description":"Removes a project's contribution link to an objective. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Unlink project objective","openapi":"/forge/reference/openapi-v3.json delete /api/v3/projects/{projectId}/objectives/{objectiveId}","href":"/forge/reference/http-api/projects/unlinkobjective"},{"title":"Transfer project ownership","description":"Hands a project to another team or department. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Transfer project ownership","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/transfer-ownership","href":"/forge/reference/http-api/projects/transferownership"},{"title":"Change project customer","description":"Sets or clears the customer a project is for. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Change project customer","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/change-customer","href":"/forge/reference/http-api/projects/changecustomer"},{"title":"List project tasks","description":"Lists the tasks of a project the caller may read (`projects:read` at its home), newest first. Requires permission `projects:read`.","deprecated":null,"version":null,"sidebarTitle":"List project tasks","openapi":"/forge/reference/openapi-v3.json get /api/v3/projects/{projectId}/tasks","href":"/forge/reference/http-api/projects/listtasks"},{"title":"Get project task","description":"Returns a task of a project the caller may read, with its description. Requires permission `projects:read`.","deprecated":null,"version":null,"sidebarTitle":"Get project task","openapi":"/forge/reference/openapi-v3.json get /api/v3/project-tasks/{taskId}","href":"/forge/reference/http-api/projects/gettask"},{"title":"Create project task","description":"Creates a task under a project; it starts in BACKLOG with kind `generic` and no assignee. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create project task","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/tasks","href":"/forge/reference/http-api/projects/createtask"},{"title":"Update project task","description":"Changes a task's title, description, priority or tags. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update project task","openapi":"/forge/reference/openapi-v3.json patch /api/v3/project-tasks/{taskId}","href":"/forge/reference/http-api/projects/updatetask"},{"title":"Transition project task","description":"Moves a task through the canonical task status machine, including cancel and reopen. Requires permission `projects:manage`.","deprecated":null,"version":null,"sidebarTitle":"Transition project task","openapi":"/forge/reference/openapi-v3.json post /api/v3/project-tasks/{taskId}/transition","href":"/forge/reference/http-api/projects/transitiontask"},{"title":"Get project staffing","description":"Returns the project's direct staffing assignments that overlap the window, each with its worker and whether a project access grant covers the assignment's dates. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get project staffing","openapi":"/forge/reference/openapi-v3.json get /api/v3/projects/{projectId}/staffing","href":"/forge/reference/http-api/projects/getstaffing"},{"title":"Preview staffing assignment","description":"Preview a direct staffing assignment. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview staffing assignment","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/preview-staffing-assignment","href":"/forge/reference/http-api/projects/previewstaffingassignment"},{"title":"Confirm staffing assignment","description":"Staffs one worker on the project from `startsAt`, with an optional end, allocation and delivery role. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Confirm staffing assignment","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/staffing-assignments","href":"/forge/reference/http-api/projects/confirmstaffingassignment"},{"title":"Amend staffing assignment","description":"Changes the delivery role, allocation, start or end of an assignment at `expectedRevision`. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Amend staffing assignment","openapi":"/forge/reference/openapi-v3.json patch /api/v3/projects/{projectId}/staffing-assignments/{assignmentId}","href":"/forge/reference/http-api/projects/amendstaffingassignment"},{"title":"Release staffing assignment","description":"Ends an assignment at `endsAt` with a required `reason`. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Release staffing assignment","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/staffing-assignments/{assignmentId}/release","href":"/forge/reference/http-api/projects/releasestaffingassignment"},{"title":"Get project pod staffing","description":"Returns the project's pod staffing assignments that overlap the window, each with its pod. Requires permission `workforce:read`.","deprecated":null,"version":null,"sidebarTitle":"Get project pod staffing","openapi":"/forge/reference/openapi-v3.json get /api/v3/projects/{projectId}/pod-staffing","href":"/forge/reference/http-api/projects/getpodstaffing"},{"title":"Preview pod staffing","description":"Shows what staffing the pod's members on the project would do — each eligible member with a default proposal, capacity and existing assignments, the members who cannot be staffed and why, and the blockers. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview pod staffing","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/preview-pod-staffing","href":"/forge/reference/http-api/projects/previewpodstaffing"},{"title":"Confirm pod staffing","description":"Records the pod's staffing of the project and confirms the selected members' assignments at the roster revision you previewed. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Confirm pod staffing","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/pod-assignments","href":"/forge/reference/http-api/projects/confirmpodstaffing"},{"title":"Preview pod staffing reconciliation","description":"Compares a pod staffing assignment with the pod's current roster and lists the drift to reconcile. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview pod staffing reconciliation","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/pod-assignments/{podAssignmentId}/preview-reconciliation","href":"/forge/reference/http-api/projects/previewpodstaffingreconciliation"},{"title":"Reconcile pod staffing","description":"Applies confirm, amend and release changes to a pod staffing assignment's members at the revisions you previewed. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Reconcile pod staffing","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/pod-assignments/{podAssignmentId}/reconcile","href":"/forge/reference/http-api/projects/reconcilepodstaffing"},{"title":"Preview pod staffing release","description":"Lists the member assignments a pod staffing assignment originated, which a release can end with it. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview pod staffing release","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/pod-assignments/{podAssignmentId}/preview-release","href":"/forge/reference/http-api/projects/previewpodstaffingrelease"},{"title":"Release pod staffing","description":"Ends a pod staffing assignment at `endsAt` with a required `reason`, and releases the member assignments you list. Requires permission `workforce:manage`.","deprecated":null,"version":null,"sidebarTitle":"Release pod staffing","openapi":"/forge/reference/openapi-v3.json post /api/v3/projects/{projectId}/pod-assignments/{podAssignmentId}/release","href":"/forge/reference/http-api/projects/releasepodstaffing"},{"title":"List a page of the plans for an intake request, ordered by status (descending), as the Console lists them","description":"List a page of the plans for an intake request, ordered by status (descending), as the Console lists them. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the plans for an intake request, ordered by status (descending), as the Console lists them","openapi":"/forge/reference/openapi-v3.json get /api/v3/project-requests/{requestId}/plans","href":"/forge/reference/http-api/projects-staffing/admin/requests-plans"},{"title":"Get one intake request by its id","description":"Get one intake request by its id; an unknown id answers null, as the Console does. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"Get one intake request by its id","openapi":"/forge/reference/openapi-v3.json get /api/v3/project-requests/{requestId}","href":"/forge/reference/http-api/projects-staffing/admin/requests-get"},{"title":"List a page of intake requests — with a status, most recently updated first","description":"List a page of intake requests — with a status, most recently updated first; without one, by status (descending), then most recently updated first. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of intake requests — with a status, most recently updated first","openapi":"/forge/reference/openapi-v3.json get /api/v3/project-requests","href":"/forge/reference/http-api/projects-staffing/admin/requests"},{"title":"List tasks newest first, one page at a time, across projects or of one project, by status or kind — only ordinary project tasks whose project the key may read, never a factory or project-less task","description":"List tasks newest first, one page at a time, across projects or of one project, by status or kind — only ordinary project tasks whose project the key may read, never a factory or project-less task. Requires permission `projects:read`.","deprecated":null,"version":null,"sidebarTitle":"List tasks newest first, one page at a time, across projects or of one project, by status or kind — only ordinary project tasks whose project the key may read, never a factory or project-less task","openapi":"/forge/reference/openapi-v3.json get /api/v3/project-tasks","href":"/forge/reference/http-api/projects-staffing/admin/tasks"}]}]},{"group":"Knowledge","icon":"book","root":{"title":"Knowledge","sidebarTitle":"Knowledge","icon":"lightbulb","description":"Search, ask, add, read and export knowledge; curate cases and review items; manage golden sets and external sources; and read knowledge health and the Learning feed.","href":"/forge/reference/http-api/knowledge"},"pages":[{"title":"Search knowledge chunks","description":"Vector and text search, fused by rank, over the namespaces the caller can read. Requires permission `knowledge:read`.","deprecated":null,"version":null,"sidebarTitle":"Search knowledge chunks","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-chunks/search","href":"/forge/reference/http-api/knowledge/get-chunks"},{"title":"Ask a question grounded in knowledge","description":"Answer a question from retrieved knowledge chunks. Requires permission `knowledge:read`.","deprecated":null,"version":null,"sidebarTitle":"Ask a question grounded in knowledge","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge/ask","href":"/forge/reference/http-api/knowledge/ask"},{"title":"Add a knowledge entry","description":"Ingest content into a namespace the caller can write. Requires permission `knowledge:write`.","deprecated":null,"version":null,"sidebarTitle":"Add a knowledge entry","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-entries","href":"/forge/reference/http-api/knowledge/add-knowledge"},{"title":"Get a knowledge entry","description":"Read one knowledge entry and its text. Requires permission `knowledge:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a knowledge entry","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-entries/{entryId}/lookup","href":"/forge/reference/http-api/knowledge/get"},{"title":"Delete a knowledge entry","description":"Delete one knowledge entry in a namespace the caller can write. Requires permission `knowledge:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete a knowledge entry","openapi":"/forge/reference/openapi-v3.json delete /api/v3/knowledge-entries/{entryId}","href":"/forge/reference/http-api/knowledge/delete"},{"title":"Export a knowledge namespace","description":"Get a 24-hour NDJSON download URL for one readable knowledge namespace — its active entries with full text and, with includeDeleted, its tombstones as metadata only. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Export knowledge","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-export","href":"/forge/reference/http-api/knowledge/export"},{"title":"Get knowledge health","description":"What is broken in the knowledge you can read, and how far behind it is. Requires permission `knowledge:read`.","deprecated":null,"version":null,"sidebarTitle":"Get knowledge health","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-health","href":"/forge/reference/http-api/knowledge/health"},{"title":"Retry a pending knowledge entry","description":"Embed one stuck pending entry again now. Requires permission `knowledge:manage`.","deprecated":null,"version":null,"sidebarTitle":"Retry a pending knowledge entry","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-entries/{entryId}/retry","href":"/forge/reference/http-api/knowledge/retry-pending-entry"},{"title":"Request a knowledge source sync","description":"Ask one knowledge source to sync now. Requires permission `knowledge:manage`.","deprecated":null,"version":null,"sidebarTitle":"Request a knowledge source sync","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/request-sync","href":"/forge/reference/http-api/knowledge/request-source-sync"},{"title":"List knowledge sources","description":"List the newest knowledge sources in namespaces a credential can read.","deprecated":null,"version":null,"sidebarTitle":"List sources","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-synchronized-sources","href":"/forge/reference/http-api/knowledge/list-sources"},{"title":"Get a knowledge source","description":"Read one knowledge source without its private configuration.","deprecated":null,"version":null,"sidebarTitle":"Get source","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}","href":"/forge/reference/http-api/knowledge/get-source"},{"title":"List knowledge source runs","description":"Read the sync runs for one readable knowledge source, newest first.","deprecated":null,"version":null,"sidebarTitle":"List source runs","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs","href":"/forge/reference/http-api/knowledge/list-source-runs"},{"title":"Get a knowledge source's kinds","description":"Read one synchronized knowledge source's kinds — each kind's completeness with every failing condition, its verification, quarantined items and record count. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"Get source kind states","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/kind-states","href":"/forge/reference/http-api/knowledge/get-source-kind-states"},{"title":"Update knowledge source sync controls","description":"Rename, retime, pause or resume a writable knowledge source.","deprecated":null,"version":null,"sidebarTitle":"Update source","openapi":"/forge/reference/openapi-v3.json patch /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}","href":"/forge/reference/http-api/knowledge/update-source"},{"title":"List knowledge source providers","description":"List the registered providers a knowledge source can be connected through — key, label, declared modes, declared source configuration and the kinds each delivers. Requires knowledge:manage and credentials:use.","deprecated":null,"version":null,"sidebarTitle":"List source providers","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-synchronized-source-providers","href":"/forge/reference/http-api/knowledge/list-source-providers"},{"title":"List the containers a knowledge source could read","description":"List, by label, the containers in a provider's system that a new knowledge source at a writable target could read, checked as connecting a source is. Requires knowledge:manage and credentials:use.","deprecated":null,"version":null,"sidebarTitle":"List source containers","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-synchronized-source-providers/{providerKey}/search-containers","href":"/forge/reference/http-api/knowledge/list-source-containers"},{"title":"Connect a knowledge source","description":"Connect a knowledge source to one container in a registered provider's system, writing to a scope in your writable namespaces. Requires knowledge:manage and credentials:use.","deprecated":null,"version":null,"sidebarTitle":"Connect source","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-synchronized-sources","href":"/forge/reference/http-api/knowledge/create-source"},{"title":"Re-list a knowledge source","description":"Clear a knowledge source's cursor so its next run lists every item again. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Re-list source","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/relist","href":"/forge/reference/http-api/knowledge/relist-source"},{"title":"Remove a knowledge source","description":"Remove a knowledge source in a writable namespace and permanently delete every case it wrote, its runs and the source. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Remove source","openapi":"/forge/reference/openapi-v3.json delete /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}","href":"/forge/reference/http-api/knowledge/remove-source"},{"title":"Get a source's diff review state","description":"Read a synchronized source's diff policy and its runs' review phases.","deprecated":null,"version":null,"sidebarTitle":"Source diff state","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/diff","href":"/forge/reference/http-api/knowledge/get-source-diff"},{"title":"Review a run's diff","description":"Read one page of a run's held changes as its reviewer may see them.","deprecated":null,"version":null,"sidebarTitle":"Review source diff","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/review-diff","href":"/forge/reference/http-api/knowledge/review-source-diff"},{"title":"Set a source's diff policy","description":"Choose when a synchronized source's changes wait for review.","deprecated":null,"version":null,"sidebarTitle":"Set source diff policy","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/set-diff-policy","href":"/forge/reference/http-api/knowledge/set-source-diff-policy"},{"title":"Approve a run's diff","description":"Approve a held diff, or resume a failed apply, after reviewing it.","deprecated":null,"version":null,"sidebarTitle":"Approve source diff","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/approve-diff","href":"/forge/reference/http-api/knowledge/approve-source-diff"},{"title":"Reject a run's diff","description":"Stop a run's diff so nothing more of it applies.","deprecated":null,"version":null,"sidebarTitle":"Reject source diff","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/reject-diff","href":"/forge/reference/http-api/knowledge/reject-source-diff"},{"title":"Approve a run's held deletions","description":"Release the deletions a run's shrink guard holds.","deprecated":null,"version":null,"sidebarTitle":"Approve source shrink","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/approve-shrink","href":"/forge/reference/http-api/knowledge/approve-source-shrink"},{"title":"Override a run's shrink threshold","description":"Lower one run's shrink threshold to release the kinds that no longer cross it.","deprecated":null,"version":null,"sidebarTitle":"Override source shrink","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/runs/{runId}/override-shrink","href":"/forge/reference/http-api/knowledge/override-source-shrink"},{"title":"List knowledge records","description":"Page every record of the requested kinds a credential can read, complete or refused. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"List records","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-records/search","href":"/forge/reference/http-api/knowledge/list-records"},{"title":"Create a knowledge record collection","description":"Create an authored record collection — a named kind schema in one writable namespace that authored records are then written to. Requires knowledge:manage where the namespace lives.","deprecated":null,"version":null,"sidebarTitle":"Create record collection","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-collections","href":"/forge/reference/http-api/knowledge/create-record-collection"},{"title":"List knowledge subject collections","description":"List the subject collections in your readable namespaces, each with how many of its artifacts you can read. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"List subject collections","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-subject-collections","href":"/forge/reference/http-api/knowledge/list-subject-collections"},{"title":"Get a knowledge record","description":"Read one knowledge record by entry id or by its source or collection address. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"Get record","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-records/lookup","href":"/forge/reference/http-api/knowledge/get-record"},{"title":"List knowledge cases","description":"Page the knowledge cases a credential can read, filtered and sorted as the Console knowledge list. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"List cases","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-cases","href":"/forge/reference/http-api/knowledge/list-cases"},{"title":"Get a knowledge case","description":"Read one knowledge case with its text, version and stewardship. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"Get case","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-case-lookup","href":"/forge/reference/http-api/knowledge/get-case"},{"title":"List a knowledge case's versions","description":"Read the past versions of a knowledge case, newest first, a page at a time. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"List case versions","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-cases/{caseId}/versions","href":"/forge/reference/http-api/knowledge/list-case-versions"},{"title":"Get a knowledge case's pending revision","description":"Read the edit held for review on a proven knowledge case. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"Get case revision","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-cases/{caseId}/revision","href":"/forge/reference/http-api/knowledge/get-case-revision"},{"title":"List where a knowledge case was used","description":"Read the runs and chat turns that cited a knowledge case, with their outcome signals. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"List case uses","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-cases/{caseId}/uses","href":"/forge/reference/http-api/knowledge/list-case-uses"},{"title":"Create a knowledge case","description":"Write a new knowledge case into a writable namespace. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Create case","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-cases","href":"/forge/reference/http-api/knowledge/create-case"},{"title":"Edit a knowledge case","description":"Rewrite a knowledge case's title and text at the version you read. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Edit case","openapi":"/forge/reference/openapi-v3.json patch /api/v3/knowledge-cases/{caseId}","href":"/forge/reference/http-api/knowledge/update-case"},{"title":"Verify a knowledge case","description":"Attest that a knowledge case is still correct. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Verify case","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-cases/{caseId}/verify","href":"/forge/reference/http-api/knowledge/verify-case"},{"title":"Grade a knowledge case","description":"Set a knowledge case's grade with a reason. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Grade case","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-cases/{caseId}/set-grade","href":"/forge/reference/http-api/knowledge/set-case-grade"},{"title":"Set a knowledge case's steward","description":"Set or clear a knowledge case's steward and verification interval. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Set case steward","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-cases/{caseId}/set-steward","href":"/forge/reference/http-api/knowledge/set-case-steward"},{"title":"List knowledge review items","description":"Page the knowledge review queue for the namespaces a credential can read, each pending item with its Console handoff. Requires knowledge:read at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List review items","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-reviews","href":"/forge/reference/http-api/knowledge/list-reviews"},{"title":"Get a knowledge review item","description":"Read one knowledge review item, whatever its status. Requires knowledge:read at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Get a review item","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-reviews/{reviewId}","href":"/forge/reference/http-api/knowledge/get-review"},{"title":"Decide a knowledge review item","description":"Resolve one pending knowledge review item with a grade, merge, verification or dismissal and a recorded note, as a steward does in Console. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Decide a review item","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-reviews/{reviewId}/decide","href":"/forge/reference/http-api/knowledge/decide-review"},{"title":"List what the knowledge base learned","description":"Page the Learning feed (cases created, promoted, replaced, moved, deleted, regraded and merged) for the namespaces a credential can read. Requires knowledge:read at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List learning","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-learning-events","href":"/forge/reference/http-api/knowledge/list-learning"},{"title":"List retrieval golden sets","description":"List the retrieval golden sets a credential can see, each with its newest run and the baselines it is judged against, as the Console Knowledge Quality page. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"List golden sets","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-golden-sets","href":"/forge/reference/http-api/knowledge/list-golden-sets"},{"title":"List a golden set's runs","description":"Read one retrieval golden set's eval runs, newest first — recall@k, MRR, per-case scores and baseline regression. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"List golden set runs","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-golden-sets/{goldenSetId}/runs","href":"/forge/reference/http-api/knowledge/list-golden-set-runs"},{"title":"Create a retrieval golden set","description":"Create a retrieval golden set — golden cases of a query and its expected keys, searched in namespaces the credential can read. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Create golden set","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-golden-sets","href":"/forge/reference/http-api/knowledge/create-golden-set"},{"title":"Update a retrieval golden set","description":"Replace a retrieval golden set's name, scope, namespaces and cases, or archive it; a set with runs keeps its namespaces and cases. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Update golden set","openapi":"/forge/reference/openapi-v3.json patch /api/v3/knowledge-golden-sets/{goldenSetId}","href":"/forge/reference/http-api/knowledge/update-golden-set"},{"title":"Run a retrieval golden set","description":"Schedule one manual retrieval eval run of an active golden set at a chosen k. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Run golden set","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-golden-sets/{goldenSetId}/run","href":"/forge/reference/http-api/knowledge/run-golden-set"},{"title":"Get the knowledge learning settings","description":"Read the deployment-wide knowledge learning settings in force, which keys carry a stored value, and when each was last written. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"Get settings","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-settings","href":"/forge/reference/http-api/knowledge/get-settings"},{"title":"Change a knowledge learning setting","description":"Store one deployment-wide knowledge learning setting its rule accepts, audited with the value before and after. Requires platform:manage.","deprecated":null,"version":null,"sidebarTitle":"Set setting","openapi":"/forge/reference/openapi-v3.json patch /api/v3/knowledge-settings/{settingKey}","href":"/forge/reference/http-api/knowledge/set-setting"},{"title":"Start a knowledge re-embed","description":"Schedule a re-embed of every knowledge namespace embedded under another model than the active one, and of the app vector tables alongside. Requires knowledge:manage.","deprecated":null,"version":null,"sidebarTitle":"Start re-embed","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-reembed-runs","href":"/forge/reference/http-api/knowledge/start-reembed"},{"title":"Get the latest knowledge re-embed run","description":"Read the newest knowledge re-embed run's progress — status, target model, namespace and entry counts, and its failed rows in your readable namespaces. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"Get re-embed run","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-reembed-latest-run","href":"/forge/reference/http-api/knowledge/get-reembed-run"},{"title":"List your knowledge scopes","description":"List every knowledge namespace your credential can read or write, with its scope type, entity and name, exactly as every knowledge route enforces them. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"List scopes","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-scopes","href":"/forge/reference/http-api/knowledge/list-scopes"},{"title":"Get a knowledge scope's shape","description":"Read one knowledge namespace you can read, with how many entries of each content type you may read in it and the record kinds you can list there. Requires knowledge:read.","deprecated":null,"version":null,"sidebarTitle":"Get scope","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-scopes/{scopeId}","href":"/forge/reference/http-api/knowledge/get-scope"},{"title":"Get the distillation behind an improvement request and the cases it was distilled from, each shown only as far as the caller may read it","description":"Get the distillation behind an improvement request and the cases it was distilled from, each shown only as far as the caller may read it. Requires permission `knowledge:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the distillation behind an improvement request and the cases it was distilled from, each shown only as far as the caller may read it","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-improvement-requests/{requestId}/distillation","href":"/forge/reference/http-api/knowledge/admin/distillations-get"},{"title":"Preview an agent’s knowledge retrieval","description":"Preview an agent’s knowledge retrieval; optionally select one namespace readable by both viewer and agent. A Customer selection previews selected context, not a deployed ticket run. Requires permission `knowledge:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview an agent’s knowledge retrieval","openapi":"/forge/reference/openapi-v3.json post /api/v3/agents/{agentId}/preview-knowledge-search","href":"/forge/reference/http-api/knowledge/admin/search-as"},{"title":"List knowledge record collections","description":"List the authored-record collections the caller may read, in namespace and kind order, a page at a time.","deprecated":null,"version":null,"sidebarTitle":"List knowledge record collections","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-collections","href":"/forge/reference/http-api/knowledge/list-collections"},{"title":"Get a knowledge record collection","description":"Read one authored-record collection the caller may read.","deprecated":null,"version":null,"sidebarTitle":"Get a knowledge record collection","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-collections/{collectionId}","href":"/forge/reference/http-api/knowledge/get-collection"},{"title":"Create a knowledge record","description":"Write one authored record in a collection the caller may read and manage.","deprecated":null,"version":null,"sidebarTitle":"Create a knowledge record","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-collections/{collectionId}/records","href":"/forge/reference/http-api/knowledge/create-record"},{"title":"Update a knowledge record","description":"Change one authored record, by its external id, in a collection the caller may read and manage.","deprecated":null,"version":null,"sidebarTitle":"Update a knowledge record","openapi":"/forge/reference/openapi-v3.json patch /api/v3/knowledge-collections/{collectionId}/records/{externalId}","href":"/forge/reference/http-api/knowledge/update-record"},{"title":"Remove a knowledge record","description":"Remove one authored record, by its external id, from a collection the caller may read and manage.","deprecated":null,"version":null,"sidebarTitle":"Remove a knowledge record","openapi":"/forge/reference/openapi-v3.json delete /api/v3/knowledge-collections/{collectionId}/records/{externalId}","href":"/forge/reference/http-api/knowledge/remove-record"},{"title":"Get a record's annotations","description":"Read the Forge-owned annotation map on one knowledge record the caller may read.","deprecated":null,"version":null,"sidebarTitle":"Get a record's annotations","openapi":"/forge/reference/openapi-v3.json get /api/v3/knowledge-record-annotations","href":"/forge/reference/http-api/knowledge/get-annotations"},{"title":"Replace a record's annotations","description":"Replace the whole Forge-owned annotation map on a knowledge record. Omitted keys are removed; an empty map clears it.","deprecated":null,"version":null,"sidebarTitle":"Replace a record's annotations","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-records/annotate","href":"/forge/reference/http-api/knowledge/annotate"},{"title":"Get knowledge version history","description":"Prior snapshots of a case or record, newest change first, under the caller's current read access.","deprecated":null,"version":null,"sidebarTitle":"Get knowledge version history","openapi":"/forge/reference/openapi-v3.json post /api/v3/knowledge-snapshots/search","href":"/forge/reference/http-api/knowledge/history"}]},{"group":"Governance","icon":"shield-halved","root":{"title":"Governance API","sidebarTitle":"Governance","icon":"shield-halved","description":"HTTP API operations for approvals and human tasks, approval and trust policies, grants and denial explanations, Trust Fabric controls and audit exports.","href":"/forge/reference/http-api/families/governance"},"pages":[{"group":"Governance","icon":"scale-balanced","root":{"title":"Governance","sidebarTitle":"Governance","icon":"scale-balanced","description":"Work the approvals queue and your own tasks, manage approval and trust policies, read roles, grants and the permission catalog, explain decisions, and report on them.","href":"/forge/reference/http-api/governance"},"pages":[{"title":"List pending approvals","description":"List pending approvals. Requires permissions `grants:read`, `policies:read` and `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List pending approvals","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-approvals","href":"/forge/reference/http-api/governance/listapprovals"},{"title":"Get an approval by ID","description":"Get an approval by ID. Requires permissions `grants:read`, `policies:read` and `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Get an approval by ID","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-approvals/{approvalId}","href":"/forge/reference/http-api/governance/getapproval"},{"title":"List the approval decision trail for one run","description":"Returns the ordered approval decision history for a single workflow run — what was held, by which gate, and how each decision resolved. Requires permissions `grants:read`, `policies:read` and `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List a run's approval trail","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/approvals","href":"/forge/reference/http-api/governance/listrunapprovals"},{"title":"List approval policies","description":"List approval policies. Requires permissions `grants:read`, `policies:read` and `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List approval policies","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-approval-policies","href":"/forge/reference/http-api/governance/listpolicies"},{"title":"Explain a recorded decision","description":"Returns one recorded Trust Fabric decision from the calling credential's acting organization, explained from recorded evidence only — its disposition, each gate result, and the recorded gate and error-code classification. Requires permissions `grants:read`, `policies:read` and `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Explain a recorded decision","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-decisions/{decisionId}/explanation","href":"/forge/reference/http-api/governance/explaindecision"},{"title":"List recorded decisions","description":"Pages the Trust Fabric decisions recorded for the calling credential's acting organization in a time window, newest first. Requires permissions `grants:read`, `policies:read` and `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List recorded decisions","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-decisions","href":"/forge/reference/http-api/governance/listevidence"},{"title":"Get a recorded decision","description":"Returns one recorded Trust Fabric decision by id, in the same shape as a `listEvidence` item. Requires permissions `grants:read`, `policies:read` and `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a recorded decision","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-decisions/{decisionId}","href":"/forge/reference/http-api/governance/getevidence"},{"title":"List the role catalog","description":"List the Trust Fabric role catalog. Requires permissions `grants:read`, `policies:read` and `audit:read`, and `grants:read` at the platform scope or the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List the role catalog","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-roles","href":"/forge/reference/http-api/governance/listroles"},{"title":"Get the permission catalog","description":"Every Forge permission in words, by family and resource, with the roles that include it and where it is enforced. Requires permission `roles:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the permission catalog","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-permission-catalog","href":"/forge/reference/http-api/governance/getpermissioncatalog"},{"title":"List role definitions","description":"Every Forge role, system and custom, with its catalog permissions, counts by family, and the roles it includes and is included in. Requires permission `roles:read`.","deprecated":null,"version":null,"sidebarTitle":"List role definitions","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-role-definitions","href":"/forge/reference/http-api/governance/listroledefinitions"},{"title":"Get your credential's own authority","description":"No permission required. What the calling key or app can do at one place — the grants that apply and every permission's effective answer, exactly as the request gate decides.","deprecated":null,"version":null,"sidebarTitle":"Get your own authority","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/authority","href":"/forge/reference/http-api/governance/getmyauthority"},{"title":"List your credential's own grants","description":"No permission required. Every role grant behind the calling key or app, at every scope.","deprecated":null,"version":null,"sidebarTitle":"List your own grants","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/grants","href":"/forge/reference/http-api/governance/listmygrants"},{"title":"List where a permission is enforced","description":"The access-control rows that enforce one catalog permission. Requires permission `roles:read`.","deprecated":null,"version":null,"sidebarTitle":"List enforcement sites","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-permissions/{permissionKey}/enforcement-sites","href":"/forge/reference/http-api/governance/listenforcementsites"},{"title":"List who holds grants at a place","description":"Every holder of role grants covering one place, without givers or names. Requires permission `grants:read` at the org unit.","deprecated":null,"version":null,"sidebarTitle":"List holders at a place","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-holders","href":"/forge/reference/http-api/governance/listholdersat"},{"title":"Get a holder's effective authority","description":"What one holder can do at one place, layer by layer, with an optional give or revoke preview. Requires permission `grants:read` at the org unit.","deprecated":null,"version":null,"sidebarTitle":"Get a holder's authority","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-holders/{holderId}/effective-authority","href":"/forge/reference/http-api/governance/geteffectiveauthority"},{"title":"Explain why someone has or lacks a permission","description":"The Access check for a person or agent — allowed or not, why, and the grants behind it. Requires permission `grants:read` at the company.","deprecated":null,"version":null,"sidebarTitle":"Explain a permission","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-holders/{holderId}/permission-explanation","href":"/forge/reference/http-api/governance/explainactorpermission"},{"title":"Get a company's access inventory","description":"Role grants, delegations and credentials that reach one company. Requires permission `grants:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Get company access","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-company-access-overview","href":"/forge/reference/http-api/governance/getcompanyaccessoverview"},{"title":"List on-behalf-of grants","description":"Which workflow versions may act for which companies. Requires permission `grants:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List on-behalf-of grants","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-on-behalf-of-grants","href":"/forge/reference/http-api/governance/listonbehalfofgrants"},{"title":"List role grants","deprecated":null,"version":null,"sidebarTitle":"List role grants","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-grants","href":"/forge/reference/http-api/governance/listgrants"},{"title":"Give a role","description":"Give a role. Requires permission `grants:manage`, decided again where the grant is; the calling credential must hold every permission of the role there.","deprecated":null,"version":null,"sidebarTitle":"Give a role","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-holders/{holderId}/roles","href":"/forge/reference/http-api/governance/giverole"},{"title":"Revoke a role","description":"Revokes one role from a holder at exactly the scope named (a grant at another scope is untouched), as the Forge Console's Access page revokes it, and records the change, the credential and `reason` on the audit trail. Requires permission `grants:manage`, decided again where the grant is; the calling credential must hold every permission of the role there.","deprecated":null,"version":null,"sidebarTitle":"Revoke a role","openapi":"/forge/reference/openapi-v3.json delete /api/v3/governance-holders/{holderId}/roles/{roleKey}","href":"/forge/reference/http-api/governance/revokerole"},{"title":"Invite a user","description":"Invite a user. Requires permission `grants:manage` at the platform scope, as the Console does; the calling credential must hold every Builder and Auditor permission where the roles land.","deprecated":null,"version":null,"sidebarTitle":"Invite a user","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-invitations","href":"/forge/reference/http-api/governance/inviteuser"},{"title":"Revoke an on-behalf-of grant","description":"Revoke an on-behalf-of grant. Requires permission `grants:manage`, held at the platform scope; revokes one on-behalf-of (acting-for) grant.","deprecated":null,"version":null,"sidebarTitle":"Revoke on-behalf-of grant","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-on-behalf-of-grants/{grantId}/revoke","href":"/forge/reference/http-api/governance/revokeonbehalfofgrant"},{"title":"Save the MCP server configuration","description":"Save the MCP server configuration. Requires permission `apikeys:manage`, held at the platform scope; replaces the deployment's MCP server configuration.","deprecated":null,"version":null,"sidebarTitle":"Save MCP configuration","openapi":"/forge/reference/openapi-v3.json patch /api/v3/mcp-config","href":"/forge/reference/http-api/governance/updatemcpconfig"},{"title":"List agents' accountability","description":"List agents' accountability findings. Requires permissions `grants:read`, `policies:read` and `audit:read`; each agent is decided at its home.","deprecated":null,"version":null,"sidebarTitle":"List agents' accountability","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-agent-accountability","href":"/forge/reference/http-api/governance/listagentaccountability"},{"title":"Get an agent's accountability","description":"Returns one agent's accountability when your role grants hold `agents:read`, `grants:read`, `policies:read` and `audit:read` at the agent's home org unit. Requires permissions `grants:read`, `policies:read` and `audit:read`; the agent is decided at its home.","deprecated":null,"version":null,"sidebarTitle":"Get an agent's accountability","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/accountability","href":"/forge/reference/http-api/governance/getagentaccountability"},{"title":"List trust policies","description":"List trust policies. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List trust policies","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-trust-policies","href":"/forge/reference/http-api/governance/listtrustpolicies"},{"title":"List a trust policy's revisions","description":"List a trust policy's revisions. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List trust policy revisions","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-trust-policies/{trustPolicyId}/revisions","href":"/forge/reference/http-api/governance/listtrustpolicyrevisions"},{"title":"Simulate a trust policy","description":"Replay a trust policy against recorded decisions (historical). Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization.","deprecated":null,"version":null,"sidebarTitle":"Simulate a trust policy","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-trust-policies/simulate","href":"/forge/reference/http-api/governance/simulatetrustpolicy"},{"title":"Create a trust policy","description":"Creates a trust policy (revision 1 of a new chain) after the Console's validation, and answers 201 with its id. Requires permission `policies:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Create a trust policy","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-trust-policies","href":"/forge/reference/http-api/governance/createtrustpolicy"},{"title":"Edit a trust policy","description":"Edits the newest revision of a chain by writing revision n+1 with the fields sent (at least one) and the rest copied forward; the edited revision is disabled and the new one keeps its enabled state. Requires permission `policies:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Edit a trust policy","openapi":"/forge/reference/openapi-v3.json patch /api/v3/governance-trust-policies/{trustPolicyId}","href":"/forge/reference/http-api/governance/edittrustpolicy"},{"title":"Enable or disable a trust policy","description":"Enables the newest revision (after re-validating it) or disables any revision. Requires permission `policies:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Enable or disable a trust policy","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-trust-policies/{trustPolicyId}/toggle","href":"/forge/reference/http-api/governance/toggletrustpolicy"},{"title":"Remove a trust policy revision","description":"Deletes the newest revision of a chain; earlier revisions stay, and a root goes only when it is the chain's only row. Requires permission `policies:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Remove a trust policy revision","openapi":"/forge/reference/openapi-v3.json delete /api/v3/governance-trust-policies/{trustPolicyId}","href":"/forge/reference/http-api/governance/removetrustpolicy"},{"title":"Create an approval policy","description":"Creates an approval policy after the Console's validation and answers 201 with its id. Requires permission `policies:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Create an approval policy","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-approval-policies","href":"/forge/reference/http-api/governance/createapprovalpolicy"},{"title":"Update an approval policy","description":"Changes the fields sent (at least one besides `acknowledgeNoUiYet`) and answers 200 with the policy's id. Requires permission `policies:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Update an approval policy","openapi":"/forge/reference/openapi-v3.json patch /api/v3/governance-approval-policies/{approvalPolicyId}","href":"/forge/reference/http-api/governance/updateapprovalpolicy"},{"title":"Remove an approval policy","description":"Deletes the approval policy and answers 200 with its id. Requires permission `policies:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Remove an approval policy","openapi":"/forge/reference/openapi-v3.json delete /api/v3/governance-approval-policies/{approvalPolicyId}","href":"/forge/reference/http-api/governance/removeapprovalpolicy"},{"title":"Report gate denials","description":"Report gate denials for your organization. Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization.","deprecated":null,"version":null,"sidebarTitle":"Gate denial report","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-gate-deny-report","href":"/forge/reference/http-api/governance/getgatedenyreport"},{"title":"Report trust policies fired","description":"Report trust policies fired for your organization. Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization.","deprecated":null,"version":null,"sidebarTitle":"Policy fired report","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-policy-fired-report","href":"/forge/reference/http-api/governance/getpolicyfiredreport"},{"title":"Report authorization denials by surface","description":"Report authorization denials by surface for your organization. Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization.","deprecated":null,"version":null,"sidebarTitle":"Authorization surface report","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-authz-surface-report","href":"/forge/reference/http-api/governance/getauthzsurfacereport"},{"title":"Report blocked decisions by person","description":"Report blocked decisions by person for your organization. Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization.","deprecated":null,"version":null,"sidebarTitle":"Report blocked decisions by person","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-denials-by-person-report","href":"/forge/reference/http-api/governance/getdenialsbypersonreport"},{"title":"Report agent access on behalf of a person","description":"Get the agent access report for a person. Requires a Personal key acting as its owner, and permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Report agent access on behalf of a person","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-agent-access-on-behalf-of-report","href":"/forge/reference/http-api/governance/getagentaccessonbehalfofreport"},{"title":"Get the emergency stops board","description":"Get the emergency stops board. Requires permission `switches:use` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Get the emergency stops board","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-door-switch-board","href":"/forge/reference/http-api/governance/getdoorswitchboard"},{"title":"List my open work","description":"List my open work. Requires a Personal key and permission `approvals:read`.","deprecated":null,"version":null,"sidebarTitle":"List my work","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/work","href":"/forge/reference/http-api/governance/listmywork"},{"title":"Get a human task","description":"Get a human task. Requires a Personal key and permission `approvals:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a human task","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-human-tasks/{humanTaskId}","href":"/forge/reference/http-api/governance/gethumantask"},{"title":"List my attention queue","description":"List my attention queue. Requires a Personal key and permission `approvals:read`.","deprecated":null,"version":null,"sidebarTitle":"List my attention","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/attention","href":"/forge/reference/http-api/governance/listmyattention"},{"title":"List a human step's input files","description":"List a human step's input files. Requires a Personal key and permission `approvals:read`.","deprecated":null,"version":null,"sidebarTitle":"List step input files","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-human-task-input-files","href":"/forge/reference/http-api/governance/listhumantaskinputfiles"},{"title":"Get a human step input file's URL","description":"Get a signed URL for a human step's input file. Requires a Personal key and permission `approvals:read`.","deprecated":null,"version":null,"sidebarTitle":"Get step input file URL","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-human-task-input-files/{fileId}/signed-url","href":"/forge/reference/http-api/governance/gethumantaskinputfileurl"},{"title":"List Trust Fabric attention items","description":"Pages through the operator attention list of the deployment's organization, as the Forge Console Trust Fabric page shows it, decided at the deployment root. Requires permission `audit:read`, decided at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List attention items","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-attention-items","href":"/forge/reference/http-api/governance/listattention"},{"title":"Get a Trust Fabric attention item","description":"Reads one attention item, decided ones included, by the resource it is about, decided at the deployment root as `listAttention` is. Requires permission `audit:read`, decided at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Get attention item","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-attention-items/{subjectId}","href":"/forge/reference/http-api/governance/getattentionitem"},{"title":"Act on a human task","description":"Claims, releases, declines or withdraws a task as the key's owner. Requires a Personal key whose scopes reach `approvals:approve`.","deprecated":null,"version":null,"sidebarTitle":"Act on a human task","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-human-tasks/{humanTaskId}/act","href":"/forge/reference/http-api/governance/actonhumantask"},{"title":"Complete a human task","description":"Answers a task with one of its declared actions, as the key's owner. Requires a Personal key whose scopes reach `approvals:approve`.","deprecated":null,"version":null,"sidebarTitle":"Complete a human task","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-human-tasks/{humanTaskId}/complete","href":"/forge/reference/http-api/governance/completehumantask"},{"title":"Reassign a human task","description":"Reassigns a step or an approval, as the key's owner. Requires a Personal key and permission `approvals:approve`.","deprecated":null,"version":null,"sidebarTitle":"Reassign a human task","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-human-tasks/reassign","href":"/forge/reference/http-api/governance/reassignhumantask"},{"title":"Attach an output file to a human step","description":"Attaches an uploaded file as a human step's declared file output, as the key's owner. Requires a Personal key whose scopes reach `approvals:approve`.","deprecated":null,"version":null,"sidebarTitle":"Attach a step output file","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-human-task-output-files","href":"/forge/reference/http-api/governance/attachhumantaskoutputfile"},{"title":"Ask a person","description":"Asks 1 to 25 named people for a decision or input through a human task with your own form. Requires an External App or a platform key holding `human_tasks:use`.","deprecated":null,"version":null,"sidebarTitle":"Ask a person","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-requested-human-tasks","href":"/forge/reference/http-api/governance/requesthumantask"},{"title":"Get one of your asks","description":"Reads one ask you made with Ask a person, and its outcome. Requires an External App or a platform key holding `human_tasks:use`.","deprecated":null,"version":null,"sidebarTitle":"Get one of your asks","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-requested-human-task-lookup","href":"/forge/reference/http-api/governance/getrequestedhumantask"},{"title":"Withdraw one of your asks","description":"Cancels one of your open asks; a repeat is safe. Requires an External App or a platform key holding `human_tasks:use`.","deprecated":null,"version":null,"sidebarTitle":"Withdraw one of your asks","openapi":"/forge/reference/openapi-v3.json post /api/v3/governance-requested-human-tasks/withdraw","href":"/forge/reference/http-api/governance/withdrawrequestedhumantask"},{"title":"Get the gate-path registry","description":"Get the Trust Fabric gate-path registry. Requires permissions `grants:read`, `policies:read` and `audit:read` at your acting organization.","deprecated":null,"version":null,"sidebarTitle":"Gate-path registry","openapi":"/forge/reference/openapi-v3.json get /api/v3/governance-gate-path-registry","href":"/forge/reference/http-api/governance/getgatepathregistry"},{"title":"Get the MCP server configuration","description":"The deployment-wide MCP server configuration the hosted /api/mcp endpoint serves. It discloses no tenant data.","deprecated":null,"version":null,"sidebarTitle":"Get the MCP server configuration","openapi":"/forge/reference/openapi-v3.json get /api/v3/mcp-config","href":"/forge/reference/http-api/governance/getmcpconfig"}]},{"group":"Trust Fabric","icon":"shield-halved","root":{"title":"Trust Fabric administration","sidebarTitle":"Trust Fabric","icon":"shield-check","description":"Read Tier 3 command decisions, promotion candidates and policy effectiveness, and use three narrowed platform controls, with a platform API key.","href":"/forge/reference/http-api/trust-fabric"},"pages":[{"title":"Engage the platform kill switch, which halts every run, with a reason. Release stays in the Console","description":"Engage the platform kill switch, which halts every run, with a reason. Release stays in the Console. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Engage the platform kill switch, which halts every run, with a reason. Release stays in the Console","openapi":"/forge/reference/openapi-v3.json post /api/v3/trust-fabric-kill-switch/engage","href":"/forge/reference/http-api/trust-fabric/admin/kill-engage"},{"title":"List a page of the recent Tier 3 free-form command decisions (disposition, inferred risk, severity and the command's hash), grouped by disposition and newest first within each","description":"List a page of the recent Tier 3 free-form command decisions (disposition, inferred risk, severity and the command's hash), grouped by disposition and newest first within each. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the recent Tier 3 free-form command decisions (disposition, inferred risk, severity and the command's hash), grouped by disposition and newest first within each","openapi":"/forge/reference/openapi-v3.json get /api/v3/trust-fabric-tier3-invocations","href":"/forge/reference/http-api/trust-fabric/admin/tier3-invocations"},{"title":"List frequent low-risk Tier 3 command patterns (by hash, count and last seen) that could become catalog commands","description":"List frequent low-risk Tier 3 command patterns (by hash, count and last seen) that could become catalog commands. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List frequent low-risk Tier 3 command patterns (by hash, count and last seen) that could become catalog commands","openapi":"/forge/reference/openapi-v3.json get /api/v3/trust-fabric-tier3-promotion-candidates","href":"/forge/reference/http-api/trust-fabric/admin/tier3-promotion-candidates"},{"title":"List a page of the governance decisions recorded for one catalog command (disposition, inferred risk, severity and the command's hash), newest first","description":"List a page of the governance decisions recorded for one catalog command (disposition, inferred risk, severity and the command's hash), newest first. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the governance decisions recorded for one catalog command (disposition, inferred risk, severity and the command's hash), newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/trust-fabric-commands/{commandId}/decisions","href":"/forge/reference/http-api/trust-fabric/admin/command-decisions"},{"title":"Get the governance status of a human prompt in a chat session — whether an approval holds it, and the approval link when the key's owner may approve","description":"Get the governance status of a human prompt in a chat session — whether an approval holds it, and the approval link when the key's owner may approve. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the governance status of a human prompt in a chat session — whether an approval holds it, and the approval link when the key's owner may approve","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions/{sessionId}/trust-status","href":"/forge/reference/http-api/trust-fabric/admin/chat-status"},{"title":"Count one run's command decisions by tier (1, 2, 3), by disposition (allowed, held, blocked) and by inferred risk class","description":"Count one run's command decisions by tier (1, 2, 3), by disposition (allowed, held, blocked) and by inferred risk class. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Count one run's command decisions by tier (1, 2, 3), by disposition (allowed, held, blocked) and by inferred risk class","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/tier-breakdown","href":"/forge/reference/http-api/trust-fabric/admin/run-tier-breakdown"},{"title":"List a page of the policies, in the order they were created, each with its hold count, block rate and last trigger since a start time","description":"List a page of the policies, in the order they were created, each with its hold count, block rate and last trigger since a start time. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the policies, in the order they were created, each with its hold count, block rate and last trigger since a start time","openapi":"/forge/reference/openapi-v3.json get /api/v3/trust-fabric-policy-effectiveness","href":"/forge/reference/http-api/trust-fabric/admin/policy-effectiveness"},{"title":"Get the tool security (egress) policy — the allowed and blocked host patterns, the blocked header names and the command blocklist pattern, or null before it is seeded","description":"Get the tool security (egress) policy — the allowed and blocked host patterns, the blocked header names and the command blocklist pattern, or null before it is seeded. Requires permission `policies:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the tool security (egress) policy — the allowed and blocked host patterns, the blocked header names and the command blocklist pattern, or null before it is seeded","openapi":"/forge/reference/openapi-v3.json get /api/v3/trust-fabric-tool-security-policy","href":"/forge/reference/http-api/trust-fabric/admin/tool-security-policy"},{"title":"Set the publish judge to enforce, with a reason. Moving it to warn or off stays in the Console","description":"Set the publish judge to enforce, with a reason. Moving it to warn or off stays in the Console. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Set the publish judge to enforce, with a reason. Moving it to warn or off stays in the Console","openapi":"/forge/reference/openapi-v3.json post /api/v3/trust-fabric-postures/{postureKey}/enforce","href":"/forge/reference/http-api/trust-fabric/admin/posture-enforce"},{"title":"Stop or resume the agents governance door, with a reason. The people and API-keys doors stay in the Console","description":"Stop or resume the agents governance door, with a reason. The people and API-keys doors stay in the Console. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Stop or resume the agents governance door, with a reason. The people and API-keys doors stay in the Console","openapi":"/forge/reference/openapi-v3.json patch /api/v3/trust-fabric-doors/{door}","href":"/forge/reference/http-api/trust-fabric/admin/doors-agents"},{"title":"Get the platform kill switch — whether it is engaged, the reason it was engaged with, when it was last engaged and released, and who did each by name","description":"Get the platform kill switch — whether it is engaged, the reason it was engaged with, when it was last engaged and released, and who did each by name. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Get the platform kill switch — whether it is engaged, the reason it was engaged with, when it was last engaged and released, and who did each by name","openapi":"/forge/reference/openapi-v3.json get /api/v3/trust-fabric-kill-switch","href":"/forge/reference/http-api/trust-fabric/admin/kill-state"},{"title":"Get one agent's trust assurance — its readiness report, its accountability (owner, review date and identity confirmation) and whether its stored definition hash matches its current definition","description":"Get one agent's trust assurance — its readiness report, its accountability (owner, review date and identity confirmation) and whether its stored definition hash matches its current definition. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get one agent's trust assurance — its readiness report, its accountability (owner, review date and identity confirmation) and whether its stored definition hash matches its current definition","openapi":"/forge/reference/openapi-v3.json get /api/v3/trust-fabric-agent-assurance","href":"/forge/reference/http-api/trust-fabric/admin/agent-assurance"}]},{"title":"Trust Investigation","sidebarTitle":"Trust investigation","icon":"magnifying-glass","description":"Explain permission grants and recorded Trust Fabric decision causes within an authorized organization audience.","href":"/forge/reference/http-api/trust-investigation"},{"group":"Compliance","icon":"file-shield","root":{"title":"Compliance","sidebarTitle":"Compliance","icon":"file-shield","description":"Export the whole deployment's audit events and governance decision records, and summarize them, as a deployment-root auditor.","href":"/forge/reference/http-api/compliance"},"pages":[{"title":"Export audit events","description":"Export the deployment's audit events. Requires permission `audit:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Export audit events","openapi":"/forge/reference/openapi-v3.json get /api/v3/compliance-export-audit","href":"/forge/reference/http-api/compliance/audit"},{"title":"Export governance decision records","description":"Export the deployment's governance decision records. Requires permission `audit:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Export governance decisions","openapi":"/forge/reference/openapi-v3.json get /api/v3/compliance-export-governance","href":"/forge/reference/http-api/compliance/governance"},{"title":"Summarize audit and governance records","description":"Summarize the deployment's audit and governance records. Requires permission `audit:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Compliance summary","openapi":"/forge/reference/openapi-v3.json get /api/v3/compliance-export-summary","href":"/forge/reference/http-api/compliance/summary"}]}]},{"group":"Quality","icon":"gavel","root":{"title":"Quality API","sidebarTitle":"Quality","icon":"gavel","description":"HTTP API operations for machine judges, their rubrics and verdicts, and evaluation sets and runs.","href":"/forge/reference/http-api/families/quality"},"pages":[{"group":"Judges","icon":"scale-balanced","root":{"title":"Judges","sidebarTitle":"Judges","icon":"scale-balanced","description":"Read machine judges, their rubrics, drift alerts and verdicts; override, promote or demote a judgment; and re-judge a skill, agent, procedure or workflow.","href":"/forge/reference/http-api/judges"},"pages":[{"title":"List judges","description":"Returns every judge, sorted by name, with its tier, its rubric, its 30-day metrics and calibration health, and its highest-severity active drift signal. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"List judges","openapi":"/forge/reference/openapi-v3.json get /api/v3/judges","href":"/forge/reference/http-api/judges/list"},{"title":"Get judge","description":"Get a judge. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"Get judge","openapi":"/forge/reference/openapi-v3.json get /api/v3/judges/{judgeId}","href":"/forge/reference/http-api/judges/get"},{"title":"Get judge rubric","description":"Returns a judge's rubric prose and its criteria, weights, aggregation formula and verdict thresholds, without the scoring guidance. Requires permissions `grants:read`, `policies:read` and `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Get judge rubric","openapi":"/forge/reference/openapi-v3.json get /api/v3/judges/{judgeId}/rubric","href":"/forge/reference/http-api/judges/getrubric"},{"title":"List judge drift alerts","description":"List judge drift alerts. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"List judge drift alerts","openapi":"/forge/reference/openapi-v3.json get /api/v3/judge-drift-alerts","href":"/forge/reference/http-api/judges/listdriftalerts"},{"title":"List judge verdicts","description":"Returns one judge's verdicts, newest first, a page at a time. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"List judge verdicts","openapi":"/forge/reference/openapi-v3.json get /api/v3/judges/{judgeId}/verdicts","href":"/forge/reference/http-api/judges/listverdicts"},{"title":"List judge admissions","description":"Returns the primitive admissions waiting for a decision, lowest composite score first, a page at a time, each with the proposed primitive's name, each panel judge's score and who proposed it. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"List judge admissions","openapi":"/forge/reference/openapi-v3.json get /api/v3/judge-admissions","href":"/forge/reference/http-api/judges/listadmissions"},{"title":"Get judge admission","description":"Returns one admission in any state with each panel judge's full verdict. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"Get judge admission","openapi":"/forge/reference/openapi-v3.json get /api/v3/judge-admissions/{admissionId}","href":"/forge/reference/http-api/judges/getadmission"},{"title":"List subject judge verdicts","description":"Returns the verdicts on one subject, newest first, a page at a time, each with its per-criterion scores and at most 10 findings (`findingCount` is the full count). Requires permissions `grants:read`, `policies:read` and `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List subject judge verdicts","openapi":"/forge/reference/openapi-v3.json get /api/v3/judge-subjects/{subjectId}/verdicts","href":"/forge/reference/http-api/judges/listsubjectverdicts"},{"title":"Get subject judge activity","description":"Get what a judge is doing to a subject. Requires permissions `grants:read`, `policies:read` and `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Get subject judge activity","openapi":"/forge/reference/openapi-v3.json get /api/v3/judge-subjects/{subjectId}/activity","href":"/forge/reference/http-api/judges/getsubjectactivity"},{"title":"Get latest judge verdict","description":"Returns the most recent verdict on one subject, or a null `verdict`. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"Get latest judge verdict","openapi":"/forge/reference/openapi-v3.json get /api/v3/judge-subjects/{subjectId}/latest-verdict","href":"/forge/reference/http-api/judges/getlatestverdict"},{"title":"Override judge verdict","description":"Override a judge verdict. Requires permission `judges:use`.","deprecated":null,"version":null,"sidebarTitle":"Override judge verdict","openapi":"/forge/reference/openapi-v3.json post /api/v3/judge-verdicts/{verdictId}/override","href":"/forge/reference/http-api/judges/overrideverdict"},{"title":"Promote judge","description":"Moves a provisional judge to `approved` after re-checking its latest 30-day metrics — at least 100 dispatches and an agreement rate of at least 0.85. Requires permission `judges:manage`.","deprecated":null,"version":null,"sidebarTitle":"Promote judge","openapi":"/forge/reference/openapi-v3.json post /api/v3/judges/{judgeId}/promote","href":"/forge/reference/http-api/judges/promote"},{"title":"Demote judge","description":"Moves a judge to `provisional` (the default) or `deprecated`, which retires it, with a `reason` of at least 20 characters after trimming, recorded in the audit event. Requires permission `judges:manage`.","deprecated":null,"version":null,"sidebarTitle":"Demote judge","openapi":"/forge/reference/openapi-v3.json post /api/v3/judges/{judgeId}/demote","href":"/forge/reference/http-api/judges/demote"},{"title":"Resolve judge admission","description":"Resolve a primitive admission. Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"Resolve judge admission","openapi":"/forge/reference/openapi-v3.json post /api/v3/judge-admissions/{admissionId}/resolve","href":"/forge/reference/http-api/judges/resolveadmission"},{"title":"Re-judge skill","description":"Schedules the skill-quality judge on one skill, named by its `skillId` (as `GET /api/v2/skills/get` takes it). Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"Re-judge skill","openapi":"/forge/reference/openapi-v3.json post /api/v3/judges/rejudge-skill","href":"/forge/reference/http-api/judges/rejudgeskill"},{"title":"Re-judge agent","description":"Schedules the agent-quality judge on one agent, named by its `id` (as `GET /api/v2/agents/get` returns it). Requires permission `synthesis:approve`.","deprecated":null,"version":null,"sidebarTitle":"Re-judge agent","openapi":"/forge/reference/openapi-v3.json post /api/v3/judges/rejudge-agent","href":"/forge/reference/http-api/judges/rejudgeagent"},{"title":"Re-judge procedure","description":"Schedules the procedure-correctness judge on one procedure version, named as `GET /api/v2/procedures/get` takes it — `procedureId` and an optional `version`. Requires permission `procedures:approve`.","deprecated":null,"version":null,"sidebarTitle":"Re-judge procedure","openapi":"/forge/reference/openapi-v3.json post /api/v3/judges/rejudge-procedure","href":"/forge/reference/http-api/judges/rejudgeprocedure"},{"title":"Re-judge workflow","description":"Schedules the Architect judge on a workflow's draft, named by the workflow's `workflowId`. Requires permission `workflows:manage`.","deprecated":null,"version":null,"sidebarTitle":"Re-judge workflow","openapi":"/forge/reference/openapi-v3.json post /api/v3/judges/rejudge-workflow","href":"/forge/reference/http-api/judges/rejudgeworkflow"}]},{"group":"Evals","icon":"clipboard-check","root":{"title":"Evals","sidebarTitle":"Evals","icon":"clipboard-check","description":"Author evaluation sets, start and cancel metered runs, browse runs and compare results.","href":"/forge/reference/http-api/evals"},"pages":[{"title":"List evaluation sets","description":"Returns the evaluation sets the caller may read, newest first. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"List evaluation sets","openapi":"/forge/reference/openapi-v3.json get /api/v3/evals","href":"/forge/reference/http-api/evals/list"},{"title":"Get an evaluation set by ID","description":"Returns one evaluation set with its test cases (`EvalSetDetail`), or with `sub=runs` a page of its runs, newest first (`EvalRun`; `limit` and `cursor` page them as `listEvals` does). Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Get an evaluation set by ID","openapi":"/forge/reference/openapi-v3.json get /api/v3/evals/{evalId}","href":"/forge/reference/http-api/evals/get"},{"title":"Create an evaluation set","description":"Creates an `active` evaluation set and returns it as `EvalSetDetail`. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Create an evaluation set","openapi":"/forge/reference/openapi-v3.json post /api/v3/evals","href":"/forge/reference/http-api/evals/create"},{"title":"Update an evaluation set","description":"Changes a set's name, description (`null` clears it), test cases (replaced as a whole) or tags, and returns it as `EvalSetDetail`. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Update an evaluation set","openapi":"/forge/reference/openapi-v3.json patch /api/v3/evals/{evalId}","href":"/forge/reference/http-api/evals/update"},{"title":"Archive an evaluation set","description":"Archives a set, one-way — there is no unarchive over this API. Requires permission `agents:write`.","deprecated":null,"version":null,"sidebarTitle":"Archive an evaluation set","openapi":"/forge/reference/openapi-v3.json delete /api/v3/evals/{evalId}","href":"/forge/reference/http-api/evals/archive"},{"title":"Compare evaluation runs","description":"Compares 2-10 runs, computed on read and never stored. Requires permission `agents:read`.","deprecated":null,"version":null,"sidebarTitle":"Compare evaluation runs","openapi":"/forge/reference/openapi-v3.json get /api/v3/eval-run-comparison","href":"/forge/reference/http-api/evals/compareruns"},{"title":"Start an evaluation run","description":"Queues a run of an active evaluation set against `modelId` and answers `201` with the `pending` run. Requires permissions `agents:write` and `inference:use`.","deprecated":null,"version":null,"sidebarTitle":"Start an evaluation run","openapi":"/forge/reference/openapi-v3.json post /api/v3/evals/{evalId}/runs","href":"/forge/reference/http-api/evals/startrun"},{"title":"Cancel an evaluation run","description":"Cancels a `pending` or `running` run and answers `200` with it, now `cancelled`. Requires permissions `agents:write` and `inference:use`.","deprecated":null,"version":null,"sidebarTitle":"Cancel an evaluation run","openapi":"/forge/reference/openapi-v3.json post /api/v3/eval-runs/{runId}/cancel","href":"/forge/reference/http-api/evals/cancelrun"}]}]},{"group":"Integrations","icon":"plug","root":{"title":"Integrations API","sidebarTitle":"Integrations","icon":"plug","description":"HTTP API operations for credentials and connections, environments, vendors, capability providers, sandboxes, webhooks, email and notifications.","href":"/forge/reference/http-api/families/integrations"},"pages":[{"group":"Connections and credentials","icon":"plug","root":{"title":"Connections administration","sidebarTitle":"Connections","icon":"plug","description":"Administer Credentials, OAuth bindings and Slack delivery, and read managed secret metadata, Slack workspace connections and external tool configurations, with a platform API key.","href":"/forge/reference/http-api/connections-credentials"},"pages":[{"title":"Approve a pending credential, with an optional review note","description":"Approve a pending credential, with an optional review note. Requires permission `credentials:approve`.","deprecated":null,"version":null,"sidebarTitle":"Approve a pending credential, with an optional review note","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-credentials/{credentialId}/approve","href":"/forge/reference/http-api/connections-credentials/admin/credentials-approve"},{"title":"Reject a pending credential, with an optional review note","description":"Reject a pending credential, with an optional review note. Requires permission `credentials:approve`.","deprecated":null,"version":null,"sidebarTitle":"Reject a pending credential, with an optional review note","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-credentials/{credentialId}/reject","href":"/forge/reference/http-api/connections-credentials/admin/credentials-reject"},{"title":"Bind a connected OAuth account to a new credential at a scope, without copying its tokens","description":"Bind a connected OAuth account to a new credential at a scope, without copying its tokens. Requires permission `credentials:write`.","deprecated":null,"version":null,"sidebarTitle":"Bind a connected OAuth account to a new credential at a scope, without copying its tokens","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-oauth-bindings","href":"/forge/reference/http-api/connections-credentials/admin/oauth-bindings-create"},{"title":"Delete one procedure credential by id","description":"Delete one procedure credential by id. Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete one procedure credential by id","openapi":"/forge/reference/openapi-v3.json delete /api/v3/procedures/{procedureId}/credentials/{credentialId}","href":"/forge/reference/http-api/connections-credentials/admin/procedure-credentials"},{"title":"List a page of the credentials for one tool that this key may read, in creation order (never a secret value)","description":"List a page of the credentials for one tool that this key may read, in creation order (never a secret value). Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the credentials for one tool that this key may read, in creation order (never a secret value)","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools/{toolId}/credentials","href":"/forge/reference/http-api/connections-credentials/admin/tools-credentials"},{"title":"Get one external tool configuration (never its service-account key or client secret)","description":"Get one external tool configuration (never its service-account key or client secret). Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"Get one external tool configuration (never its service-account key or client secret)","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-external-tool-configurations/{configurationId}","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-configuration"},{"title":"Delete one connection credential (or remove its OAuth grant binding)","description":"Delete one connection credential (or remove its OAuth grant binding). Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete one connection credential (or remove its OAuth grant binding)","openapi":"/forge/reference/openapi-v3.json delete /api/v3/connection-credentials/{credentialId}","href":"/forge/reference/http-api/connections-credentials/admin/credentials-remove"},{"title":"Get one managed secret's metadata — its name, lifecycle state, store, version and consumer count (never the value)","description":"Get one managed secret's metadata — its name, lifecycle state, store, version and consumer count (never the value). Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"Get one managed secret's metadata — its name, lifecycle state, store, version and consumer count (never the value)","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-secrets/{secretId}","href":"/forge/reference/http-api/connections-credentials/admin/secret"},{"title":"Choose whether build validation may use this credential","description":"Choose whether build validation may use this credential; answers the sibling credentials whose grant it cleared. Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Choose whether build validation may use this credential","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-credentials/{credentialId}/set-build-validation-grant","href":"/forge/reference/http-api/connections-credentials/admin/credentials-build-validation-grant"},{"title":"List a connection's OAuth client registrations and the accounts connected through them, with each account's lifecycle (never a person's identity)","description":"List a connection's OAuth client registrations and the accounts connected through them, with each account's lifecycle (never a person's identity). Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"List a connection's OAuth client registrations and the accounts connected through them, with each account's lifecycle (never a person's identity)","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-oauth-accounts","href":"/forge/reference/http-api/connections-credentials/admin/oauth-accounts"},{"title":"List a page of an org unit's active Slack workspace connections, in the order they were installed — each workspace, its scopes, lifecycle and last health status, and whether Agent View is on","description":"List a page of an org unit's active Slack workspace connections, in the order they were installed — each workspace, its scopes, lifecycle and last health status, and whether Agent View is on. Requires permission `connections:manage`.","deprecated":null,"version":null,"sidebarTitle":"List a page of an org unit's active Slack workspace connections, in the order they were installed — each workspace, its scopes, lifecycle and last health status, and whether Agent View is on","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-slack-workspaces","href":"/forge/reference/http-api/connections-credentials/admin/slack-workspaces"},{"title":"List what consumes a managed secret, a page at a time — each Credential field or environment slot that holds it (never the value)","description":"List what consumes a managed secret, a page at a time — each Credential field or environment slot that holds it (never the value). Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"List what consumes a managed secret, a page at a time — each Credential field or environment slot that holds it (never the value)","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-secrets/{secretId}/consumers","href":"/forge/reference/http-api/connections-credentials/admin/secret-consumers"},{"title":"List a page of a procedure's credentials this key may read, in creation order, with each field's kind (never a value)","description":"List a page of a procedure's credentials this key may read, in creation order, with each field's kind (never a value). Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a procedure's credentials this key may read, in creation order, with each field's kind (never a value)","openapi":"/forge/reference/openapi-v3.json get /api/v3/procedures/{procedureId}/credentials","href":"/forge/reference/http-api/connections-credentials/admin/procedures-credentials"},{"title":"Get a tool's deployment-wide (system-scoped) credential, or null (never a secret value)","description":"Get a tool's deployment-wide (system-scoped) credential, or null (never a secret value). Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a tool's deployment-wide (system-scoped) credential, or null (never a secret value)","openapi":"/forge/reference/openapi-v3.json get /api/v3/tools/{toolId}/system-credential","href":"/forge/reference/http-api/connections-credentials/admin/tools-system-credential"},{"title":"List a page of the credentials this key may read, in every approval state, in creation order (never a secret value)","description":"List a page of the credentials this key may read, in every approval state, in creation order (never a secret value). Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the credentials this key may read, in every approval state, in creation order (never a secret value)","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-credentials","href":"/forge/reference/http-api/connections-credentials/admin/credentials"},{"title":"List a page of the credentials this key may read in one approval state, in creation order (never a secret value)","description":"List a page of the credentials this key may read in one approval state, in creation order (never a secret value). Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the credentials this key may read in one approval state, in creation order (never a secret value)","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-approval-states/{approvalState}/credentials","href":"/forge/reference/http-api/connections-credentials/admin/credentials-by-state"},{"title":"The credential registry — vendors, their connections and the credentials this key may read under each, with health rollups","description":"The credential registry — vendors, their connections and the credentials this key may read under each, with health rollups. Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"The credential registry — vendors, their connections and the credentials this key may read under each, with health rollups","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-credential-registry","href":"/forge/reference/http-api/connections-credentials/admin/credentials-registry"},{"title":"List the managed secrets, newest first, a page at a time — each one's name, lifecycle state, store, version and consumer count (never a value)","description":"List the managed secrets, newest first, a page at a time — each one's name, lifecycle state, store, version and consumer count (never a value). Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"List the managed secrets, newest first, a page at a time — each one's name, lifecycle state, store, version and consumer count (never a value)","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-secrets","href":"/forge/reference/http-api/connections-credentials/admin/secrets"},{"title":"List the external tool configurations — each provider, workspace domain, OAuth client id, scopes and status, and whether its service-account key and client secret are set (never the values)","description":"List the external tool configurations — each provider, workspace domain, OAuth client id, scopes and status, and whether its service-account key and client secret are set (never the values). Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"List the external tool configurations — each provider, workspace domain, OAuth client id, scopes and status, and whether its service-account key and client secret are set (never the values)","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-external-tool-configurations","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-configurations"},{"title":"Get one external tool identity, without its credential","description":"Get one external tool identity, without its credential. Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"Get one external tool identity, without its credential","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-external-tool-identities/{identityId}","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identity"},{"title":"List external tool identities a page at a time, without their credentials, optionally by provider or status","description":"List external tool identities a page at a time, without their credentials, optionally by provider or status. Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"List external tool identities a page at a time, without their credentials, optionally by provider or status","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-external-tool-identities","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identities"},{"title":"List the external tool identities a Forge principal operates, a page at a time, without their credentials","description":"List the external tool identities a Forge principal operates, a page at a time, without their credentials. Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"List the external tool identities a Forge principal operates, a page at a time, without their credentials","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-external-tool-principals/{principalId}/identities","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identities-by-principal"},{"title":"List Slack delivery operations that need an operator, one page at a time — unknown ones, then dead ones, each newest updated first","description":"List Slack delivery operations that need an operator, one page at a time — unknown ones, then dead ones, each newest updated first. Requires permission `connections:manage`.","deprecated":null,"version":null,"sidebarTitle":"List Slack delivery operations that need an operator, one page at a time — unknown ones, then dead ones, each newest updated first","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-slack-delivery-problems","href":"/forge/reference/http-api/connections-credentials/admin/slack-delivery-problems"},{"title":"One Slack delivery operation's state and attempts","description":"One Slack delivery operation's state and attempts. Requires permission `connections:manage`.","deprecated":null,"version":null,"sidebarTitle":"One Slack delivery operation's state and attempts","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-slack-delivery-operations/{operationId}","href":"/forge/reference/http-api/connections-credentials/admin/slack-delivery-operation"},{"title":"Mark a credential as authenticating to a production or a vendor sandbox tenant","description":"Mark a credential as authenticating to a production or a vendor sandbox tenant. Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Mark a credential as authenticating to a production or a vendor sandbox tenant","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-credentials/{credentialId}/set-environment","href":"/forge/reference/http-api/connections-credentials/admin/credentials-environment"},{"title":"Preview moving a managed secret to 1Password — whether it is eligible, what blocks it and any migration in flight","description":"Preview moving a managed secret to 1Password — whether it is eligible, what blocks it and any migration in flight. Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Preview moving a managed secret to 1Password — whether it is eligible, what blocks it and any migration in flight","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-secrets/{secretId}/migration-preview","href":"/forge/reference/http-api/connections-credentials/admin/secret-migration-preview"},{"title":"Create, or rotate in place, a vendor connection's credential at a scope from its field values","description":"Create, or rotate in place, a vendor connection's credential at a scope from its field values. Requires permission `credentials:write`.","deprecated":null,"version":null,"sidebarTitle":"Create, or rotate in place, a vendor connection's credential at a scope from its field values","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-credentials/provision","href":"/forge/reference/http-api/connections-credentials/admin/connection-credentials-provision"},{"title":"The Slack provider control plane's mode and its 30-day authorization counts for an org unit","description":"The Slack provider control plane's mode and its 30-day authorization counts for an org unit. Requires permission `connections:manage`.","deprecated":null,"version":null,"sidebarTitle":"The Slack provider control plane's mode and its 30-day authorization counts for an org unit","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-slack-control-plane","href":"/forge/reference/http-api/connections-credentials/admin/slack-control-plane"},{"title":"List a credential's recent verification results — status, time and HTTP status","description":"List a credential's recent verification results — status, time and HTTP status. Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"List a credential's recent verification results — status, time and HTTP status","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-credentials/{credentialId}/verifications","href":"/forge/reference/http-api/connections-credentials/admin/credentials-verifications"},{"title":"An OAuth grant's lifecycle and the credentials bound to it","description":"An OAuth grant's lifecycle and the credentials bound to it. Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"An OAuth grant's lifecycle and the credentials bound to it","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-oauth-grants/{grantId}/blast-radius","href":"/forge/reference/http-api/connections-credentials/admin/oauth-grants-blast-radius"},{"title":"Expired credentials this key may read, and bound provider records with no eligible credential","description":"Expired credentials this key may read, and bound provider records with no eligible credential. Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"Expired credentials this key may read, and bound provider records with no eligible credential","openapi":"/forge/reference/openapi-v3.json get /api/v3/connection-credential-blast-radius","href":"/forge/reference/http-api/connections-credentials/admin/credentials-blast-radius"},{"title":"Remove an OAuth binding's credential","description":"Remove an OAuth binding's credential; the account stays connected while other bindings use it. Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Remove an OAuth binding's credential","openapi":"/forge/reference/openapi-v3.json delete /api/v3/connection-oauth-bindings/{bindingId}","href":"/forge/reference/http-api/connections-credentials/admin/oauth-bindings-remove"},{"title":"Requeue a dead Slack delivery operation, with an operator note","description":"Requeue a dead Slack delivery operation, with an operator note. Requires permission `connections:manage`.","deprecated":null,"version":null,"sidebarTitle":"Requeue a dead Slack delivery operation, with an operator note","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-slack-delivery-operations/{operationId}/requeue","href":"/forge/reference/http-api/connections-credentials/admin/slack-delivery-requeue"},{"title":"Resolve an unknown Slack delivery operation as delivered or abandoned, with an operator note","description":"Resolve an unknown Slack delivery operation as delivered or abandoned, with an operator note. Requires permission `connections:manage`.","deprecated":null,"version":null,"sidebarTitle":"Resolve an unknown Slack delivery operation as delivered or abandoned, with an operator note","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-slack-delivery-operations/{operationId}/reconcile","href":"/forge/reference/http-api/connections-credentials/admin/slack-delivery-reconcile"},{"title":"Disconnect a Slack workspace from an org unit","description":"Disconnect a Slack workspace from an org unit. Requires permission `connections:manage`.","deprecated":null,"version":null,"sidebarTitle":"Disconnect a Slack workspace from an org unit","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-slack-workspaces/{connectionId}/revoke","href":"/forge/reference/http-api/connections-credentials/admin/slack-workspaces-revoke"},{"title":"Revoke a credential, with an optional review note","description":"Revoke a credential, with an optional review note. Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Revoke a credential, with an optional review note","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-credentials/{credentialId}/revoke","href":"/forge/reference/http-api/connections-credentials/admin/credentials-revoke"},{"title":"Rotate or set an external tool configuration's service-account key or OAuth client secret","description":"Rotate or set an external tool configuration's service-account key or OAuth client secret. Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"Rotate or set an external tool configuration's service-account key or OAuth client secret","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-external-tool-configurations/{configurationId}/set-credentials","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-configuration-credentials"},{"title":"Verify a Slack workspace connection's bot credential with Slack and record its health","description":"Verify a Slack workspace connection's bot credential with Slack and record its health. Requires permission `connections:manage`.","deprecated":null,"version":null,"sidebarTitle":"Verify a Slack workspace connection's bot credential with Slack and record its health","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-slack-workspaces/{connectionId}/healthcheck","href":"/forge/reference/http-api/connections-credentials/admin/slack-workspaces-healthcheck"},{"title":"Seal a credential to its own scope, or share it down to descendant org units","description":"Seal a credential to its own scope, or share it down to descendant org units. Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Seal a credential to its own scope, or share it down to descendant org units","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-credentials/{credentialId}/set-sharing","href":"/forge/reference/http-api/connections-credentials/admin/credentials-sharing"},{"title":"Seal a connection credential to its own scope, or share it down to descendant org units","description":"Seal a connection credential to its own scope, or share it down to descendant org units. Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Seal a connection credential to its own scope, or share it down to descendant org units","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-credentials/{credentialId}/set-sharing-for-unit","href":"/forge/reference/http-api/connections-credentials/admin/connection-credentials-sharing"},{"title":"Turn Slack Agent View on or off for one workspace connection","description":"Turn Slack Agent View on or off for one workspace connection. Requires permission `connections:manage`.","deprecated":null,"version":null,"sidebarTitle":"Turn Slack Agent View on or off for one workspace connection","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-slack-workspaces/{connectionId}/set-agent-view","href":"/forge/reference/http-api/connections-credentials/admin/slack-workspaces-agent-view"},{"title":"Update an external tool configuration's display name, workspace domain, OAuth client id, redirect URI, scopes or tools (never its secrets)","description":"Update an external tool configuration's display name, workspace domain, OAuth client id, redirect URI, scopes or tools (never its secrets). Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update an external tool configuration's display name, workspace domain, OAuth client id, redirect URI, scopes or tools (never its secrets)","openapi":"/forge/reference/openapi-v3.json patch /api/v3/connection-external-tool-configurations/{configurationId}","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-configuration-update"},{"title":"Set an external tool configuration's status","description":"Set an external tool configuration's status. Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set an external tool configuration's status","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-external-tool-configurations/{configurationId}/set-status","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-configuration-status"},{"title":"Rename an external tool identity or change its granted scopes","description":"Rename an external tool identity or change its granted scopes. Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"Rename an external tool identity or change its granted scopes","openapi":"/forge/reference/openapi-v3.json patch /api/v3/connection-external-tool-identities/{identityId}","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identity-update"},{"title":"Set an external tool identity's status (pending, active, suspended or revoked)","description":"Set an external tool identity's status (pending, active, suspended or revoked). Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set an external tool identity's status (pending, active, suspended or revoked)","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-external-tool-identities/{identityId}/set-status","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identity-status"},{"title":"Run a live verification of a credential against its vendor and record the outcome","description":"Run a live verification of a credential against its vendor and record the outcome. Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"Run a live verification of a credential against its vendor and record the outcome","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-credentials/{credentialId}/verify","href":"/forge/reference/http-api/connections-credentials/admin/credentials-verify"},{"title":"Run a live verification of a credential from an org unit's view and record the outcome","description":"Run a live verification of a credential from an org unit's view and record the outcome. Requires permission `credentials:read`.","deprecated":null,"version":null,"sidebarTitle":"Run a live verification of a credential from an org unit's view and record the outcome","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-credentials/{credentialId}/verify-for-unit","href":"/forge/reference/http-api/connections-credentials/admin/credentials-verify-for-unit"},{"title":"Probe an external tool identity against its provider and record the outcome","description":"Probe an external tool identity against its provider and record the outcome. Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"Probe an external tool identity against its provider and record the outcome","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-external-tool-identities/{identityId}/verify","href":"/forge/reference/http-api/connections-credentials/admin/external-tools-identity-verify"},{"title":"Replace an OAuth client registration's client secret, guarded by its generation","description":"Replace an OAuth client registration's client secret, guarded by its generation. Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Replace an OAuth client registration's client secret, guarded by its generation","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-oauth-registrations/{registrationId}/rotate-secret","href":"/forge/reference/http-api/connections-credentials/admin/oauth-registrations-rotate-secret"},{"title":"Revoke a connected OAuth account's grant, with a reason, and ask the provider to revoke its token","description":"Revoke a connected OAuth account's grant, with a reason, and ask the provider to revoke its token. Requires permission `credentials:manage`.","deprecated":null,"version":null,"sidebarTitle":"Revoke a connected OAuth account's grant, with a reason, and ask the provider to revoke its token","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-oauth-grants/{grantId}/revoke","href":"/forge/reference/http-api/connections-credentials/admin/oauth-grants-revoke"},{"title":"Create an external tool configuration","description":"Create an external tool configuration. The service-account key and OAuth client secret are encrypted before they are stored and never returned.","deprecated":null,"version":null,"sidebarTitle":"Create an external tool configuration","openapi":"/forge/reference/openapi-v3.json post /api/v3/connection-external-tool-configurations","href":"/forge/reference/http-api/connections-credentials/create-external-tool-configuration"},{"title":"Create a procedure credential","description":"Create an approved system-scope credential for a procedure. Each secret field goes to the secrets store; no answer carries it.","deprecated":null,"version":null,"sidebarTitle":"Create a procedure credential","openapi":"/forge/reference/openapi-v3.json post /api/v3/procedures/{procedureId}/credentials","href":"/forge/reference/http-api/connections-credentials/create-procedure-credential"},{"title":"Create a tool credential","description":"Create a pending tool credential at a scope from its field values. Each secret goes to the secrets store; no answer carries it.","deprecated":null,"version":null,"sidebarTitle":"Create a tool credential","openapi":"/forge/reference/openapi-v3.json post /api/v3/tools/{toolId}/credentials","href":"/forge/reference/http-api/connections-credentials/create-tool-credential"}]},{"group":"Environments and secrets","icon":"server","root":{"title":"Environments administration","sidebarTitle":"Environments","icon":"server","description":"Create, list, rename and remove Environment Connections, and set their credentials, with a platform API key.","href":"/forge/reference/http-api/environments-secrets"},"pages":[{"title":"Create an Environment Connection without a credential, homed at the deployment root","description":"Create an Environment Connection without a credential, homed at the deployment root; answers its id. Requires permission `environments:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create an Environment Connection without a credential, homed at the deployment root","openapi":"/forge/reference/openapi-v3.json post /api/v3/environment-connections","href":"/forge/reference/http-api/environments-secrets/admin/connections-create"},{"title":"Create an Environment Connection with its credential","description":"Create an Environment Connection with its credential; answers its id. Requires permission `environments:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create an Environment Connection with its credential","openapi":"/forge/reference/openapi-v3.json post /api/v3/environment-connections/create-with-credential","href":"/forge/reference/http-api/environments-secrets/admin/connections-create-with-credential"},{"title":"Delete an Environment Connection and revoke its credential","description":"Delete an Environment Connection and revoke its credential. Requires permission `environments:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete an Environment Connection and revoke its credential","openapi":"/forge/reference/openapi-v3.json delete /api/v3/environment-connections/{connectionId}","href":"/forge/reference/http-api/environments-secrets/admin/connections-remove"},{"title":"Rename an Environment Connection","description":"Rename an Environment Connection. Requires permission `environments:manage`.","deprecated":null,"version":null,"sidebarTitle":"Rename an Environment Connection","openapi":"/forge/reference/openapi-v3.json patch /api/v3/environment-connections/{connectionId}","href":"/forge/reference/http-api/environments-secrets/admin/connections-update"},{"title":"List a page of the workspace's Environment Connections, in creation order","description":"List a page of the workspace's Environment Connections, in creation order. Requires permission `environments:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the workspace's Environment Connections, in creation order","openapi":"/forge/reference/openapi-v3.json get /api/v3/environment-connections","href":"/forge/reference/http-api/environments-secrets/admin/connections-list"},{"title":"Replace an Environment Connection's credential","description":"Replace an Environment Connection's credential. Requires permission `environments:manage`.","deprecated":null,"version":null,"sidebarTitle":"Replace an Environment Connection's credential","openapi":"/forge/reference/openapi-v3.json post /api/v3/environment-connections/{connectionId}/replace-credential","href":"/forge/reference/http-api/environments-secrets/admin/connections-replace-credential"}]},{"group":"Vendors","icon":"building","root":{"title":"Vendors administration","sidebarTitle":"Vendors","icon":"store","description":"Administer the vendor registry, its API specs and its knowledge notes, and read connection clients and remote MCP catalogs, with a platform API key.","href":"/forge/reference/http-api/vendors"},"pages":[{"title":"Add an operator knowledge note (a pitfall or quirk) to a vendor","description":"Add an operator knowledge note (a pitfall or quirk) to a vendor. Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Add an operator knowledge note (a pitfall or quirk) to a vendor","openapi":"/forge/reference/openapi-v3.json post /api/v3/vendor-lessons","href":"/forge/reference/http-api/vendors/admin/notes-add"},{"title":"Approve or quarantine one tool of a remote MCP server at the schema hash its latest discovery recorded, with its risk level","description":"Approve or quarantine one tool of a remote MCP server at the schema hash its latest discovery recorded, with its risk level. Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Approve or quarantine one tool of a remote MCP server at the schema hash its latest discovery recorded, with its risk level","openapi":"/forge/reference/openapi-v3.json post /api/v3/tools/{toolId}/set-mcp-tool-policy","href":"/forge/reference/http-api/vendors/admin/mcp-tool-policy"},{"title":"Attach an API spec (OpenAPI, Markdown or a link) to a vendor","description":"Attach an API spec (OpenAPI, Markdown or a link) to a vendor. Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Attach an API spec (OpenAPI, Markdown or a link) to a vendor","openapi":"/forge/reference/openapi-v3.json post /api/v3/vendor-api-specs","href":"/forge/reference/http-api/vendors/admin/specs-attach"},{"title":"Create a vendor in the registry","description":"Create a vendor in the registry. Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Create a vendor in the registry","openapi":"/forge/reference/openapi-v3.json post /api/v3/vendors","href":"/forge/reference/http-api/vendors/admin/create"},{"title":"Edit a vendor's name, description, links, aliases or tags","description":"Edit a vendor's name, description, links, aliases or tags. Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Edit a vendor's name, description, links, aliases or tags","openapi":"/forge/reference/openapi-v3.json patch /api/v3/vendors/{vendorId}","href":"/forge/reference/http-api/vendors/admin/update"},{"title":"Edit a vendor API spec's title, source, notes, version or connection","description":"Edit a vendor API spec's title, source, notes, version or connection. Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Edit a vendor API spec's title, source, notes, version or connection","openapi":"/forge/reference/openapi-v3.json patch /api/v3/vendor-api-specs/{apiSpecId}","href":"/forge/reference/http-api/vendors/admin/specs-update"},{"title":"Edit an operator knowledge note's content or connection","description":"Edit an operator knowledge note's content or connection. Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Edit an operator knowledge note's content or connection","openapi":"/forge/reference/openapi-v3.json patch /api/v3/vendor-lessons/{lessonId}","href":"/forge/reference/http-api/vendors/admin/notes-update"},{"title":"Get a vendor and the tools, procedures and capability providers linked to it","description":"Get a vendor and the tools, procedures and capability providers linked to it. Requires permission `vendors:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a vendor and the tools, procedures and capability providers linked to it","openapi":"/forge/reference/openapi-v3.json get /api/v3/vendor-detail","href":"/forge/reference/http-api/vendors/admin/detail"},{"title":"Link a tool or procedure to a vendor (a link that already exists answers its id)","description":"Link a tool or procedure to a vendor (a link that already exists answers its id). Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Link a tool or procedure to a vendor (a link that already exists answers its id)","openapi":"/forge/reference/openapi-v3.json post /api/v3/vendors/{vendorId}/links","href":"/forge/reference/http-api/vendors/admin/links-add"},{"title":"List a page of a vendor's attached API specs, in the order they were attached","description":"List a page of a vendor's attached API specs, in the order they were attached. Requires permission `vendors:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a vendor's attached API specs, in the order they were attached","openapi":"/forge/reference/openapi-v3.json get /api/v3/vendor-api-specs","href":"/forge/reference/http-api/vendors/admin/specs"},{"title":"List a page of a vendor's connections by name, each with its Credentials' scope and verification state and its connected OAuth accounts' lifecycle (never a value or a person's identity)","description":"List a page of a vendor's connections by name, each with its Credentials' scope and verification state and its connected OAuth accounts' lifecycle (never a value or a person's identity). Requires permission `vendors:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a vendor's connections by name, each with its Credentials' scope and verification state and its connected OAuth accounts' lifecycle (never a value or a person's identity)","openapi":"/forge/reference/openapi-v3.json get /api/v3/vendor-connections","href":"/forge/reference/http-api/vendors/admin/connections"},{"title":"List a page of a vendor's active earned lessons and knowledge notes, in the order they were recorded","description":"List a page of a vendor's active earned lessons and knowledge notes, in the order they were recorded. Requires permission `vendors:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a vendor's active earned lessons and knowledge notes, in the order they were recorded","openapi":"/forge/reference/openapi-v3.json get /api/v3/vendor-lessons","href":"/forge/reference/http-api/vendors/admin/lessons"},{"title":"List a page of the vendor registry, newest first, each vendor with its tool, procedure and provider link counts","description":"List a page of the vendor registry, newest first, each vendor with its tool, procedure and provider link counts. Requires permission `vendors:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the vendor registry, newest first, each vendor with its tool, procedure and provider link counts","openapi":"/forge/reference/openapi-v3.json get /api/v3/vendors","href":"/forge/reference/http-api/vendors/admin/list"},{"title":"Get a connection's generated client surface by selection — its index at a path, its resource families, one family, one type, or its implementation files","description":"Get a connection's generated client surface by selection — its index at a path, its resource families, one family, one type, or its implementation files. Requires permission `vendors:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a connection's generated client surface by selection — its index at a path, its resource families, one family, one type, or its implementation files","openapi":"/forge/reference/openapi-v3.json get /api/v3/vendor-connection-client-surface","href":"/forge/reference/http-api/vendors/admin/connections-client-surface"},{"title":"Get a remote MCP connection's discovered tool catalog and each tool's policy state","description":"Get a remote MCP connection's discovered tool catalog and each tool's policy state. Requires permission `vendors:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a remote MCP connection's discovered tool catalog and each tool's policy state","openapi":"/forge/reference/openapi-v3.json get /api/v3/vendor-connection-mcp-catalog","href":"/forge/reference/http-api/vendors/admin/connections-mcp-catalog"},{"title":"Remove a vendor API spec (a spec already removed succeeds)","description":"Remove a vendor API spec (a spec already removed succeeds). Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Remove a vendor API spec (a spec already removed succeeds)","openapi":"/forge/reference/openapi-v3.json delete /api/v3/vendor-api-specs/{apiSpecId}","href":"/forge/reference/http-api/vendors/admin/specs-remove"},{"title":"Retire a knowledge note (it is superseded, not deleted)","description":"Retire a knowledge note (it is superseded, not deleted). Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Retire a knowledge note (it is superseded, not deleted)","openapi":"/forge/reference/openapi-v3.json post /api/v3/vendor-lessons/{lessonId}/retire","href":"/forge/reference/http-api/vendors/admin/notes-retire"},{"title":"Set a vendor's approval status","description":"Set a vendor's approval status. Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Set a vendor's approval status","openapi":"/forge/reference/openapi-v3.json post /api/v3/vendors/{vendorId}/set-approval-status","href":"/forge/reference/http-api/vendors/admin/approval-status-set"},{"title":"Unlink a tool or procedure from its vendor (a link already removed succeeds)","description":"Unlink a tool or procedure from its vendor (a link already removed succeeds). Requires permission `vendors:write`.","deprecated":null,"version":null,"sidebarTitle":"Unlink a tool or procedure from its vendor (a link already removed succeeds)","openapi":"/forge/reference/openapi-v3.json delete /api/v3/vendor-links/{linkId}","href":"/forge/reference/http-api/vendors/admin/links-remove"}]},{"group":"Capabilities","icon":"plug","root":{"title":"Capabilities","sidebarTitle":"Capabilities","icon":"plug","description":"Read and configure the deployment's capability domains, their provider chains, the provider catalog, credential health, org bindings and recent capability changes.","href":"/forge/reference/http-api/capabilities"},"pages":[{"title":"List capability domains","description":"Returns every capability domain with its status, dispatch mode and active provider chain. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List capability domains","openapi":"/forge/reference/openapi-v3.json get /api/v3/capabilities","href":"/forge/reference/http-api/capabilities/list"},{"title":"Get a capability domain","description":"Returns one capability domain with its available providers and the credential health of each provider in its active chain. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Get a capability domain","openapi":"/forge/reference/openapi-v3.json get /api/v3/capabilities/{domain}","href":"/forge/reference/http-api/capabilities/get"},{"title":"List a capability's recent audit events","description":"Returns the most recent recorded changes to one capability domain, newest first, with event, category and time only; the actor and the change detail stay in Console. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List a capability's recent audit events","openapi":"/forge/reference/openapi-v3.json get /api/v3/capabilities/{domain}/audit-events","href":"/forge/reference/http-api/capabilities/listauditevents"},{"title":"List catalogued providers","description":"Returns every catalogued provider with the capability domains it serves. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"List catalogued providers","openapi":"/forge/reference/openapi-v3.json get /api/v3/providers","href":"/forge/reference/http-api/providers/list"},{"title":"Get a provider","description":"Returns one catalogued provider with the capability chains that use it and the credential health of each connection target it authenticates through. Requires permissions `grants:read`, `policies:read` and `audit:read` at the deployment root.","deprecated":null,"version":null,"sidebarTitle":"Get a provider","openapi":"/forge/reference/openapi-v3.json get /api/v3/providers/{providerKey}","href":"/forge/reference/http-api/providers/get"},{"title":"List a provider's recent audit events","description":"Returns the most recent recorded changes to one provider, newest first, with event, category and time only; the actor and the change detail (option diffs) stay in Console. Requires permission `audit:read` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"List a provider's recent audit events","openapi":"/forge/reference/openapi-v3.json get /api/v3/providers/{providerKey}/audit-events","href":"/forge/reference/http-api/providers/listauditevents"},{"title":"Get a capability's binding readiness for an org unit","description":"Get a capability's provider binding readiness for an org unit. Requires permission `credentials:read` at the org unit.","deprecated":null,"version":null,"sidebarTitle":"Get a capability's binding readiness","openapi":"/forge/reference/openapi-v3.json get /api/v3/capabilities/{domain}/binding-readiness","href":"/forge/reference/http-api/capabilities/getbindingreadiness"},{"title":"Set a capability's provider chain","description":"Sets the ordered provider chain of a capability domain and, optionally, each provider's binding options, as the Console's capability editor does. Requires permission `platform:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Set a capability's provider chain","openapi":"/forge/reference/openapi-v3.json post /api/v3/capabilities/{domain}/set-chain","href":"/forge/reference/http-api/capabilities/setchain"},{"title":"Turn a capability off","description":"Turns a capability domain off — its chain becomes empty and its provider records are disabled, so nothing resolves for it; per-provider options are kept for re-enabling. Requires permission `platform:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Turn a capability off","openapi":"/forge/reference/openapi-v3.json post /api/v3/capabilities/{domain}/disable","href":"/forge/reference/http-api/capabilities/disable"},{"title":"Bind an org unit to a capability provider","description":"Binds one org unit to an enabled provider record of a bindable capability (`file_hosting`, `source_control`, `typed_judgments`), as the Console's binding editor does. Requires permission `platform:manage` at the org unit.","deprecated":null,"version":null,"sidebarTitle":"Bind an org unit to a capability provider","openapi":"/forge/reference/openapi-v3.json post /api/v3/capabilities/{domain}/bind-organization","href":"/forge/reference/http-api/capabilities/bindorganization"},{"title":"Set a provider's options","description":"Replaces a provider's global options, validated against its options schema. Requires permission `platform:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Set a provider's options","openapi":"/forge/reference/openapi-v3.json post /api/v3/providers/{providerKey}/set-options","href":"/forge/reference/http-api/providers/setoptions"},{"title":"Enable a provider","description":"Enables a provider, and its records in every capability domain whose chain names it, so it resolves there again; a record of a domain whose chain does not name it stays off. Requires permission `platform:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Enable a provider","openapi":"/forge/reference/openapi-v3.json post /api/v3/providers/{providerKey}/enable","href":"/forge/reference/http-api/providers/enable"},{"title":"Disable a provider","description":"Disables a provider and its records in every capability domain, so resolution skips it; a pinned foundation record stays on. Requires permission `platform:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Disable a provider","openapi":"/forge/reference/openapi-v3.json post /api/v3/providers/{providerKey}/disable","href":"/forge/reference/http-api/providers/disable"},{"title":"Create a provider record","description":"Adds a provider record to a capability domain for a protocol-generic adapter (for example the inference `openai-compatible` adapter), an approved vendor and a connection with an approved credential. Requires permission `platform:manage` at the platform scope.","deprecated":null,"version":null,"sidebarTitle":"Create a provider record","openapi":"/forge/reference/openapi-v3.json post /api/v3/provider-records","href":"/forge/reference/http-api/providers/createrecord"}]},{"group":"Sandboxes","icon":"box","root":{"title":"Sandboxes","sidebarTitle":"Sandboxes","icon":"box","description":"Inspect a run's sandboxes over the Platform API: runs that used them, the fleet summary, a run's lineage, active sandboxes and step commands; diff two snapshots and replay a command.","href":"/forge/reference/http-api/sandboxes"},"pages":[{"title":"List recent runs that used sandboxes","description":"Lists the runs whose sandbox lineages changed most recently, newest first, with each run's lineage count and last change. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"List sandbox runs","openapi":"/forge/reference/openapi-v3.json get /api/v3/sandbox-runs","href":"/forge/reference/http-api/sandboxes/listruns"},{"title":"Get the sandbox fleet summary","description":"Returns the cached fleet summary the hourly reconciler writes — live, referenced and orphaned snapshot counts and bytes, procedure images and whether each is present, and running VMs by owner. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"Get sandbox fleet summary","openapi":"/forge/reference/openapi-v3.json get /api/v3/sandbox-fleet-summary","href":"/forge/reference/http-api/sandboxes/getfleetsummary"},{"title":"Get a run's sandbox lineage graph","description":"Returns the sandbox lineages a run owns and every snapshot in them — runtime, resources, the step and agent that created each, status, expiry, size, cost and labels. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"Get sandbox lineage","openapi":"/forge/reference/openapi-v3.json get /api/v3/sandbox-runs/{runId}/lineage","href":"/forge/reference/http-api/sandboxes/getlineage"},{"title":"List a run's active sandboxes","description":"Lists the sandboxes the run's running steps hold, with the lineage each step created snapshots in. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"List active sandboxes","openapi":"/forge/reference/openapi-v3.json get /api/v3/sandbox-runs/{runId}/active-sandboxes","href":"/forge/reference/http-api/sandboxes/listactive"},{"title":"List a step's sandbox commands","description":"List a step's sandbox commands. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"List sandbox commands","openapi":"/forge/reference/openapi-v3.json get /api/v3/sandbox-runs/{runId}/commands","href":"/forge/reference/http-api/sandboxes/listcommands"},{"title":"Diff two sandbox snapshots","description":"Diff two sandbox snapshots. Requires permission `factories:read`.","deprecated":null,"version":null,"sidebarTitle":"Diff sandbox snapshots","openapi":"/forge/reference/openapi-v3.json get /api/v3/sandbox-snapshot-diff","href":"/forge/reference/http-api/sandboxes/diffsnapshots"},{"title":"Run a command against a sandbox snapshot","description":"Starts a billable VM restored from the snapshot, runs `command` as `sh -c` with the timeout (default 60 seconds), releases the VM and answers the exit code, stdout and stderr (at most 262,144 characters each). Requires permission `factories:manage`.","deprecated":null,"version":null,"sidebarTitle":"Replay sandbox command","openapi":"/forge/reference/openapi-v3.json post /api/v3/sandbox-snapshots/{snapshotId}/replay-command","href":"/forge/reference/http-api/sandboxes/replaycommand"}]},{"group":"Webhooks","icon":"webhook","root":{"title":"Webhooks","sidebarTitle":"Webhooks","icon":"webhook","description":"Subscribe External Apps to scope-gated platform events and replay a past delivery. Each delivery is the v2 event envelope, signed with a timestamped HMAC (X-Forge-Signature-V2) and retried.","href":"/forge/reference/http-api/webhooks"},"pages":[{"title":"Create a webhook","description":"Create a webhook subscription for an External App. Returns the signing secret once — store it immediately.","deprecated":null,"version":null,"sidebarTitle":"Create","openapi":"/forge/reference/openapi-v3.json post /api/v3/webhooks","href":"/forge/reference/http-api/webhooks/create"},{"title":"Delete a webhook","description":"Revoke a webhook subscription by id.","deprecated":null,"version":null,"sidebarTitle":"Delete","openapi":"/forge/reference/openapi-v3.json delete /api/v3/webhooks/{webhookId}","href":"/forge/reference/http-api/webhooks/delete"},{"title":"Rotate webhook secret","description":"Mint a new signing secret for an existing webhook subscription. Returns the new secret once.","deprecated":null,"version":null,"sidebarTitle":"Rotate secret","openapi":"/forge/reference/openapi-v3.json post /api/v3/webhooks/{webhookId}/rotate-secret","href":"/forge/reference/http-api/webhooks/rotatesecret"},{"title":"Replay a webhook delivery","description":"Re-send one of the calling External App's past webhook deliveries as a new delivery of the same event.","deprecated":null,"version":null,"sidebarTitle":"Replay","openapi":"/forge/reference/openapi-v3.json post /api/v3/webhook-deliveries/{deliveryId}/replay","href":"/forge/reference/http-api/webhooks/replay"},{"title":"Events","description":"GET /api/v2/events — the cursor-paginated canonical event log an External App reconciles webhook delivery against. Opaque cursors, type filtering, the two-layer visibility rule, and the 30-day window.","deprecated":null,"version":null,"sidebarTitle":"Events","openapi":"/forge/reference/openapi-v3.json get /api/v3/events","href":"/forge/reference/http-api/events"},{"title":"Update a webhook subscription's URL, events, label or auth token (null clears the token)","description":"Update a webhook subscription's URL, events, label or auth token (null clears the token); an id that names no subscription changes nothing. Requires permission `webhooks:manage`.","deprecated":null,"version":null,"sidebarTitle":"Update a webhook subscription's URL, events, label or auth token (null clears the token)","openapi":"/forge/reference/openapi-v3.json patch /api/v3/webhooks/{webhookId}","href":"/forge/reference/http-api/webhooks/admin/update"},{"title":"List a page of a webhook subscription's deliveries, newest first","description":"List a page of a webhook subscription's deliveries, newest first. Requires permission `webhooks:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a webhook subscription's deliveries, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/webhooks/{webhookId}/deliveries","href":"/forge/reference/http-api/webhooks/admin/deliveries"},{"title":"List a page of dead-lettered webhook deliveries, newest first, optionally by status and event type","description":"List a page of dead-lettered webhook deliveries, newest first, optionally by status and event type. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of dead-lettered webhook deliveries, newest first, optionally by status and event type","openapi":"/forge/reference/openapi-v3.json get /api/v3/webhook-dead-letters","href":"/forge/reference/http-api/webhooks/admin/dead-letters"},{"title":"Pause a webhook subscription","description":"Pause a webhook subscription; an id that names no subscription changes nothing. Requires permission `webhooks:manage`.","deprecated":null,"version":null,"sidebarTitle":"Pause a webhook subscription","openapi":"/forge/reference/openapi-v3.json post /api/v3/webhooks/{webhookId}/pause","href":"/forge/reference/http-api/webhooks/admin/pause"},{"title":"Resume a webhook subscription and clear its failure count","description":"Resume a webhook subscription and clear its failure count; an id that names no subscription changes nothing. Requires permission `webhooks:manage`.","deprecated":null,"version":null,"sidebarTitle":"Resume a webhook subscription and clear its failure count","openapi":"/forge/reference/openapi-v3.json post /api/v3/webhooks/{webhookId}/resume","href":"/forge/reference/http-api/webhooks/admin/resume"},{"title":"Count dead-lettered webhook deliveries by status and by event type","description":"Count dead-lettered webhook deliveries by status and by event type. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"Count dead-lettered webhook deliveries by status and by event type","openapi":"/forge/reference/openapi-v3.json get /api/v3/webhook-dead-letter-stats","href":"/forge/reference/http-api/webhooks/admin/dead-letters-stats"},{"title":"Get delivery health over the last 24 hours for each named webhook subscription","description":"Get delivery health over the last 24 hours for each named webhook subscription. Requires permission `webhooks:read`.","deprecated":null,"version":null,"sidebarTitle":"Get delivery health over the last 24 hours for each named webhook subscription","openapi":"/forge/reference/openapi-v3.json get /api/v3/webhook-health","href":"/forge/reference/http-api/webhooks/admin/health"},{"title":"Send a test delivery to a webhook subscription and answer its delivery id","description":"Send a test delivery to a webhook subscription and answer its delivery id. Requires permission `webhooks:manage`.","deprecated":null,"version":null,"sidebarTitle":"Send a test delivery to a webhook subscription and answer its delivery id","openapi":"/forge/reference/openapi-v3.json post /api/v3/webhooks/{webhookId}/test","href":"/forge/reference/http-api/webhooks/admin/test"},{"title":"List a page of every webhook subscription, admin-owned and app-owned, newest first","description":"List a page of every webhook subscription, admin-owned and app-owned, newest first; no signing secret or auth token is answered. Requires permission `webhooks:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of every webhook subscription, admin-owned and app-owned, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/webhooks","href":"/forge/reference/http-api/webhooks/admin/list"},{"title":"Replay a pending dead-lettered webhook delivery as a new delivery and answer its id","description":"Replay a pending dead-lettered webhook delivery as a new delivery and answer its id. Requires permission `webhooks:manage`.","deprecated":null,"version":null,"sidebarTitle":"Replay a pending dead-lettered webhook delivery as a new delivery and answer its id","openapi":"/forge/reference/openapi-v3.json post /api/v3/webhook-dead-letters/{deadLetterId}/replay","href":"/forge/reference/http-api/webhooks/admin/dead-letters-replay"},{"title":"Revoke a webhook subscription","description":"Revoke a webhook subscription; an id that names no subscription changes nothing. Requires permission `webhooks:manage`.","deprecated":null,"version":null,"sidebarTitle":"Revoke a webhook subscription","openapi":"/forge/reference/openapi-v3.json post /api/v3/webhooks/{webhookId}/revoke","href":"/forge/reference/http-api/webhooks/admin/revoke"},{"title":"Redeliver an event","description":"Replay the newest delivery of one event to one of the calling app's webhook subscriptions.","deprecated":null,"version":null,"sidebarTitle":"Redeliver an event","openapi":"/forge/reference/openapi-v3.json post /api/v3/webhook-deliveries/redeliver","href":"/forge/reference/http-api/webhooks/redeliverevent"},{"title":"List a delivery's attempts","description":"Each attempt of one of the calling app's deliveries, newest last, at most ten, with the receiver's status.","deprecated":null,"version":null,"sidebarTitle":"List a delivery's attempts","openapi":"/forge/reference/openapi-v3.json get /api/v3/webhook-deliveries/{deliveryId}/attempts","href":"/forge/reference/http-api/webhooks/listdeliveryattempts"}]},{"group":"Email","icon":"envelope","root":{"title":"Email administration","sidebarTitle":"Email","icon":"envelope","description":"Read and administer inbound email routes, the inbound email ingress and the sending domain with a platform API key.","href":"/forge/reference/http-api/email"},"pages":[{"title":"Create an inbound email route — a local part that drops its mail, or starts a workflow through a trigger the route owns","description":"Create an inbound email route — a local part that drops its mail, or starts a workflow through a trigger the route owns. Requires permission `webhooks:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create an inbound email route — a local part that drops its mail, or starts a workflow through a trigger the route owns","openapi":"/forge/reference/openapi-v3.json post /api/v3/email-routes","href":"/forge/reference/http-api/email/admin/routes-create"},{"title":"Delete an inbound email route and the workflow trigger it owns","description":"Delete an inbound email route and the workflow trigger it owns. Requires permission `webhooks:manage`.","deprecated":null,"version":null,"sidebarTitle":"Delete an inbound email route and the workflow trigger it owns","openapi":"/forge/reference/openapi-v3.json delete /api/v3/email-routes/{routeId}","href":"/forge/reference/http-api/email/admin/routes-delete"},{"title":"Change an inbound email route's sender policy, rate or whether it is enabled","description":"Change an inbound email route's sender policy, rate or whether it is enabled. Requires permission `webhooks:manage`.","deprecated":null,"version":null,"sidebarTitle":"Change an inbound email route's sender policy, rate or whether it is enabled","openapi":"/forge/reference/openapi-v3.json patch /api/v3/email-routes/{routeId}","href":"/forge/reference/http-api/email/admin/routes-update"},{"title":"List a page of the inbound email routes, oldest first — each local part, its kind, sender policy, rate and whether it is enabled","description":"List a page of the inbound email routes, oldest first — each local part, its kind, sender policy, rate and whether it is enabled. Requires permission `webhooks:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the inbound email routes, oldest first — each local part, its kind, sender policy, rate and whether it is enabled","openapi":"/forge/reference/openapi-v3.json get /api/v3/email-routes","href":"/forge/reference/http-api/email/admin/routes"},{"title":"List the outbound email outbox, newest first, a page at a time — each delivery's sender, status and attempts","description":"List the outbound email outbox, newest first, a page at a time — each delivery's sender, status and attempts. Requires permission `webhooks:read`.","deprecated":null,"version":null,"sidebarTitle":"List the outbound email outbox, newest first, a page at a time — each delivery's sender, status and attempts","openapi":"/forge/reference/openapi-v3.json get /api/v3/email-deliveries","href":"/forge/reference/http-api/email/admin/deliveries"},{"title":"List received email, newest first, a page at a time — each message's id, disposition and attachment count","description":"List received email, newest first, a page at a time — each message's id, disposition and attachment count. Requires permission `webhooks:read`.","deprecated":null,"version":null,"sidebarTitle":"List received email, newest first, a page at a time — each message's id, disposition and attachment count","openapi":"/forge/reference/openapi-v3.json get /api/v3/email-inbound","href":"/forge/reference/http-api/email/admin/inbound"},{"title":"Pause or resume inbound email","description":"Pause or resume inbound email. Requires permission `webhooks:manage`.","deprecated":null,"version":null,"sidebarTitle":"Pause or resume inbound email","openapi":"/forge/reference/openapi-v3.json post /api/v3/email-ingress/set-status","href":"/forge/reference/http-api/email/admin/ingress-status"},{"title":"Get the email sending domain, the credential scope and each sender's From address and reply policy","description":"Get the email sending domain, the credential scope and each sender's From address and reply policy. Requires permission `webhooks:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the email sending domain, the credential scope and each sender's From address and reply policy","openapi":"/forge/reference/openapi-v3.json get /api/v3/email-senders","href":"/forge/reference/http-api/email/admin/senders"},{"title":"Get the inbound email ingress — its token prefix and status (never the token)","description":"Get the inbound email ingress — its token prefix and status (never the token). Requires permission `webhooks:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the inbound email ingress — its token prefix and status (never the token)","openapi":"/forge/reference/openapi-v3.json get /api/v3/email-ingress","href":"/forge/reference/http-api/email/admin/ingress"}]},{"group":"Notifications","icon":"bell","root":{"title":"Notifications administration","sidebarTitle":"Notifications","icon":"bell","description":"List the notification event types and the recent outbound Slack sends with a platform API key.","href":"/forge/reference/http-api/notifications"},"pages":[{"title":"List the notification event types","description":"List the notification event types; for each, its payload fields, cluster and per-channel delivery, and which channels have a provider; needs audit:read, grants:read and policies:read at the platform scope. Requires permissions `audit:read`, `grants:read` and `policies:read`.","deprecated":null,"version":null,"sidebarTitle":"List the notification event types","openapi":"/forge/reference/openapi-v3.json get /api/v3/notification-event-types","href":"/forge/reference/http-api/notifications/admin/event-types"},{"title":"List a page of the outbound Slack sends, newest first, optionally for one surface — each send's surface, event type, outcome and Slack timestamps","description":"List a page of the outbound Slack sends, newest first, optionally for one surface — each send's surface, event type, outcome and Slack timestamps. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the outbound Slack sends, newest first, optionally for one surface — each send's surface, event type, outcome and Slack timestamps","openapi":"/forge/reference/openapi-v3.json get /api/v3/notification-slack-sends","href":"/forge/reference/http-api/notifications/admin/slack-sends"}]}]},{"group":"Cost and operations","icon":"chart-line","root":{"title":"Cost and operations API","sidebarTitle":"Cost and operations","icon":"chart-line","description":"HTTP API operations for budgets, spending limits, token events and prices, the attention board, run audit, workflow analytics and health.","href":"/forge/reference/http-api/families/cost-and-operations"},"pages":[{"group":"Costs and budgets","icon":"coins","root":{"title":"Costs and budgets administration","sidebarTitle":"Costs and budgets","icon":"coins","description":"Manage budgets, spending limits and budget alerts, and read token events, cost aggregates and model prices, with a platform API key.","href":"/forge/reference/http-api/costs-budgets"},"pages":[{"title":"Get the budget status of the caller's acting org unit","description":"Returns the budget of the caller's acting org unit — its own budget node — with budget, used, remaining and percent-used amounts in cents. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Get budget status","openapi":"/forge/reference/openapi-v3.json get /api/v3/me/budget-status","href":"/forge/reference/http-api/budgets/getstatus"},{"title":"Cost","sidebarTitle":"Cost","icon":"coins","description":"Read the deployment's spend totals and one customer's spend.","href":"/forge/reference/http-api/cost"},{"title":"Deployment-wide bucketed cost summary","description":"Returns the deployment's pre-aggregated spend totals over a time range — one total per bucket, or one interface's total per bucket when `interfaceId` is named. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Deployment cost summary","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-summary","href":"/forge/reference/http-api/cost/summary"},{"title":"Per-customer cost aggregates","description":"Returns spend aggregates for one customer. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Customer cost","openapi":"/forge/reference/openapi-v3.json get /api/v3/customers/{customerId}/cost","href":"/forge/reference/http-api/cost/customer"},{"title":"Acknowledge a triggered budget alert","description":"Acknowledge a triggered budget alert. Requires permission `cost:manage`.","deprecated":null,"version":null,"sidebarTitle":"Acknowledge a triggered budget alert","openapi":"/forge/reference/openapi-v3.json post /api/v3/cost-budget-alerts/{alertId}/acknowledge","href":"/forge/reference/http-api/costs-budgets/admin/budgets-alerts-acknowledge"},{"title":"Create a spend-threshold alert on a budget","description":"Create a spend-threshold alert on a budget. Requires permission `cost:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create a spend-threshold alert on a budget","openapi":"/forge/reference/openapi-v3.json post /api/v3/cost-budgets/{budgetId}/alerts","href":"/forge/reference/http-api/costs-budgets/admin/budgets-alerts-create"},{"title":"Create a budget anchored at an org unit, optionally under a parent budget","description":"Create a budget anchored at an org unit, optionally under a parent budget. Requires permission `cost:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create a budget anchored at an org unit, optionally under a parent budget","openapi":"/forge/reference/openapi-v3.json post /api/v3/cost-budgets","href":"/forge/reference/http-api/costs-budgets/admin/budgets-create"},{"title":"Create or update the spending limit for a scope and period","description":"Create or update the spending limit for a scope and period. Requires permission `cost:manage`.","deprecated":null,"version":null,"sidebarTitle":"Create or update the spending limit for a scope and period","openapi":"/forge/reference/openapi-v3.json post /api/v3/cost-limits/upsert","href":"/forge/reference/http-api/costs-budgets/admin/limits-upsert"},{"title":"Remove a spending limit (an unknown id changes nothing)","description":"Remove a spending limit (an unknown id changes nothing). Requires permission `cost:manage`.","deprecated":null,"version":null,"sidebarTitle":"Remove a spending limit (an unknown id changes nothing)","openapi":"/forge/reference/openapi-v3.json delete /api/v3/cost-limits/{limitId}","href":"/forge/reference/http-api/costs-budgets/admin/limits-remove"},{"title":"Turn a spending limit on or off","description":"Turn a spending limit on or off. Requires permission `cost:manage`.","deprecated":null,"version":null,"sidebarTitle":"Turn a spending limit on or off","openapi":"/forge/reference/openapi-v3.json post /api/v3/cost-limits/{limitId}/set-enabled","href":"/forge/reference/http-api/costs-budgets/admin/limits-enabled"},{"title":"Freeze a spending limit (an operator kill switch), with a reason","description":"Freeze a spending limit (an operator kill switch), with a reason. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Freeze a spending limit (an operator kill switch), with a reason","openapi":"/forge/reference/openapi-v3.json post /api/v3/cost-limits/{limitId}/freeze","href":"/forge/reference/http-api/costs-budgets/admin/limits-freeze"},{"title":"Unfreeze a spending limit, with a reason","description":"Unfreeze a spending limit, with a reason. Requires permission `switches:use`.","deprecated":null,"version":null,"sidebarTitle":"Unfreeze a spending limit, with a reason","openapi":"/forge/reference/openapi-v3.json post /api/v3/cost-limits/{limitId}/unfreeze","href":"/forge/reference/http-api/costs-budgets/admin/limits-unfreeze"},{"title":"Get a run step's booked sandbox compute cost and open leases","description":"Get a run step's booked sandbox compute cost and open leases. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a run step's booked sandbox compute cost and open leases","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/step-sandbox-costs/{nodeId}","href":"/forge/reference/http-api/costs-budgets/admin/runs-step-sandbox-cost"},{"title":"List a page of the spending limits for a scope, by scope id (none first), then createdAt, then id","description":"List a page of the spending limits for a scope, by scope id (none first), then createdAt, then id. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the spending limits for a scope, by scope id (none first), then createdAt, then id","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-limit-scopes/{scope}/limits","href":"/forge/reference/http-api/costs-budgets/admin/limits"},{"title":"List a page of every spending limit across scopes, in id order","description":"List a page of every spending limit across scopes, in id order. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of every spending limit across scopes, in id order","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-limits","href":"/forge/reference/http-api/costs-budgets/admin/limits-all"},{"title":"List a page of the token events, newest first","description":"List a page of the token events, newest first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the token events, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-token-events","href":"/forge/reference/http-api/costs-budgets/admin/token-events"},{"title":"List a page of the token events in a time range, newest first","description":"List a page of the token events in a time range, newest first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the token events in a time range, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-time-range-token-events","href":"/forge/reference/http-api/costs-budgets/admin/token-events-time-range"},{"title":"List a page of an agent's token events, newest first, optionally in a time range","description":"List a page of an agent's token events, newest first, optionally in a time range. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of an agent's token events, newest first, optionally in a time range","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/token-events","href":"/forge/reference/http-api/costs-budgets/admin/token-events-agent"},{"title":"List a page of a workflow's token events, newest first","description":"List a page of a workflow's token events, newest first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a workflow's token events, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/token-events","href":"/forge/reference/http-api/costs-budgets/admin/token-events-workflow"},{"title":"List a page of a session's token events, newest first","description":"List a page of a session's token events, newest first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a session's token events, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-sessions/{sessionKey}/token-events","href":"/forge/reference/http-api/costs-budgets/admin/token-events-session"},{"title":"List a page of a session's token events within the key's org units, newest first","description":"List a page of a session's token events within the key's org units, newest first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a session's token events within the key's org units, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-sessions/{sessionKey}/scoped-token-events","href":"/forge/reference/http-api/costs-budgets/admin/token-events-session-in-scope"},{"title":"Rank active agents by spend over a time window, with run counts, success rate, tokens and prior-period totals","description":"Rank active agents by spend over a time window, with run counts, success rate, tokens and prior-period totals. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Rank active agents by spend over a time window, with run counts, success rate, tokens and prior-period totals","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-agent-leaderboard","href":"/forge/reference/http-api/costs-budgets/admin/agents-leaderboard"},{"title":"Get the Personal key's owner's cumulative cost and turn timer on a chat session's agent thread","description":"Get the Personal key's owner's cumulative cost and turn timer on a chat session's agent thread. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the Personal key's owner's cumulative cost and turn timer on a chat session's agent thread","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-threads/{threadId}/cost","href":"/forge/reference/http-api/costs-budgets/admin/thread-cost"},{"title":"Get a chat session's token totals, model counts and most recent token events","description":"Get a chat session's token totals, model counts and most recent token events. Requires permission `chat:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a chat session's token totals, model counts and most recent token events","openapi":"/forge/reference/openapi-v3.json get /api/v3/chat-sessions/{sessionId}/token-usage","href":"/forge/reference/http-api/costs-budgets/admin/session-tokens"},{"title":"List a page of a budget's alerts — untriggered first, then triggered, each in creation order","description":"List a page of a budget's alerts — untriggered first, then triggered, each in creation order. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a budget's alerts — untriggered first, then triggered, each in creation order","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-budgets/{budgetId}/alerts","href":"/forge/reference/http-api/costs-budgets/admin/budgets-alerts"},{"title":"List a page of a budget's triggered, unacknowledged alerts, in creation order","description":"List a page of a budget's triggered, unacknowledged alerts, in creation order. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a budget's triggered, unacknowledged alerts, in creation order","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-budgets/{budgetId}/pending-alerts","href":"/forge/reference/http-api/costs-budgets/admin/budgets-alerts-pending"},{"title":"List a page of a budget's transactions (type, amount and time), newest first","description":"List a page of a budget's transactions (type, amount and time), newest first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a budget's transactions (type, amount and time), newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-budgets/{budgetId}/transactions","href":"/forge/reference/http-api/costs-budgets/admin/budgets-transactions"},{"title":"Get a budget's spend, allocation and utilization","description":"Get a budget's spend, allocation and utilization. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a budget's spend, allocation and utilization","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-budgets/{budgetId}/utilization","href":"/forge/reference/http-api/costs-budgets/admin/budgets-utilization"},{"title":"List the current per-model token prices","description":"List the current per-model token prices. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List the current per-model token prices","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-current-pricing","href":"/forge/reference/http-api/costs-budgets/admin/pricing-current"},{"title":"List the current per-model token prices, with the built-in defaults","description":"List the current per-model token prices, with the built-in defaults. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List the current per-model token prices, with the built-in defaults","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-current-prices","href":"/forge/reference/http-api/costs-budgets/admin/pricing-current-prices"},{"title":"Get a model's latest recorded price","description":"Get a model's latest recorded price. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a model's latest recorded price","openapi":"/forge/reference/openapi-v3.json get /api/v3/models/{modelId}/latest-price","href":"/forge/reference/http-api/costs-budgets/admin/pricing-latest"},{"title":"List a page of a model's price history, newest first","description":"List a page of a model's price history, newest first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a model's price history, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/models/{modelId}/price-history","href":"/forge/reference/http-api/costs-budgets/admin/pricing-history"},{"title":"Get the price a model had at a time","description":"Get the price a model had at a time. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the price a model had at a time","openapi":"/forge/reference/openapi-v3.json get /api/v3/models/{modelId}/historical-price","href":"/forge/reference/http-api/costs-budgets/admin/pricing-at"},{"title":"List a page of a model's price history (the Console analytics read), newest first","description":"List a page of a model's price history (the Console analytics read), newest first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a model's price history (the Console analytics read), newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/models/{modelId}/scoped-price-history","href":"/forge/reference/http-api/costs-budgets/admin/pricing-history-in-scope"},{"title":"Get the prompt-cache hit rate and estimated savings over a time window, overall and per agent","description":"Get the prompt-cache hit rate and estimated savings over a time window, overall and per agent. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the prompt-cache hit rate and estimated savings over a time window, overall and per agent","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-cache-efficiency","href":"/forge/reference/http-api/costs-budgets/admin/cache-efficiency"},{"title":"List a page of an agent's cost aggregates for a bucket and time range, oldest bucket first","description":"List a page of an agent's cost aggregates for a bucket and time range, oldest bucket first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of an agent's cost aggregates for a bucket and time range, oldest bucket first","openapi":"/forge/reference/openapi-v3.json get /api/v3/agents/{agentId}/cost-aggregates","href":"/forge/reference/http-api/costs-budgets/admin/aggregates-agent"},{"title":"List a page of a model's cost aggregates for a bucket and time range, oldest bucket first","description":"List a page of a model's cost aggregates for a bucket and time range, oldest bucket first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a model's cost aggregates for a bucket and time range, oldest bucket first","openapi":"/forge/reference/openapi-v3.json get /api/v3/models/{modelId}/cost-aggregates","href":"/forge/reference/http-api/costs-budgets/admin/aggregates-model"},{"title":"List a page of a workflow's cost aggregates for a bucket and time range, oldest bucket first","description":"List a page of a workflow's cost aggregates for a bucket and time range, oldest bucket first. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a workflow's cost aggregates for a bucket and time range, oldest bucket first","openapi":"/forge/reference/openapi-v3.json get /api/v3/workflows/{workflowId}/cost-aggregates","href":"/forge/reference/http-api/costs-budgets/admin/aggregates-workflow"},{"title":"Record an allocation, expense, transfer or adjustment against a budget","description":"Record an allocation, expense, transfer or adjustment against a budget. Requires permission `cost:manage`.","deprecated":null,"version":null,"sidebarTitle":"Record an allocation, expense, transfer or adjustment against a budget","openapi":"/forge/reference/openapi-v3.json post /api/v3/cost-budgets/{budgetId}/transactions","href":"/forge/reference/http-api/costs-budgets/admin/budgets-transactions-record"},{"title":"Set a budget's limit in cents","description":"Set a budget's limit in cents. Requires permission `cost:manage`.","deprecated":null,"version":null,"sidebarTitle":"Set a budget's limit in cents","openapi":"/forge/reference/openapi-v3.json post /api/v3/cost-budgets/{budgetId}/set-limit","href":"/forge/reference/http-api/costs-budgets/admin/budgets-limit"},{"title":"Get one budget","description":"Get one budget. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Get one budget","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-budgets/{budgetId}","href":"/forge/reference/http-api/costs-budgets/admin/budgets-get"},{"title":"Get the budget hierarchy as a tree of up to 200 budgets, refused past it","description":"Get the budget hierarchy as a tree of up to 200 budgets, refused past it; for each, its limit, period spend, burn rate, days until exhausted, status and triggered alert count. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the budget hierarchy as a tree of up to 200 budgets, refused past it","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-budget-tree","href":"/forge/reference/http-api/costs-budgets/admin/budgets-tree"},{"title":"Get token and cost totals over a time window, overall, per agent and per model, across the org units the key holds cost:read at","description":"Get token and cost totals over a time window, overall, per agent and per model, across the org units the key holds cost:read at. Requires permission `cost:read`.","deprecated":null,"version":null,"sidebarTitle":"Get token and cost totals over a time window, overall, per agent and per model, across the org units the key holds cost:read at","openapi":"/forge/reference/openapi-v3.json get /api/v3/cost-token-summary","href":"/forge/reference/http-api/costs-budgets/admin/token-summary"}]},{"group":"Observe and ops","icon":"binoculars","root":{"title":"Observe and ops administration","sidebarTitle":"Observe and ops","icon":"binoculars","description":"Read the attention board, run audit and workflow analytics, and acknowledge items and add notes, with a platform API key.","href":"/forge/reference/http-api/observe-ops"},"pages":[{"title":"Acknowledge an attention item so it leaves the active board until the acknowledgment expires (24 hours by default)","description":"Acknowledge an attention item so it leaves the active board until the acknowledgment expires (24 hours by default). Requires permission `platform:manage`.","deprecated":null,"version":null,"sidebarTitle":"Acknowledge an attention item so it leaves the active board until the acknowledgment expires (24 hours by default)","openapi":"/forge/reference/openapi-v3.json post /api/v3/ops-attention-items/acknowledge","href":"/forge/reference/http-api/observe-ops/admin/attention-acknowledge"},{"title":"Add an investigation note to a run, an agent or another resource","description":"Add an investigation note to a run, an agent or another resource; answers the note's id. Requires permission `audit:read`.","deprecated":null,"version":null,"sidebarTitle":"Add an investigation note to a run, an agent or another resource","openapi":"/forge/reference/openapi-v3.json post /api/v3/ops-notes","href":"/forge/reference/http-api/observe-ops/admin/notes-add"},{"title":"List a page of a run's audit events, newest first. Events about people need workforce:read","description":"List a page of a run's audit events, newest first. Events about people need workforce:read. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of a run's audit events, newest first. Events about people need workforce:read","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/audit-events","href":"/forge/reference/http-api/observe-ops/admin/runs-audit-events"},{"title":"List the deployment's attention items — failed and stuck runs, pending approvals, invalid credentials and other signals, most severe first","description":"List the deployment's attention items — failed and stuck runs, pending approvals, invalid credentials and other signals, most severe first. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List the deployment's attention items — failed and stuck runs, pending approvals, invalid credentials and other signals, most severe first","openapi":"/forge/reference/openapi-v3.json get /api/v3/ops-attention-items","href":"/forge/reference/http-api/observe-ops/admin/attention"},{"title":"List a page of the investigation notes on a resource, newest first","description":"List a page of the investigation notes on a resource, newest first. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List a page of the investigation notes on a resource, newest first","openapi":"/forge/reference/openapi-v3.json get /api/v3/ops-notes","href":"/forge/reference/http-api/observe-ops/admin/notes"},{"title":"List recently failed workflow runs since a start time","description":"List recently failed workflow runs since a start time. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List recently failed workflow runs since a start time","openapi":"/forge/reference/openapi-v3.json get /api/v3/ops-recent-failed-runs","href":"/forge/reference/http-api/observe-ops/admin/runs-recent-failures"},{"title":"List the slowest workflow steps by duration","description":"List the slowest workflow steps by duration. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"List the slowest workflow steps by duration","openapi":"/forge/reference/openapi-v3.json get /api/v3/ops-slowest-steps","href":"/forge/reference/http-api/observe-ops/admin/steps-slowest"},{"title":"Get a run's audit packet — its disposition, approvals, governance decisions, key events and recommended actions","description":"Get a run's audit packet — its disposition, approvals, governance decisions, key events and recommended actions. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"Get a run's audit packet — its disposition, approvals, governance decisions, key events and recommended actions","openapi":"/forge/reference/openapi-v3.json get /api/v3/runs/{runId}/audit-packet","href":"/forge/reference/http-api/observe-ops/admin/runs-audit-packet"},{"title":"Get the workflow performance overview for a time window","description":"Get the workflow performance overview for a time window. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the workflow performance overview for a time window","openapi":"/forge/reference/openapi-v3.json get /api/v3/ops-performance","href":"/forge/reference/http-api/observe-ops/admin/performance"},{"title":"Get the workflow reliability overview for a time window","description":"Get the workflow reliability overview for a time window. Requires permission `workflows:read`.","deprecated":null,"version":null,"sidebarTitle":"Get the workflow reliability overview for a time window","openapi":"/forge/reference/openapi-v3.json get /api/v3/ops-reliability","href":"/forge/reference/http-api/observe-ops/admin/reliability"}]},{"group":"Health","icon":"heart-pulse","root":{"title":"Health","sidebarTitle":"Health","icon":"heart-pulse","description":"Check that the deployment answers and the credential authenticates.","href":"/forge/reference/http-api/health"},"pages":[{"title":"Authenticated liveness check","description":"Confirms the deployment is reachable and the caller's credential authenticates. Requires permission `platform:read`.","deprecated":null,"version":null,"sidebarTitle":"Authenticated liveness check","openapi":"/forge/reference/openapi-v3.json get /api/v3/health","href":"/forge/reference/http-api/health/get"},{"title":"Required-notification health","description":"Read whether required workflow notifications are still being delivered.","deprecated":null,"version":null,"sidebarTitle":"Required-notification health","openapi":"/forge/reference/openapi-v3.json get /api/v3/health-notifications","href":"/forge/reference/http-api/health/notifications"},{"title":"Stop state","description":"Read whether Forge is stopped or global spend is frozen.","deprecated":null,"version":null,"sidebarTitle":"Stop state","openapi":"/forge/reference/openapi-v3.json get /api/v3/health-stops","href":"/forge/reference/http-api/health/stops"},{"title":"Usage summary","description":"Read how often each MCP tool or route was called over a day range, and with what outcome.","deprecated":null,"version":null,"sidebarTitle":"Usage summary","openapi":"/forge/reference/openapi-v3.json get /api/v3/usage-summary","href":"/forge/reference/http-api/health/usage"}]}]}]}]},{"tab":"Forge Console","icon":"display","hidden":true,"pages":[{"title":"Forge Console","href":"/forge/console"}]}]},"basePath":"","title":"List role grants - Gloo","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":["c2aa737661","b0f84f53ff","a9bb46feb3","2b790eda92"],"chunks":["OpenApiReferenceProvider-CiUHMMOm.js","snippetPresets-BgfXU7Bw.js","utils-DWvOwgy_.js","style-to-object-BY3JEAdk.js","utils-BN7RXSMJ.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-CFw8bq89.js","conditional-requirements-CFM0id0Q.js","cloneDeep-CAwdfOU2.js","_Uint8Array-BJr8e-ZL.js","isObject-FP1Yky1u.js","Page-CVJ-f_k1.js","CodeSnippet-D_HwgQO_.js","DynamicMarkdown-CQM9Bhbv.js","SectionHeading-DpbrP8nQ.js","icon-BPCgijHy.js","ApiExamples-XX0UgMZK.js","usePlaygroundInputsStore-DXDFSa1V.js","shallow-CdX5aREi.js","isEqual-CoOaxexF.js","CodeSnippets-Cg2wpzWm.js","getApiPlaygroundDisplay-CmCoerhe.js","MethodPill-GQ8DuY0c.js","getPastedJson-Cb5mT31m.js","Check2Icon-a7bUI6e8.js","axios-CsQoIw0U.js","Markdown-CX2QY19L.js","AssistantPageLink-CY3bFglh.js","dist-Dl6_zDnT.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}