← Back to blog

Tool Chaining API: Run Multi-Step Tool Pipelines in One Request

October 5, 2026 · Eric · 7 min read

Agent Media Tools ships dozens of small, single-purpose endpoints. Sometimes one call is not the shape you need: you want a UUID, then its base64 form, then a shareable URL for that string — in one round trip, with one response you can log. That is what POST /api/chain does. You send an array of steps, each step names a tool and its inputs, and any input can reference a field from an earlier step's response using a {{step.field}} placeholder.

There is no saved object to create first, no pipeline ID to manage, and no account required for the free tools. This guide covers the request contract, the exact tools the chain executor supports, the templating rules, failure behavior, and how the same feature behaves when a webhook triggers it. If you instead want named, reusable workflows with run history, that is the Pipeline Builder — the differences are covered near the end.

The request contract

One POST, one JSON body:

POST https://agentmediatools.com/api/chain
Content-Type: application/json

{
  "workflow": "release-notes-lite",
  "steps": [
    { "id": "ids", "tool": "uuid-generator", "input": { "count": "3" } }
  ]
}

The response gives you the whole run, not just the last value:

FieldMeaning
successtrue only if every step succeeded
chain_idGenerated id for this run (also prefixed onto each step id)
workflow, parent_idExactly what you sent, or null
total_steps, completedHow many steps you asked for and how many succeeded
failedtrue if any step failed
duration_msSum of the per-step durations
resultsObject keyed by your step id, with the tool response under data
traceOrdered array of step records: step, tool, success, duration_ms, data or error

A three-step chain with curl

This chain generates three UUIDs, base64-encodes them, then stores the result in a paste:

curl -s https://agentmediatools.com/api/chain \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "uuid-to-paste",
    "steps": [
      { "id": "ids",     "tool": "uuid-generator", "input": { "count": "3" } },
      { "id": "encoded", "tool": "base64",         "input": { "action": "encode", "text": "{{ids.uuids}}" } },
      { "id": "note",    "tool": "pastebin",       "input": { "title": "UUID batch", "content": "{{encoded.output}}" } }
    ]
  }'

The trimmed shape of a successful run (values abbreviated):

{
  "success": true,
  "chain_id": "ch_ab12cd34k9",
  "workflow": "uuid-to-paste",
  "total_steps": 3,
  "completed": 3,
  "failed": false,
  "results": {
    "ids":     { "step": "ids",     "tool": "uuid-generator", "success": true,
                 "data": { "success": true, "count": 3, "uuids": ["…","…","…"], "version": "v4" } },
    "encoded": { "step": "encoded", "tool": "base64", "success": true,
                 "data": { "success": true, "action": "encode", "output": "…" } },
    "note":    { "step": "note",    "tool": "pastebin", "success": true,
                 "data": { "success": true, "slug": "…", "url": "https://agentmediatools.com/p/…",
                           "raw_url": "https://agentmediatools.com/p/…/raw" } }
  },
  "trace": [ { "step_id": "ch_ab12cd34k9:ids", "step": "ids", "duration_ms": 1, "…": "…" } ]
}

Because pastebin returns url and raw_url, your client only needs to read results.note.data.url to get the final artifact link.

How {{step.field}} resolution works

The rules are deliberately small, and knowing them avoids most surprises:

That stop-on-failure behavior is intentional: chains are for short, dependent sequences where a broken middle step makes the rest meaningless. If you need branches or conditionals, use the Pipeline Builder instead (below).

Tools the chain executor supports

The chain runner is a fixed allowlist. Any other tool id returns HTTP 400 with {"code":"UNSUPPORTED_TOOL"} naming the offending step, so validate your step list before you ship it.

Step toolInput fields you can send
uuid-generatorcount (1–50), v7 for time-ordered UUIDs
password-generatorlength (1–128), symbols, numbers, uppercase
base64action (encode or decode), text
timestamp-convertervalue (unix seconds, or now)
unit-convertervalue, from, to, category
text-difftext1, text2
jwt-decodertoken
ip-lookupNo input; returns ip, city, region, country, isp, lat, lon
pastebincontent, title, syntax, expires_in_hours, is_public
short-urlurl, custom_slug
burn-notecontent, max_views, expires_in_hours
dead-dropcontent (or message), passphrase

Python example with requests

The same call from Python — three steps that look up the caller's IP, grab a timestamp, and diff the country code against a target value:

import requests

payload = {
    "workflow": "geo-check",
    "steps": [
        {"id": "ip",    "tool": "ip-lookup",           "input": {}},
        {"id": "stamp", "tool": "timestamp-converter", "input": {"value": "now"}},
        {"id": "diff",  "tool": "text-diff",           "input": {"text1": "{{ip.country}}", "text2": "US"}},
    ],
}

r = requests.post("https://agentmediatools.com/api/chain", json=payload, timeout=30)
r.raise_for_status()
run = r.json()

print(run["success"], run["completed"], "/", run["total_steps"], f'{run["duration_ms"]}ms')
for step in run["trace"]:
    print(step["step"], step["tool"], step["success"], step["duration_ms"])

if run["failed"]:
    # The failing step carries an error message; later steps did not run.
    for step in run["trace"]:
        if not step["success"]:
            raise SystemExit(f'{step["step"]} failed: {step["error"]}')

text-diff returns counts and arrays (added, removed, additions, deletions) rather than a rendered diff string, so it is best used as a gate: branch on added being zero instead of trying to print its output as prose.

Triggering a chain from a webhook

Chains can also run behind a webhook inbox. Configure the chain once for an inbox slug:

curl -s -X POST https://agentmediatools.com/hook/YOUR_INBOX_SLUG/chain \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "deploy-ping",
    "steps": [
      { "id": "log", "tool": "pastebin", "input": { "title": "{{header.x-event-type}}", "content": "{{payload.body}}" } }
    ]
  }'

Then every POST to /hook/YOUR_INBOX_SLUG fires that chain in the background. Inside step inputs you get payload placeholders in addition to the step placeholders:

GET /hook/{slug}/chain returns the stored configuration and DELETE /hook/{slug}/chain removes it. Webhook delivery itself is covered in Build a webhook inbox in 30 seconds.

Chaining vs. Pipeline Builder vs. MCP

Three overlapping features ship today, and picking the right one is mostly about whether the workflow needs to persist:

ApproachUse it when
POST /api/chainYou have the steps in hand and want one request and one response. Stateless, inline JSON, no account needed for the free tools this executor supports.
Pipeline Builder (/api/pipelines, /api/pipeline/run)You want a saved, named workflow with an owner, run history, and support for more step types including conditions. These routes require a signed-in session or an agent key, and only the owner can execute a pipeline.
MCP run_workflow_easyYou are inside an MCP client and want the same idea as a native tool call — up to 12 steps in order, with later steps referencing earlier results as $steps.STEP_ID.path.

In short: /api/chain is the imperative, one-shot form; the Pipeline Builder is the managed, reusable form; the MCP tool is the same operation surfaced to an agent host.

Limits and failure codes

Chain requests are ordinary API traffic. They are not credit-metered, and they count against the same free daily pool as the tools they call: 10 requests per day per anonymous IP, 25 per day for a signed-in free account, 25 per day for a free agent key, and 1,000 per day for a Pro key. When a pool is exhausted you get HTTP 429 with a machine-readable code such as ANON_DAILY_LIMIT, FREE_USER_DAILY_LIMIT, AGENT_FREE_DAILY_LIMIT, or AGENT_PAID_DAILY_LIMIT. Check current plans and limits before you build hard-coded retry logic on those numbers.

Other responses worth handling explicitly:

Try it in the Toolbox

Chain these tools in the browser, save the ones you reuse as a pipeline, or call them from your own code with the same endpoints.

Open toolbox