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

# 2026-08-09 — Breaking: `workflowInputs` removed; workflow-input interpolation added

> GET /api/v2/workflows/get-input-schema no longer returns the legacy workflowInputs blob. Node literals, agent prompts and publish messages can interpolate a run's launch arguments.

**2026-08-09**

Breaking: GET /api/v2/workflows/get-input-schema no longer returns the legacy workflowInputs blob. Node literals, agent prompts, and publish messages can now interpolate launch arguments.

Last updated 2026-11-11

·
applies to 2026-08-09

·
main

## Summary

A workflow's input contract had two representations: the canonical typed array `workflowInputSchema`, and a legacy untyped `workflowInputs` blob keyed by field name. The blob is gone — removed from storage, from the platform's own read paths, and from the public response.

This is a **breaking change to a published endpoint**. `GET /api/v2/workflows/get-input-schema` no longer returns a `workflowInputs` key at all.

## Breaking change

> [!WARNING]
>
> **`data.workflowInputs` is removed from `GET /api/v2/workflows/get-input-schema`.**
>
> The key is **absent** from the response object, not `null`. A caller that reads `body.data.workflowInputs` now gets `undefined` rather than a blob or a null. Read `body.data.workflowInputSchema` instead.

Nothing else about the endpoint changed: the route, the `workflows:read` scope, the `id` query parameter, the `200` / `403` / `404` statuses, and the `data.id` / `data.version` / `data.workflowInputSchema` fields are all unchanged.

## Migration

Replace any read of `workflowInputs` with `workflowInputSchema`. The typed array carries the same information plus the field ordering the blob could not express.

Before — reading the blob, or falling back to it:

```ts theme={null}
const { data } = await client.getWorkflowInputSchema(workflowId);

// `workflowInputs` is gone from the SDK type, so this line no longer
// compiles. On a raw (untyped) response body it reads `undefined`.
const legacy = data.workflowInputs as Record<string, { type: string }> | null;
const fields = data.workflowInputSchema ?? legacy;
```

After — the typed array is the only source:

```ts theme={null}
import type { WorkflowInputField } from "@tangogroup/forge-sdk";

const { data } = await client.getWorkflowInputSchema(workflowId);

// `[]` ⇒ the active version declares no inputs. `null` ⇒ the contract could
// not be read, and `data.version` says why: `null` ⇒ no active version;
// a number ⇒ the active version's contract is unreadable and dispatch
// answers 503 until the workflow is republished.
const fields: WorkflowInputField[] | null = data.workflowInputSchema;

// A run parameter is a field carrying neither `derived` nor `asset` —
// those two are computed and bound by the platform, and supplying one
// at dispatch is rejected rather than ignored.
const runParameters = (fields ?? []).filter((f) => !f.derived && !f.asset);
```

The response shape a caller now sees:

```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": "..." }
}
```

Mapping from the old blob's keys to the array's fields:

| Legacy blob | Typed array |
| - | - |
| the `Record` key | `name` |
| `type` | `type` |
| `required: true` / `optional: true` | `required: boolean` (always present) |
| `description` | `description` |
| — (unrepresentable) | `validation` (`enum` · `min` · `max` · `pattern`) |
| — (unrepresentable) | `derived` · `asset` · `defaultExpr` |
| — (key order not guaranteed) | array order is the declared order |

## Client packages

* **`@tangogroup/forge-sdk`** — `WorkflowInputSchemaResult.workflowInputs` removed. The field was typed `unknown`, so consumers that never read it need no source change; consumers that did will now fail to compile, which is the intended signal.
* **`@tangogroup/forge-mcp`** — the same field removed from `WorkflowInputSchemaResult`. The `forge_get_workflow_input_schema` tool passes the response through unchanged, so its output no longer carries the key.

## Why the blob is gone rather than deprecated

Two representations of one contract meant every reader had to decide which one won, and a "canonical first, legacy fallback" bridge quietly turned an un-backfilled row into an empty contract. Removing the second representation removes that decision. `workflowInputSchema` is now the only thing stored, the only thing dispatch validates against, and the only thing returned — an empty array means "declares no inputs", and a version carrying no array at all is refused at dispatch with `workflowV2/contract-unmigrated` instead of silently launching with none.

Background: the typed array came first; a later clear-then-narrow change retired the blob.

## New: `{{workflow.<name>}}` interpolation in node literals

The same change added a second way for a node to read a launch argument. Wiring an input with `source: { workflowInput: "key" }` hands a node a whole slot fed by that argument. **Interpolation** puts the value *inside* a string instead — a `{{workflow.<name>}}` reference the orchestrator substitutes at dispatch.

The reference is honoured in three places: a node input's `literal` value, an agent node's `prompt` text, and a publish node's `message` text.

```json theme={null}
{
  "inputs": {
    "pageFilters": {
      "type": "array",
      "required": true,
      "literal": [{ "dimensionName": "Time", "memberIds": ["{{workflow.periodLabel}}"] }]
    }
  }
}
```

### Scope rules

`{{fieldName}}` and `{{inputs.fieldName}}` are node-scoped — the name must be a key in *that node's* resolved `inputs` — and are honoured only in an agent `prompt` or a publish `message`. `{{workflow.name}}` skips the node entirely and reads the run's launch arguments, so it needs no `inputs` entry, but the name must be declared on the workflow's input contract.

Inside a `literal`, `{{workflow.<name>}}` is the **only** form that resolves. A literal has no node-scoped resolver, so `{{inputs.x}}` and bare `{{x}}` are passed to the node verbatim.

Only `literal` bindings are interpolated. A value arriving through `source` or `workflowInput` is passed through untouched even when it contains `{{…}}` text, so run data cannot rewrite itself. Object *keys* are never scanned — only string values.

### Substitution keeps the type when the reference is the whole string

A literal that is exactly one reference — `"{{workflow.regions}}"` — is replaced by the **typed** value, so a `string[]` workflow input fills an array-typed slot as a real array. A reference embedded in surrounding text — `"FY{{workflow.year}}-Q{{workflow.qtr}}"` — is stringified and spliced.

### Failure behaviour differs by surface

An unresolvable reference in a `literal` throws and fails the node, naming the input. In an agent prompt or publish message, an unknown key renders as the empty string so operators never see `{{undefined}}` in a published message.

Two validator codes fire before publish:

| Code | Severity | Fires on |
| - | - | - |
| `WORKFLOW_REF_MISSING` | error | `{{workflow.x}}` where `x` is not a declared workflow input, or is optional with neither a `default` nor a `defaultExpr` |
| `LITERAL_TEMPLATE_UNRECOGNIZED` | warning | a literal containing any `{{…}}` that is not a valid `{{workflow.x}}` reference — typos, Handlebars blocks, bare `{{x}}`, and the prompt-only `{{inputs.x}}` spelling |

Give any interpolated input a value on every run — required, `derived`, or optional carrying a `default` / `defaultExpr`. Optional-with-no-default is **rejected at publish time**: the preflight wiring gate refuses a draft carrying any `severity: "error"` issue, and wiring errors are not overridable. That strictness is the point — the alternative is a graph that publishes clean and then throws only on the runs where the operator left the field blank, failing in production after passing its first test.

Full reference: [Reference a workflow input from inside a node](https://docs.gloo.com/forge/build/compose-a-workflow.md#reference-a-workflow-input-from-inside-a-node).

***

*See also: [Compose a Workflow](https://docs.gloo.com/forge/build/compose-a-workflow.md) | [getInputSchema](https://docs.gloo.com/forge/reference/http-api/workflows/getInputSchema.md) | [Workflows HTTP API](https://docs.gloo.com/forge/reference/http-api/workflows) | [Workflow Execution Flow](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md)*


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