Skip to main content
The synthesis queue is the ledger of synthesis requests. Each request asks Forge to build a skill, an agent or a procedure, and a finished build waits in the queue for a person’s decision. The routes on this page (at v2, under /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:approve is 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 holds synthesis: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 on status, kind, reviewerAssignedTo and factoryId and up to 50 rows per page. The filters on kind and factoryId apply after the page is read, so a page can be short, or empty, while meta.hasMore is true; follow meta.nextCursor until meta.hasMore is false.
  • List Builder holds: the draft procedures the Builder holds for operator review, newest first, at most 100; meta.partial is 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.
A request id that is missing, malformed, unknown or in another workspace answers 404 resource_missing “Synthesis request not found”.

Decisions

The bulk contract

Every decision takes ids: 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 200 with {requested, affected, skipped}. requested is the number of ids sent, affected the number changed, and skipped lists the rest in the order they were sent. affected plus the length of skipped always equals requested.
  • An id this deployment cannot find is a skipped item, never a 404.
Each skipped item is {id, reason}, and two reasons carry one more field. The reasons are a closed set:

Repeats

Without an Idempotency-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 keep synthesis:approve, so every curator operation, reads included, needs it. A recommendation never carries its workspace, its judge verdict row, its curator run or who reviewed it.

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: Every settings operation is decided at the platform scope. A write answers a read of what it wrote, so it needs 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’s createdBy 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.