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

# Forge function reference

> Choose a Forge MCP action, learn its prerequisites and follow its result without guessing identifiers or retry behavior.

Use [the quickstart](https://docs.trycontinuum.ai/forge/agents.md) first. Every call uses the active brand and normal [MCP sign-in and access rules](https://docs.trycontinuum.ai/mcp/reference.md).

Checked 2026-11-09: **17 query actions** and **19 management actions**. These are contract entries, not a promise that every source format or client can execute them.

Fetch only the action you need with `help_describe {tool, action}`. Some connectors advertise an older action enum. If your client cannot represent an action, refresh its tool discovery or use a client that exposes the current contract; do not silently substitute another action.

The [operation index](https://docs.trycontinuum.ai/forge/agent-manifest.json) supplies compact routing facts. Full inputs stay in runtime discovery. Fields marked required below include action-specific validator requirements that a flat JSON schema may omit. Successful Forge results use `{status: "ok", action, result}`; read the fields below inside `result`.

> [!WARNING]
>
> `render_preview` is a preflight, not a pixel render. Inspect saved delivery settings: omitted settings inherit. Show the person the rows, destinations and any spend before confirming. Use the exact `confirmationToken` returned by the Forge action.

## At a glance

| Action | What it does | Role |
| - | - | - |
| [`forge_query.templates`](#forge_query-templates) | List granted or built render templates. | Viewer or higher |
| [`forge_query.template`](#forge_query-template) | Read exposed variables, required values, budgets, outputs and contractHash. | Viewer or higher |
| [`forge_query.sets`](#forge_query-sets) | List saved sets, optionally filtered by templateKey. | Viewer or higher |
| [`forge_query.set`](#forge_query-set) | Read saved rows, inherited effective values and delivery settings. | Viewer or higher |
| [`forge_query.set_revisions`](#forge_query-set_revisions) | Read kept states of a set. | Viewer or higher |
| [`forge_query.destinations`](#forge_query-destinations) | Read delivery and approval destinations. | Viewer or higher |
| [`forge_query.jobs`](#forge_query-jobs) | List render jobs, optionally filtered by templateKey, setId, batchId or status. | Viewer or higher |
| [`forge_query.job`](#forge_query-job) | Refresh a single render job and its output files. | Viewer or higher |
| [`forge_query.batch`](#forge_query-batch) | Read a batch, waiting briefly for its jobs to settle. | Viewer or higher |
| [`forge_query.scenes`](#forge_query-scenes) | List accessible 3D scenes and their fillable keys. | Viewer or higher |
| [`forge_query.set_diff`](#forge_query-set_diff) | Compare two rows or two kept states as rendered. | Viewer or higher |
| [`forge_query.template_tree`](#forge_query-template_tree) | Read branches, revision history, publications and the default variant. | Viewer or higher |
| [`forge_query.template_layers`](#forge_query-template_layers) | Read editable compositions and layers of a revision. | Viewer or higher |
| [`forge_query.template_revision`](#forge_query-template_revision) | Read a revision and its source identity. | Viewer or higher |
| [`forge_query.template_diff`](#forge_query-template_diff) | Compare edits of two revisions of one template. | Viewer or higher |
| [`forge_query.template_run`](#forge_query-template_run) | Read the publishing run for this exact revision source. | Viewer or higher |
| [`forge_query.sources`](#forge_query-sources) | List the brand’s uploaded template sources and parse/build state. | Viewer or higher |
| [`forge_manage.set_create`](#forge_manage-set_create) | Save rows for one template. | Operator or higher |
| [`forge_manage.set_update`](#forge_manage-set_update) | Update a saved set with a revision check. | Operator or higher |
| [`forge_manage.set_fork`](#forge_manage-set_fork) | Copy the current set or one of its kept states. | Operator or higher |
| [`forge_manage.set_delete`](#forge_manage-set_delete) | Delete a saved render set. | Operator or higher |
| [`forge_manage.suggest_rows`](#forge_manage-suggest_rows) | Draft values from a brief, documents or media. | Operator or higher |
| [`forge_manage.apply_suggestions`](#forge_manage-apply_suggestions) | Append selected draft rows once. | Operator or higher |
| [`forge_manage.source_begin`](#forge_manage-source_begin) | Create a signed-in mixed-file upload handoff. | Operator or higher |
| [`forge_manage.source_status`](#forge_manage-source_status) | Read upload readiness and classified resource IDs. | Operator or higher |
| [`forge_manage.source_figma`](#forge_manage-source_figma) | Import Figma frames as design templates, or list the frames in a Figma file. | Operator or higher |
| [`forge_manage.render_preview`](#forge_manage-render_preview) | Validate selected rows and show where each result will go. | Operator or higher |
| [`forge_manage.render_confirm`](#forge_manage-render_confirm) | Redeem the reviewed preflight token and queue the batch. | Operator or higher |
| [`forge_manage.scene_fill`](#forge_manage-scene_fill) | Fill an accessible scene from the brand and brief. | Operator or higher |
| [`forge_manage.scene_render`](#forge_manage-scene_render) | Redeem a reviewed scene fill and queue its outputs. | Operator or higher |
| [`forge_manage.rows_patch`](#forge_manage-rows_patch) | Upsert or remove selected rows with a revision check. | Operator or higher |
| [`forge_manage.set_retarget`](#forge_manage-set_retarget) | Pin an existing set to a published template revision. | Operator or higher |
| [`forge_manage.template_preview`](#forge_manage-template_preview) | Preview proposed edits without saving a revision. | Operator or higher |
| [`forge_manage.template_save`](#forge_manage-template_save) | Save edits as a new immutable revision. | Operator or higher |
| [`forge_manage.template_forge`](#forge_manage-template_forge) | Start or advance publication of an eligible revision source. | Admin or Owner |
| [`forge_manage.template_set_default`](#forge_manage-template_set_default) | Choose the variant everyone opens by default. | Admin or Owner |

## Sources

### `forge_query.sources`

List the brand’s uploaded template sources and parse/build state.

| Contract | Behavior |
| - | - |
| Required inputs | `action` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | items: assetId, family, parseState, forgeState; more |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"sources"}`.

### `forge_manage.source_begin`

Create a signed-in mixed-file upload handoff.

| Contract | Behavior |
| - | - |
| Required inputs | `action` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | `upload_intent_id`, `open_url`, `expires_at`, `max_files` |
| Role | Operator or higher |
| Side effects | Creates an upload intent; completing an eligible source upload can start automatic preparation. |
| Potential spend | No generation started by this call. |
| Confirmation | Explain automatic preparation and smoke-render spend and obtain permission BEFORE completing an eligible source upload; waiting for `template_forge` does not prevent it. |
| Completion | Returns inline; upload, parsing and eligible preparation continue separately. |
| Retry | Do not retry blindly: another call creates another handoff. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"source_begin"}`.

### `forge_manage.source_status`

Read upload readiness and classified resource IDs.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `upload_intent_id` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | documentIds, mediaAssetIds, templateAssetIds, `source_refs`, sources |
| Role | Operator or higher |
| Side effects | Reads the handoff; saves nothing. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again while processing. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"source_status"}`.

### `forge_manage.source_figma`

Import Figma frames as design templates, or list the frames in a Figma file.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `figmaUrl` |
| Conditions | Uses the brand's Figma connection and the signed-in person's Continuum session. Read `forge_query` sources until parsed, then `forge_query` template for its text columns. |
| Returns | File link without figmaNodeIds: fileKey, fileName, frames, next (nothing imported). Frame link or figmaNodeIds: fileKey, assets, templateAssetIds, templateKeys (web: plus the asset id), next |
| Role | Operator or higher |
| Side effects | A file link lists its frames and imports nothing. A frame link, or figmaNodeIds (up to 5), imports each frame into the Library as a design template that renders as its templateKey with no build. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | If the call times out, repeat it with the same arguments: it joins the import still running. |
| Errors | `INTEGRATION_REQUIRED`: connect Figma for the brand; `PERMISSION_DENIED`: the brand's Figma account can't open this file; `NOT_FOUND`: no such Figma file or frame; UNAUTHENTICATED: no signed-in session; import from the Forge page instead; `VALIDATION_ERROR`: not a figma.com/design link |

Schema: `help_describe {"tool":"forge_manage","action":"source_figma"}`.

## Template revisions

### `forge_query.templates`

List granted or built render templates.

| Contract | Behavior |
| - | - |
| Required inputs | `action` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | items: key, bindingId, sourceAssetId; nextCursor |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"templates"}`.

### `forge_query.template`

Read exposed variables, required values, budgets, outputs and contractHash.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `templateKey` |
| Conditions | Use bindingId from discovery when the key matches multiple workspaces. |
| Returns | Template contract; layout is omitted |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"template"}`.

### `forge_query.template_tree`

Read branches, revision history, publications and the default variant.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `assetId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | templateId, defaultVariantId, variants\[].revisions |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"template_tree"}`.

### `forge_query.template_layers`

Read editable compositions and layers of a revision.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `revisionId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | Layer inventory and supported edits |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"template_layers"}`.

### `forge_query.template_revision`

Read a revision and its source identity.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `revisionId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | Revision: id, variantId, sourceAssetId, sourceVersionId, edits |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"template_revision"}`.

### `forge_query.template_diff`

Compare edits of two revisions of one template.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `revisionId`, `toRevisionId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | from, to, edits |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `VALIDATION_ERROR`: revisions must belong to one template |

Schema: `help_describe {"tool":"forge_query","action":"template_diff"}`.

### `forge_query.template_run`

Read the publishing run for this exact revision source.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `assetId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | run (may be null), state and needs when present |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"template_run"}`.

### `forge_manage.template_preview`

Preview proposed edits without saving a revision.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `assetId`, `parentRevisionId`, `edits` |
| Conditions | Read `template_layers` first. Edits are also checked against the revision edit contract. |
| Returns | Edited layer values, svgBytes, next; no SVG body |
| Role | Operator or higher |
| Side effects | Validates and previews; saves nothing. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Re-read state after an uncertain response; no general replay guarantee. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"template_preview"}`.

### `forge_manage.template_save`

Save edits as a new immutable revision.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `assetId`, `parentRevisionId`, `edits` |
| Conditions | Exactly one of name (new branch) or variantId (extend its current head). Requires a signed-in user session. |
| Returns | revision (id, variantId, sourceAssetId), replayed |
| Role | Operator or higher |
| Side effects | Writes a source/version and revision; preserves the Original. Eligible saved sources can automatically prepare and publish. |
| Potential spend | Yes: parsing the saved package can start automatic preparation and smoke-render spend. |
| Confirmation | Obtain explicit permission for saving and its automatic preparation/spend BEFORE `template_save`; there is no separate render-preview token for this path. |
| Completion | Returns inline. |
| Retry | Same save derives a replay key; optional UUID idempotencyKey. Re-read after a head conflict. |
| Errors | `PERMISSION_DENIED`: signed-in session required; CONFLICT: branch head changed |

Schema: `help_describe {"tool":"forge_manage","action":"template_save"}`.

### `forge_manage.template_forge`

Start or advance publication of an eligible revision source.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `assetId`, `step` |
| Conditions | step=start needs templateName; step=decisions needs decisions. Native HTML/components/Blender do not use this action. |
| Returns | source or run, next; inspect `template_run` |
| Role | Admin or Owner |
| Side effects | Changes publishing state; can run smoke renders and publish automatically. |
| Potential spend | Yes: smoke renders can spend provider budget, including after start. |
| Confirmation | Obtain explicit permission for this publishing run and its smoke-render spend before starting; this action has no `render_preview` token. |
| Completion | Returns inline; inspect `template_run` while the run continues. |
| Retry | Read `template_run` first. Step in only where parked; on CONFLICT re-read instead of replaying steps. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"template_forge"}`.

### `forge_manage.template_set_default`

Choose the variant everyone opens by default.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `assetId`, `variantId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | templateId, defaultVariantId |
| Role | Admin or Owner |
| Side effects | Changes the default template variant. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Re-read `template_tree` before retrying; confirm the intended default. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"template_set_default"}`.

## Render sets

### `forge_query.sets`

List saved sets, optionally filtered by templateKey.

| Contract | Behavior |
| - | - |
| Required inputs | `action` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | Saved render sets |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"sets"}`.

### `forge_query.set`

Read saved rows, inherited effective values and delivery settings.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `setId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | id, revision, rows, resolved, settings, template revision pin |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"set"}`.

### `forge_query.set_revisions`

Read kept states of a set.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `setId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | Kept set revisions for `set_fork` or `set_diff` |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"set_revisions"}`.

### `forge_query.set_diff`

Compare two rows or two kept states as rendered.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `setId` |
| Conditions | Supply rowIds=\[a,b], or fromRevision with optional toRevision (default: current). |
| Returns | Differences in effective values and render settings |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"set_diff"}`.

### `forge_manage.set_create`

Save rows for one template.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `templateKey`, `name`, `rows` |
| Conditions | Use bindingId when ambiguous; templateRevisionId, when supplied, must identify a published revision. |
| Returns | Saved set: id, revision, rows and template pin |
| Role | Operator or higher |
| Side effects | Creates a saved set; queues no renders. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | No general replay guarantee; discover existing sets after an uncertain response. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"set_create"}`.

### `forge_manage.set_update`

Update a saved set with a revision check.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `setId`, `expectedRevision` |
| Conditions | settings merges named keys; null clears nullable settings. Prefer `rows_patch` for surgical row changes. |
| Returns | Saved set with its new revision |
| Role | Operator or higher |
| Side effects | Writes supplied fields; rows replaces the ENTIRE row list. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | On `render_set_revision_conflict`, re-read set and reconcile; never replace expectedRevision blindly. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"set_update"}`.

### `forge_manage.set_fork`

Copy the current set or one of its kept states.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `setId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | New set: id, revision and rows |
| Role | Operator or higher |
| Side effects | Creates a separate set; optional revision selects a kept state. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | No general replay guarantee; inspect sets after an uncertain response. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"set_fork"}`.

### `forge_manage.set_delete`

Delete a saved render set.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `setId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | deleted: set ID |
| Role | Operator or higher |
| Side effects | Deletes the set. |
| Potential spend | No generation started by this call. |
| Confirmation | Ask for an explicit yes before calling. This action directly deletes; it does not issue its own confirmationToken. |
| Completion | Returns inline. |
| Retry | Do not retry blindly; re-read the set after an uncertain response. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"set_delete"}`.

### `forge_manage.suggest_rows`

Draft values from a brief, documents or media.

| Contract | Behavior |
| - | - |
| Required inputs | `action` |
| Conditions | Provide setId or templateKey, and prompt or documentIds or mediaAssetIds. parentRowId requires setId. |
| Returns | Unsaved suggested rows with stable draft IDs and field evidence |
| Role | Operator or higher |
| Side effects | Uses AI; saves nothing. |
| Potential spend | AI drafting may consume model budget. |
| Confirmation | Use only when the person’s request authorizes AI drafting and its potential model spend; that request is sufficient consent. No server confirmation token is issued. |
| Completion | Returns inline. |
| Retry | Another call drafts again; retain selected draft IDs for `apply_suggestions`. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"suggest_rows"}`.

### `forge_manage.apply_suggestions`

Append selected draft rows once.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `setId`, `expectedRevision`, `rows` |
| Conditions | Every selected row must retain its draft id. |
| Returns | setId, revision, appliedRowIds, replayed |
| Role | Operator or higher |
| Side effects | Appends the selected drafts, preserving other rows. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Selected draft IDs provide replay protection; on a genuine revision conflict, re-read and reconcile. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"apply_suggestions"}`.

### `forge_manage.rows_patch`

Upsert or remove selected rows with a revision check.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `setId`, `expectedRevision` |
| Conditions | Supply nonempty rows or removeRowIds. Ask for explicit consent before removing rows. |
| Returns | Updated set and resolved rows |
| Role | Operator or higher |
| Side effects | Changes only selected rows; omitting a row ID appends a new row. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Use stable row IDs; re-read on a revision conflict. ID-less appends can duplicate on retry. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"rows_patch"}`.

### `forge_manage.set_retarget`

Pin an existing set to a published template revision.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `setId`, `expectedRevision`, `templateRevisionId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | Updated set and template revision pin |
| Role | Operator or higher |
| Side effects | Changes the template pin after validating existing rows. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Re-read on revision conflict; do not substitute an unpublished or unrelated revision. |
| Errors | `VALIDATION_ERROR`: `template_revision_unpublished`; CONFLICT: `render_set_revision_conflict` |

Schema: `help_describe {"tool":"forge_manage","action":"set_retarget"}`.

## Rendering

### `forge_query.destinations`

Read delivery and approval destinations.

| Contract | Behavior |
| - | - |
| Required inputs | `action` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | Slack/approval destinations, Meta account IDs, next |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"destinations"}`.

### `forge_query.jobs`

List render jobs, optionally filtered by templateKey, setId, batchId or status.

| Contract | Behavior |
| - | - |
| Required inputs | `action` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | items containing job IDs and status |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"jobs"}`.

### `forge_query.job`

Refresh a single render job and its output files.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `jobId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | Render job, status and available outputs |
| Role | Viewer or higher |
| Side effects | Refreshes stored status; starts no new render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"job"}`.

### `forge_query.batch`

Read a batch, waiting briefly for its jobs to settle.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `batchId` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | batchId, done, counts, jobs\[].outputs |
| Role | Viewer or higher |
| Side effects | Refreshes stored status; starts no new render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Bounded wait: waitSeconds 0–55; use 50 in a background task until done=true. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"batch"}`.

### `forge_manage.render_preview`

Validate selected rows and show where each result will go.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `setId` |
| Conditions | Omitted delivery/final settings inherit from the saved set; inspect them. null slackDestinationId disables posting. final=true requires Admin/Owner. |
| Returns | Readiness, destinations, confirmationToken, next |
| Role | Operator or higher |
| Side effects | Preflight only; queues no renders. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Refresh after changed inputs or an expired token. Override a refusal only after the person agrees to its named flag. |
| Errors | `VALIDATION_ERROR`: `render_fonts_missing`; CONFLICT: `render_set_revision_conflict` |

Schema: `help_describe {"tool":"forge_manage","action":"render_preview"}`.

### `forge_manage.render_confirm`

Redeem the reviewed preflight token and queue the batch.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `confirmationToken` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | batchId and render job records |
| Role | Operator or higher |
| Side effects | Queues rendering and the reviewed delivery/approval work. |
| Potential spend | Yes: rendering can spend provider budget. |
| Confirmation | Show readiness, rows and destinations; wait for the person’s yes, then pass the exact returned confirmationToken. |
| Completion | Returns a batch immediately; read `forge_query` batch/job. |
| Retry | Single-use token. After an uncertain response inspect existing jobs; do not obtain another token and blindly render twice. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_manage","action":"render_confirm"}`.

## Scenes

### `forge_query.scenes`

List accessible 3D scenes and their fillable keys.

| Contract | Behavior |
| - | - |
| Required inputs | `action` |
| Conditions | Use only identifiers returned for this brand. |
| Returns | items: assetId, versionId, outputs, field keys |
| Role | Viewer or higher |
| Side effects | Reads state; starts no render. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | Safe to read again. |
| Errors | `needs_brand` / `needs_role`: resolve access first; `NOT_FOUND` / `VALIDATION_ERROR`: retain the returned reason |

Schema: `help_describe {"tool":"forge_query","action":"scenes"}`.

### `forge_manage.scene_fill`

Fill an accessible scene from the brand and brief.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `assetId`, `versionId` |
| Conditions | Use assetId/versionId/output IDs returned by scenes. |
| Returns | values, outputs, confirmationToken; nothing rendered |
| Role | Operator or higher |
| Side effects | Reads brand inputs and signs the proposed fill; renders nothing. |
| Potential spend | No generation started by this call. |
| Confirmation | None for this action. |
| Completion | Returns inline. |
| Retry | On `scene_version_stale` re-read scenes; a new fill creates a fresh confirmation. |
| Errors | CONFLICT: `scene_version_stale`; `VALIDATION_ERROR`: `scene_output_unknown` |

Schema: `help_describe {"tool":"forge_manage","action":"scene_fill"}`.

### `forge_manage.scene_render`

Redeem a reviewed scene fill and queue its outputs.

| Contract | Behavior |
| - | - |
| Required inputs | `action`, `confirmationToken` |
| Conditions | The service reloads the current scene at submission; immutable scene-version execution is not guaranteed. Recheck scenes before confirming; if it changed, fill/review again. |
| Returns | assetId, values, jobs\[{outputId, jobId}], next |
| Role | Operator or higher |
| Side effects | Queues one scene render per output into the Library. |
| Potential spend | Yes: scene rendering can spend provider budget; this response does not supply a price estimate. |
| Confirmation | Show filled values and outputs, explain potential spend (estimate may be unavailable), wait for a yes, then pass the exact `scene_fill` token. |
| Completion | Scene jobs use the template’s scene history in Forge and the Library; they are not Forge render-set batches. |
| Retry | Token is single-use; after an uncertain response inspect history before another fill/render. |
| Errors | `VALIDATION_ERROR`: `expired_confirmation`; CONFLICT: `confirmation_spent` |

Schema: `help_describe {"tool":"forge_manage","action":"scene_render"}`.

## Recover from a refusal

* **Revision conflict:** re-read the set or template head, reconcile the intended change, and preview again. A set's numeric `expectedRevision` is different from a template revision UUID.
* **Ambiguous template key:** select the discovered `bindingId`; do not guess a workspace.
* **Insufficient role:** preserve `needs_role` or `PERMISSION_DENIED` and request the appropriate brand role. `final=true` and template publication need Admin or Owner.
* **Expired or spent token:** inspect existing jobs first if submission may have succeeded. Otherwise preview/fill again and obtain a new yes; never turn an uncertain response into an automatic second render.
* **Missing fonts or another overridable refusal:** pass a flag only when `details.overrides` names it and the person explicitly accepts that specific problem. Other refusals remain blocking.
* **Partial or failed batch:** inspect each job. `done=true` means settled, including failures; it does not mean every output succeeded. Preserve job IDs and reasons.
* **Scene jobs:** use the template's scene history in Forge and the Library. Do not pass a scene job ID to the render-set job API without a supported contract.

No Forge webhook subscription or cancellation action is established by this catalog. Your host application starts MCP calls and retains their identifiers.

## Example call sequences

These are sequential MCP `tools/call` parameters, not an executable batch. UUIDs, tokens, template and variable keys are illustrative: substitute the exact discovered values. Populate required template fields before preflight. Obtain permission for automatic preparation/spend before completing a source upload or saving a revision; pause for the person's yes before render confirmation. A render price estimate may be unavailable.

Keep each returned identity for the next call. After publication, rediscover the matching template key/binding and use the published revision UUID. For scenes, recheck the version before confirming; the service still reloads the current scene. Follow the individual action's conditions above.

* **An existing template.** The discovered binding is 666…; `set_create` returns set id 555…; `render_confirm` returns batchId 777…. Replace each with its actual returned value. The illustrative headline key must also be replaced by an exposed variable key. Calls, in order: `[{"name":"forge_query","arguments":{"action":"template","templateKey":"discovered-template-key","bindingId":"66666666-6666-4666-8666-666666666666"}},{"name":"forge_manage","arguments":{"action":"set_create","templateKey":"discovered-template-key","name":"Example set","rows":[{"id":"22222222-2222-4222-8222-222222222222","parentId":null,"label":"Example","overrides":{"headline":"Your message"}}],"bindingId":"66666666-6666-4666-8666-666666666666"}},{"name":"forge_query","arguments":{"action":"set","setId":"55555555-5555-4555-8555-555555555555"}},{"name":"forge_manage","arguments":{"action":"render_preview","setId":"55555555-5555-4555-8555-555555555555","slackDestinationId":null,"final":false}},{"name":"forge_manage","arguments":{"action":"render_confirm","confirmationToken":"token-returned-by-render-preview"}},{"name":"forge_query","arguments":{"action":"batch","batchId":"77777777-7777-4777-8777-777777777777","waitSeconds":50}}]`
* **A supported source revision.** Upload intent: 888…. Uploaded source asset: 111…. Observed parent revision: 222…. `template_save` returns revision.sourceAssetId=333… and revision.id=444…. Use 333… for `template_run`/`template_forge`, and the published 444… for templateRevisionId. After publication, rediscover templateKey and bindingId (666…). The `template_forge` start example is CONDITIONAL: skip it if a run already exists. Wait for publication before `set_create`. Calls, in order: `[{"name":"forge_manage","arguments":{"action":"source_begin"}},{"name":"forge_manage","arguments":{"action":"source_status","upload_intent_id":"88888888-8888-4888-8888-888888888888"}},{"name":"forge_query","arguments":{"action":"sources"}},{"name":"forge_query","arguments":{"action":"template_tree","assetId":"11111111-1111-4111-8111-111111111111"}},{"name":"forge_query","arguments":{"action":"template_revision","revisionId":"22222222-2222-4222-8222-222222222222"}},{"name":"forge_query","arguments":{"action":"template_layers","revisionId":"22222222-2222-4222-8222-222222222222"}},{"name":"forge_manage","arguments":{"action":"template_preview","assetId":"11111111-1111-4111-8111-111111111111","parentRevisionId":"22222222-2222-4222-8222-222222222222","edits":{}}},{"name":"forge_manage","arguments":{"action":"template_save","assetId":"11111111-1111-4111-8111-111111111111","parentRevisionId":"22222222-2222-4222-8222-222222222222","edits":{},"name":"Example variant"}},{"name":"forge_query","arguments":{"action":"template_run","assetId":"33333333-3333-4333-8333-333333333333"}},{"name":"forge_manage","arguments":{"action":"template_forge","assetId":"33333333-3333-4333-8333-333333333333","step":"start","templateName":"example-template"}},{"name":"forge_manage","arguments":{"action":"set_create","templateKey":"discovered-template-key","name":"Example set","rows":[{"id":"22222222-2222-4222-8222-222222222222","parentId":null,"label":"Example","overrides":{"headline":"Your message"}}],"bindingId":"66666666-6666-4666-8666-666666666666","templateRevisionId":"44444444-4444-4444-8444-444444444444"}}]`
* **An accessible scene.** scenes supplies assetId 111… and versionId 222…. `scene_fill` returns the reviewed token; `scene_render` returns separate jobs\[].jobId values. Recheck the scene before confirmation; the current service does not enforce the token’s source version at render time. Calls, in order: `[{"name":"forge_query","arguments":{"action":"scenes"}},{"name":"forge_manage","arguments":{"action":"scene_fill","assetId":"11111111-1111-4111-8111-111111111111","versionId":"22222222-2222-4222-8222-222222222222","brief":{"headline":"Your message"}}},{"name":"forge_manage","arguments":{"action":"scene_render","confirmationToken":"token-returned-by-scene-fill"}}]`

## What's next

* [Agent quickstart](https://docs.trycontinuum.ai/forge/agents.md): Choose a function and execute safely.
* [Design systems](https://docs.trycontinuum.ai/forge/design-systems.md): Check source formats and execution boundaries.


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