404, and a
revoked one answers 409 invalid_state on every write.POST /api/v2/webhooks/updatechanges a subscription’surl,eventsorlabel, under the checks create runs.POST /api/v2/webhooks/pauseandPOST /api/v2/webhooks/resumestop and restart deliveries. A resume clears the failure streak.POST /api/v2/webhooks/testqueues onewebhook.testdelivery with a new envelopeideach 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.
webhooks:manage, and the list requires webhooks:read. See
Webhooks.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-statusanswers 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-searchandGET /api/v3/chat-channel-searchanswer their toplimitmatches, at most 50. Alimitabove 50 now reads 50 where it used to be a400. Alimitbelow 1 is a400.GET /api/v3/webhook-healthanswers one row per id insubscriptionIds. It used to drop the ids past the 200th without saying so. It now answers400namingsubscriptionIdswhen you send more than 200.
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(v2costs/admin/budgets/tree) answers at most 200 budgets. Its OpenAPI operation carriesx-forge-paging: boundedandx-forge-bound: 200. It now takeslimitandcursorlike other bounded lists.limitdoes not cut the tree,meta.hasMoreis alwaysfalse,meta.nextCursoris alwaysnull, and anycursoris a400. A hierarchy of more than 200 budgets is still a409 conflict, as before. You never get part of a tree.GET /api/v3/agent-available-models(v2external/listAvailableModelsForAgent) answers at most 1,000 models and carriesx-forge-bound: 1000. It keeps the OpenAI{ object: "list", data }shape exactly: it takes nolimitorcursor, and it adds nometa.
- An agent’s
externalModelAllowlistcan name at most 1,000 models.POST /api/v3/agents/find-or-create(v2external/findOrCreateAgent) andPATCH /api/v3/agents/{agentId}with a platform or personal key (v2agents/admin/update) answer a longer list with400 bad_request. Itserror.detailsnames the field, with the codetoo_big. - The model catalog can hold at most 1,000 active models.
POST /api/v3/modelsandPOST /api/v3/models/{modelId}/toggle-activeanswer an activation past that with409 conflict. Deactivate a model first.
500 error rather than part of the list.- A
404for a record that doesn’t exist answersresource_missing.not_foundnow means only that no route serves the path. - A
409whose resource is in the wrong state (an archived channel, a revoked webhook, a run that cannot restart) answersinvalid_state.conflictnow means a uniqueness or concurrency break. - A
403that a grant would fix answerspermission_denied, with the permission inerror.requiredPermission.forbiddennow means no grant would change the answer. - A
403sent while an operator has stopped Forge answersoperator_stopped.
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.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.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.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)
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(v2chat/admin/sessions):limitis 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(v2connections/admin/slack/delivery/problems):limitis 1 to 100 (default 25). Unknown deliveries come first, then dead ones, each newest updated first.GET /api/v3/external-apps/{externalAppId}/owned-agents(v2external-apps/admin/owned-agents):limitis 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(v2projects/admin/tasks):limitis 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(v2models/admin/catalog/search-with-usage):limitis 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.
x-forge-paging: database in the OpenAPI document.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(v2procedures/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 newworkflowVersionId. A workflow with two published versions that both pin it appears twice.GET /api/v3/judges(v2judges/list):meta.partialis gone. Each judge’s drift alert count stops at 100, the same asGET /api/v3/judges/{judgeId}.
data shape:GET /api/v3/me/work(v2governance/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 tolimit, and a call with nocursorstill 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 whilemeta.hasMoreis true, and a step that escalates while you page can appear twice.GET /api/v3/factory-codebase-files(v2factories/listCodebaseFiles): you now get every indexed file once, with its full chunk count. It used to stop after reading 500 index entries and setmeta.partial: true. A file with many chunks can produce pages that have no files whilemeta.hasMoreis true.
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.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/webhooksdeclared alimitmaximum 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 largerlimitfor every credential, external apps included. The v2 routes keep their own maximums:GET /api/v2/webhooksstill takes up to 200.
/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.- Every MCP server tool input now lists its bounds in
tools/list: aminimumand amaximumon each number, amaxLengthon each free-text string and amaxItemson each list. - A value outside its bounds is refused with
invalid_inputbefore any request is sent. Alimitabove its maximum used to be lowered to it silently; it is now refused, so a caller that sent a largerlimitmust send one within the listed maximum.
- The MCP server now confirms
forge_dispatch_workflow,forge_run_workflow_and_wait,forge_restart_runandforge_start_run_analysisbefore 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_requiredwith aconfirmationTokento send back once the user agrees. forge_run_workflow_and_waitwith onlyrunIdfollows a started run and is not confirmed.forge_call_operationconfirms the operations that start a run the same way:dispatchWorkflow,restartRun,startRunAnalysis,testRunWorkflowDraftandlaunchWorkflowDebugAttempt. The confirmation names each argument that changes the run, such as its version, callback URL or a raised cap.
forge_list_run_artifacts,forge_list_run_events,forge_list_knowledge_reviews,forge_list_knowledge_scopesandforge_list_knowledge_casesnow takefields. The text answer keeps only the named row keys;structuredContentstill carries whole rows. See the MCP server reference.
- Ten MCP server list tools now take
fields, a list of row keys to keep. These includeforge_list_runs,forge_list_agents,forge_list_workflowsandforge_list_approvals. For example,forge_list_runs {"fields":["status","error"]}answers each run asid,statusanderroronly. - A projected row always keeps its
id. The projection applies to the text content:structuredContentstill carries whole rows. - An unknown key is refused as
invalid_inputbefore any request.error.details[]names the key and lists the keys a row has inallowed.
- Every MCP server refusal’s text starts with
Forge API error (<status> <code>):orForge MCP error (<code>):, and every refusal carriesstructuredContent.error. A host’s own input-validation failure is now aninvalid_inputrefusal in that format instead of anMCP error -32602text. - An
invalid_inputrefusal lists each failing field inerror.details, with the values the field accepts asallowed. - A
not_foundrefusal’s next step names the connection’s dedicatedforge_list_…tool when it lists one, before the generic operation call. - A refusal’s
decisionIdcan always be passed toforge_explain_denial. Withoutaudit:read,grants:readandpolicies:readthe explanation answers withdecision: nullinstead of refusing.
- 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_requiredwithconfirmationUrl. 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/createand waits for the decision. - An External App’s destructive calls run once a person with
apps:managepreauthorizes 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).
- 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 wholestructuredContent, and refuses any tool that is not read-only. See the MCP server reference.
forge_explain_denialreads a refusal’sdecisionIdfirst 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 holdingaudit:read,grants:readandpolicies:readgot404 Decision not found.- An id neither read finds answers with
decision: nullinstead of refusing the explanation. - A
403’s next step now passes itsdecisionIdtoforge_explain_denial, beside the refused permission.
forge_get_runnow ends its content with tworesource_linkitems, 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_workflowlinks the workflow’s definition (forge://workflows/{workflowId}) by the id it returned, even when it was called with a name.
- The first three results of
forge_search_operationson the MCP server now carryinputSchema, with the componentschemasit references, so a caller can build aforge_call_operationinput without first callingforge_describe_operation. - A schema over 2 KB is left out, and that result says
inputSchemaOmitted: true.
- Every MCP server tool’s text content is now at most 16 KiB.
forge_get_current_actorwithdetail: "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.structuredContentis unchanged and carries the whole answer.
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(v2synthesis/listBuilderHolds):datais now the array of holds, newest hold first.limitis 1 to 100 (default 50).GET /api/v3/knowledge-subject-collections(v2knowledge/subjectCollections/list):datais now the array of collections. A page reads one readable namespace at a time, so a page can be short while more namespaces follow.limitis 1 to 100 (default 50).GET /api/v3/runs/{runId}/step-searches(v2runs/admin/step-searches): each item is oneknowledge_searchcall. Repeated searches are no longer merged into one item.limitis 1 to 100 (default 50).POST /api/v3/knowledge-synchronized-source-providers/{providerKey}/search-containers(v2knowledge/synchronized-sources/listContainers): bounded at 1,000 containers (x-forge-bound). A provider that offers more answers409withLIST_CONTAINERS_TOO_MANY, where it used to return a cut list withmeta.partial: true(or, for a Freshservice account past 1,000 workspaces, an internal error). Narrow the search and ask again.
data array:GET /api/v3/runs/{runId}/step-contexts(v2runs/listStepContext): newest recorded first. It is no longer sorted by kind.limitis 1 to 100 (default 50).GET /api/v3/skill-sets(v2skills/listSets): the active sets, a page at a time.limitis 1 to 100 (default 50).GET /api/v3/workflow-steps(v2workflows/listSteps): newest change first. A filter applies to each page, so a filtered page can be short.limitis 1 to 100 (default 50).GET /api/v3/model-fallback-chains(v2models/listFallbackChains): in creation order. It used to list system chains first, then by name.limitis 1 to 100 (default 50).GET /api/v3/factories/{factoryId}/releases(v2factories/listReleases): every release milestone of the factory, most recently updated first.limitis 1 to 100 (default 50).
x-forge-paging: window) accepts limit from 1 to 1,000, and its read is never cut short./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 adderror.docUrl,meta.requestId, anderror.codewhere the vendor’s was missing ornull. 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.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.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.- A
readorwriterequest spends from a fallback bucket with the same burst and refill as its credential’s bucket. It carries theRateLimit-*headers as usual;RateLimit-Remainingis an estimate while the fallback serves. - An
expensiverequest, or any request whose fallback also faults, answers503with codeinternal_errorandRetry-After: 1. Nothing ran: retry after the delay.
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.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.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(v2customers/listScopes):datawas{ scopes, count }withmeta.partial. It is now the array of scopes, oldest link first, andmeta.partialis gone.limitis 1 to 100 (default 100).GET /api/v3/workers/{workerId}/expertise-tags(v2people/admin/workers/expertise-tags):datawas{ tags, truncated }. It is now the array of tags, with notruncated.limitis 1 to 100 (default 100).
data array:GET /api/v3/me/api-keys(v2api-keys/admin/own-keys) andGET /api/v3/personal-keys(v2api-keys/admin/personal-keys): active keys newest first, then revoked keys newest first.limitis 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(v2roles/admin/grants/holder):limitis 1 to 40 (default 40), andmeta.partialis 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(v2knowledge/synchronized-sources/list): newest first across every namespace you can read, or the one you name.limitis 1 to 100 (default 100). It used to answer the newest 100 withmeta.partial: true; every source is now reachable.
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.- A
422answersunprocessableinstead ofbad_request: the request is well formed, but Forge refuses one of its values. A reusedIdempotency-Keystill answersidempotency_key_reuse. PATCH /api/v2/memory/updateon a forgotten memory answers410goneinstead of409 conflict.POST /api/v2/knowledge/askwith a frozen or exhausted budget answers402payment_requiredinstead of403 forbidden. The refusal still carries itsdecisionId.
/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.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(v2knowledge/collections/list):datawas{ status: "complete", collections }, or{ status: "too_large" }when you could read too many collections. It is now the array of collections, and there is notoo_largeanswer.limitis 1 to 100 (default 100), in namespace and kind order.GET /api/v3/synthesis-templates(v2synthesis/listTemplates):datawas{ templates, count }. It is now the array of templates, with nocount.limitis 1 to 200 (default 200), in status and kind order.GET /api/v3/planning-blocked-tasks(v2planning/listBlockedTasks):datawas{ tasks }. It is now the array of tasks.limitis 1 to 200 (default 100), newest first.GET /api/v3/me/blockers(v2planning/admin/my-blockers) andGET /api/v3/planning-could-help(v2planning/admin/could-help):datawas{ tasks, partial }. It is now the array of tasks.limitis 1 to 100 (default 50).
data array:GET /api/v3/tools-needing-attention(v2tools/listNeedingAttention):limitis 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(v2providers/listAuditEvents):limitis 1 to 50 (default 10), newest first. Alimitabove 50 now reads 50, where it used to be a400.GET /api/v3/governance-trust-policies/{trustPolicyId}/revisions(v2governance/listTrustPolicyRevisions):limitis 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(v2governance/listRoles):limitis 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(v2knowledge/goldenSets/list):limitis 1 to 100 (default 50), newest first, the active sets and then, withincludeArchived=true, the archived ones. It used to return at most the newest 50 of each.
/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.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.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.
