← Back to blog

Pipeline Presets API: One Call, Five Agent Recipes

October 14, 2026 · Eric · 7 min read

Most useful agent tasks are not one tool call. They are a small chain: fetch a page, extract the article, tidy the markdown, hand it to a model. Getting a batch of invoices into structured JSON is three or four steps. Captioning an image is a fetch plus a vision call. Every one of those chains is something you end up re-implementing in every agent you build.

Pipeline presets are productized versions of those chains. You pick a preset id, send one request, and get back a finished, structured result plus a step-by-step and an itemized billing record. There is no YAML DSL to learn and no orchestration service to stand up — the server runs the steps and tells you exactly what it charged for.

This post covers the two endpoints behind the feature, all five shipped presets, working curl and requests examples, the MCP tools, and the billing and limits you should know before wiring it into production.

The five presets that ship today

Presets are discovered at runtime, not from a static doc, so the list can grow without you changing code. At the time of writing, five are available:

Preset idWhat it doesInputs
url-markdownFetch a public article and return readable markdownurl
url-structuredFetch a page and map fields into JSON via CSS selectors or heuristicsurl, schema
pdf-markdownPDF text extraction → cleaned markdown for LLM contexturl or a PDF file upload
document-intakepdf-markdown plus heuristic structured fields (emails, amounts, dates)url or a PDF file upload
image-describeVision caption or visual question answering for a public image or uploadurl/image_url, optional prompt, task_type

If you only need one of the underlying tools — say a single PDF extraction with no intake fields — call that tool directly instead. The presets exist to remove glue code, not to replace the toolbox. (The standalone versions are covered in PDF Processing APIs, Structured Web Scraping, and Web Utility APIs.)

Step 1 — List the presets (no key needed)

The discovery endpoint is public. It returns the preset catalogue, the credit cost table for the nested tools, and the free daily allowances, so your agent can decide what a run will cost before it spends anything:

curl -s https://agentmediatools.com/api/pipeline-presets

The shape looks like this (trimmed):

{
  "success": true,
  "presets": [
    {
      "id": "url-markdown",
      "name": "Article URL → markdown",
      "description": "Readable article extract as markdown (uses article-extract; counts as a tool call).",
      "credits_note": "Free daily tool call (no flexible credits unless over shared daily limits).",
      "inputs": ["url"]
    },
    {
      "id": "document-intake",
      "name": "Document intake pack",
      "description": "PDF → markdown + heuristic structured fields (emails, amounts, dates).",
      "credits_note": "1 credit for pdf-to-markdown after free daily + free structured heuristics.",
      "inputs": ["pdf_url or pdf file"]
    }
  ],
  "credit_costs": {
    "describe-image": 2,
    "structured-scrape": 2,
    "pdf-to-markdown": 1,
    "pipeline-preset": 1
  },
  "free_daily": {
    "describe-image": 0,
    "structured-scrape": 3,
    "pdf-to-markdown": 5,
    "pipeline-preset": 5
  }
}

Two things worth internalizing from that response. First, the orchestration fee is its own small line item and is free for the first few runs each day. Second, describe-image has a free daily allowance of 0 — vision is always metered. Plan accordingly if your agent batch-captions.

Step 2 — Run a preset with curl

Everything goes through one endpoint. URL-based presets take JSON:

curl -s -X POST https://agentmediatools.com/api/pipeline-presets/run \
  -H "Authorization: Bearer $AMT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset":"url-markdown","url":"https://example.com/blog/post"}'

And you get back a normalized envelope — result, steps, and billing:

{
  "success": true,
  "preset": "url-markdown",
  "result": {
    "title": "Example post",
    "byline": "Jane Writer",
    "excerpt": "A short summary...",
    "markdown": "# Example post\n\nBody text as markdown...",
    "char_count": 8123
  },
  "steps": [{ "tool": "article-extract", "success": true }],
  "billing": { "orchestration": { "...": "..." }, "steps": [] }
}

File-based presets (pdf-markdown, document-intake, and image-describe with a local file) are multipart/form-data with the file in the file field:

curl -s -X POST https://agentmediatools.com/api/pipeline-presets/run \
  -H "Authorization: Bearer $AMT_API_KEY" \
  -F "preset=document-intake" \
  -F "file=@invoices/october.pdf"

That returns the markdown and the heuristic fields in one shot:

{
  "success": true,
  "preset": "document-intake",
  "result": {
    "markdown": "# Invoice\n\n...",
    "engine": "pdf-parse",
    "pages": 3,
    "structured": {
      "emails": ["billing@vendor.example"],
      "amounts": ["$1,240.00", "USD 89"],
      "dates": ["2026-10-01", "10/14/2026"]
    },
    "char_count": 4210
  },
  "steps": [
    { "tool": "pdf-to-markdown", "success": true },
    { "tool": "extract-structured", "success": true }
  ],
  "billing": { "orchestration": { "...": "..." }, "steps": [{ "...": "..." }] }
}

The structured block is deliberately conservative: unique email matches (up to 20), currency-looking amounts (up to 30), and date patterns (up to 20). The engine field reports which extractor ran — pdftotext or pdf-parse — and pages is only populated when the parser can report it. It is a triage layer for routing and validating, not a replacement for a real invoice parser. If you need typed fields with guaranteed presence, use url-structured with your own selectors, or pipe the markdown into your own extraction prompt.

Step 3 — URL + schema → JSON

url-structured is the preset for "I know which fields I want." Give it a lightweight schema; each property can carry a CSS selector, and anything without one falls back to heuristic field matching:

curl -s -X POST https://agentmediatools.com/api/pipeline-presets/run \
  -H "Authorization: Bearer $AMT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "url-structured",
    "url": "https://example.com/shop/widget",
    "schema": {
      "properties": {
        "name":  { "selector": "h1.product-title", "type": "string" },
        "price": { "selector": "span.price", "type": "string" },
        "in_stock": { "selector": ".stock-flag", "type": "string" }
      }
    }
  }'
{
  "success": true,
  "preset": "url-structured",
  "result": {
    "url": "https://example.com/shop/widget",
    "data": { "name": "Widget", "price": "$19", "in_stock": "In stock" }
  },
  "steps": [{ "tool": "structured-scrape", "success": true }],
  "billing": { "orchestration": { "...": "..." }, "steps": [{ "...": "..." }] }
}

Up to 40 properties are mapped per run. A string schema is accepted too — if you are passing schema as a JSON string it must parse, otherwise the request is rejected with schema must be valid JSON.

Step 4 — Vision in one hop

image-describe accepts a public image URL (or an upload) plus an optional prompt and a task_type of caption (default) or query:

curl -s -X POST https://agentmediatools.com/api/pipeline-presets/run \
  -H "Authorization: Bearer $AMT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset":"image-describe","image_url":"https://example.com/photo.jpg","task_type":"caption"}'
{
  "success": true,
  "preset": "image-describe",
  "result": {
    "description": "A golden retriever asleep on a wooden deck...",
    "task_type": "caption",
    "prompt": "Describe this image in detail.",
    "model": "moondream"
  },
  "steps": [{ "tool": "describe-image", "success": true }],
  "billing": { "orchestration": { "...": "..." }, "steps": [{ "...": "..." }] }
}

Custom prompts are capped at 500 characters and output tokens at 512. Use task_type: "query" with a specific prompt when you want an answer rather than a caption.

A Python helper for all five

A single function covers the whole family, which is the real payoff — one retry policy, one logging line, one place to read billing from your Python agent:

import os
import requests

BASE = "https://agentmediatools.com"
HEADERS = {"Authorization": "Bearer " + os.environ["AMT_API_KEY"]}

def run_preset(preset, *, url=None, schema=None, prompt=None,
               task_type=None, file_path=None):
    data = {"preset": preset}
    if url:
        data["url"] = url
    if schema:
        data["schema"] = schema
    if prompt:
        data["prompt"] = prompt
    if task_type:
        data["task_type"] = task_type

    files = None
    if file_path:
        files = {"file": open(file_path, "rb")}
    try:
        r = requests.post(f"{BASE}/api/pipeline-presets/run",
                          headers=HEADERS, data=data, files=files, timeout=180)
    finally:
        if files:
            files["file"].close()
    r.raise_for_status()
    payload = r.json()
    print(preset, "steps:", [s["tool"] for s in payload["steps"]])
    return payload["result"]

# Article → markdown
doc = run_preset("url-markdown", url="https://example.com/post")

# PDF → markdown + triage fields
intake = run_preset("document-intake", file_path="invoices/october.pdf")
print(intake["structured"]["amounts"])

Because presets accept either a URL or an upload, the same helper works for the "URL from a webhook" and "file from disk" cases your agent hits in production.

Same thing over MCP

If your agent speaks MCP, the presets are first-class tools on the hosted server at /api/mcp (same bearer agent key). list_pipeline_presets takes no arguments and returns the catalogue; run_pipeline_preset takes preset, plus url, schema, prompt, and task_type as needed:

{
  "name": "run_pipeline_preset",
  "arguments": {
    "preset": "document-intake",
    "url": "https://example.com/statement.pdf"
  }
}

An MCP client gets the same JSON envelope back, including steps and billing. Connection setup is covered in Connect Claude to Agent Media Tools in 5 Minutes.

Billing, limits, and error handling

Three rules cover almost everything:

Input handling is strict and worth knowing before you point this at a user-supplied URL. Only public http/https URLs are accepted; localhost, private address ranges, and embedded URL credentials are refused. Redirects are followed with a cap, the preset fetchers time out at 25 seconds, and pages are capped at 2 MB of HTML. Those are the same public-network guards that back the toolbox generally, which is one reason to route agent URL fetching through the API instead of raw fetching in your runtime.

Error responses are flat and list the valid options, which makes self-repair easy for an agent:

StatusWhenBody highlights
400preset missingpreset required + full presets array
404Unknown preset idUnknown preset: ... + valid presets
400url-structured without url/schema, or bad schema stringurl and schema required for url-structured / schema must be valid JSON
400File-based preset with no url and no filepdf file or url required / image file or url required
402Out of free daily allowance and flexible creditserror + billing detail

When a preset is the wrong tool

Presets trade flexibility for a single call, so be honest about the boundary. If you need to inspect intermediate output, branch conditionally mid-chain, or chain more than a handful of steps, use the underlying endpoints or the pipeline builder instead — presets are fixed recipes, not a general workflow engine. If you need a genuinely custom multi-step chain with your own logic between steps, the pipeline builder and the MCP run_workflow_easy tool are the right level of abstraction.

For the common four chains — article to markdown, PDF to markdown, PDF to triage fields, URL to typed JSON, and image to text — a preset is one request, one response, one billing line. That is the whole point.

Run presets in the browser or from your agent

Try the presets in the toolbox, or call them from your agent with an API key.

Open toolbox Preset API page