Skip to main content
Update, pause, resume, test and list deliveries for your own webhooks.
An External App now runs its own webhook subscriptions without the Console. Each route acts on the calling app’s own subscriptions only: another app’s or an unknown subscription answers 404, and a revoked one answers 409 invalid_state on every write.
  • POST /api/v2/webhooks/update changes a subscription’s url, events or label, under the checks create runs.
  • POST /api/v2/webhooks/pause and POST /api/v2/webhooks/resume stop and restart deliveries. A resume clears the failure streak.
  • POST /api/v2/webhooks/test queues one webhook.test delivery with a new envelope id each time. A test delivery no longer counts toward the auto-pause streak, from the Console or the API.
  • GET /api/v2/webhooks/deliveries?subscriptionId= lists a subscription’s deliveries, newest first, a page at a time.
The writes require webhooks:manage, and the list requires webhooks:read. See Webhooks.
Four array reads are declared bounded lists.
Four GET operations that answer an array now say in the OpenAPI document how big that array can be. Each one carries x-forge-paging: bounded with its maximum in x-forge-bound, and always answers the whole list with meta.hasMore: false.
  • GET /api/v3/me/budget-status answers at most one item: the acting org unit’s budget node. A credential with no org unit gets an empty list instead of an error.
  • GET /api/v3/factory-codebase-search and GET /api/v3/chat-channel-search answer their top limit matches, at most 50. A limit above 50 now reads 50 where it used to be a 400. A limit below 1 is a 400.
  • GET /api/v3/webhook-health answers one row per id in subscriptionIds. It used to drop the ids past the 200th without saying so. It now answers 400 naming subscriptionIds when you send more than 200.
Two more array reads state their bound.
A list read that answers an array either takes a cursor or states, in x-forge-bound, the most items it answers. Two more reads now state their bound.
  • GET /api/v3/cost-budget-tree (v2 costs/admin/budgets/tree) answers at most 200 budgets. Its OpenAPI operation carries x-forge-paging: bounded and x-forge-bound: 200. It now takes limit and cursor like other bounded lists. limit does not cut the tree, meta.hasMore is always false, meta.nextCursor is always null, and any cursor is a 400. A hierarchy of more than 200 budgets is still a 409 conflict, as before. You never get part of a tree.
  • GET /api/v3/agent-available-models (v2 external/listAvailableModelsForAgent) answers at most 1,000 models and carries x-forge-bound: 1000. It keeps the OpenAI { object: "list", data } shape exactly: it takes no limit or cursor, and it adds no meta.
Writes refused past the bounds. Two limits keep the agent model list within its bound:
  • An agent’s externalModelAllowlist can name at most 1,000 models. POST /api/v3/agents/find-or-create (v2 external/findOrCreateAgent) and PATCH /api/v3/agents/{agentId} with a platform or personal key (v2 agents/admin/update) answer a longer list with 400 bad_request. Its error.details names the field, with the code too_big.
  • The model catalog can hold at most 1,000 active models. POST /api/v3/models and POST /api/v3/models/{modelId}/toggle-active answer an activation past that with 409 conflict. Deactivate a model first.
If the catalog ever holds more active models than its bound, the agent model list answers a 500 error rather than part of the list.
Console documentation starts with current operator tasks.
The Console documentation now starts with assigned work, organizational knowledge, workflows, run investigation, agent configuration, and planning. The platform has a dedicated Knowledge system section covering artifacts, lifecycle, retrieval, review, and agent use, separate from operational recipes. Your first session and the dashboard guide separate onboarding from dashboard mechanics. Navigation uses the Console’s section names and places My Work under Production. Section overviews and selected operating guides have been checked against their current screens.
Forge documentation navigation and task-guide quality.
The platform overview now includes a foundational map connecting interfaces, Trust Fabric, work, platform services, and external systems. Navigation uses consistent icons and one curated API reference menu. Get access and build/operate overviews are easier to find.Console guides now describe the current planning, audit history, Architect Health, and Synthesis controls. Integrator guidance corrects capability resolution, runtime OAuth handling, and current Knowledge API reference bindings.
New error codes resource_missing, invalid_state, permission_denied and operator_stopped; param on every validation detail; per-operation code enums.
A client can now branch on the error code alone. No status changed:
  • A 404 for a record that doesn’t exist answers resource_missing. not_found now means only that no route serves the path.
  • A 409 whose resource is in the wrong state (an archived channel, a revoked webhook, a run that cannot restart) answers invalid_state. conflict now means a uniqueness or concurrency break.
  • A 403 that a grant would fix answers permission_denied, with the permission in error.requiredPermission. forbidden now means no grant would change the answer.
  • A 403 sent while an operator has stopped Forge answers operator_stopped.
Every error.details entry names its param. Each operation’s error responses now point at ErrorResponse<status>, whose error.code enum lists the codes that status can carry.If your client branches on forbidden, not_found or conflict, accept the new codes as well.
Draft reset copies schema components; unowned schema references are caught before a run.
Resetting a draft to a published version (Console Reset draft or POST /api/v2/workflows/resetDraft) now replaces the draft’s schema components with copies of the version’s, and every input and output schemaComponentId on the reset draft names one of those copies. Before, the draft kept pointing at the version’s components and its next test run failed at the first node that used one.A reset that would leave a reference pointing at nothing is refused and changes nothing. Over the API, a draft or version with more than 500 schema components is refused with conflict.Validation reports a new error, SCHEMA_REF_NOT_OWNED, for any input or output schema reference that names a component this draft does not own. A draft test run with such a reference is refused before it starts, naming each node and field; POST /api/v2/workflows/testRunDraft answers invalid_state (409). Draft node writes, including the API’s node create and update, refuse an input reference the draft does not own, as they already did for outputs.
Every 403 carries requiredPermission and a decisionId.
Every 403 from the Platform API now carries both error.requiredPermission and error.decisionId. Before this, a refusal about the credential itself (the wrong kind of credential, an External App with no owning organization) recorded no decision, and a refusal that one grant does not fix left requiredPermission out. Now requiredPermission is the permission the caller lacks, or null when no grant would change the answer, and every decisionId can be explained with GET /api/v3/me/denials/{decisionId}. See forbidden.
Every create operation answers 201 Created.
Every create* operation in the Forge API now answers 201 Created when it succeeds. 37 of them already did. The 25 below answered 200 and now answer 201, in both /api/v3 and /api/v2, with the same body as before. The OpenAPI documents declare 201 for each one. Forge is not yet in production, so this change ships without a compatibility period.If your client checks for exactly 200, accept any 2xx status instead, or check for 201 on these operations. A repeat with the same Idempotency-Key gets the status the first call got.On the channel layer, POST /api/v3/memory keeps one entry per agent and channel. A create for an agent and channel that already have an entry replaces that entry’s summary and answers its id, also with 201.
  • POST /api/v3/agents/create-draft (createAgentDraftAdmin)
  • POST /api/v3/cost-budgets (createBudgetAdmin)
  • POST /api/v3/cost-budgets/{budgetId}/alerts (createBudgetAlertAdmin)
  • POST /api/v3/email-routes (createEmailRouteAdmin)
  • POST /api/v3/environment-connections (createEnvironmentConnectionAdmin)
  • POST /api/v3/environment-connections/create-with-credential (createEnvironmentConnectionWithCredentialAdmin)
  • POST /api/v3/evals (createEvalSet)
  • POST /api/v3/connection-external-tool-configurations (createExternalToolConfigurationAdmin)
  • POST /api/v3/model-fallback-chains (createFallbackChainAdmin)
  • POST /api/v3/workflows/{workflowId}/ingress-triggers (createIngressTrigger)
  • POST /api/v3/knowledge-collections/{collectionId}/records (createKnowledgeRecord)
  • POST /api/v3/memory (createMemory)
  • POST /api/v3/models (createModelAdmin)
  • POST /api/v3/model-slots (createModelSlotAdmin)
  • POST /api/v3/connection-oauth-bindings (createOAuthBindingAdmin)
  • POST /api/v3/org-unit-drafts (createOrgChartDraftAdmin)
  • POST /api/v3/org-unit-structure-types (createOrgStructureTypeAdmin)
  • POST /api/v3/procedures/{procedureId}/credentials (createProcedureCredentialAdmin)
  • POST /api/v3/tools (createToolAdmin)
  • POST /api/v3/tools/{toolId}/credentials (createToolCredentialAdmin)
  • POST /api/v3/vendors (createVendorAdmin)
  • POST /api/v3/workers (createWorkerAdmin)
  • POST /api/v3/roles (createWorkerRoleAdmin)
  • POST /api/v3/workflows/create-from-template (createWorkflowFromTemplate)
  • POST /api/v3/workflows/{workflowId}/triggers (createWorkflowTrigger)
Five more lists page with a cursor.
Five list operations used to answer one array with no way to read past it. Some stopped at a limit of their own, and some sorted rows after a bounded read, so a short answer did not prove you had reached the end. Each one now pages like Forge’s other database lists. Send limit, then send the meta.nextCursor you get back as cursor, and keep going until meta.nextCursor is null. Every item you may read appears exactly once across the pages, and data is still the array of items.A page can hold fewer items than limit, or none, while meta.hasMore is true: it leaves out items you may not read, or stops when it has read as much as one page may. Keep following meta.nextCursor.
  • GET /api/v3/chat-sessions (v2 chat/admin/sessions): limit is 1 to 100 (default 50). Sessions come newest activity first in one exact order. Sessions with the same activity time keep one place, so none repeats or goes missing across a page boundary. A page that reads past many sessions you may not see ends short with more to read, where it used to be an error.
  • GET /api/v3/connection-slack-delivery-problems (v2 connections/admin/slack/delivery/problems): limit is 1 to 100 (default 25). Unknown deliveries come first, then dead ones, each newest updated first.
  • GET /api/v3/external-apps/{externalAppId}/owned-agents (v2 external-apps/admin/owned-agents): limit is 1 to 100 (default 50). Order change: agents now come oldest created first, where they came most recently updated first.
  • GET /api/v3/project-tasks (v2 projects/admin/tasks): limit is 1 to 100 (default 50), newest first. A task whose project Forge cannot yet decide you may read ends the page just before it, with more to read. The list used to stop there and drop every later task.
  • GET /api/v3/models-with-usage-search (v2 models/admin/catalog/search-with-usage): limit is 1 to 100 (default 50). Order change: matches come in model id order, so models of one provider come together. They used to come in no stated order, all at once. A page reads at most 1,000 catalog models, so a rare match can take several pages, some of them empty.
The four lists in the first four items now carry x-forge-paging: database in the OpenAPI document.
Forge's foundational platform map.
The Forge overview now maps Console, API, MCP, Trust Fabric, collaboration among agents, people, and deterministic code, shared platform services including Knowledge, and scoped connections to external systems. The spatial map has an equivalent narrow-screen presentation and uses Forge’s shared diagram language. Integration guidance now clearly separates Console’s Convex-backed implementation from external applications using the API.
Three cut lists page with a cursor; the judge list counts drift alerts to 100 and drops meta.partial.
Four list operations could stop before the end of their list and said so with meta.partial. Three now page like Forge’s other database lists: send limit, then pass the meta.nextCursor you get back as cursor, and keep going until meta.nextCursor is null. limit is 1 to 100 (default 100) for each. A page can hold fewer items than limit while meta.hasMore is true, so keep following meta.nextCursor. None of the four answers meta.partial any more.Response shape changes. Forge is not yet in production, so these ship without a compatibility period.
  • GET /api/v3/procedures/{procedureId}/version-callers (v2 procedures/listVersionCallers): you now get one caller for each published workflow version that pins the procedure version, not one for each workflow. Each caller has a new workflowVersionId. A workflow with two published versions that both pin it appears twice.
  • GET /api/v3/judges (v2 judges/list): meta.partial is gone. Each judge’s drift alert count stops at 100, the same as GET /api/v3/judges/{judgeId}.
Paging changes only. These keep their data shape:
  • GET /api/v3/me/work (v2 governance/listMyWork): this is your full My Work list. Before, each source stopped at its newest 200 rows and each review queue at 50 items. Forge now reads your own index: the steps and approvals that ask you, oldest first, then each review queue whose permission you hold. Other people’s work is not read, so your first page holds your oldest items up to limit, and a call with no cursor still gets them. Each page is sorted the way the Console sorts My Work, and each item appears once as you page. An item that starts asking you after you have paged past its place shows up the next time you list from the start. While Forge is still indexing work that existed before your index, a listing reads every open step and approval instead: then a page can be short or empty while meta.hasMore is true, and a step that escalates while you page can appear twice.
  • GET /api/v3/factory-codebase-files (v2 factories/listCodebaseFiles): you now get every indexed file once, with its full chunk count. It used to stop after reading 500 index entries and set meta.partial: true. A file with many chunks can produce pages that have no files while meta.hasMore is true.
Read an organization's knowledge with actingFor.
Each external organization’s knowledge lives in its own partition. A knowledge read reaches it only when it names the organization with actingFor, the organization’s orgUnitId: getChunks, ask, get, cases/list, cases/get, cases/update, records/list and records/get take it, as do the matching MCP tools. It needs knowledge:read (knowledge:manage to edit) at that organization’s own unit or at platform scope; a grant on Gloo’s root does not reach it. A refused actingFor answers 403, and an admitted read is recorded before it is answered.GET /api/v2/knowledge/scopes/list lists the organizations a caller may act for. A read without actingFor reads Gloo’s knowledge only. File uploads may bind to an organization (scopeType: "organization") with files:write at its unit or platform scope.See Acting for an organization.
Every ingest names its owner.
New artifact now asks for the Owner first: Gloo, or one organization (a customer or capital partner) by name. Nothing is chosen for you, and the form cannot be saved until you choose. An organization owner is its own scope, so its knowledge is read only for that organization.Synced sources currently add Gloo knowledge; Add source says so.A customer’s overview and an organization’s org unit page show an Organization knowledge card with its entry count, top cases and a link to browse it. Its links act for the organization, so a Gloo-side reader who may act for it opens its cases.See Artifacts, Knowledge sources and Customers.
A limit above its declared maximum is a 400.
Breaking change. Every operation whose limit declares a maximum in the OpenAPI document now refuses a larger limit. It used to read the maximum and answer that many items. Now it answers 400 with error.code bad_request, and error.details holds one entry with path limit and code too_big. The message is “limit must be at most N”, where N is the declared maximum. The maximums themselves are unchanged. Forge is not yet in production, so this change ships without a compatibility period.To read more items than one page holds, send the maximum and follow meta.nextCursor (list paging).One /api/v3 maximum is narrowed:
  • GET /api/v3/webhooks declared a limit maximum of 200. A platform or personal key reaches the admin list, which serves at most 100, so the v3 route now declares 100 and refuses a larger limit for every credential, external apps included. The v2 routes keep their own maximums: GET /api/v2/webhooks still takes up to 200.
When a /api/v3 route serves different credentials from different /api/v2 operations, it declares the smallest of their limit maximums and enforces that one for every credential.
MCP tool inputs declare their bounds.
  • Every MCP server tool input now lists its bounds in tools/list: a minimum and a maximum on each number, a maxLength on each free-text string and a maxItems on each list.
  • A value outside its bounds is refused with invalid_input before any request is sent. A limit above its maximum used to be lowered to it silently; it is now refused, so a caller that sent a larger limit must send one within the listed maximum.
MCP tools that start workflow runs are confirmed.
  • The MCP server now confirms forge_dispatch_workflow, forge_run_workflow_and_wait, forge_restart_run and forge_start_run_analysis before they run: a workflow run’s steps write to the systems the workflow connects to, and a run analysis’s agent may call its granted external tools.
  • A host with form elicitation asks the user. Any other host, and the hosted endpoint, answers confirmation_required with a confirmationToken to send back once the user agrees.
  • forge_run_workflow_and_wait with only runId follows a started run and is not confirmed. forge_call_operation confirms the operations that start a run the same way: dispatchWorkflow, restartRun, startRunAnalysis, testRunWorkflowDraft and launchWorkflowDebugAttempt. The confirmation names each argument that changes the run, such as its version, callback URL or a raised cap.
Five more MCP list tools take fields.
  • forge_list_run_artifacts, forge_list_run_events, forge_list_knowledge_reviews, forge_list_knowledge_scopes and forge_list_knowledge_cases now take fields. The text answer keeps only the named row keys; structuredContent still carries whole rows. See the MCP server reference.
MCP list tools take a fields projection.
  • Ten MCP server list tools now take fields, a list of row keys to keep. These include forge_list_runs, forge_list_agents, forge_list_workflows and forge_list_approvals. For example, forge_list_runs {"fields":["status","error"]} answers each run as id, status and error only.
  • A projected row always keeps its id. The projection applies to the text content: structuredContent still carries whole rows.
  • An unknown key is refused as invalid_input before any request. error.details[] names the key and lists the keys a row has in allowed.
MCP refusals share one format.
  • Every MCP server refusal’s text starts with Forge API error (<status> <code>): or Forge MCP error (<code>): , and every refusal carries structuredContent.error. A host’s own input-validation failure is now an invalid_input refusal in that format instead of an MCP error -32602 text.
  • An invalid_input refusal lists each failing field in error.details, with the values the field accepts as allowed.
  • A not_found refusal’s next step names the connection’s dedicated forge_list_… tool when it lists one, before the generic operation call.
  • A refusal’s decisionId can always be passed to forge_explain_denial. Without audit:read, grants:read and policies:read the explanation answers with decision: null instead of refusing.
MCP destructive calls are confirmed in the Forge Console.
  • On a host without form elicitation, a destructive call on the MCP server by a Personal key or an interactive sign-in is refused confirmation_required with confirmationUrl. The key’s owner approves or denies that exact call on the Console page, and the identical retried call runs once. No confirmation token is returned, and one that is sent is ignored.
  • A host that declares URL elicitation is sent the link through elicitation/create and waits for the decision.
  • An External App’s destructive calls run once a person with apps:manage preauthorizes the app on its Console page. Until then, and for platform keys, the deprecated confirmation token still works; a sunset date will be announced.
  • A stdio install needs a Forge deployment with the confirmation routes (/api/v2/me/confirmations).
MCP answers over 16 KiB link their whole or say how to page.
  • A list or search whose text answer is shortened at 16 KiB now says, in its truncation note, how to page. Rows left out of the text come back with the same cursor and a smaller limit; the cursor it returned continues after the whole page, past them.
  • A single-record or computed read that is shortened links its whole answer with a resource_link. Reads that already had a resource link that resource.
  • New resource template forge://tools/{toolName}/result{?input}. It runs a read-only tool’s call again with your credential and returns its whole structuredContent, and refuses any tool that is not read-only. See the MCP server reference.
MCP explains a refusal to the credential it refused.
  • forge_explain_denial reads a refusal’s decisionId first as the caller’s own recorded denial (GET /api/v2/me/denials/{decisionId}), which needs no permission. Before, it read only the organization’s recorded evidence. A refusal made at Door B is not recorded there, so a caller holding audit:read, grants:read and policies:read got 404 Decision not found.
  • An id neither read finds answers with decision: null instead of refusing the explanation.
  • A 403’s next step now passes its decisionId to forge_explain_denial, beside the refused permission.
MCP run and workflow reads link their resources.
  • forge_get_run now ends its content with two resource_link items, the run’s report (forge://runs/{runId}/report.md) and its timeline (forge://runs/{runId}/timeline), so a host can read either without another tool call. See the MCP server reference.
  • forge_get_workflow links the workflow’s definition (forge://workflows/{workflowId}) by the id it returned, even when it was called with a name.
MCP operation search returns input schemas.
  • The first three results of forge_search_operations on the MCP server now carry inputSchema, with the component schemas it references, so a caller can build a forge_call_operation input without first calling forge_describe_operation.
  • A schema over 2 KB is left out, and that result says inputSchemaOmitted: true.
MCP tool text answers fit 16 KiB.
  • Every MCP server tool’s text content is now at most 16 KiB. forge_get_current_actor with detail: "full" answered with more than 170 KB of text on a large account.
  • An answer over the cap keeps the first items of its long lists, says how many were left out, and ends with a [Truncated: …] note. structuredContent is unchanged and carries the whole answer.
Nine capped lists page with a cursor or state a bound.
Nine list operations used to read a capped window, so past the cap their last page said meta.truncated: true or meta.partial: true, and you could not reach the rest. Eight of them now page the database: send limit, then send the meta.nextCursor you get back as cursor, until meta.nextCursor is null. Every item you may read appears exactly once across the pages. The ninth states its bound. None of the nine answers meta.partial any more, and the OpenAPI document no longer carries x-forge-read-cap on any operation.A page can hold fewer items than limit, or none, while meta.hasMore is true: it leaves out items you may not read, or one Forge cannot decide yet. Keep following meta.nextCursor.The workflow-step and release lists are ordered by last change. An item changed while you page moves ahead of your cursor, so that walk does not return it again; start a new walk to see it.Response shape changes. Forge is not yet in production, so these ship without a compatibility period.
  • GET /api/v3/synthesis-builder-holds (v2 synthesis/listBuilderHolds): data is now the array of holds, newest hold first. limit is 1 to 100 (default 50).
  • GET /api/v3/knowledge-subject-collections (v2 knowledge/subjectCollections/list): data is now the array of collections. A page reads one readable namespace at a time, so a page can be short while more namespaces follow. limit is 1 to 100 (default 50).
  • GET /api/v3/runs/{runId}/step-searches (v2 runs/admin/step-searches): each item is one knowledge_search call. Repeated searches are no longer merged into one item. limit is 1 to 100 (default 50).
  • POST /api/v3/knowledge-synchronized-source-providers/{providerKey}/search-containers (v2 knowledge/synchronized-sources/listContainers): bounded at 1,000 containers (x-forge-bound). A provider that offers more answers 409 with LIST_CONTAINERS_TOO_MANY, where it used to return a cut list with meta.partial: true (or, for a Freshservice account past 1,000 workspaces, an internal error). Narrow the search and ask again.
Paging and order changes. These keep their data array:
  • GET /api/v3/runs/{runId}/step-contexts (v2 runs/listStepContext): newest recorded first. It is no longer sorted by kind. limit is 1 to 100 (default 50).
  • GET /api/v3/skill-sets (v2 skills/listSets): the active sets, a page at a time. limit is 1 to 100 (default 50).
  • GET /api/v3/workflow-steps (v2 workflows/listSteps): newest change first. A filter applies to each page, so a filtered page can be short. limit is 1 to 100 (default 50).
  • GET /api/v3/model-fallback-chains (v2 models/listFallbackChains): in creation order. It used to list system chains first, then by name. limit is 1 to 100 (default 50).
  • GET /api/v3/factories/{factoryId}/releases (v2 factories/listReleases): every release milestone of the factory, most recently updated first. limit is 1 to 100 (default 50).
Window lists. A list that pages a window (x-forge-paging: window) accepts limit from 1 to 1,000, and its read is never cut short.
The platform error envelope on every /api/ route but the procedure sandbox door; /api/inference/v1/oauth/token deprecated.
Every /api/ route but the procedure sandbox door now answers an error in the platform error envelope, { error: { code, message, docUrl }, meta: { requestId } }, with the same id in the X-Request-Id header:
  • The GitHub, Linear and procedure repo-merge webhook receivers, ingress under /api/v2/ingress/, and the SendGrid inbound and event doors answered a flat { error: "…" } body before. Their statuses are unchanged.
  • /api/inference/v1/* and the coding-agent gateway keep the OpenAI or Anthropic error body their SDKs read, and add error.docUrl, meta.requestId, and error.code where the vendor’s was missing or null. An upstream error the gateway passes through carries them too.
POST /api/inference/v1/oauth/token is deprecated. It answers Deprecation and Link: </oauth/token>; rel="successor-version"; use POST /oauth/token, which answers the same.
Organization knowledge access is checked at the organization.
A knowledge read with a Customer scope (scopeType: "customer") now acts for that Customer’s organization. It reads the organization’s knowledge only when the credential, or the person, holds knowledge:read at the organization’s own unit or at platform scope; a grant at Gloo’s root no longer reaches it. Writes need knowledge:manage at the same place. A request acts for at most one organization.POST /api/v2/knowledge/getChunks and POST /api/v2/knowledge/ask record a knowledge_acting_for_read audit event for each such read before they answer. If that event cannot be written, the read is refused with a 500 rather than answered unrecorded.Agents never choose an organization. A run reads the organization of the Customer its signed trigger named, and an explicit Customer scope in an agent’s request is refused. People and credentials on an organization’s own side read that organization’s knowledge in place of Gloo’s company knowledge.
The organization knowledge scope type.
Knowledge has a new scope type, organization. It names one external organization’s knowledge, kept apart from Gloo’s own. A knowledge case’s scopeType and the scopeType filters of the case list and the Learning feed now list it.No case is in an organization scope yet, so the filter matches nothing. A request that names organization as a scope to write, upload, search, ask or export is refused with invalid_value, as an unknown scope is. MCP’s forge_get_knowledge_case and forge_list_knowledge_cases gain the value in their next major release.See Knowledge.
The rate limiter never admits a request without a limit.
Until now, a request that met a fault in the rate limiter’s store was admitted with no limit at all. Now no request runs without one:
  • A read or write request spends from a fallback bucket with the same burst and refill as its credential’s bucket. It carries the RateLimit-* headers as usual; RateLimit-Remaining is an estimate while the fallback serves.
  • An expensive request, or any request whose fallback also faults, answers 503 with code internal_error and Retry-After: 1. Nothing ran: retry after the delay.
Every credential’s requests also spend from an organization ceiling: one bucket per class at ten times a credential’s burst and refill. A Forge deployment serves one organization, so the ceiling is deployment-wide. GET /api/v2/me/limits reports it under organization, with scope: "deployment". A 429 from the ceiling says “This organization” rather than “This credential”.The OpenAPI documents now declare RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on every response that carries them: every response to a request whose rate limit was spent. A 401, a route’s own 429 and the limiter’s own 503 carry none. The 503 and every 429 declare Retry-After. See rate limiting.
Request records carry the error, 30-day retention, X-Request-Id everywhere.
GET /api/v3/me/requests/{requestId} now keeps a request for 30 days instead of 7. For a non-2xx answer the record also carries errorCode and errorMessage, the error.code and error.message your response carried, so you can find out later why a request was refused. Every response now carries an X-Request-Id header, including GET /api/openapi.json, GET /api/v3/openapi.json and GET /api/docs, and both OpenAPI documents declare it on every response. GET /api/v3/me/usage still counts the last 7 days.
Six capped lists page with a cursor; the role catalog holds at most 500 roles.
Six list operations used to stop at a fixed number of items, or mark a short read with meta.partial or truncated, and gave you no way to read the rest. Each one now pages like Forge’s other database lists. Send limit, then send the meta.nextCursor you get back as cursor, and keep going until meta.nextCursor is null. Every item you may read appears exactly once across the pages, and each operation carries x-forge-paging: database in the OpenAPI document. A page can hold fewer items than limit, or none, while meta.hasMore is true: keep following meta.nextCursor.Response shape changes. Forge is not yet in production, so these ship without a compatibility period.
  • GET /api/v3/customers/{customerId}/scopes (v2 customers/listScopes): data was { scopes, count } with meta.partial. It is now the array of scopes, oldest link first, and meta.partial is gone. limit is 1 to 100 (default 100).
  • GET /api/v3/workers/{workerId}/expertise-tags (v2 people/admin/workers/expertise-tags): data was { tags, truncated }. It is now the array of tags, with no truncated. limit is 1 to 100 (default 100).
Paging changes only. These keep their data array:
  • GET /api/v3/me/api-keys (v2 api-keys/admin/own-keys) and GET /api/v3/personal-keys (v2 api-keys/admin/personal-keys): active keys newest first, then revoked keys newest first. limit is 1 to 100 (default 100). The deployment-wide list used to stop at 1,000 keys; every key is now reachable.
  • GET /api/v3/role-grant-holder (v2 roles/admin/grants/holder): limit is 1 to 40 (default 40), and meta.partial is gone. A grant Forge cannot decide you may read is left out, and the page moves on past it, never an error.
  • GET /api/v3/knowledge-synchronized-sources (v2 knowledge/synchronized-sources/list): newest first across every namespace you can read, or the one you name. limit is 1 to 100 (default 100). It used to answer the newest 100 with meta.partial: true; every source is now reachable.
A bounded list. GET /api/v3/governance-role-definitions (v2 governance/listRoleDefinitions) answers the whole role catalog in one response, and its data declares maxItems: 500. The catalog holds at most 500 role definitions, built-in and custom together: creating one more is refused with invalid_state, whose details are { "param": "roleKey", "limit": 500 }. meta.partial stays in the response and is always false.
New error codes unprocessable, gone and payment_required; 401 before the body on v3.
Each refusal status now has an error code of its own:
  • A 422 answers unprocessable instead of bad_request: the request is well formed, but Forge refuses one of its values. A reused Idempotency-Key still answers idempotency_key_reuse.
  • PATCH /api/v2/memory/update on a forgotten memory answers 410 gone instead of 409 conflict.
  • POST /api/v2/knowledge/ask with a frozen or exhausted budget answers 402 payment_required instead of 403 forbidden. The refusal still carries its decisionId.
An /api/v3 request without a valid credential now gets its 401 before Forge reads the body, so a malformed or oversized body no longer answers 400 or 413 first.
Ten capped lists page with a cursor.
Ten list operations used to stop at a fixed number of items. Past that point they said meta.truncated: true or meta.partial: true, or refused the whole list, and gave you no way to read the rest. Each one now pages like Forge’s other database lists. Send limit, then send the meta.nextCursor you get back as cursor, and keep going until meta.nextCursor is null. Every item you may read appears exactly once across the pages. Each one carries x-forge-paging: database in the OpenAPI document, and none of them answers meta.partial any more.A page can hold fewer items than limit, or none, while meta.hasMore is true: it leaves out items you may not read. Keep following meta.nextCursor.Response shape changes. Five of these lists used to wrap their items in an object under data. They now answer data as the array of items itself. Forge is not yet in production, so this change ships without a compatibility period.
  • GET /api/v3/knowledge-collections (v2 knowledge/collections/list): data was { status: "complete", collections }, or { status: "too_large" } when you could read too many collections. It is now the array of collections, and there is no too_large answer. limit is 1 to 100 (default 100), in namespace and kind order.
  • GET /api/v3/synthesis-templates (v2 synthesis/listTemplates): data was { templates, count }. It is now the array of templates, with no count. limit is 1 to 200 (default 200), in status and kind order.
  • GET /api/v3/planning-blocked-tasks (v2 planning/listBlockedTasks): data was { tasks }. It is now the array of tasks. limit is 1 to 200 (default 100), newest first.
  • GET /api/v3/me/blockers (v2 planning/admin/my-blockers) and GET /api/v3/planning-could-help (v2 planning/admin/could-help): data was { tasks, partial }. It is now the array of tasks. limit is 1 to 100 (default 50).
On the three blocked-task lists, a page reads at most 50 tasks. A task whose project Forge cannot decide you may read is left out, and the page moves on past it, never an error.Paging changes only. These five keep their data array:
  • GET /api/v3/tools-needing-attention (v2 tools/listNeedingAttention): limit is 1 to 50 (default 10). Tools come in catalog order, and one page reads at most 1,000 catalog rows.
  • GET /api/v3/providers/{providerKey}/audit-events (v2 providers/listAuditEvents): limit is 1 to 50 (default 10), newest first. A limit above 50 now reads 50, where it used to be a 400.
  • GET /api/v3/governance-trust-policies/{trustPolicyId}/revisions (v2 governance/listTrustPolicyRevisions): limit is 1 to 200 (default 200), oldest first, starting with the root. A chain with more than 200 rows used to leave out its oldest revisions. Every revision is now reachable.
  • GET /api/v3/governance-roles (v2 governance/listRoles): limit is 1 to 200 (default 200), in role key order. The catalog used to stop at 200 roles. Every role is now reachable.
  • GET /api/v3/knowledge-golden-sets (v2 knowledge/goldenSets/list): limit is 1 to 100 (default 50), newest first, the active sets and then, with includeArchived=true, the archived ones. It used to return at most the newest 50 of each.
Unknown paths outside /api/ answer in the error envelope.
A path outside /api/ that no route serves now answers 404 not_found in the standard error envelope, with docUrl, meta.requestId and the X-Request-Id header, as paths under /api/ already did. Before, these requests got a plain-text 404 with no request id. A served path called with another method answers 405 method_not_allowed with an Allow header: GET /oauth/token names OPTIONS, POST. Every path a route serves answers as before.Every response now carries X-Request-Id, including webhook and ingress answers, the OAuth token and JWKS endpoints, CORS preflights and redirects. A response that already named an id keeps it. An unexpected failure outside /api/v2 now answers 500 internal_error in the envelope with its id, where it used to answer a plain 500; its status is unchanged.
Deduplicate webhooks on one key.
The webhook-id header now carries the envelope’s event id instead of the delivery id. It is the same on every retry and on a replay, so a Standard Webhooks library’s built-in deduplication and the documented rule (deduplicate on the envelope id) agree. X-Forge-Delivery still names the delivery; use it to read a delivery’s attempts or replay it.The webhook-signature HMAC covers webhook-id, so a verifier keeps working without change.See Delivery headers.
Rotate a webhook secret without an outage.
POST /api/v2/webhooks/rotate-secret no longer cuts the old secret off at once. Until previousSecretExpiresAt in the rotate response (at least 24 hours), the webhook-signature header carries two signatures, one per secret, so a receiver keeps verifying while it deploys the new secret. A second rotation inside the window replaces the old secret, so at most two are live. After the window the old secret never signs again and is deleted.X-Forge-Signature-V2 uses only the new secret from the moment of rotation. A receiver that verifies only that header must switch at once, as before.See Rotating the secret.