/api/v2/synthesis/*) are the Console’s Synthesis queue for machines: they read the same rows and run the same commands as the Console, in this deployment’s workspace.
A caller never names a workspace or an org unit. A request on the wire never carries its workspace, its Builder channel or thread, or who asked for it, held it or assigned its reviewer. Times are epoch milliseconds.
Authority
Each operation is decided at the platform scope, the reads included. A grant that covers only some org units receives
403 permission_denied, and a refused decision writes nothing. The credential’s scopes must also reach the permission.
- A Personal key acts as its owner. The owner must be an active person whose own grants hold the permission at the platform scope, and the key’s scopes narrow what it may use.
synthesis:approveis in no default scope set, so a Personal key carries it only when its owner picks it, and such a key expires sooner; see Approve and administer scopes. - An External App or a platform API key needs a role grant at the platform scope whose role carries the permission. The built-in apps are not seeded with
synthesis:approve. - A Forge agent can never hold
synthesis:approve. Agents do work; they never approve.
Who decided
A decision is recorded wherever the Console records the person who made it: the request’s reviewer assignment, a curator recommendation’s reviewer, the procedure lifecycle event and the audit event. Through this API the decider is the calling credential:grantedBy lists, sorted and without repeats, who gave each of the app’s or key’s enabled platform-scope grants whose role carries synthesis:approve. A curator decision made through a Personal key names the owner’s worker as its audit actor, as the Console does. Responses never name who decided.
Human tasks
Each request awaiting review or provisional, and each pending curator recommendation, is a group human task that asks everyone who holdssynthesis:approve at the platform scope now and is an active person with an email (see Review queues). A Personal key decides each item through its task, as its owner: the owner’s grants narrowed to the key’s scopes must make them someone the task asks, and an item someone else claimed is theirs. A bulk decision skips those ids as not_a_candidate and claimed_by_other; Decide curator recommendation answers 403 and 409. An External App or a platform API key decides as before, and the item’s open task is closed.
Reads
- List synthesis requests: one page of the queue, default status
provisional, with filters onstatus,kind,reviewerAssignedToandfactoryIdand up to 50 rows per page. The filters onkindandfactoryIdapply after the page is read, so a page can be short, or empty, whilemeta.hasMoreis true; followmeta.nextCursoruntilmeta.hasMoreis false. - List Builder holds: the draft procedures the Builder holds for operator review, newest first, at most 100;
meta.partialis true when there are more. Holds are listed only: a held draft is approved or sent back on the procedure itself, in the Console’s Procedures page. - Get synthesis request: one request by
id. - Get Builder conversation: the Builder’s messages for one request, found through the request’s own record. The route never takes a channel id.
404 resource_missing “Synthesis request not found”.
Decisions
- Promote synthesis requests: each
provisionalrequest completes, and its primitive is approved. - Demote synthesis requests: each
provisionalorawaiting_reviewrequest is rejected with yourreason, which cannot be undone. - Accept synthesis requests: each
awaiting_reviewrequest moves toprovisionaldespite its failing review verdict. - Assign synthesis reviewer: set an active person as each request’s reviewer, or clear it.
The bulk contract
Every decision takesids: 1 to 50 request ids, each non-empty and none repeated. Anything else is 400 bad_request “ids must hold 1-50 unique ids”, and an unknown field is 400. The Console’s own command runs over the ids:
- One call is one transaction. If it fails, nothing was written and the answer is
500. - Otherwise the answer is
200with{requested, affected, skipped}.requestedis the number of ids sent,affectedthe number changed, andskippedlists the rest in the order they were sent.affectedplus the length ofskippedalways equalsrequested. - An id this deployment cannot find is a skipped item, never a
404.
{id, reason}, and two reasons carry one more field. The reasons are a closed set:
Repeats
Without anIdempotency-Key, a repeated promote, demote or accept changes nothing: each id it already moved is skipped as wrong_status. A repeated assign reviewer is not a no-op: it applies the same assignment again, re-stamps the assignment time and writes another audit event.
With an Idempotency-Key, the same key and body within 24 hours returns the recorded 200 only while the caller still holds synthesis:approve at the platform scope; otherwise 409 idempotency_result_unavailable, and the decision never runs twice. The same key with a different body is 422. If an outcome is unknown, repeat with the same key or read the requests; never retry under a new key. See Synthesis approvals.
Curator queue
The Curator compares primitives of the same kind and records a recommendation for each pair it judges to overlap. These routes are the Console’s curator queue (see Synthesis budgets and the Curator) for machines, over the recommendations it records for the platform workspace. Brian Johnson ruled on 2026-10-14 that the curator’s reads keepsynthesis:approve, so every curator operation, reads included, needs it.
- List curator recommendations: one page of pending recommendations, optionally of one
kind. - Get curator recommendation: one recommendation with the judge’s rationale and scores and each primitive’s id and name.
- Decide curator recommendation: merge, deprecate one side, keep both or mark distinct.
- Close keep-both curator recommendations: close up to 50
keep_bothrecommendations at once, following the bulk contract above, wherenot_keep_bothnames a recommendation that is notkeep_both.
Synthesis settings
These routes are the Console’s Synthesis Settings and Synthesis Templates pages for machines (see Synthesis budgets and the Curator), over this deployment’s workspace:- List synthesis templates, Create synthesis template, Update synthesis template and Delete synthesis template: the constraints the Spec Linter checks every Builder draft against.
- Get synthesis budget and Set synthesis budget: the workspace’s monthly synthesis spend cap, its alert threshold and its rolling window.
- Get the just-in-time synthesis default and Set the just-in-time synthesis default: whether new Workflow Architect channels synthesize missing capabilities just in time.
platform:read as well as synthesis:manage. The credential’s scopes must reach both: a credential without synthesis:manage is refused naming it, and one without platform:read is refused naming that. The grants are then decided at the platform scope, platform:read first, and the refusal names the first one missing. Neither the Console nor these routes record an audit event for a settings change. A template never carries its workspace or who created it, and a budget never carries its row id or workspace.
Who wrote it
A template’screatedBy and a budget’s or JIT default’s updatedBy take the writer as the decisions above do: a Personal key’s owner’s subject, external-app:<id> or platform-key:<id>. Responses never return them.
The Forge MCP server exposes these twenty operations in the governance tool group.
