API reference

Quickstart

Create a key on your dashboard, then merge two PDFs:

$ export PAPERPIPE_KEY=pp_YOUR_KEY
$ curl https://paperpipe.amaryx.com/api/v1/merge \
    -H "Authorization: Bearer $PAPERPIPE_KEY" \
    -F file=@q3-invoice-0412.pdf \
    -F file=@signed-lease.pdf \
    -o merged.pdf

The response body is the file. If something goes wrong you get JSON instead, see Errors.

Authentication

Send your API key as a bearer token on every request:

Authorization: Bearer pp_YOUR_KEY

Keys start with pp_. Create and delete them on the dashboard, up to 10 per account. A key is shown once when you create it and we keep only a hash, so store it somewhere safe. Keys can only be created once your email address is confirmed.

The dashboard itself calls the same endpoints with your login session instead of a key.

Operations

Every operation is POST /api/v1/{op} with a multipart/form-data body. Send input files as repeated file parts, in order. Send options as plain form fields. A successful response is the result file. Each operation costs 1 operation of your quota, except office-to-pdf, which costs 5. Failed calls cost nothing.

merge

Combines two or more PDFs into one, in the order you send them. No options.

$ curl https://paperpipe.amaryx.com/api/v1/merge \
    -H "Authorization: Bearer $PAPERPIPE_KEY" \
    -F file=@cover-letter.pdf \
    -F file=@q3-invoice-0412.pdf \
    -F file=@signed-lease.pdf \
    -o merged.pdf

split

Splits one PDF into several and returns them as a ZIP. Give either ranges or every, not both.

$ curl https://paperpipe.amaryx.com/api/v1/split \
    -H "Authorization: Bearer $PAPERPIPE_KEY" \
    -F file=@board-pack-2026-q3.pdf \
    -F ranges="1-3,5,7-" \
    -o board-pack-parts.zip

organize

Reorders, deletes and rotates pages of one PDF.

$ curl https://paperpipe.amaryx.com/api/v1/organize \
    -H "Authorization: Bearer $PAPERPIPE_KEY" \
    -F file=@scan-0007.pdf \
    -F pages="3,1,2,4-6" \
    -F rotate="1:90" \
    -o scan-0007-fixed.pdf

compress

Makes one PDF smaller.

$ curl https://paperpipe.amaryx.com/api/v1/compress \
    -H "Authorization: Bearer $PAPERPIPE_KEY" \
    -F file=@site-survey-photos.pdf \
    -F level=balanced \
    -o site-survey-photos-small.pdf

images-to-pdf

Turns JPG, PNG, WebP and TIFF images into one PDF, one image per page, in the order you send them.

$ curl https://paperpipe.amaryx.com/api/v1/images-to-pdf \
    -H "Authorization: Bearer $PAPERPIPE_KEY" \
    -F file=@kitchen-before.jpg \
    -F file=@kitchen-after.jpg \
    -F page_size=a4 \
    -F margin_mm=10 \
    -o kitchen.pdf

pdf-to-images

Renders pages of one PDF as images. The response is a single image when the result has one page and a ZIP when it has more.

$ curl https://paperpipe.amaryx.com/api/v1/pdf-to-images \
    -H "Authorization: Bearer $PAPERPIPE_KEY" \
    -F file=@brochure-spring.pdf \
    -F format=jpg \
    -F dpi=200 \
    -F pages="1-2" \
    -o brochure-pages.zip

office-to-pdf

Converts one document to PDF. Supported types: doc, docx, xls, xlsx, ppt, pptx, odt, ods, odp, rtf, csv and txt. No options. This operation costs 5 because it runs a full office suite.

$ curl https://paperpipe.amaryx.com/api/v1/office-to-pdf \
    -H "Authorization: Bearer $PAPERPIPE_KEY" \
    -F file=@service-agreement-v3.docx \
    -o service-agreement-v3.pdf

Usage

Returns how many operations you have used this month. It does not count against your quota.

$ curl https://paperpipe.amaryx.com/api/v1/usage \
    -H "Authorization: Bearer $PAPERPIPE_KEY"
{"used": 118, "quota": 1000, "resets_at": "2026-11-01T00:00:00Z"}

Errors

Errors are JSON with the same two fields everywhere. error is written for people, so you can show it as it is. code is stable, so you can branch on it.

{
  "error": "You've used this month's 250 operations. Upgrade at https://paperpipe.amaryx.com/#account for more.",
  "code": "quota_exceeded"
}

Limits and quotas

Prices are in euros and include VAT. Request size is the total of all files in one request. Quotas reset on the 1st of each month (UTC). Every operation costs 1, except office-to-pdf at 5, and failed calls are free.

MCP

paperpipe is a remote MCP server over Streamable HTTP, so an agent can use the operations as tools. It takes the same Authorization: Bearer pp_... key as the REST API.

Claude Code

$ claude mcp add --transport http paperpipe https://paperpipe.amaryx.com/mcp \
    --header "Authorization: Bearer pp_YOUR_KEY"

Cursor

Add this to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "paperpipe": {
      "url": "https://paperpipe.amaryx.com/mcp",
      "headers": { "Authorization": "Bearer pp_YOUR_KEY" }
    }
  }
}

Other clients

Any client that supports Streamable HTTP can connect with the url and headers shown above. The key is sent in the Authorization header. Check your client's documentation for where it keeps its MCP server list.

Tools

Every tool takes a files list. Each item is {"url": "https://..."} for a public URL, or {"base64": "...", "filename": "signed-lease.pdf"} for content you hold. Options are the same as the REST fields and are passed as strings.

A tool does not return the file itself. It returns a download link that is valid for 1 hour, as text and as an MCP resource link. After that the file is deleted and the link answers 404 expired.

{
  "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": {
    "name": "merge_pdfs",
    "arguments": {
      "files": [
        { "url": "https://files.northgate.example/q3-invoice-0412.pdf" },
        { "base64": "JVBERi0xLjcK...", "filename": "signed-lease.pdf" }
      ]
    }
  }
}

Tool errors are returned with isError: true and the same human-readable message the REST API gives in error.

Data handling

Uploaded files are processed and deleted right away. They are not stored. Results made through MCP are kept for 1 hour so the agent can download them, then deleted.

paperpipe stores account data, API key hashes and a usage log of operation, size and time. The log holds no file names or content. It is hosted in Germany (Hetzner) and run by Amaryx, a one-person studio in Espoo, Finland. See the privacy policy and terms.