Build a chain

Background: Chain.

Start one

Create a chain from the navigator’s Chains section. It is written to .tinspec/chains/<name>.yaml and committed like everything else.

Two views of the same chain:

Steps — an ordered list of cards. Use this for the common linear case.
Graph — the full canvas. Use this when the flow genuinely branches.

Add steps

Add step opens the request picker: any saved request, any spec endpoint, or an inline copy you can edit inside the chain without touching the original.

Use a reference when the request is shared and should stay in sync. Use inline when the step needs chain-specific tweaks.

Only HTTP, GraphQL, and unary gRPC can be steps. WebSocket and streaming gRPC are shown disabled — a chain step expects exactly one response, which a duplex session does not produce.

Extract values

Run the step once, then click a field in the JSON response. That creates an extraction:

extract:
  - var: userId
    from: body
    path: data.id

from is body (dotted path), header (header name as path), or status.

Downstream, use {{userId}} anywhere — the next step’s URL, body, or headers. In both the Steps cards and the Graph inspector, the variable chips insert the placeholder at your cursor rather than making you type it.

Branch and loop

condition — an expression with true and false handles.
router — ordered rules, first match wins, one handle each. A rule with an empty expression always matches, so put it last as the default.
loop — iterate a count or a list variable, with body and done handles.
split / merge — fan out and join.
delay — wait.

Data nodes (input, environment, math, transform, generator, set, aggregate) shape values between requests without needing a script. generator produces a uuid, random int, random string, timestamp, sequence, or list value.

For anything genuinely custom, a script node runs JavaScript in the sandboxed runtime; the keys of the object it returns become output variables.

Assert inside the chain

An assert node validates status, body, header, or a variable and routes to a pass or fail branch — so a chain can check its own intermediate state and take a different path rather than merely failing.

It uses the same assertion vocabulary as request tests; see Test a response.

Run it

Three ways:

Run all.
Run to here — everything up to and including one node.
Test this node — just one, using the variables currently in scope.

Events stream live while it runs. Nodes carry a status ring (running / done / skipped / error), the activated branch animates, pruned branches fade, and the bottom dock tabs between the event log and the current variables. The final snapshot records which nodes were skipped or pruned and which assertion failed.

Validation catches the usual mistakes

As you author, Tinspec checks for missing request references, variables consumed but never produced, extraction paths that do not exist in the spec’s documented 2xx response, non-chainable protocols, and dangling edges. Problems show on the step; errors disable Run.

Cookies and auth

The shared cookie jar is inherited, so a login that sets a session cookie is followed by calls that carry it with zero configuration. A step that references a saved request carries that request’s auth provider and sender.

Attach it as a pre-run

The payoff: set a chain as a request’s pre-run chain (the Chain tab in the request editor). The chain runs first, its outputs merge into the environment, then the request goes. Authenticate-then-call becomes one ⌘↵.

Let Tinspec plan it

For an endpoint whose body requires ids you do not have, use Build prerequisites… — from the Docs send menu, the Form toolbar, the navigator’s context menu, or the command palette.

It reads the spec for required *Id body fields and path parameters, finds the POST that produces each by matching resource stems, recurses, and groups independent steps. It prefers to reference saved requests you already have and generates a step only where nothing matches. Bodies are filled from your successful sends where available, otherwise from the spec’s examples.

You see the planned steps, the reasoning, and anything unresolved before it creates the chain and sets it as the endpoint’s pre-run.

Troubleshooting

unresolved variable {{x}} in body (chain node 'n') — a step consumes a variable nothing produced. The validator flags this before you run; check the producing step’s extraction ran and spelled the name the same way.

A step is disabled in the picker. It is WebSocket or a streaming gRPC method. Not chainable — see above.

Extraction path flagged as invalid. The dotted path does not appear in the spec’s documented 2xx response for that endpoint. Either the path is wrong or the spec is behind; check Spec Changes.