> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Synthesis

> 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.

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](https://docs.gloo.com/forge/console/platform/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

| Operations | Permission |
| - | - |
| The four reads | `platform:read` |
| The four decisions | `synthesis:approve` |
| The four curator operations, reads included | `synthesis:approve` |
| The three settings reads | `platform:read` |
| The five settings writes | `synthesis:manage`, and the scopes must also reach `platform:read` |

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](https://docs.gloo.com/forge/console/settings/personal-keys.md#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:

| Credential | Recorded as | Audit `actorType` | Audit detail |
| - | - | - | - |
| Personal key | The owner's subject, exactly what the Console stores when that person decides | `human` | `via: "personal_key"`, `apiKeyId` |
| External App | `external-app:<id>` | `system` | `via: "external_app"`, `externalApplicationId`, `grantedBy` |
| Platform API key | `platform-key:<id>` | `system` | `via: "platform_key"`, `apiKeyId`, `grantedBy` |

`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](https://docs.gloo.com/forge/reference/http-api/governance#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](https://docs.gloo.com/forge/reference/http-api/synthesis/decideCuratorRecommendation.md) 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](https://docs.gloo.com/forge/reference/http-api/synthesis/listRequests.md): 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](https://docs.gloo.com/forge/reference/http-api/synthesis/listBuilderHolds.md): 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](https://docs.gloo.com/forge/console/platform/procedures.md) page.
* [Get synthesis request](https://docs.gloo.com/forge/reference/http-api/synthesis/getRequest.md): one request by `id`.
* [Get Builder conversation](https://docs.gloo.com/forge/reference/http-api/synthesis/getBuilderConversation.md): 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

* [Promote synthesis requests](https://docs.gloo.com/forge/reference/http-api/synthesis/promoteRequests.md): each `provisional` request completes, and its primitive is approved.
* [Demote synthesis requests](https://docs.gloo.com/forge/reference/http-api/synthesis/demoteRequests.md): each `provisional` or `awaiting_review` request is rejected with your `reason`, which cannot be undone.
* [Accept synthesis requests](https://docs.gloo.com/forge/reference/http-api/synthesis/acceptRequests.md): each `awaiting_review` request moves to `provisional` despite its failing review verdict.
* [Assign synthesis reviewer](https://docs.gloo.com/forge/reference/http-api/synthesis/assignReviewer.md): set an active person as each request's reviewer, or clear it.

### 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:

| `reason` | Extra field | Meaning |
| - | - | - |
| `not_found` | — | The id is malformed or unknown, or names a request in another workspace. |
| `wrong_status` | `status` | The request is not in the status the command needs: `provisional` to promote, `provisional` or `awaiting_review` to demote, `awaiting_review` to accept. `status` is its current status. |
| `improved_version_not_eligible` | — | Promote only: a later improvement already superseded the version this improve request built, so nothing was approved. |
| `no_placeholder_primitive` | — | Accept only: the request has no built primitive to accept. |
| `promote_refused` | `detail` | Accept only: the primitive could not move to provisional (for example, it is already in a final state). `detail` is the refusal. |
| `not_a_candidate` | — | Personal key only: the request's human task does not ask the key's owner, through the key's scopes. |
| `claimed_by_other` | — | Personal key only: someone else claimed the request's human task. |
| `other` | `detail` | Any other refusal, passed through as `detail`. |

### 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](https://docs.gloo.com/forge/reference/idempotency.md#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](https://docs.gloo.com/forge/run/synthesis-budgets-and-curator.md)) 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.

* [List curator recommendations](https://docs.gloo.com/forge/reference/http-api/synthesis/listCuratorRecommendations.md): one page of pending recommendations, optionally of one `kind`.
* [Get curator recommendation](https://docs.gloo.com/forge/reference/http-api/synthesis/getCuratorRecommendation.md): one recommendation with the judge's rationale and scores and each primitive's id and name.
* [Decide curator recommendation](https://docs.gloo.com/forge/reference/http-api/synthesis/decideCuratorRecommendation.md): merge, deprecate one side, keep both or mark distinct.
* [Close keep-both curator recommendations](https://docs.gloo.com/forge/reference/http-api/synthesis/closeKeepBothCuratorRecommendations.md): close up to 50 `keep_both` recommendations at once, following the bulk contract above, where `not_keep_both` names a recommendation that is not `keep_both`.

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](https://docs.gloo.com/forge/run/synthesis-budgets-and-curator.md)), over this deployment's workspace:

* [List synthesis templates](https://docs.gloo.com/forge/reference/http-api/synthesis/listTemplates.md), [Create synthesis template](https://docs.gloo.com/forge/reference/http-api/synthesis/createTemplate.md), [Update synthesis template](https://docs.gloo.com/forge/reference/http-api/synthesis/updateTemplate.md) and [Delete synthesis template](https://docs.gloo.com/forge/reference/http-api/synthesis/deleteTemplate.md): the constraints the Spec Linter checks every Builder draft against.
* [Get synthesis budget](https://docs.gloo.com/forge/reference/http-api/synthesis/getBudget.md) and [Set synthesis budget](https://docs.gloo.com/forge/reference/http-api/synthesis/setBudget.md): the workspace's monthly synthesis spend cap, its alert threshold and its rolling window.
* [Get the just-in-time synthesis default](https://docs.gloo.com/forge/reference/http-api/synthesis/getJitDefault.md) and [Set the just-in-time synthesis default](https://docs.gloo.com/forge/reference/http-api/synthesis/setJitDefault.md): whether new Workflow Architect channels synthesize missing capabilities just in time.

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](https://docs.gloo.com/forge/reference/mcp-server.md) exposes these twenty operations in the `governance` tool group.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.