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.
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" } }
]
}
steps (required) — an ordered array. Each entry has an id (used for templating and for keying results), a tool id, and an input object of that tool's parameters.workflow (optional) — a free-form label echoed back in the response, useful when you log many chains.parent_id (optional) — a correlation id, also echoed back. It is there so a caller that fires chains on behalf of something else can tie results together.The response gives you the whole run, not just the last value:
| Field | Meaning |
|---|---|
success | true only if every step succeeded |
chain_id | Generated id for this run (also prefixed onto each step id) |
workflow, parent_id | Exactly what you sent, or null |
total_steps, completed | How many steps you asked for and how many succeeded |
failed | true if any step failed |
duration_ms | Sum of the per-step durations |
results | Object keyed by your step id, with the tool response under data |
trace | Ordered array of step records: step, tool, success, duration_ms, data or error |
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.
The rules are deliberately small, and knowing them avoids most surprises:
"{{ids.uuids}}" is substituted; a number or boolean is passed through untouched.results.<id>.data.{{ids.uuids}} becomes one comma-joined string, which is exactly what you want when feeding a text field like base64.text.Step 'missing' not found in chain results.failed becomes true, and completed tells you how far you got. The trace shows the error on the step that broke.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).
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 tool | Input fields you can send |
|---|---|
uuid-generator | count (1–50), v7 for time-ordered UUIDs |
password-generator | length (1–128), symbols, numbers, uppercase |
base64 | action (encode or decode), text |
timestamp-converter | value (unix seconds, or now) |
unit-converter | value, from, to, category |
text-diff | text1, text2 |
jwt-decoder | token |
ip-lookup | No input; returns ip, city, region, country, isp, lat, lon |
pastebin | content, title, syntax, expires_in_hours, is_public |
short-url | url, custom_slug |
burn-note | content, max_views, expires_in_hours |
dead-drop | content (or message), passphrase |
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.
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:
{{payload.field}} — a field from the incoming JSON body{{header.field}} — a request header value{{timestamp}} and {{slug}} — generated values you can use for titles and namesGET /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.
Three overlapping features ship today, and picking the right one is mostly about whether the workflow needs to persist:
| Approach | Use it when |
|---|---|
POST /api/chain | You 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_easy | You 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.
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:
INVALID_INPUT — steps was missing, empty, or not an array.UNSUPPORTED_TOOL — a step named a tool outside the executor's allowlist. The response identifies the step."failed": true — the chain itself ran but a step failed. This is the case to branch on; do not treat a 200 as success.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