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

# Workflows

> Discover workflow definitions, read their input schema, publish and test-run drafts, dispatch new runs, and register a signed completion callback.

Workflows are directed graphs of agent, router, join, human, and publish nodes. The Workflows domain exposes the published catalog of workflow definitions and the entry point for triggering a run from an external system. Once dispatched, the run shows up in the Runs domain.

## Resource shape

The list returns `WorkflowSummary` rows and `get` returns the `Workflow` detail; both carry the same allowlisted identity fields (`id`, `name`, `description`, `ownerId`, `owningOrgUnitId`, timestamps, and so on). The list adds readable run counts; the detail adds the active version, deployment, and readable recent runs. The `name` is the dispatch key. Each read decides the workflow at its home org unit: the caller needs `workflows:read` there, and a workflow it cannot read answers `404` or is left out of the list.

## Workflow ownership (External Apps and Personal keys)

Organization-owned External Apps can create empty drafts at their owning unit or a covered factory. Drafts record `externalApp:<id>` as their owner/creator attribution and persist the chosen home directly. A Personal key creates as its owner, at the home the Console gives that person's workflow (the factory's, else the owner's, else the deployment root; a factory must be one the key may read), stamped with the owner. A platform API key cannot create. Draft updates use the caller's read and write grants at the stored home; app ownership alone lends no authority. The list/detail readers retain their existing owner/creator strings, while the draft DTO omits those stamps.

## Operations

Draft writes:

* `POST /api/v3/workflows` — [create](https://docs.gloo.com/forge/reference/http-api/workflows/create.md)
* `PATCH /api/v3/workflows/{workflowId}/draft` — [updateDraft](https://docs.gloo.com/forge/reference/http-api/workflows/updateDraft.md)

Both need the `workflows:write` scope and home grants for `workflows:write` plus `workflows:read`. Publishing is a [lifecycle write](#workflow-lifecycle).

Draft graph reads and edits (structure and content only; agent, worker, person, recipient, channel, credential, vault, tool, procedure, model and sandbox settings stay in Console):

* `GET /api/v3/workflows/{workflowId}/draft-graph` — [getDraftGraph](https://docs.gloo.com/forge/reference/http-api/workflows/getDraftGraph.md) — read the draft's nodes and edges, at most 200 and 400, with `meta.partial`
* `POST /api/v3/workflows/{workflowId}/draft-nodes` — [createDraftNode](https://docs.gloo.com/forge/reference/http-api/workflows/createDraftNode.md)
* `PATCH /api/v3/workflows/{workflowId}/draft-nodes/{nodeId}` — [updateDraftNode](https://docs.gloo.com/forge/reference/http-api/workflows/updateDraftNode.md)
* `DELETE /api/v3/workflows/{workflowId}/draft-nodes/{nodeId}` — [deleteDraftNode](https://docs.gloo.com/forge/reference/http-api/workflows/deleteDraftNode.md)
* `POST /api/v3/workflows/{workflowId}/draft-edges` — [createDraftEdge](https://docs.gloo.com/forge/reference/http-api/workflows/createDraftEdge.md)
* `PATCH /api/v3/workflows/{workflowId}/draft-edges/{edgeId}` — [updateDraftEdge](https://docs.gloo.com/forge/reference/http-api/workflows/updateDraftEdge.md)
* `DELETE /api/v3/workflows/{workflowId}/draft-edges/{edgeId}` — [deleteDraftEdge](https://docs.gloo.com/forge/reference/http-api/workflows/deleteDraftEdge.md)

The read needs `workflows:read` at the workflow's home; the six edits need the `workflows:write` scope and home grants for `workflows:write` plus `workflows:read`.

Draft validation:

* `GET /api/v3/workflows/{workflowId}/draft-validation` — [validateDraft](https://docs.gloo.com/forge/reference/http-api/workflows/validateDraft.md) — the Console validator's findings and publishability for the draft, read-only, under `workflows:read` at the workflow's home

Published versions (read-only; rollback and reset are [lifecycle writes](#workflow-lifecycle), and [retire](https://docs.gloo.com/forge/reference/http-api/workflows/retire.md) is a workflow catalog write, below):

* `GET /api/v3/workflows/{workflowId}/versions` — [listVersions](https://docs.gloo.com/forge/reference/http-api/workflows/listVersions.md) — page the workflow's published versions, newest first
* `GET /api/v3/workflow-versions/{versionId}` — [getVersion](https://docs.gloo.com/forge/reference/http-api/workflows/getVersion.md) — read one published version
* `GET /api/v3/workflow-versions/{versionId}/graph` — [getVersionGraph](https://docs.gloo.com/forge/reference/http-api/workflows/getVersionGraph.md) — read one version's frozen nodes and edges, at most 200 and 400, with `meta.partial`

All three need `workflows:read` at the workflow's home.

Workflow lifecycle (see [Workflow lifecycle](#workflow-lifecycle)):

* `POST /api/v3/workflows/{workflowId}/publish-draft` — [publishDraft](https://docs.gloo.com/forge/reference/http-api/workflows/publishDraft.md) — publish the draft as a new active version
* `POST /api/v3/workflows/{workflowId}/test-run-draft` — [testRunDraft](https://docs.gloo.com/forge/reference/http-api/workflows/testRunDraft.md) — start a test run of the draft
* `POST /api/v3/workflow-versions/{versionId}/activate` — [rollback](https://docs.gloo.com/forge/reference/http-api/workflows/rollback.md) — make a superseded version active again
* `POST /api/v3/workflows/{workflowId}/reset-draft` — [resetDraft](https://docs.gloo.com/forge/reference/http-api/workflows/resetDraft.md) — replace the draft with a published version, discarding its edits
* `GET /api/v3/workflow-capability-readiness` — [getCapabilityReadiness](https://docs.gloo.com/forge/reference/http-api/workflows/getCapabilityReadiness.md) — whether each Agent node's agent holds what the node needs
* `GET /api/v3/workflows/{workflowId}/agent-readiness` — [getAgentReadiness](https://docs.gloo.com/forge/reference/http-api/workflows/getAgentReadiness.md) — whether each Run-as-Agent node's agent can be dispatched
* `GET /api/v3/workflows/{workflowId}/run-cost-forecast` — [getRunCostForecast](https://docs.gloo.com/forge/reference/http-api/workflows/getRunCostForecast.md) — the next run's expected cost

Workflow catalog (each write needs `workflows:manage` at the workflow's home; a same-key purge retry returns the recorded result and never purges twice):

* `POST /api/v3/workflows/{workflowId}/retire` — [retire](https://docs.gloo.com/forge/reference/http-api/workflows/retire.md) — stop a workflow from being launched
* `POST /api/v3/workflows/{workflowId}/unretire` — [unretire](https://docs.gloo.com/forge/reference/http-api/workflows/unretire.md) — allow a retired workflow to be launched again
* `POST /api/v3/workflows/{workflowId}/trash` — [trash](https://docs.gloo.com/forge/reference/http-api/workflows/trash.md) — soft-delete a workflow
* `POST /api/v3/workflows/{workflowId}/restore` — [restore](https://docs.gloo.com/forge/reference/http-api/workflows/restore.md) — undo a trash
* `POST /api/v3/workflows/{workflowId}/purge` — [purge](https://docs.gloo.com/forge/reference/http-api/workflows/purge.md) — delete a trashed workflow and everything it owns
* `POST /api/v3/workflows/{workflowId}/set-tags` — [setTags](https://docs.gloo.com/forge/reference/http-api/workflows/setTags.md) — replace a workflow's tags
* `POST /api/v3/workflows/{workflowId}/set-owning-org-unit` — [setOwningOrgUnit](https://docs.gloo.com/forge/reference/http-api/workflows/setOwningOrgUnit.md) — move a workflow to another owning org unit
* `POST /api/v3/workflows/{workflowId}/replace-asset` — [replaceAsset](https://docs.gloo.com/forge/reference/http-api/workflows/replaceAsset.md) — bind a platform file to a workflow's asset input
* `POST /api/v3/workflows/create-from-template` — [createFromTemplate](https://docs.gloo.com/forge/reference/http-api/workflows/createFromTemplate.md) — instantiate a workflow template
* `GET /api/v3/workflows/{workflowId}/assets` — [listAssets](https://docs.gloo.com/forge/reference/http-api/workflows/listAssets.md) — the files bound to a workflow's asset inputs
* `GET /api/v3/workflow-templates` — [listTemplates](https://docs.gloo.com/forge/reference/http-api/workflows/listTemplates.md) — the workflow templates
* `GET /api/v3/workflow-lookup` — [getByName](https://docs.gloo.com/forge/reference/http-api/workflows/getByName.md) — look a workflow up by its name
* `GET /api/v3/workflows/{workflowId}/bundle-export` — [exportBundle](https://docs.gloo.com/forge/reference/http-api/workflows/exportBundle.md) — export a workflow and its dependencies as a portable bundle

Workflow Architect (a Personal key starts and continues a conversation, see [Driving the Architect from the API](#driving-the-architect-from-the-api); plans and synthesis batches are decided by a person, through their human task or in Console):

* `GET /api/v3/workflows/{workflowId}/architect-status` — [getArchitectStatus](https://docs.gloo.com/forge/reference/http-api/workflows/getArchitectStatus.md) — whether the draft has a live Architect conversation and whether a person's decision is pending, with the Console link, under `workflows:read` at the workflow's home
* `GET /api/v3/workflows/{workflowId}/architect-plan` — [getArchitectPlan](https://docs.gloo.com/forge/reference/http-api/workflows/getArchitectPlan.md) — the pending plan and the human task a person decides it on, under `workflows:read` at the workflow's home
* `GET /api/v3/workflows/{workflowId}/architect-progress` — [getArchitectProgress](https://docs.gloo.com/forge/reference/http-api/workflows/getArchitectProgress.md) — the build manifest and synthesis drive, at most 200 rows each with `meta.partial`, under `workflows:read` at the workflow's home
* `GET /api/v3/workflows/{workflowId}/synthesis-confirmation` — [getSynthesisConfirmation](https://docs.gloo.com/forge/reference/http-api/workflows/getSynthesisConfirmation.md) — the pending synthesis batch with its specs and estimates, under `workflows:write` at the workflow's home
* `GET /api/v3/workflows/{workflowId}/architect-decisions` — [getArchitectDecisions](https://docs.gloo.com/forge/reference/http-api/workflows/getArchitectDecisions.md) — the resolved plans and batches, newest first, under `workflows:read` at the workflow's home
* `GET /api/v3/workflows/{workflowId}/architect-jit-mode` — [getArchitectJitMode](https://docs.gloo.com/forge/reference/http-api/workflows/getArchitectJitMode.md) — the conversation's and the workspace's just-in-time synthesis modes, under `workflows:read` at the workflow's home
* `POST /api/v3/runs/{runId}/ask-architect-to-fix` — [askArchitectToFixRun](https://docs.gloo.com/forge/reference/http-api/workflows/askArchitectToFixRun.md) — open a failed run's failure in an Architect conversation, under `workflows:write` at the run's workflow's home
* `POST /api/v3/workflows/create-from-chat-task` — [createFromChatTask](https://docs.gloo.com/forge/reference/http-api/workflows/createFromChatTask.md) — save a completed Personal Agent task as a workflow, Personal key only
* `POST /api/v3/workflows/{workflowId}/set-architect-jit-mode` — [setArchitectJitMode](https://docs.gloo.com/forge/reference/http-api/workflows/setArchitectJitMode.md) — turn just-in-time synthesis on or off, for the draft's author or a `platform:manage` holder
* `POST /api/v3/workflows/start-architect-conversation` — [startArchitectConversation](https://docs.gloo.com/forge/reference/http-api/workflows/startArchitectConversation.md) — create a workflow from a brief and start the Architect's first turn, Personal key only
* `POST /api/v3/workflows/{workflowId}/architect-messages` — [sendArchitectMessage](https://docs.gloo.com/forge/reference/http-api/workflows/sendArchitectMessage.md) — send the next message and start its turn, Personal key only; refused while a turn is in progress
* `GET /api/v3/workflows/{workflowId}/architect-messages` — [listArchitectMessages](https://docs.gloo.com/forge/reference/http-api/workflows/listArchitectMessages.md) — one transcript page and the turn's state to poll, under `workflows:write` at the workflow's home
* `POST /api/v3/workflows/{workflowId}/cancel-architect-turn` — [cancelArchitectTurn](https://docs.gloo.com/forge/reference/http-api/workflows/cancelArchitectTurn.md) — ask a running turn to stop, under `workflows:write` at the workflow's home
* `POST /api/v3/workflows/{workflowId}/reset-architect-conversation` — [resetArchitectConversation](https://docs.gloo.com/forge/reference/http-api/workflows/resetArchitectConversation.md) — archive the conversation so the next message starts fresh, under `workflows:write` at the workflow's home

Draft debugging and canvas tools (see [Draft debugging](#draft-debugging)):

* `GET /api/v3/workflows/{workflowId}/debug-options` — [getDebugOptions](https://docs.gloo.com/forge/reference/http-api/workflows/getDebugOptions.md) — a draft node and the production runs to debug it against
* `POST /api/v3/workflows/{workflowId}/debug-attempts` — [prepareDebugAttempt](https://docs.gloo.com/forge/reference/http-api/workflows/prepareDebugAttempt.md) — freeze a draft node and plan a debug attempt, Personal key only
* `POST /api/v3/workflow-debug-attempts/{attemptId}/launch` — [launchDebugAttempt](https://docs.gloo.com/forge/reference/http-api/workflows/launchDebugAttempt.md) — run a prepared attempt, Personal key only
* `GET /api/v3/workflow-debug-attempts/{attemptId}` — [getDebugAttempt](https://docs.gloo.com/forge/reference/http-api/workflows/getDebugAttempt.md) — one of your attempts and, once run, its output
* `POST /api/v3/workflow-debug-attempts/{attemptId}/cancel` — [cancelDebugAttempt](https://docs.gloo.com/forge/reference/http-api/workflows/cancelDebugAttempt.md) — stop a queued or running attempt
* `GET /api/v3/workflow-debug-attempts/{attemptId}/history` — [listDebugAttemptHistory](https://docs.gloo.com/forge/reference/http-api/workflows/listDebugAttemptHistory.md) — your earlier attempts of the same node
* `GET /api/v3/workflow-debug-attempts/{attemptId}/comparison` — [compareDebugAttempts](https://docs.gloo.com/forge/reference/http-api/workflows/compareDebugAttempts.md) — an attempt beside an earlier finished one
* `GET /api/v3/workflow-debug-attempts/{attemptId}/files` — [listDebugFiles](https://docs.gloo.com/forge/reference/http-api/workflows/listDebugFiles.md) — the files an attempt read and wrote
* `GET /api/v3/workflow-debug-attempts/{attemptId}/file-urls/{fileId}` — [getDebugFileUrl](https://docs.gloo.com/forge/reference/http-api/workflows/getDebugFileUrl.md) — a bearer download link for one of them
* `GET /api/v3/workflow-debug-attempts/{attemptId}/tool-calls` — [listDebugToolCalls](https://docs.gloo.com/forge/reference/http-api/workflows/listDebugToolCalls.md) — an attempt's tool calls, newest first, a page at a time (`limit` 1–200, default 50)
* `GET /api/v3/workflow-versions/{versionId}/debug-preview-options` — [getDebugPreviewOptions](https://docs.gloo.com/forge/reference/http-api/workflows/getDebugPreviewOptions.md) — a published version's nodes and source runs
* `GET /api/v3/workflow-versions/{versionId}/debug-slice-preview` — [previewDebugSlice](https://docs.gloo.com/forge/reference/http-api/workflows/previewDebugSlice.md) — the historical inputs a published slice would read
* `GET /api/v3/procedures/{procedureId}/repin-preview` — [previewProcedureRepin](https://docs.gloo.com/forge/reference/http-api/workflows/previewProcedureRepin.md) — what re-pinning a procedure's draft callers changes, under `workflows:read`
* `POST /api/v3/workflows/{workflowId}/repin-procedure` — [repinProcedure](https://docs.gloo.com/forge/reference/http-api/workflows/repinProcedure.md) — re-pin procedure nodes of one draft, under `workflows:write` at its home
* `POST /api/v3/workflows/test-route-condition` — [testRouteCondition](https://docs.gloo.com/forge/reference/http-api/workflows/testRouteCondition.md) — evaluate a route condition against a sample input, under `workflows:read`

Reads:

* `GET /api/v3/workflows` — [listWorkflows](https://docs.gloo.com/forge/reference/http-api/workflows) — list published workflow definitions
* `GET /api/v3/workflows/{workflowId}` — [getWorkflow](https://docs.gloo.com/forge/reference/http-api/workflows) — fetch a single workflow definition by ID
* `GET /api/v3/workflows/{workflowId}/input-schema` — [getInputSchema](https://docs.gloo.com/forge/reference/http-api/workflows/getInputSchema.md) — fetch the active (or a named published) version's input-schema shape for typed UI rendering
* `GET /api/v3/workflows/{workflowId}/draft` — [getDraft](https://docs.gloo.com/forge/reference/http-api/workflows/getDraft.md) — read the workflow's editable draft: identity, metadata and canonical input contract
* `GET /api/v3/workflows/{workflowId}/triggers` — [listTriggers](https://docs.gloo.com/forge/reference/http-api/workflows/listTriggers.md) — list the workflow's schedules and other triggers
* `GET /api/v3/workflow-triggers/{triggerId}` — [getTrigger](https://docs.gloo.com/forge/reference/http-api/workflows/getTrigger.md) — read one trigger
* `GET /api/v3/workflow-triggers` — [listScheduleRoster](https://docs.gloo.com/forge/reference/http-api/workflows/listScheduleRoster.md) — every trigger the caller may read, across workflows, with its latest run
* `POST /api/v3/workflows/{workflowId}/triggers` — [createTrigger](https://docs.gloo.com/forge/reference/http-api/workflows/createTrigger.md) — schedule a workflow (cron or one-shot)
* `PATCH /api/v3/workflow-triggers/{triggerId}` — [updateTrigger](https://docs.gloo.com/forge/reference/http-api/workflows/updateTrigger.md) — change a schedule
* `POST /api/v3/workflow-triggers/{triggerId}/pause` — [pauseTrigger](https://docs.gloo.com/forge/reference/http-api/workflows/pauseTrigger.md) — stop a schedule firing
* `POST /api/v3/workflow-triggers/{triggerId}/resume` — [resumeTrigger](https://docs.gloo.com/forge/reference/http-api/workflows/resumeTrigger.md) — resume a paused schedule
* `DELETE /api/v3/workflow-triggers/{triggerId}` — [deleteTrigger](https://docs.gloo.com/forge/reference/http-api/workflows/deleteTrigger.md) — delete a trigger
* `POST /api/v3/workflows/{workflowId}/ingress-triggers` — [createIngressTrigger](https://docs.gloo.com/forge/reference/http-api/workflows/createIngressTrigger.md) — create an inbound URL; returns its token once
* `POST /api/v3/workflow-triggers/{triggerId}/set-ingress-status` — [setIngressStatus](https://docs.gloo.com/forge/reference/http-api/workflows/setIngressStatus.md) — pause or resume an inbound URL
* `POST /api/v3/workflow-triggers/{triggerId}/rotate-ingress-token` — [rotateIngressToken](https://docs.gloo.com/forge/reference/http-api/workflows/rotateIngressToken.md) — mint a new token; returns it once
* `PATCH /api/v3/workflow-triggers/{triggerId}/ingress-config` — [updateIngressConfig](https://docs.gloo.com/forge/reference/http-api/workflows/updateIngressConfig.md) — change an inbound URL's config
* `GET /api/v3/fiscal-calendars` — [listFiscalCalendars](https://docs.gloo.com/forge/reference/http-api/workflows/listFiscalCalendars.md) — list fiscal calendars
* `GET /api/v3/fiscal-calendars/{calendarName}` — [getFiscalCalendar](https://docs.gloo.com/forge/reference/http-api/workflows/getFiscalCalendar.md) — read one fiscal calendar
* `POST /api/v3/fiscal-calendars` — [createFiscalCalendar](https://docs.gloo.com/forge/reference/http-api/workflows/createFiscalCalendar.md) — create a fiscal calendar
* `PATCH /api/v3/fiscal-calendars/{calendarName}` — [updateFiscalCalendar](https://docs.gloo.com/forge/reference/http-api/workflows/updateFiscalCalendar.md) — change a fiscal calendar
* `DELETE /api/v3/fiscal-calendars/{calendarName}` — [deleteFiscalCalendar](https://docs.gloo.com/forge/reference/http-api/workflows/deleteFiscalCalendar.md) — delete a fiscal calendar no published version cites
* `GET /api/v3/workflow-steps` — [listSteps](https://docs.gloo.com/forge/reference/http-api/workflows/listSteps.md) — browse the step library
* `POST /api/v3/workflow-steps` — [createStep](https://docs.gloo.com/forge/reference/http-api/workflows/createStep.md) — add a step library entry
* `PATCH /api/v3/workflow-steps/{stepId}` — [updateStep](https://docs.gloo.com/forge/reference/http-api/workflows/updateStep.md) — change a step library entry
* `DELETE /api/v3/workflow-steps/{stepId}` — [deleteStep](https://docs.gloo.com/forge/reference/http-api/workflows/deleteStep.md) — remove a step library entry
* `GET /api/v3/workflow-triggers/{triggerId}/ingress-invocations` — [listIngressInvocations](https://docs.gloo.com/forge/reference/http-api/workflows/listIngressInvocations.md) — pages an ingress trigger's requests, newest first

Writes:

* `POST /api/v3/workflows/dispatch` — [dispatch](https://docs.gloo.com/forge/reference/http-api/workflows/dispatch.md) — trigger a run by workflow name or id with input arguments; with `workflowId`, `versionId` runs one of its published versions

## Schedules and other triggers

A workflow can be started by a schedule (`cron`), a single scheduled fire (`one_shot`), a capability URL (`ingress`) or a routed email (`email`). `listTriggers` and `getTrigger` read them: kind, timing, whether each follows the active version or pins one, the org unit its fires run at, and when it fires next. A trigger is visible only when the caller holds `workflows:read` at both the workflow's home and the trigger's `orgUnitId`, because the runs a trigger starts are recorded at its `orgUnitId`. The owner, creator, stored inputs and ingress material are never returned.

[listIngressInvocations](https://docs.gloo.com/forge/reference/http-api/workflows/listIngressInvocations.md) reads an ingress trigger's requests under the same rule, and [listScheduleRoster](https://docs.gloo.com/forge/reference/http-api/workflows/listScheduleRoster.md) lists every trigger the caller may read across workflows, with each one's latest run when the caller may read runs there.

The trigger writes run the Console's own commands and need `workflows:manage` where the Console decides it: at the workflow's home and the new trigger's org unit for a create, and at the trigger's org unit and the platform scope for every other write. A trigger runs a published version, so its agents and bound companies are decided for the caller as at a publish. A Personal key's trigger belongs to its owner's worker seat; an External App's or platform API key's belongs to the app or key and stops when it loses `workflows:manage`. An ingress token and its URL are returned once, at create and rotate, and never stored. An email trigger is changed with its email route.

## Fiscal calendars

Fiscal calendars name the fiscal-year start month that `fiscalPeriod()` expressions and derived launch inputs use. Machine credentials with `workflows:read` can list the deployment-wide catalog or read one calendar by its lowercase slug. The response omits row ids and the people who created or changed each calendar.

Creating, changing and deleting a calendar, and the step library's writes, need `workflows:manage` held at the **platform scope** (the elevated `workflows:manage` scope; Forge agents can never hold it), plus the `workflows:read` scope because each answers what it wrote. A calendar's name never changes, and a calendar an active published version cites cannot be deleted. Each change is audited with the credential (a Personal key as its owner).

## Step library

The step library holds reusable steps: a command with its inputs, outputs and success criteria. [listSteps](https://docs.gloo.com/forge/reference/http-api/workflows/listSteps.md) browses it under `workflows:read` at the platform scope, never returning a step's author. [createStep](https://docs.gloo.com/forge/reference/http-api/workflows/createStep.md), [updateStep](https://docs.gloo.com/forge/reference/http-api/workflows/updateStep.md) and [deleteStep](https://docs.gloo.com/forge/reference/http-api/workflows/deleteStep.md) change it under `workflows:manage`; a step's author is always the caller. Deleting a step does not change workflows already built from it, which keep their own copy of its command. With an `Idempotency-Key`, the library's writes replay under the [workflow library rule](https://docs.gloo.com/forge/reference/idempotency.md#workflow-library-replay).

## Workflow lifecycle

Publishing a draft, test-running it, rolling back to a version and resetting the draft need `workflows:manage` held at the **platform scope**, as the Console decides it (the elevated `workflows:manage` scope; Forge agents can never hold it), plus the `workflows:read` scope because each success answers a read, and the workflow must be readable at its home. A Personal key acts as its owner, narrowed by its scopes; an External App or platform API key acts as itself. Each change is stored and audited with that actor under the Console's own audit events.

Publishing and rolling back decide the version's agents and bound companies for the caller as at a Console publish: `agents:use` for the agents it runs and `credentials:use` at each bound company. The `workflows:manage` scope carries both, and each is still decided at its own home. Publish and rollback require `expectedActiveVersionId`, so two callers never publish over each other. Validate a draft with [validateDraft](https://docs.gloo.com/forge/reference/http-api/workflows/validateDraft.md) before publishing it. A test run is a run: read and cancel it with the [runs](https://docs.gloo.com/forge/reference/http-api/runs) routes.

The three reads need `workflows:read` at the workflow's home. With an `Idempotency-Key`, publish, rollback and reset replay under the [workflow lifecycle rule](https://docs.gloo.com/forge/reference/idempotency.md#workflow-lifecycle-replay), and a test run under the [workflow dispatch rule](https://docs.gloo.com/forge/reference/idempotency.md#workflow-dispatch-replay).

## Driving the Architect from the API

A Personal key runs the same loop a person runs in the Architect drawer. Each turn acts for the key's owner, never with more than the key's scopes carry, and each start or send spends one of the key's Architect turns (60 an hour, burst 10; `429 rate_limited` with `Retry-After` past that).

**1. Start the conversation**

`POST /api/v3/workflows/start-architect-conversation` with your brief. The answer names the new workflow and its draft, with `turn.state: "running"`.

**2. Poll until the turn is idle**

`GET /api/v3/workflows/{workflowId}/architect-messages` no faster than every 2 seconds until `turn.state` is `"idle"`, then read the new `architect` items. A turn ends within 9 minutes.

**3. Let a person decide a plan or batch**

When the Architect proposes a plan, `getArchitectPlan` returns it with its `humanTaskId`. A person confirms it with `POST /api/v3/governance-human-tasks/{humanTaskId}/complete` (which needs `approvals:write:decide`) or in the Console; a pending synthesis batch works the same way through `getSynthesisConfirmation`.

**4. Continue**

`POST /api/v3/workflows/{workflowId}/architect-messages` with the next message once the turn is idle. A message sent while a turn is running, queued or stopping is refused with `409` and nothing is queued.

`cancelArchitectTurn` stops a running turn at its next step, and `resetArchitectConversation` archives a conversation that cannot continue. An External App or a platform API key can read, cancel and reset, but not start or send.

## Draft debugging

Draft debugging runs one node of a workflow's draft against the inputs of a past production run, as the Console builder's **Debug** does. Find the node and a source run with [getDebugOptions](https://docs.gloo.com/forge/reference/http-api/workflows/getDebugOptions.md), [prepare](https://docs.gloo.com/forge/reference/http-api/workflows/prepareDebugAttempt.md) an attempt (the node is frozen, its inputs resolved, each side effect planned as simulated or real), [launch](https://docs.gloo.com/forge/reference/http-api/workflows/launchDebugAttempt.md) it with its `planHash`, and poll [getDebugAttempt](https://docs.gloo.com/forge/reference/http-api/workflows/getDebugAttempt.md) for its output.

* **Who.** The debug routes need `workflows:use`, and the credential's scopes must also reach `workflows:read`; both are decided at the workflow's home. A missing, trashed, unhomed or unreachable workflow is a `404`.
* **The source run's companies.** An attempt carries the source run's historical values, so preparing from a run and reading an attempt also need `workflows:use` at every company the run carries; otherwise it is the same `404`. Once the source run has been deleted, its attempts are `404` too.
* **Debugging is personal.** As in the Console, you debug drafts you created and read attempts you started. A Personal key is its owner; an External App or a platform API key is its own creator. Another person's attempt is the same `404` as a missing one.
* **Running needs a person.** Preparing and launching run the node as the attempt's creator: governance and `credentials:use` are decided for them. So these two routes need a Personal key; any other credential is `403` with `personRequired: true`.
* **The flag.** When draft debugging (`workflow_debug_execution`) is off for you (a Personal key's owner) or for the deployment (an app or platform API key), every debug route answers `409 conflict`.
* **What never crosses.** An attempt's agent thread and creator, a file's storage handle, and a tool call's agent. A file's download link is a bearer link, recorded before it exists.
* **Published previews** read a version, not an attempt: they are not personal. The slice preview returns the source run's historical values, so it also needs `workflows:use` at every company the run carries.
* **Retries.** With an `Idempotency-Key`, the attempt writes replay under the [workflow debug rule](https://docs.gloo.com/forge/reference/idempotency.md#workflow-debug-replay); a launch's key is also the launch's own.

The canvas tools sit beside it: [previewProcedureRepin](https://docs.gloo.com/forge/reference/http-api/workflows/previewProcedureRepin.md) and [repinProcedure](https://docs.gloo.com/forge/reference/http-api/workflows/repinProcedure.md) move a procedure's draft callers to a new version, and [testRouteCondition](https://docs.gloo.com/forge/reference/http-api/workflows/testRouteCondition.md) tries a router branch condition.

## Reading the input schema

Integrations that render typed input forms before dispatch (Slack `/workflow` modals, custom dashboards, the Forge Console dispatch dialog) call `GET /api/v3/workflows/{workflowId}/input-schema` to retrieve the input shape for the workflow's active version. Add `versionId` to read one published version's contract instead (the form for re-running a specific version). The response carries two parallel fields:

```json theme={null}
{
  "data": {
    "id": "workflows:abc123",
    "version": 3,
    "workflowInputSchema": [
      {
        "name": "url",
        "type": "string",
        "required": true,
        "description": "URL to crawl",
        "validation": { "pattern": "^https?://" }
      },
      {
        "name": "depth",
        "type": "number",
        "required": false,
        "default": 3,
        "validation": { "min": 1, "max": 10 }
      }
    ]
  },
  "meta": { "requestId": "..." }
}
```

* **`workflowInputSchema`** is the input contract. Array-of-objects so order is preserved across the wire. Each entry declares `name`, `type` (`"string"` · `"number"` · `"boolean"` · `"object"` · `"file"` · `"string[]"` · `"number[]"` · `"file[]"`), `required: boolean`, and optional `default`, `description`, `validation` (`enum` · `min` · `max` · `pattern`).

Every writer persists a defined array — publish, clone, and reset all coalesce to `[]` rather than storing a hole — so a version whose `workflowInputSchema` is an empty array declares no inputs. It is not a version whose contract lives somewhere else: there is nowhere else left for it to live.

> [!WARNING]
>
> **`workflowInputs` was removed on 2026-08-09**. The legacy untyped blob is no longer a key in the response — it is absent, not `null`. There is no fallback: `workflowInputSchema` is the only representation of the contract, on the wire and in storage.

`workflowInputSchema: null` has **two** meanings, and `version` tells them apart:

| `version` | `workflowInputSchema` | Meaning | What a client should do |
| - | - | - | - |
| `null` | `null` | The workflow exists but has no active version (e.g. only drafts). | Fall back to a workflow-select-only UI. Dispatch will be refused until someone publishes. |
| a number | `null` | An active version exists but its input contract is unreadable. | Do **not** offer dispatch — `POST /api/v3/workflows/dispatch` answers `503` for it. Surface "this workflow must be republished". |
| a number | `[]` | The active version declares no inputs. | Offer dispatch with no arguments. |

Treating the second row as the first renders a launchable-looking workflow whose dispatch then fails, which is why the discriminator is worth reading rather than checking `workflowInputSchema` alone. A `404` indicates the workflow id does not exist or is malformed.

### Dispatch validation

The dispatch endpoint validates `runtimeArgs` against `workflowInputSchema` strictly — no type coercion. A `"42"` string supplied for a `type: "number"` field is rejected with a `400 bad_request`, not silently coerced. Required fields missing from `runtimeArgs` produce a `400` listing the missing field name. Validation constraints (`enum`, `min`, `max`, `pattern`) are enforced server-side. Unknown args (keys that name no declared field) are rejected to keep the contract bidirectional.

`workflowInputSchema` is the only representation dispatch reads, and there is no legacy fallback at validation time. Every writer persists it, and an empty array is how "declares no inputs" is spelled. A version carrying **no** canonical array at all has an *unreadable* contract, not an empty one, and there is no backfill left to wait for. Dispatch refuses it before validating arguments, so the failure is never blamed on the caller's `runtimeArgs`:

* `POST /api/v3/workflows/dispatch` → `503`, `error.code: "internal_error"`, message `This workflow's input contract is unreadable; it must be republished before it can be dispatched`.
* [Signed ingress](https://docs.gloo.com/forge/run/ingress.md) → `503`, reason prefixed `workflow contract unavailable: workflowV2/contract-unmigrated:`.

The remedy belongs to the workflow's owner — republishing the workflow restores dispatch — so a sender should back off and retry rather than change its request.

Required scope: `workflows:read`.

## Dispatch callbacks

`POST /api/v3/workflows/dispatch` accepts an optional `callback` object. When supplied, the run's terminal state produces **exactly one** signed POST to your URL, so an integration can wait for a result without polling `GET /api/v3/runs/{runId}`.

**callback** `object`

Register a one-shot completion callback. Omit for fire-and-forget dispatch.

**properties**

**url** `string` *required*

HTTPS destination for the delivery. Validated synchronously at dispatch time.

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/workflows/dispatch" \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "issue-triage",
        "inputs": { "issueId": "GH-1234" },
        "callback": { "url": "https://hooks.example.com/forge/issue-triage" }
      }'
```

### Who can use it

**External Application callers only.** The delivery is signed with the calling app's signing secret; a platform API key that belongs to no app has none, and Forge will not deliver an unsigned POST to a caller-supplied URL — at the receiver that is indistinguishable from a forgery. A caller with no owning app gets `422`.

### Validation at dispatch time

The URL is checked before the dispatch is accepted, not at delivery time twenty minutes later:

| Status | Cause |
| - | - |
| `400` | The shape is wrong — `callback` is not an object, or `callback.url` is missing or not a string. |
| `422` | The shape is right but the value is refused: the URL is not HTTPS, or resolves to a private / loopback / link-local host, or the caller has no owning External Application. |

### What gets delivered

One POST at terminal run state, through the same pipeline that carries webhook subscriptions: 3 attempts with 5s / 10s / 20s backoff, a 10-second timeout, `redirect: "error"` (a redirect is a delivery failure, not something to follow), and the dead-letter queue on exhaustion.

The body is always the **v2 envelope** — there is no v1 callback shape:

```json theme={null}
{
  "id": "callbackevent_<runId>",
  "type": "workflow.completed",
  "apiVersion": "2026-08-01",
  "occurredAt": 1785500000000,
  "orderingKey": "run_<runId>",
  "initiator": { "kind": "externalApp", "id": "fca_..." },
  "data": {
    "runId": "...",
    "workflowName": "issue-triage",
    "status": "completed",
    "completedAt": "2026-07-31T12:00:00.000Z",
    "durationMs": 42000,
    "stepCount": 6
  }
}
```

`type` is `workflow.completed` only for a genuinely completed run. **`failed` and `cancelled` both map to `workflow.failed`** — a caller waiting on a result cares that it did not get one. The exact terminal status is on `data.status`.

> [!NOTE]
>
> `id` is deterministic (`callbackevent_<runId>`), so all three delivery attempts carry the same event id and your dedupe key holds. It is deliberately **not** an event-log id: a callback is point-to-point and is not written to the canonical log, so `GET /api/v3/events` will not resolve it.

### Verifying a callback

Callbacks are signed with a **callback signing secret** — one per External App, a different key from `client_secret`. It is minted lazily the first time the app uses a callback, revealed once, and rotatable via [`POST /api/v3/external-apps/{externalAppId}/rotate-callback-secret`](https://docs.gloo.com/forge/reference/http-api/externalApps/rotateCallbackSecret).

The header and algorithm are identical to webhook subscriptions:

```
X-Forge-Signature-V2: t=<unix-ms>,v1=<hex-sha256-hmac>
```

`v1` is the HMAC-SHA256 over `t + "." + body`, keyed by the callback signing secret. The timestamp is inside the signed message, so a captured delivery cannot have its `t` refreshed without the key. **Reject deliveries whose `t` is more than 5 minutes from now, in either direction** — without that check the timestamp buys you nothing. Retries are re-signed with a fresh `t`, so a legitimate retry never trips your window.

Sign over the **bytes you received**, not a re-serialization: a `JSON.parse` → `JSON.stringify` round trip can reorder keys or reformat numbers and will break verification.

```js Node.js theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_MS = 5 * 60 * 1000;

// `rawBody` must be the exact request body bytes as a string.
// `secret` is the app's callbackSigningSecret, NOT its client_secret.
export function verifyForgeCallback(rawBody, header, secret, nowMs = Date.now()) {
  const parts = Object.fromEntries(
    String(header ?? "")
      .split(",")
      .map((kv) => kv.split("=").map((piece) => piece.trim())),
  );
  if (!/^\d+$/.test(parts.t ?? "") || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) return false;
  if (Math.abs(nowMs - Number(parts.t)) > TOLERANCE_MS) return false;

  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest();
  const received = Buffer.from(parts.v1, "hex");
  return expected.length === received.length && timingSafeEqual(expected, received);
}
```

```python Python theme={null}
import hashlib
import hmac
import re
import time

TOLERANCE_MS = 5 * 60 * 1000


# `raw_body` must be the exact request bytes, not a re-serialized dict.
# `secret` is the app's callback signing secret, NOT its client_secret.
def verify_forge_callback(raw_body: bytes, header: str, secret: str, now_ms: int = 0) -> bool:
    now_ms = now_ms or int(time.time() * 1000)
    parts = dict(kv.strip().split("=", 1) for kv in (header or "").split(",") if "=" in kv)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not re.fullmatch(r"\d+", t) or not re.fullmatch(r"[0-9a-f]{64}", v1):
        return False
    if abs(now_ms - int(t)) > TOLERANCE_MS:
        return False

    expected = hmac.new(
        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, v1)
```

Delivery headers are `X-Forge-Event` (the event type), `X-Forge-Delivery` (stable across all attempts of the same delivery), and `X-Forge-Signature-V2`.

### Known limitation: one callback per run row

The delivery id is derived from the run id, which is what makes the callback exactly-once. The consequence is that **a workflow rerun on the same run row does not re-arm the callback** — the enqueue finds the row already present and returns without scheduling a second POST. A rerun is an operator action against an existing run, not a second dispatch, and the caller that asked for a completion signal has already been given one. If you need a signal per attempt, dispatch again rather than rerunning.

> [!WARNING]
>
> A callback is a notification, not a delivery guarantee. After 3 failed attempts the delivery dead-letters. Treat the callback as a latency optimization over polling, and keep a reconciliation path that reads `GET /api/v3/runs/{runId}` for runs you never heard back about.

## Starting a run without a credential

Senders that cannot hold an OAuth token — GitHub, Linear, Zapier, vendor "notify this URL" fields — use **[signed workflow ingress](https://docs.gloo.com/forge/run/ingress.md)** instead: an unauthenticated capability URL scoped to one workflow, with optional per-trigger HMAC verification, idempotency, and a rate limit. Ingress has no callback; the run is observed through the Runs API or a webhook subscription.

## Common workflows

Discover a workflow, read its input schema, and trigger a run:

```bash theme={null}
curl "$FORGE_BASE/api/v3/workflows" \
  -H "Authorization: Bearer $FORGE_TOKEN"

curl "$FORGE_BASE/api/v3/workflows/workflows:abc123/input-schema" \
  -H "Authorization: Bearer $FORGE_TOKEN"

curl -X POST "$FORGE_BASE/api/v3/workflows/dispatch" \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "issue-triage", "inputs": {"issueId": "GH-1234"}}'
```

The response includes the new run ID. Track the run via the [Runs domain](https://docs.gloo.com/forge/reference/http-api/runs).

## Related

* [Workflows overview](https://docs.gloo.com/forge/build/compose-a-workflow.md) — conceptual background on graph orchestration
* [Workflow node types](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#the-workflow-graph) — agent, router, join, human, publish
* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token


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