# cputools — Full reference

_Compiled 2026-06-18. Source pages tagged for: cputools._

## /docs/cputools-overview

# cputools

The CPU work your agent shouldn't host itself. One call, fractions of a cent, no server to babysit.

```bash
curl -X POST https://api.relaystation.ai/v1/pdf/merge \
  -H 'X-Payment: <base64 EIP-3009 auth>' \
  -H 'Idempotency-Key: merge-invoices-20260605' \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"inline":"<base64 pdf>"},{"inline":"<base64 pdf>"}]}'
```

## What it is

cputools is a pay-per-call utility API by Relaystation. The suite is **86 operations across nine categories** — plus a **pipeline runtime** that composes them — behind one endpoint: PDF (19 ops, incl. encrypt/decrypt/compress/render/OCR, **HTML→PDF generation**, **Office→PDF conversion** (docx/xlsx/pptx → PDF), and extract-images/diff/bookmarks/attachments), CSV (convert/dedupe/select), image (13 ops: resize/convert/compress/rotate/metadata/crop/blur/sharpen/grayscale/exif-strip/dominant-color/composite/contact-sheet), codes (qr/barcode generate + qr-decode + color-convert), utils (hash/hmac/base64/uuid/jwt-decode/jwt-verify), generate (og-image/mock-data/invoice/chart/qr-logo/favicon/placeholder/identicon), archive (zip/unzip/gzip), **data** — the ETL transform layer: filter, sort, group-by, join, union, profile, cast, pivot, schema-infer, validate, diff, derive, fillna, dropna, rename, slice, explode, sample, **Excel in/out** (from-xlsx/to-xlsx), and **sql** (full SQL over your file on a sandboxed DuckDB) — and **text** (case/slugify/diff/count/regex-extract/template/markdown-to-html/html-to-text/sanitize-html). Your agent sends a file and an x402 payment, gets back a result, and never created an account. Pay per call with x402 or top up with a card via Stripe — one Relaystation balance funds cputools and every other Relaystation product. No subscription, no minimum.

These are the tools you could self-host — they're built on open-source [pdf-lib](https://pdf-lib.js.org/), [pdf.js](https://mozilla.github.io/pdf.js/), [qpdf](https://qpdf.sourceforge.io/), [poppler](https://poppler.freedesktop.org/), [Tesseract](https://tesseract-ocr.github.io/), [Papaparse](https://www.papaparse.com/), [sharp](https://sharp.pixelplumbing.com/), [jose](https://github.com/panva/jose), [satori](https://github.com/vercel/satori), [faker](https://fakerjs.dev/), [fflate](https://github.com/101arrowz/fflate), [DuckDB](https://duckdb.org/), and [LibreOffice](https://www.libreoffice.org/) (via [Gotenberg](https://gotenberg.dev/)), plus Node's built-in `crypto`. We just run them so you don't have to: no Lambda layer to wrangle, no native binary to compile into your image, no cold-start tax on your own infrastructure. One HTTPS call, a result back, done.

cputools is now a **transform platform**, not just a catalog: the data category and the pipeline runtime compose into ETL chains in a single call. Document rendering is live at both ends — HTML→PDF (Chromium) and Office→PDF (LibreOffice) — and media tenants are the next frontier.

## The lodestone

The whole product is one HTTPS call:

1. Your agent `POST`s to `https://api.relaystation.ai/v1/<category>/<op>` with the tool's payload.
2. The payload carries the file inline (base64, ≤ 4 MB) — or a storage reference (`{"inputKey":"..."}`) for larger files.
3. An `X-Payment` header carries the x402 (EIP-3009) authorization; an `Idempotency-Key` header makes the call safe to retry.
4. cputools runs the transform and returns a JSON envelope: the result inline (base64) when small, or `{ outputKey, outputUrl }` (a presigned GET) when large.

No account, no signup step, no deposit-then-withdraw. The wallet that signs the payment is the identity, so your transaction history is there if you come back. Or use a `Bearer rs_live_*` API key if you'd rather fund from a prepaid balance.

An `outputKey` chains: pass it as the next op's `inputKey` and run multi-step transforms without re-uploading — the full I/O model (inline / scratch / baton) is the canonical [Passing & receiving files](/docs/receiving-outputs) page.

## The tools, one endpoint

| Category | Ops | Billing | Reference |
|---|---|---|---|
| **PDF** | merge, split, rotate, pages, watermark, form, extract-text, metadata, encrypt, decrypt, compress, render, OCR, from-html, from-office, images, diff, bookmarks, attachments (19) | per page (from-html/from-office + metadata/bookmarks/attachments flat) | [PDF tools →](/docs/pdf-tools) |
| **CSV** | convert, dedupe, select (3) | per MB | [CSV tools →](/docs/csv-tools) |
| **Image** | resize, convert, compress, rotate, metadata, crop, blur, sharpen, grayscale, exif-strip, dominant-color, composite, contact-sheet (13) | per megapixel (metadata/dominant-color flat) | [Image tools →](/docs/image-tools) |
| **Codes** | QR, barcode, qr-decode, color-convert (4) | flat | [QR & barcode →](/docs/qr-tools) |
| **Utils** | hash, hmac, base64, uuid, jwt-decode, jwt-verify (6) | per MB (uuid/jwt flat) | [Utils tools →](/docs/utils-tools) |
| **Generate** | og-image, mock-data, invoice, chart, qr-logo, favicon, placeholder, identicon (8) | flat | [Generate tools →](/docs/generate-tools) |
| **Archive** | zip, unzip, gzip (3) | per MB (input) | [Archive tools →](/docs/archive-tools) |
| **Data** | filter, sort, groupby, join, union, profile, cast, pivot, schema-infer, validate, diff, derive, fillna, dropna, rename, slice, explode, **Excel** from-xlsx/to-xlsx (19); **sql** (sandboxed DuckDB) | per MB (sql tier higher) | [Data tools →](/docs/data-tools) · [SQL →](/docs/data-sql) |
| **Pipeline** | run — compose a chain of transforms in one call | sum of the steps | [Pipeline →](/docs/pipeline) |

Send a file inline (base64, ≤ 4 MB) or by storage reference for larger files (≤ 50 MB); get the result back the same way. A small per-MB egress surcharge applies only to storage-ref outputs (the >4 MB path). The heavy ops (encrypt/decrypt/compress/render/OCR, data **sql**, **HTML→PDF**, and **Office→PDF**) run vendored qpdf, poppler, Tesseract, DuckDB, headless Chromium, and LibreOffice on dedicated engines — same request shape, same per-call billing.

## Pricing

From $0.0002 per call. No subscription, no minimum, no commitment. Pay per call with x402, or top up with a card via Stripe — one Relaystation balance funds cputools and every other Relaystation product. [See full pricing →](/pricing)

## Built on a substrate

The whole suite rides one chassis: payment, idempotency, the inline-vs-storage-ref I/O convention, per-page/per-MB/per-megapixel metering, and the compute-worker pattern were paid for once. Adding a new tool on top is small and bounded — a new operation in an existing category is a few dozen lines of glue; a whole new category is a single in-process module plus its pricing rows. The utils, generate, and archive categories (eleven ops) landed as ~530 and ~440 lines of route code with the shared substrate left byte-identical; the data category added zero dependencies; the `data/sql` engine was DuckDB dropped into the same worker tier as a single vendored binary (no Docker), and the pipeline runtime reused the existing transforms verbatim. That's why the catalog went from 8 PDF ops to 86 across nine categories — plus a composable runtime, HTML→PDF generation, and Office→PDF conversion (LibreOffice via Gotenberg, the first HTTP-upstream engine) — without a rewrite, and why the next tier — media — is an engine-drop away rather than a re-architecture.

## Why pay-per-call wins here

Every PDF-API incumbent except one gates behind a monthly minimum or a credit catalog you have to pre-commit to. cputools is the one an agent can call once, pay a fraction of a cent, and leave — and we undercut even the closest pay-per-call peer by roughly 10×. Compute for in-process PDF ops is nearly free, so the price is a positioning number, not a cost-recovery exercise: dramatically under the incumbents, but still real money, never a subsidized loss-leader. The only real variable cost is egress on large outputs, which is why a small per-MB surcharge rides the storage-ref path and nothing else.

## Next

[PDF tools](/docs/pdf-tools) · [Office tools](/docs/office) · [CSV tools](/docs/csv-tools) · [Image tools](/docs/image-tools) · [QR & barcode](/docs/qr-tools) · [Utils tools](/docs/utils-tools) · [Generate tools](/docs/generate-tools) · [Archive tools](/docs/archive-tools) · [Data tools](/docs/data-tools) · [Data — SQL](/docs/data-sql) · [Pipeline](/docs/pipeline) · [MCP tools](/docs/cputools-mcp-tools) · [Pricing](/pricing) · [API reference](/api-reference) · [x402 wire format](https://relaystation.ai/docs/x402) · [Authentication](https://relaystation.ai/docs/authentication)

## /docs/pdf-tools

# PDF tools

Twenty-one PDF operations, one endpoint, one uniform request/response shape. Every op is a `POST https://api.relaystation.ai/v1/pdf/<op>`. The pure-PDF ops (merge … metadata, images, diff, bookmarks, attachments) run in-process on pdf-lib / pdf.js; the heavier ops run on dedicated engines — encrypt, compress, repair, render, OCR, ocr-searchable, and verify-signatures on vendored **qpdf**, **poppler** (including `pdfsig`), and **Tesseract**; **from-html (HTML→PDF) on a vendored headless Chromium**; and **from-office (Office→PDF) on LibreOffice (Gotenberg)** — same request shape, same per-call billing. `from-html` **generates** a PDF from scratch (an invoice, a report, a certificate); `from-office` **converts** an existing office document (docx, xlsx, pptx, …) into one.

## Inputs and outputs — the uniform shape

Every op takes its file (or files) as an **input source** and returns a uniform **output envelope**. You never stream a raw file; the body is always JSON.

**Input source** — one of two shapes per file field:

```json
{ "inline": "<base64-encoded PDF>" }          // for files ≤ 4 MB
{ "inputKey": "<scratch object key>" }         // for larger files
```

For files above the 4 MB inline ceiling, mint a one-time presigned upload first:

```bash
curl -X POST https://api.relaystation.ai/v1/cputools/upload-url \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Content-Type: application/json' \
  -d '{"ext":"pdf","contentType":"application/pdf"}'
# → { "url": "...", "fields": { ... }, "inputKey": "...", "expiresAt": "...", "maxBytes": 52428800 }
```

Then upload with a **multipart/form-data `POST` to `url`** — include every entry from `fields` as a form field, then a `file` field carrying the bytes (the standard S3 presigned-POST form). Finally pass `{"inputKey":"..."}` as the file to the op route. The presigned POST is customer-scoped, short-lived, and size-capped at `maxBytes` (S3 rejects an oversized body at upload time). An x402 lodestone wallet can mint one too — minting is free; only the op that consumes the bytes bills.

**Output envelope** — always JSON, under an `output` key:

```json
{
  "output": {
    "inline": "<base64>",            // present when the result ≤ 4 MB
    "outputKey": "...",              // present when the result > 4 MB
    "outputUrl": "https://...",      // presigned GET for the scratch key
    "sizeBytes": 12345,
    "contentType": "application/pdf",
    "filename": "merged.pdf"
  }
}
```

The inline-vs-reference threshold is operator-tunable (`cputools.io.max_inline_bytes`, default 4 MB). Results at or under it come back inline; larger results are written to a scratch key and returned as a presigned `outputUrl`. The full inline / scratch / baton model — and recipes for downloading or chaining outputs — is in [Passing & receiving files](/docs/receiving-outputs).

## Billing

Per-page ops bill the page count × the per-page rate, **minimum one page**. `metadata` is a flat per-call charge. The per-op rates are operator-tunable (`cputools.price.pdf.<op>.per_page_micros`); the launch defaults:

| Op | Billed on | Rate |
|---|---|---|
| `merge` | output pages | $0.001 / page |
| `split` | source pages | $0.001 / page |
| `rotate` | result pages | $0.001 / page |
| `pages` | result pages | $0.001 / page |
| `watermark` | pages stamped | $0.001 / page |
| `form` | pages | $0.001 / page |
| `extract-text` | source pages | $0.002 / page |
| `metadata` | per call | $0.001 flat |
| `encrypt` | pages | $0.001 / page |
| `compress` | pages | $0.001 / page |
| `repair` | pages | $0.001 / page |
| `render` | output pages | $0.001 / page |
| `ocr` | source pages | $0.003 / page |
| `ocr-searchable` | source pages | $0.004 / page |
| `verify-signatures` | per call | $0.001 flat |
| `from-html` | per call | $0.003 flat |
| `from-office` | per call | $0.005 flat |
| `images` | pages scanned | $0.001 / page |
| `diff` | combined pages of both inputs | $0.001 / page |
| `bookmarks` | per call | $0.001 flat |
| `attachments` | per call | $0.001 flat |

These are launch defaults; the live `402` challenge is authoritative (an unauthenticated `POST` returns the exact price). Every billable call needs an `Idempotency-Key` header — omit it and the chassis generates one per call.

## merge

Combine 2–50 PDFs into one, in the order given.

```json
POST /v1/pdf/merge
{ "files": [ {"inline":"<b64>"}, {"inputKey":"..."} ], "filename": "combined.pdf" }
```

## split

Split one PDF by 1-based ranges (`"1-3,5,8-10"`) into separate documents, or `burst: true` to explode every page into its own single-page PDF. Omit `ranges` (or pass `"all"`) for the whole document.

```json
POST /v1/pdf/split
{ "file": {"inline":"<b64>"}, "ranges": "1-3,7-9" }
```

Split produces multiple files, so it returns a **manifest** (not the single output envelope): each entry is a storage reference you can re-submit as an `inputKey` to another op.

```json
{ "files": [ {"index": 0, "outputKey": "...", "outputUrl": "https://...", "pages": 3, "sizeBytes": 12345} ] }
```

## rotate

Rotate pages by 90 / 180 / 270 degrees. `pages` is an optional 1-based range string; omit it to rotate every page.

```json
POST /v1/pdf/rotate
{ "file": {"inline":"<b64>"}, "degrees": "90", "pages": "1,3-5" }
```

## pages

Edit page structure. One of three actions:

- `delete` — drop a range of pages: `{"action":"delete","file":{...},"pages":"2,4-6"}`
- `reorder` — supply the new 1-based page order: `{"action":"reorder","file":{...},"order":[3,1,2]}`
- `insert` — splice another PDF in at a 1-based position (`at: 1` inserts before the first page; `at: N+1` appends): `{"action":"insert","file":{...},"insert":{...},"at":2}`

## watermark

Stamp text on every page (or a `pages` range). Tune `opacity` (0–1), `size` (pt, ≤ 400), `color` (`#RRGGBB`), and `position` (`center` | `top-left` | `top-right` | `bottom-left` | `bottom-right`).

```json
POST /v1/pdf/watermark
{ "file": {"inline":"<b64>"}, "text": "CONFIDENTIAL", "opacity": 0.2, "position": "center" }
```

## form

Fill or flatten an AcroForm. Pass `fields` as a map of field name → string or boolean (checkbox); set `flatten: true` to bake the values in so the form is no longer editable.

```json
POST /v1/pdf/form
{ "file": {"inline":"<b64>"}, "fields": {"name":"Ada Lovelace","subscribe":true}, "flatten": true }
```

## extract-text

Pull text + structure out of a PDF (engine: pdf.js / unpdf). Returns per-page text plus the concatenated whole. `pages` is an optional 1-based range string.

```json
POST /v1/pdf/extract-text
{ "file": {"inline":"<b64>"}, "pages": "1-5" }
```

Response (not an output envelope — this op returns parsed text directly):

```json
{ "totalPages": 12, "pages": [ {"page": 1, "text": "..."} ], "text": "..." }
```

## metadata

Read document metadata, or set any of `title`, `author`, `subject`, `keywords`, `creator`, `producer`. Read by omitting `set`; write by passing it. Flat per-call price. A read returns `{ "metadata": { ... } }`; a write returns the standard output envelope with the updated PDF.

```json
POST /v1/pdf/metadata
{ "file": {"inline":"<b64>"}, "set": {"title":"Q3 Report","author":"finance-bot"} }
```

## encrypt

Password-protect a PDF (qpdf, 256-bit AES). Supply `userPassword` (the open password), `ownerPassword` (permissions password), or both — at least one. Neither may begin with `-`. Supplying only an `ownerPassword` leaves the open password empty: anyone can open the document, but permissions stay owner-gated (the standard PDF model).

Eight optional **permission booleans** — the canonical PDF permission set — restrict what an opened document allows: `print`, `printHighRes`, `copy` (text/graphics extraction), `modify`, `annotate`, `fillForms` (fill in form fields), `extract` (extract for accessibility), and `assemble` (insert/delete/rotate pages). An **absent** boolean means the qpdf default (allowed); pass `false` to restrict. Permissions are enforced by PDF viewers against the owner password.

Two notes on the set: `print` and `printHighRes` fold into one print level — `print:false` blocks printing entirely, `print:true` with `printHighRes:false` allows only low-resolution printing, and `print:true` alone allows full-quality printing. And `copy` is the live text/graphics extraction control; `extract` is the separate *accessibility*-extraction bit, which PDF 2.0 (the 256-bit encryption used here) deprecated and always grants — so `extract:false` may be a no-op on modern viewers. Use `copy:false` to actually block extraction.

```json
POST /v1/pdf/encrypt
{ "file": {"inline":"<b64>"}, "userPassword": "hunter2", "ownerPassword": "admin-only",
  "print": true, "printHighRes": false, "copy": false, "modify": false,
  "annotate": false, "fillForms": true, "assemble": false }
```

Passwords ride only in the request body to the IAM-gated worker — they're never logged.

## compress

Recompress a PDF's object and content streams (qpdf). Billed **per page, not by savings** — the compression ratio depends entirely on the document (an already-optimized PDF may not shrink). Set `linearize: true` for web "fast view" (byte-range streaming).

```json
POST /v1/pdf/compress
{ "file": {"inline":"<b64>"}, "linearize": true }
```

Looking for a "linearize" / web-optimize op? It's this flag — `linearize: true` on compress IS the linearization path (there is no separate `pdf/linearize` op).

## repair

Repair a damaged PDF (qpdf). Two steps in one call: `qpdf --check` **diagnoses** the document (a findings report — broken xref, stream-length mismatches, structural warnings), then a full **rewrite** re-serializes it, reconstructing the cross-reference table and normalizing structure. Billed per page (compress's rate). Returns the repaired PDF **always as a storage ref** plus the diagnosis:

```json
POST /v1/pdf/repair
{ "file": {"inline":"<b64>"} }
```

```json
{ "output": { "outputKey": "...", "outputUrl": "https://...", "sizeBytes": 51234, "contentType": "application/pdf", "filename": "repaired.pdf" },
  "repair": { "exitCode": 2, "findings": ["xref not found", "Attempting to reconstruct cross-reference table", "..."] } }
```

`repair.exitCode` is qpdf's `--check` verdict: `0` clean, `2` errors found, `3` warnings — all three still produce a rewritten output. A PDF too damaged to parse at all returns `422 PDF_PARSE_FAILED` (charge reversed).

## render

Rasterize PDF pages to PNG or JPEG (poppler `pdftoppm`). `pages` is an optional 1-based range (default: all); `dpi` ≤ 300 (default 150); `format` is `png` or `jpeg`. Non-embedded standard-14 fonts (Helvetica, Times, …) render correctly via a vendored DejaVu Sans substitution. **Capped at 40 pages and 300 DPI** — over either returns `422` pre-charge. Billed per **output** page.

```json
POST /v1/pdf/render
{ "file": {"inline":"<b64>"}, "pages": "1-5", "dpi": 200, "format": "png" }
```

Render produces multiple images, so it returns a **manifest** (like split), one presigned-GET image ref per page:

```json
{ "images": [ {"index": 0, "page": 1, "outputKey": "...", "outputUrl": "https://..."} ] }
```

## ocr

Extract text from a scanned/image PDF (poppler `pdftoppm` → Tesseract LSTM). `pages` is an optional 1-based range (default: all). **Synchronous and capped at 5 pages** — the call must clear a ~30-second window, so larger asynchronous OCR jobs are coming. Over the cap returns `422 OCR_TOO_MANY_PAGES_SYNC` (which advertises the cap) before any charge. Billed per **source** page.

`lang` selects the OCR language from the **deployed 10-language roster**: `eng` (default), `spa`, `fra`, `deu`, `ita`, `por`, `nld`, `pol`, `rus`, `chi_sim`. The live roster is the operator-tunable `cputools.ocr.langs`; an off-roster `lang` returns a **free** `422 UNSUPPORTED_LANG` that names the roster. The same `lang` parameter (and roster) applies to `ocr-searchable` and [`image/ocr`](/docs/image-tools).

```json
POST /v1/pdf/ocr
{ "file": {"inline":"<b64>"}, "pages": "1-3", "lang": "spa" }
```

Response (parsed text, not an output envelope):

```json
{ "pages": [ {"page": 1, "text": "..."} ], "text": "..." }
```

## ocr-searchable

Turn a scanned PDF into a **searchable PDF**: per page, the worker rasterizes (`pdftoppm`), Tesseract emits a page PDF carrying the original page image plus an **invisible text layer**, and qpdf merges the pages. The result looks identical but is selectable, copyable, and indexable. Same `pages` / `lang` parameters and the same 5-page synchronous cap as `ocr`; billed per **source** page at a premium over plain OCR (it runs OCR *plus* PDF assembly).

```json
POST /v1/pdf/ocr-searchable
{ "file": {"inline":"<b64>"}, "pages": "1-3", "lang": "eng" }
```

The output is **always a storage ref** — `{ output: { outputKey, outputUrl, sizeBytes, contentType, filename } }`, never inline (the render convention; OCR'd page images are large). Fetch the PDF from the presigned `outputUrl`, or chain `outputKey` straight into another op.

## from-html

**Generate a PDF from HTML** — render caller-supplied HTML/CSS to a PDF on a headless Chromium worker. This is how you produce invoices, reports, contracts, and certificates from a template + data: build the HTML, get back a print-ready PDF. Flat per-call price.

```json
POST /v1/pdf/from-html
{ "html": "<h1>Invoice #1042</h1>…",
  "options": { "format": "A4", "margin": {"top":"2cm","bottom":"2cm"}, "printBackground": true,
    "headerTemplate": "<div style='font-size:8px;width:100%;text-align:right'>Invoice #1042</div>",
    "footerTemplate": "<div style='font-size:8px;width:100%;text-align:center'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>",
    "pageRanges": "1-3" } }
```

`options` (all optional): `format` (`A4` | `Letter` | `Legal` | `A3` | `A5` | `Tabloid` | `Ledger`), `landscape` (boolean), `margin` (`top` / `right` / `bottom` / `left`, each a size string in `px`, `cm`, `mm`, or `in`), `printBackground` (boolean), `scale` (0.1–2). Plus print furniture and output controls: `headerTemplate` / `footerTemplate` (HTML for the running header/footer — use the `date`, `title`, `url`, `pageNumber`, and `totalPages` classes to inject values; leave room with `margin`), `displayHeaderFooter` (boolean — auto-enabled when you supply a template, so you rarely set it yourself; set `false` to suppress), `pageRanges` (a subset to print, e.g. `"1-5, 8"`; default all pages), and `tagged` (emit a tagged/accessible PDF — **default `true`**). The HTML itself is capped at 5 MB (`cputools.render.max_html_bytes`, operator-tunable; over → free `422 HTML_TOO_LARGE`). Returns the standard output envelope (a PDF).

**Sandboxed by design.** The renderer is locked **read-only with no network and no JavaScript**: every external resource request — `<img>`, `<link>`, `<script>`, `fetch`, `@import`, `file://` — is blocked, so the renderer can't reach the network (no SSRF) or execute scripts. **The header/footer templates render under the same wall** — they cannot fetch or execute anything either. That means **assets must be inlined**: `data:` URIs for images, inline `<style>` for CSS. For a chart, render it server-side and embed the PNG as a `data:` URI. Static, templated HTML is the sweet spot.

## from-office

**Convert an Office document to PDF** — docx, xlsx, pptx, odt, ods, odp, rtf, txt, or csv in; a print-ready PDF out (LibreOffice via Gotenberg). Flat per-call price. The `filename` is required — its extension is how the format is recognized.

```json
POST /v1/pdf/from-office
{ "file": {"inline":"<base64 docx>"}, "filename": "q3-report.docx" }
```

Takes the standard input source (`{ "inline": "<b64>" }` ≤ 4 MB, or `{ "inputKey": "..." }` for larger files — capped at 30 MB for this op) and returns the standard output envelope (a PDF). An unsupported extension returns `422 UNSUPPORTED_FORMAT` and an oversized input `422 INPUT_TOO_LARGE` — both **before any charge**. If the conversion itself can't be delivered (a corrupt file, an upstream failure), the call returns `422 CONVERT_FAILED` and the charge is reversed: you pay only for a delivered PDF.

## images

**Extract the embedded images from a PDF** — pull every raster image XObject out of the document and return each as a PNG. Billed per page scanned; `pages` is an optional 1-based range string (default: all). Useful for harvesting figures, scans, or logos a PDF carries.

```json
POST /v1/pdf/images
{ "file": { "inline": "<base64-pdf>" }, "pages": "1-5" }
```

Returns a manifest: one entry per extracted image, each `output` a standard output envelope (PNG):

```json
{ "images": [ {"page": 1, "index": 0, "width": 800, "height": 600, "output": { ... }} ], "count": 1, "truncated": false }
```

Capped at **200 images** per call — extraction stops there and the response sets `truncated: true`.

## diff

**Compare two PDFs by their text** — extract the text of both and return a unified diff. Per-page price, billed on the combined page count of both inputs. Pure-text compare (layout/visual diff is not in scope). `context` (optional, 0–100, default 3) sets the unified-diff context lines.

```json
POST /v1/pdf/diff
{ "a": { "inline": "<base64-pdf>" }, "b": { "inputKey": "uploads/v2.pdf" }, "context": 3 }
```

Returns `{ patch, changed }` — a unified-diff string (`createTwoFilesPatch` format) plus a boolean; `changed: false` when the two carry identical text.

## bookmarks

**Read the outline / bookmark tree** of a PDF. Flat per-call price. Read-only (writing bookmarks is not in scope yet).

```json
POST /v1/pdf/bookmarks
{ "file": { "inline": "<base64-pdf>" } }
```

Returns `{ outline, count }` — a recursive tree of `{ title, children }` plus the total node count. Empty array when the PDF has no outline.

## attachments

**List or extract embedded file attachments** of a PDF. Flat per-call price.

```json
POST /v1/pdf/attachments
{ "file": { "inline": "<base64-pdf>" }, "extract": true }
```

Returns `{ attachments, count }` — one entry per embedded file (`{ filename, size }`, first 100); with `extract: true`, each entry also carries an `output` envelope with the file bytes. Empty array when the PDF carries no attachments.

## verify-signatures

Inspect a PDF's **digital signatures** (poppler `pdfsig`). Flat per-call price.

```json
POST /v1/pdf/verify-signatures
{ "file": {"inline":"<b64>"} }
```

```json
{ "signatures": [ {
    "index": 1,
    "signerCommonName": "Jane Doe",
    "signerDistinguishedName": "CN=Jane Doe,O=Acme",
    "signingTime": "Jun 11 2026 14:02:11",
    "hashAlgorithm": "SHA-256",
    "signatureType": "ETSI.CAdES.detached",
    "signatureValidation": "Signature is Valid.",
    "certificateValidation": "Certificate issuer isn't Trusted."
  } ],
  "signatureCount": 1 }
```

**What it checks — read this before relying on it.** This op performs **structural verification + digest intactness**: the signature is present, the signed byte range hasn't been modified since signing (`signatureValidation`), and the signer's identity fields are surfaced. **Certificate-chain trust is not evaluated — no CA store is deployed**, so `certificateValidation` will typically report that the issuer chain couldn't be checked. It answers "is this document signed, by whom, and is it unmodified?" — not "do I trust the signer's certificate authority?". An **unsigned** document returns `"signatures": []` with `signatureCount: 0` — a normal outcome, not an error.

This op pairs with [Relaystation e-sign](https://relaystation.ai/docs/esigndoc) as the **verification half**: send documents for legally-binding signature there, verify what came back (or any third-party-signed PDF) here.

## Large files and the retry tail

For a file above the 4 MB inline ceiling, mint a presigned upload (see above), `POST` the bytes, and pass `{"inputKey":"..."}` to the worker op. The worker ops are synchronous: the API holds the connection while qpdf/poppler/Tesseract run. A worst-case job near the window (a 40-page render, a 5-page OCR) can occasionally exceed the API Gateway's ~30-second integration timeout and return a `504`. This is safe: **re-issue the same request with the same `Idempotency-Key`** and the chassis returns the already-computed result without charging twice.

## Errors

- `402 PAYMENT_REQUIRED` — no valid payment (see [x402](https://relaystation.ai/docs/x402)).
- `422 PDF_PARSE_FAILED` — the input didn't parse as a PDF.
- `422 WRONG_PASSWORD` / `PDF_ENCRYPTED` — render/OCR an encrypted PDF (remove its password with a desktop tool first; in-platform decrypt is unavailable).
- `422 RENDER_TOO_MANY_PAGES` / `DPI_TOO_HIGH` / `OCR_TOO_MANY_PAGES_SYNC` — over a render/OCR cap (charged nothing).
- `422 UNSUPPORTED_LANG` — an OCR `lang` outside the deployed roster (`cputools.ocr.langs`); the error names the roster (charged nothing).
- `422 BAD_RANGE` — a malformed or out-of-bounds page range.
- `422 UNSUPPORTED_FORMAT` / `INPUT_TOO_LARGE` / `CONVERT_FAILED` — from-office: extension not in the allowlist or input over the size cap (charged nothing), or the conversion couldn't be delivered (charge reversed).
- `400 VALIDATION_ERROR` — the request body failed schema validation.

## Next

[Overview](/docs/cputools-overview) · [Pricing](/pricing) · [API reference](/api-reference) · [x402 wire format](https://relaystation.ai/docs/x402) · [Authentication](https://relaystation.ai/docs/authentication)

## /docs/csv-tools

# CSV tools

Three in-process tabular operations on [Papaparse](https://www.papaparse.com/). Every op is a `POST https://api.relaystation.ai/v1/csv/<op>`. cputools **transforms** tabular text — it never evaluates a cell as a formula, so there is no spreadsheet-formula execution surface.

## Inputs and outputs

Same uniform shape as the [PDF tools](/docs/pdf-tools): the `file` is an **input source** — `{ "inline": "<base64>" }` for ≤ 4 MB, or `{ "inputKey": "..." }` (from `POST /v1/cputools/upload-url`) for up to 50 MB. The result comes back in the uniform **output envelope** (inline base64 ≤ 4 MB, or a presigned `outputUrl` above it), with the right content type — `text/csv`, `text/tab-separated-values`, `application/json`, or `application/x-ndjson`.

## Billing

Per-MB of input, **minimum 1 MiB**, at the operator-tunable `cputools.price.csv.<op>.per_mb_micros` (launch default $0.0002 / MB). The live `402` challenge is authoritative.

| Op | Billed on | Rate |
|---|---|---|
| `convert` | input MB | $0.0002 / MB |
| `dedupe` | input MB | $0.0002 / MB |
| `select` | input MB | $0.0002 / MB |

## convert

Convert between `csv`, `tsv`, `json` (array of row objects), and `ndjson`. `from` defaults to `csv`; `to` is required; `delimiter` overrides the csv/tsv separator.

```json
POST /v1/csv/convert
{ "file": {"inline":"<b64>"}, "from": "csv", "to": "json" }
```

## dedupe

Drop duplicate rows, preserving first-seen order. Pass `columns` to dedupe on a subset of key columns; omit it to dedupe on the whole row.

```json
POST /v1/csv/dedupe
{ "file": {"inline":"<b64>"}, "columns": ["email"] }
```

## select

Project columns: pass **exactly one** of `columns` (keep + reorder) or `drop` (remove).

```json
POST /v1/csv/select
{ "file": {"inline":"<b64>"}, "columns": ["name", "email"] }
```

## Sample

```bash
curl -X POST https://api.relaystation.ai/v1/csv/convert \
  -H 'X-Payment: <base64 EIP-3009 auth>' \
  -H 'Idempotency-Key: convert-export-20260606' \
  -H 'Content-Type: application/json' \
  -d '{"file":{"inline":"bmFtZSxhZ2UKQWxpY2UsMzAK"},"to":"json"}'
```

## Errors

- `402 PAYMENT_REQUIRED` — no valid payment.
- `422 CSV_PARSE_FAILED` — malformed input (e.g. a row with more cells than the header, or non-object JSON elements). Rejected **before** any charge.
- `422 UNKNOWN_COLUMN` — a `columns`/`drop` name isn't in the header (the response lists the offenders).
- `400 VALIDATION_ERROR` — the body failed schema validation (e.g. both `columns` and `drop` on `select`).

## Next

[PDF tools](/docs/pdf-tools) · [Image tools](/docs/image-tools) · [QR & barcode](/docs/qr-tools) · [Pricing](/pricing) · [API reference](/api-reference)

## /docs/image-tools

# Image tools

Raster operations on [sharp](https://sharp.pixelplumbing.com/) (libvips), plus image OCR on Tesseract. Every op is a `POST https://api.relaystation.ai/v1/image/<op>`.

## Inputs and outputs

Same uniform shape as the [PDF tools](/docs/pdf-tools): the `file` is an **input source** — `{ "inline": "<base64>" }` for ≤ 4 MB, or `{ "inputKey": "..." }` (from `POST /v1/cputools/upload-url`) for up to 50 MB. The transformed image returns in the uniform **output envelope** (inline base64 ≤ 4 MB, or a presigned `outputUrl` above it). Supported formats: PNG, JPEG, WebP, AVIF, TIFF, GIF.

## Billing

Per **megapixel of the input** (width × height ÷ 1,000,000), **minimum 1**, at the operator-tunable `cputools.price.image.<op>.per_mp_micros` (launch default $0.0003 / MP). `metadata` is flat. The live `402` challenge is authoritative.

| Op | Billed on | Rate |
|---|---|---|
| `resize` | input megapixels | $0.0003 / MP |
| `convert` | input megapixels | $0.0003 / MP |
| `compress` | input megapixels | $0.0003 / MP |
| `rotate` | input megapixels | $0.0003 / MP |
| `crop` | input megapixels | $0.0003 / MP |
| `blur` | input megapixels | $0.0003 / MP |
| `sharpen` | input megapixels | $0.0003 / MP |
| `grayscale` | input megapixels | $0.0003 / MP |
| `exif-strip` | input megapixels | $0.0003 / MP |
| `composite` | base megapixels | $0.0003 / MP |
| `contact-sheet` | total input MP | $0.0003 / MP |
| `adjust` | input megapixels | $0.0003 / MP |
| `trim` | input megapixels | $0.0003 / MP |
| `extend` | input megapixels | $0.0003 / MP |
| `metadata` | per call | $0.0005 flat |
| `dominant-color` | per call | $0.0002 flat |
| `ocr` | per call | $0.003 flat |
| `from-html` | per call | $0.003 flat |

`from-html` is **flat-billed** (output dimensions aren't known until after the render, so there's no per-MP pre-auth — the same model as [`pdf/from-html`](/docs/pdf-tools)).

## More image ops (Brief 175)

Beyond resize/convert/compress/rotate/metadata, these sharp-backed ops ship:

- **`crop`** — `{ file, left, top, width, height }`; extract a region (out-of-bounds → `422 CROP_OUT_OF_BOUNDS`).
- **`blur`** — `{ file, sigma? }`; Gaussian blur.
- **`sharpen`** — `{ file, sigma? }`.
- **`grayscale`** — `{ file }`.
- **`exif-strip`** — `{ file }`; auto-orients per EXIF, then drops all metadata (pixels + orientation preserved, EXIF/GPS gone).
- **`dominant-color`** — `{ file }`; returns `{ dominant: { r, g, b }, hex }` (flat-billed read).
- **`composite`** — `{ file (base), overlay, gravity? | (top,left), opacity? }`; overlay/watermark one image onto another.
- **`contact-sheet`** — `{ files: <source>[], columns?, cellWidth?, cellHeight?, gap?, background? }`; tile images into a thumbnail-grid PNG.
- **`adjust`** — `{ file, brightness?, saturation?, hue?, lightness?, negate?, tint? }`; tune color/tone (at least one).
- **`trim`** — `{ file, threshold? }`; auto-crop uniform-color borders.
- **`extend`** — `{ file, top?/bottom?/left?/right?, background?, extendWith? }`; pad on any side.
- **`from-html`** — `{ html, type?, fullPage?, clip?, omitBackground?, width?, height? }`; render provided HTML to an image (headless Chromium screenshot).

All transform ops return the uniform JSON output envelope and keep the input format where applicable (`contact-sheet` and `from-html` are the new-format exceptions).

## resize

Resize to a target `width` and/or `height` (at least one). `fit` controls how the image fills the box: `cover` | `contain` | `fill` | `inside` | `outside`.

Set `animated: true` to read an animated GIF/WebP with all its frames intact — every frame is resized and the animation is preserved (billing counts the frames: pages × width × height).

```json
POST /v1/image/resize
{ "file": {"inline":"<b64>"}, "width": 800, "fit": "inside", "animated": true }
```

## convert

Re-encode to another format. `format` is the target (`png` | `jpeg` | `webp` | `avif`); `quality` (1–100) applies to lossy formats. **AVIF** is supported as an output target (modern, high-compression). Set `animated: true` to preserve all frames of an animated input — `gif`/`webp` targets keep the animation stack; other targets flatten.

```json
POST /v1/image/convert
{ "file": {"inline":"<b64>"}, "format": "webp", "quality": 82 }
```

## compress

Re-encode at lower quality in the current format.

```json
POST /v1/image/compress
{ "file": {"inline":"<b64>"}, "quality": 70 }
```

## rotate

Rotate by `angle` degrees and/or `flip` (vertical) / `flop` (horizontal).

```json
POST /v1/image/rotate
{ "file": {"inline":"<b64>"}, "angle": 90 }
```

## metadata

Read dimensions, format, color space, and EXIF presence — no bytes returned, flat-billed.

```json
POST /v1/image/metadata
{ "file": {"inline":"<b64>"} }
```

Response: `{ "metadata": { "width": 1920, "height": 1080, "format": "jpeg", ... } }`.

## OCR

Extract text from an image (Tesseract LSTM on the cputools worker — PNG, JPEG, TIFF, BMP, WebP). Flat per-call price (`cputools.price.image.ocr.flat_micros`, $0.003 at launch).

`lang` selects the OCR language from the **deployed 10-language roster**: `eng` (default), `spa`, `fra`, `deu`, `ita`, `por`, `nld`, `pol`, `rus`, `chi_sim`. The live roster is the operator-tunable `cputools.ocr.langs`; an off-roster `lang` returns a **free** `422 UNSUPPORTED_LANG` naming the roster — the same parameter and roster as the [PDF OCR ops](/docs/pdf-tools).

Pass `tsv: true` to also get Tesseract's TSV output — per-word bounding boxes and confidences — alongside the plain text.

```json
POST /v1/image/ocr
{ "file": {"inline":"<b64 image>"}, "lang": "deu", "tsv": true }
```

Response (JSON, no bytes): `{ "text": "...", "tsv": "level\tpage_num\t..." }`. There is no pre-charge image-format guard — Tesseract is the parser; a non-image input returns `422 IMAGE_PARSE_FAILED` with the charge reversed.

## adjust

Tune color and tone in one pass (sharp's modulate bundle). Supply at least one of: `brightness` (0–10 multiplier), `saturation` (0–10), `hue` (−360–360 degrees), `lightness` (−100–100), `negate` (invert), `tint` (`{ r, g, b }`). Per-MP billed; keeps the input format.

```json
POST /v1/image/adjust
{ "file": {"inline":"<b64>"}, "brightness": 1.1, "saturation": 1.3, "tint": { "r": 255, "g": 240, "b": 200 } }
```

## trim

Auto-crop a uniform-color border (e.g. trim the whitespace around a logo). Optional `threshold` (0–255) controls how close to uniform a pixel must be to be trimmed.

```json
POST /v1/image/trim
{ "file": {"inline":"<b64>"}, "threshold": 10 }
```

## extend

Pad an image on any side (the inverse of `crop`). Give pixel counts for `top` / `bottom` / `left` / `right` (at least one positive). `background` is a hex string (`"#rrggbb"`) or `{ r, g, b, alpha? }`; `extendWith` selects the fill mode (`background` | `copy` | `repeat` | `mirror`).

```json
POST /v1/image/extend
{ "file": {"inline":"<b64>"}, "top": 40, "bottom": 40, "background": "#ffffff" }
```

## from-html

Render caller-supplied HTML to a **png/jpeg/webp** image — the screenshot counterpart of [`pdf/from-html`](/docs/pdf-tools), on the same dedicated headless-Chromium render worker via `page.screenshot`. Use it for social cards, chart/badge rendering, or any HTML-templated graphic.

Body: `{ html, type?: "png"|"jpeg"|"webp", fullPage?, clip?: { x, y, width, height }, omitBackground?, width?, height? }`.

**Sandboxed / SSRF-walled** identically to `pdf/from-html`: the renderer has **no network** and **no JavaScript** — every request whose scheme is not `data:` is aborted, so all assets must be inlined as `data:` URIs / inline `<style>` (the contract). Two pre-charge validation rules: `clip` and `fullPage` are mutually exclusive (`400`), and `omitBackground` (transparent background) requires `png`/`webp` — with `jpeg` it `400`s (JPEG has no alpha channel).

```json
POST /v1/image/from-html
{ "html": "<div style=\"font:48px sans-serif;padding:40px\">Hello</div>", "type": "png", "fullPage": true }
```

Because the image is a binary output, it rides the uniform output envelope — see [Passing & receiving files](/docs/receiving-outputs) for how to fetch the bytes (inline base64 ≤ 4 MB, or a presigned `outputUrl` above it).

## Sample

```bash
curl -X POST https://api.relaystation.ai/v1/image/resize \
  -H 'X-Payment: <base64 EIP-3009 auth>' \
  -H 'Idempotency-Key: thumb-20260606' \
  -H 'Content-Type: application/json' \
  -d '{"file":{"inline":"<base64 image>"},"width":400}'
```

## Errors

- `402 PAYMENT_REQUIRED` — no valid payment.
- `422 IMAGE_PARSE_FAILED` — the input didn't decode as a supported image.
- `422 IMAGE_TOO_LARGE` — the input exceeds `cputools.image.max_megapixels`.
- `422 UNSUPPORTED_LANG` — an OCR `lang` outside the deployed roster (`cputools.ocr.langs`); the error names the roster (charged nothing).
- `422 HTML_TOO_LARGE` — `from-html` input over `cputools.render.max_html_bytes`.
- `400 VALIDATION_ERROR` — the body failed schema validation (incl. `from-html`'s `clip`+`fullPage` and `omitBackground`+`jpeg` conflicts).

## Next

[PDF tools](/docs/pdf-tools) · [CSV tools](/docs/csv-tools) · [QR & barcode](/docs/qr-tools) · [Pricing](/pricing) · [API reference](/api-reference)

## /docs/qr-tools

# QR & barcode

Two generators — no input file, just the data to encode. `POST https://api.relaystation.ai/v1/qr` and `POST https://api.relaystation.ai/v1/barcode`.

## Billing

Flat per call (no per-page/per-MB unit — there's no input file), at the operator-tunable `cputools.price.{qr,barcode}.generate.flat_micros` (launch default $0.0002). The live `402` challenge is authoritative.

| Op | Billed on | Rate |
|---|---|---|
| `qr` | per call | $0.0002 flat |
| `barcode` | per call | $0.0002 flat |

The encoded `data` is capped at 4096 characters; over it returns `422 DATA_TOO_LONG` before any charge.

## qr

Generate a QR code as PNG or SVG. `format` is `png` (default) or `svg`; `size` (px), `margin` (modules), and `ecc` (error-correction level `L` | `M` | `Q` | `H`) are optional.

```json
POST /v1/qr
{ "data": "https://relaystation.ai", "format": "svg", "ecc": "M" }
```

## barcode

Generate a 1D barcode (Code128, EAN, UPC, and friends). `type` selects the symbology; `format` is `png` (default) or `svg`.

```json
POST /v1/barcode
{ "data": "0123456789", "type": "code128", "format": "png" }
```

Both return the image in the uniform **output envelope** (inline base64, or a presigned `outputUrl` for a large SVG).

## Sample

```bash
curl -X POST https://api.relaystation.ai/v1/qr \
  -H 'X-Payment: <base64 EIP-3009 auth>' \
  -H 'Idempotency-Key: qr-20260606' \
  -H 'Content-Type: application/json' \
  -d '{"data":"https://relaystation.ai","format":"png"}'
```

## Errors

- `402 PAYMENT_REQUIRED` — no valid payment.
- `422 DATA_TOO_LONG` — the data exceeds 4096 characters (charged nothing).
- `400 VALIDATION_ERROR` — the body failed schema validation.

## Next

[PDF tools](/docs/pdf-tools) · [CSV tools](/docs/csv-tools) · [Image tools](/docs/image-tools) · [Pricing](/pricing) · [API reference](/api-reference)

## /docs/utils-tools

# Utils tools

Six in-process crypto/encoding primitives on Node's built-in [`crypto`](https://nodejs.org/api/crypto.html) and [`jose`](https://github.com/panva/jose) — the same open-source libraries you could run yourself. Every op is a `POST https://api.relaystation.ai/v1/utils/<op>`. These return a small **JSON object** (a hash, a list of UUIDs, a verification result) — there is no file output.

## Inputs

`hash`, `hmac`, and `base64` take bytes; the rest take a string. The byte-taking ops accept **either** an inline `data` string **or** a `file` input source — `{ "inline": "<base64>" }` (≤ 4 MB) or `{ "inputKey": "..." }` (from `POST /v1/cputools/upload-url`, ≤ 50 MB) — exactly one. Secret inputs (the `hmac` key, the `jwt-verify` key) ride only in the request body and are **never logged** and never echoed in an error.

## Billing

`hash`, `hmac`, `base64` bill **per MB of input** (min 1 MiB) at `cputools.price.utils.<op>.per_mb_micros` (launch default $0.0002 / MB). `uuid`, `jwt-decode`, `jwt-verify` are **flat** at `cputools.price.utils.<op>.flat_micros` (launch default $0.0001 / call). The live `402` challenge is authoritative.

| Op | Billed on | Rate |
|---|---|---|
| `hash` | input MB | $0.0002 / MB |
| `hmac` | input MB | $0.0002 / MB |
| `base64` | input MB | $0.0002 / MB |
| `uuid` | per call | $0.0001 flat |
| `jwt-decode` | per call | $0.0001 flat |
| `jwt-verify` | per call | $0.0001 flat |

## hash

Hash bytes with `sha256`, `sha512`, `sha1`, or `md5`. Returns `{ algo, hash: <hex> }`. (`sha1`/`md5` are offered for legacy checksum compatibility.)

```json
POST /v1/utils/hash
{ "data": "hello", "algo": "sha256" }
```

## hmac

Keyed HMAC over the same algorithms. Returns `{ algo, hmac: <hex> }`. The `key` is never logged.

```json
POST /v1/utils/hmac
{ "data": "hello", "key": "<secret>", "algo": "sha256" }
```

## uuid

Generate v4 UUIDs. `count` defaults to 1 and is capped at `cputools.utils.uuid.max_count` (default 1000). Returns `{ uuids: [...] }`.

```json
POST /v1/utils/uuid
{ "count": 5 }
```

## jwt-decode

Decode a JWT's header + payload **without verifying the signature** (jose). Returns `{ header, payload }`. A malformed token → `422 JWT_MALFORMED`.

```json
POST /v1/utils/jwt-decode
{ "token": "<jwt>" }
```

## jwt-verify

Verify a JWT signature, **pinned to the declared `alg`** — this blocks the alg-confusion / `alg:none` downgrade (`none` is not an accepted algorithm). `alg` is one of `HS256/384/512`, `RS256/384/512`, `ES256/384`. A valid-shape token that fails verification is a **paid answer** (`200 { valid: false, reason }`) — you paid to learn validity; only an unparseable token (`422 JWT_MALFORMED`) or an unimportable key (`422 JWT_KEY_INVALID`) is an error. The `key` is never logged.

```json
POST /v1/utils/jwt-verify
{ "token": "<jwt>", "key": "<secret-or-PEM>", "alg": "HS256" }
```

## base64

Encode or decode a string. Returns `{ data: <result> }`.

```json
POST /v1/utils/base64
{ "data": "hello", "mode": "encode" }
```

## Sample

```bash
curl -X POST https://api.relaystation.ai/v1/utils/hash \
  -H 'X-Payment: <base64 EIP-3009 auth>' \
  -H 'Idempotency-Key: hash-manifest-20260609' \
  -H 'Content-Type: application/json' \
  -d '{"data":"hello","algo":"sha256"}'
```

## Errors

- `402 PAYMENT_REQUIRED` — no valid payment.
- `422 JWT_MALFORMED` — the token isn't a well-formed JWT (jwt-decode / jwt-verify).
- `422 JWT_KEY_INVALID` — the jwt-verify key couldn't be imported for the declared `alg` (the key bytes are never echoed).
- `422 COUNT_TOO_LARGE` — `uuid` count over the cap. Rejected **before** any charge.
- `400 VALIDATION_ERROR` — the body failed schema validation (e.g. neither/both of `data`/`file`, or `alg: "none"`).

## Next

[PDF tools](/docs/pdf-tools) · [CSV tools](/docs/csv-tools) · [Image tools](/docs/image-tools) · [Generate tools](/docs/generate-tools) · [Archive tools](/docs/archive-tools) · [Pricing](/pricing) · [API reference](/api-reference)

## /docs/generate-tools

# Generate tools

Two in-process generators — render and fake data — on [satori](https://github.com/vercel/satori), [sharp](https://sharp.pixelplumbing.com/), and [`@faker-js/faker`](https://fakerjs.dev/), all pure-JS, the same open-source libraries you could run yourself. Every op is a `POST https://api.relaystation.ai/v1/generate/<op>`.

## Billing

Both ops are **flat** per-call at `cputools.price.generate.<op>.flat_micros` (launch defaults: og-image $0.0005, mock-data $0.0002). The live `402` challenge is authoritative.

| Op | Billed on | Rate |
|---|---|---|
| `og-image` | per call | $0.0005 flat |
| `mock-data` | per call | $0.0002 flat |

## og-image

Render a clean social-card **PNG** from a title (and optional subtitle + theme + size): satori builds the SVG, the vendored sharp rasterizes it. Returns the uniform **output envelope** (`image/png`, inline base64 — OG images are always small). One clean template — `title`, optional `subtitle`, `theme` (`light`/`dark`), `width` (600–2000), `height` (300–1200).

```json
POST /v1/generate/og-image
{ "title": "Quarterly report", "subtitle": "Q2 2026", "theme": "dark" }
```

## mock-data

Generate fake rows from a field→type schema. `count` rows (≤ `cputools.generate.mock-data.max_rows`, default 1000), at most `cputools.generate.mock-data.max_fields` fields (default 50). `format` is `json` (default), `csv`, or `ndjson`. Supported field types: `name`, `firstName`, `lastName`, `email`, `uuid`, `int`, `float`, `bool`, `date`, `address`, `city`, `country`, `phone`, `company`, `url`, `word`, `sentence`, `paragraph`. An unknown type → `422 UNSUPPORTED_TYPE` (pre-charge). Returns the uniform output envelope (`application/json` / `text/csv` / `application/x-ndjson`).

```json
POST /v1/generate/mock-data
{ "schema": { "name": "name", "email": "email", "age": "int" }, "count": 100, "format": "csv" }
```

## invoice

Render a clean **invoice PDF** from structured data (pdf-lib, in-process). Pass `seller` + `buyer` (`{ name, address?, email? }`), an `items` array (1–100 of `{ description, quantity, unitPrice }`), and optional `number`, `date`, `currency` (default `$`), `taxRate` (0–100 %), `notes`. Computes subtotal / tax / total. Returns the uniform output envelope (`application/pdf`). Flat per-call price.

```json
POST /v1/generate/invoice
{ "seller": { "name": "Acme LLC", "email": "billing@acme.com" },
  "buyer": { "name": "Globex" },
  "number": "INV-1042", "currency": "$",
  "items": [ { "description": "Widget", "quantity": 3, "unitPrice": 9.99 } ],
  "taxRate": 8.25 }
```

## chart

Render a **bar / line / pie chart PNG** from data points — hand-rolled SVG rasterized by the vendored sharp (no charting library, no browser). `type` is `bar`, `line`, or `pie`; `data` is 1–50 `{ label, value }` points; optional `title`, `width` (200–2000), `height` (150–2000), `color`. Flat per-call price.

```json
POST /v1/generate/chart
{ "type": "bar", "title": "Signups", "data": [ {"label":"Jan","value":120}, {"label":"Feb","value":210} ] }
```

## qr-logo

Render a **QR code with your logo composited in the center**. The QR is generated at error-correction level **H** (30 % recovery) so the centered logo doesn't break scanning, and the logo gets a white pad for quiet-zone contrast. Pass `data` (the encoded string) and `logo` (an image `{ inline }` or `{ inputKey }`), plus optional `size` (128–2000), `margin` (0–16), `logoScale` (0.1–0.35). Returns a PNG. A logo that doesn't decode as an image → `422 IMAGE_PARSE_FAILED` (pre-charge). Flat per-call price.

```json
POST /v1/generate/qr-logo
{ "data": "https://relaystation.ai", "logo": { "inline": "<base64-png>" }, "size": 512 }
```

## favicon

Generate a **favicon set** (PNGs at several sizes) from **either** an image **or** initials text — provide exactly one of `image` (`{ inline }` / `{ inputKey }`) or `text` (1–3 chars). Optional `background`, `color`, and `sizes` (default `[16, 32, 48, 180]`, ≤ 8). Returns `{ icons: [{ size, output }] }`, each `output` a uniform envelope. Flat per-call price.

```json
POST /v1/generate/favicon
{ "text": "RS", "background": "#2563eb", "color": "#ffffff" }
```

## placeholder

Render a **placeholder image** — a solid background with centered dimensions/label text (hand-rolled SVG). Pass `width` + `height` (8–4000), optional `background`, `color`, `text` (defaults to `"W×H"`), and `format` (`png` default, or `svg`). Flat per-call price.

```json
POST /v1/generate/placeholder
{ "width": 600, "height": 400, "text": "Hero image" }
```

## identicon

Render a **deterministic GitHub-style identicon** — a 5×5 mirror-symmetric PNG derived from a seed string (sha256 → colour + cell grid). The **same seed always yields the same image**, so it's a stable avatar for any stable id (email, wallet, username). Pass `seed`, optional `size` (32–1024), `background`. Flat per-call price.

```json
POST /v1/generate/identicon
{ "seed": "alice@example.com", "size": 256 }
```

## Sample

```bash
curl -X POST https://api.relaystation.ai/v1/generate/mock-data \
  -H 'X-Payment: <base64 EIP-3009 auth>' \
  -H 'Idempotency-Key: seed-fixtures-20260609' \
  -H 'Content-Type: application/json' \
  -d '{"schema":{"name":"name","email":"email"},"count":50,"format":"json"}'
```

## Errors

- `402 PAYMENT_REQUIRED` — no valid payment.
- `422 UNSUPPORTED_TYPE` — a mock-data schema field names a type outside the allowlist (the response lists the supported types). Rejected **before** any charge.
- `422 COUNT_TOO_LARGE` / `422 TOO_MANY_FIELDS` — over the row/field cap, pre-charge.
- `422 IMAGE_PARSE_FAILED` — a `qr-logo` logo or `favicon` image input didn't decode as an image. Rejected **before** any charge.
- `404` — a storage-ref `inputKey` (qr-logo logo / favicon image) is not owned by the caller.
- `400 VALIDATION_ERROR` — the body failed schema validation (e.g. an empty `title`, a width/height out of range, or `favicon` given neither/both of `image` and `text`).

## Next

[PDF tools](/docs/pdf-tools) · [CSV tools](/docs/csv-tools) · [Image tools](/docs/image-tools) · [Utils tools](/docs/utils-tools) · [Archive tools](/docs/archive-tools) · [Pricing](/pricing) · [API reference](/api-reference)

## /docs/archive-tools

# Archive tools

Three in-process archive operations on [fflate](https://github.com/101arrowz/fflate) (MIT, pure-JS) — the same open-source library you could run yourself. Every op is a `POST https://api.relaystation.ai/v1/archive/<op>`. Everything happens **in memory**: cputools never writes an entry to a filesystem, so there is no path-traversal ("zip-slip") surface — and the extraction is bomb-guarded (below).

## Inputs and outputs

Same uniform shape as the [PDF tools](/docs/pdf-tools): a `file` input source is `{ "inline": "<base64>" }` (≤ 4 MB) or `{ "inputKey": "..." }` (from `POST /v1/cputools/upload-url`, ≤ 50 MB). `zip` takes a `files` **array**. `unzip` returns a **manifest** — `{ entries: [{ name, output }] }` — where each `name` is a sanitized basename and each `output` is the uniform envelope (inline ≤ 4 MB, else a presigned `outputUrl`). `zip`/`gzip` return a single output envelope.

## Billing

Per MB of **input** (compressed) bytes, **minimum 1 MiB**, at `cputools.price.archive.<op>.per_mb_micros` (launch default $0.0002 / MB). Billing is on the input you send — so `unzip` bills the compressed archive, not its (larger) expansion. The live `402` challenge is authoritative.

| Op | Billed on | Rate |
|---|---|---|
| `zip` | total input MB | $0.0002 / MB |
| `unzip` | input MB | $0.0002 / MB |
| `gzip` | input MB | $0.0002 / MB |

## zip

Zip one or more files into a single archive. `files` is an array of input sources (≥ 1, ≤ `cputools.archive.max_files_per_zip`, default 1000); optional `filenames` must match `files.length`. Filenames are reduced to a **sanitized basename** (path separators, `..`, drive prefixes, and null bytes stripped); collisions get a `-N` suffix.

```json
POST /v1/archive/zip
{ "files": [{"inline":"<b64>"}, {"inline":"<b64>"}], "filenames": ["a.txt", "b.txt"] }
```

## unzip

Extract a zip to a manifest of entries. **Zip-bomb-guarded** in two layers (see below). A nested `.zip` entry is returned as **raw bytes — never recursively extracted** (one level only).

```json
POST /v1/archive/unzip
{ "file": {"inline":"<b64 zip>"} }
```

## gzip

Compress or decompress a single file. `mode` is `compress` (→ `application/gzip`) or `decompress` (→ `application/octet-stream`). Decompress is guarded by the same uncompressed-size cap (gzip bombs too).

```json
POST /v1/archive/gzip
{ "file": {"inline":"<b64>"}, "mode": "compress" }
```

## The zip-bomb defense (documented limits)

A decompression bomb — a tiny archive that expands to gigabytes — is stopped by **layered, operator-tunable caps**, and the rejection is a feature:

1. **Pre-charge directory check.** Before any charge, cputools reads the archive's central directory and rejects — with a `422`, **no charge** — an archive whose declared uncompressed total exceeds `cputools.archive.max_uncompressed_bytes` (default **128 MiB**), whose entry count exceeds `cputools.archive.max_entries` (default 10000), or whose per-entry declared compression ratio exceeds `cputools.archive.max_compression_ratio` (default 1000:1).
2. **Authoritative running-total during extraction.** Declared sizes can lie, so extraction streams and sums the **actual** decompressed bytes, aborting the instant it crosses the cap — memory never balloons (and the charge is refunded).
3. **Encrypted/password-protected zips are rejected** (`422 UNSUPPORTED_ENCRYPTED_ZIP`) — cputools doesn't decrypt.

## Sample

```bash
curl -X POST https://api.relaystation.ai/v1/archive/unzip \
  -H 'X-Payment: <base64 EIP-3009 auth>' \
  -H 'Idempotency-Key: unzip-bundle-20260609' \
  -H 'Content-Type: application/json' \
  -d '{"file":{"inline":"<b64 zip>"}}'
```

## Errors

- `402 PAYMENT_REQUIRED` — no valid payment.
- `422 ARCHIVE_TOO_LARGE` — declared (pre-charge) or actual (in-flight) uncompressed output over the cap.
- `422 ARCHIVE_TOO_MANY_ENTRIES` / `422 ARCHIVE_RATIO_EXCEEDED` — over the entry-count or compression-ratio cap (pre-charge).
- `422 UNSUPPORTED_ENCRYPTED_ZIP` — an encrypted/password-protected entry.
- `422 ARCHIVE_INVALID` — not a valid zip/gzip (or a ZIP64 archive, which is unsupported).
- `422 ARCHIVE_TOO_MANY_FILES` / `422 FILENAME_COUNT_MISMATCH` — zip input over the file cap, or a `filenames` length that doesn't match `files`.

## Next

[PDF tools](/docs/pdf-tools) · [CSV tools](/docs/csv-tools) · [Image tools](/docs/image-tools) · [Utils tools](/docs/utils-tools) · [Generate tools](/docs/generate-tools) · [Pricing](/pricing) · [API reference](/api-reference)

## /docs/data-tools

# Data tools

Nineteen in-process dataframe operations over tabular data — the **transform** half of ETL, including **Excel in/out** (`from-xlsx` / `to-xlsx`, the format DuckDB can't emit) and structured `derive` / cleaning ops. Each is a `POST https://api.relaystation.ai/v1/data/<op>`. Input is the csv-family union (`csv`, `tsv`, `json` array-of-rows, `ndjson`); pass `from`/`to` to pick formats (default `csv`). cputools reshapes your rows — it never evaluates a cell or a user expression as code (see `filter` below), so there is no expression-execution surface. For full SQL, see [Data — SQL](/docs/data-sql); to chain several of these in one call, see [Pipeline](/docs/pipeline).

## Inputs and outputs

Same uniform shape as the [CSV tools](/docs/csv-tools): the `file` is an **input source** — `{ "inline": "<base64>" }` for ≤ 4 MB, or `{ "inputKey": "..." }` (from `POST /v1/cputools/upload-url`) for up to 50 MB. The verbs return the uniform **output envelope** (the reshaped table, default `text/csv`); `profile` returns a JSON report.

## Billing

Per-MB of input, **minimum 1 MiB**, at the operator-tunable `cputools.price.data.<op>.per_mb_micros` (launch default $0.0002 / MB). `join` bills on the **sum** of both inputs. The live `402` challenge is authoritative.

| Op | Billed on | Rate |
|---|---|---|
| `filter` | input MB | $0.0002 / MB |
| `sort` | input MB | $0.0002 / MB |
| `groupby` | input MB | $0.0002 / MB |
| `join` | input MB (both inputs) | $0.0002 / MB |
| `union` | input MB (all inputs) | $0.0002 / MB |
| `profile` | input MB | $0.0002 / MB |
| `cast` | input MB | $0.0002 / MB |
| `pivot` | input MB | $0.0002 / MB |
| `schema-infer` | input MB | $0.0002 / MB |
| `validate` | input MB | $0.0002 / MB |
| `diff` | input MB (both inputs) | $0.0002 / MB |
| `from-xlsx` | input MB | $0.0002 / MB |
| `to-xlsx` | input MB | $0.0002 / MB |
| `derive` | input MB | $0.0002 / MB |
| `fillna` | input MB | $0.0002 / MB |
| `dropna` | input MB | $0.0002 / MB |
| `rename` | input MB | $0.0002 / MB |
| `slice` | input MB | $0.0002 / MB |
| `explode` | input MB | $0.0002 / MB |

## filter

Keep rows matching a **structured predicate** — a tree of `{ column, op, value }` leaves combined with `and` / `or` / `not`. Ops: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `startsWith`, `endsWith`, `in`, `isNull`, `notNull`. Comparisons are value-typed (numeric when both sides parse as numbers, else string). There is **no expression string** — a `value` is always a literal compared against your cell data, never executed — so the predicate is safe by construction.

```json
POST /v1/data/filter
{ "file": {"inline":"<b64>"},
  "where": { "and": [ {"column":"status","op":"eq","value":"active"},
                      {"column":"age","op":"gte","value":18} ] } }
```

## sort

Sort by one or more columns. Each key is `{ column, dir?: "asc"|"desc", type?: "string"|"number" }`.

```json
POST /v1/data/sort
{ "file": {"inline":"<b64>"}, "by": [ {"column":"age","dir":"desc","type":"number"} ] }
```

## groupby

Group by one or more columns and apply named aggregate functions — `count`, `sum`, `avg`, `min`, `max`, `first`, `last`. `count` needs no column; the rest require one. Name an aggregate with `as`.

```json
POST /v1/data/groupby
{ "file": {"inline":"<b64>"}, "by": ["country"],
  "aggregate": [ {"fn":"count","as":"n"}, {"column":"spend","fn":"sum","as":"total"} ] }
```

## join

Join two tables on one or more key pairs. `how` is `inner` (default), `left`, `right`, or `outer`. Pass `left` and `right` as input sources and `on` as `[{ "left": "...", "right": "..." }]`.

```json
POST /v1/data/join
{ "left": {"inline":"<b64>"}, "right": {"inputKey":"..."},
  "on": [ {"left":"id","right":"user_id"} ], "how": "left" }
```

## union

Concatenate two or more tables, preserving row order; the output schema is the ordered union of all columns (missing cells come back empty).

```json
POST /v1/data/union
{ "files": [ {"inline":"<b64>"}, {"inline":"<b64>"} ] }
```

## profile

A read-only data-quality report: per column the inferred type, row/null counts, distinct count, min/max, numeric mean, and the top values. Returns JSON.

```json
POST /v1/data/profile
{ "file": {"inline":"<b64>"} }
```

## cast

Coerce named columns to a target type — `string`, `integer`, `number`, `boolean`, or `date`. Best-effort: a value that can't be coerced becomes null (the cell isn't dropped).

```json
POST /v1/data/cast
{ "file": {"inline":"<b64>"}, "columns": [ {"column":"age","to":"integer"}, {"column":"joined","to":"date"} ] }
```

## pivot

Reshape between long and wide. `mode: "pivot"` spreads a column's values into new columns — `{ index: [...], columns: "<col>", values: "<col>", agg?: count|sum|avg|min|max }`. `mode: "unpivot"` melts columns into key/value rows — `{ id: [...], value?: [...] }`.

```json
POST /v1/data/pivot
{ "file": {"inline":"<b64>"}, "mode": "pivot",
  "index": ["country"], "columns": "quarter", "values": "spend", "agg": "sum" }
```

## schema-infer

Infer each column's type from the data and emit a schema. `dialect: "json-schema"` (default) returns a JSON Schema; `dialect: "sql-ddl"` returns a `CREATE TABLE` statement. Returns JSON/text.

```json
POST /v1/data/schema-infer
{ "file": {"inline":"<b64>"}, "dialect": "sql-ddl" }
```

## validate

Check each row against a **structured schema** — per column `{ type, required?, min?, max?, pattern? }`. `pattern` is a bounded, length-capped regular expression matched against the cell string (it is **not** executable code). Returns `{ valid, rowCount, errorCount, errors: [{row, column, reason}] }`.

```json
POST /v1/data/validate
{ "file": {"inline":"<b64>"},
  "schema": { "email": {"type":"string","required":true,"pattern":"^[^@]+@[^@]+$"},
              "age": {"type":"integer","min":0,"max":120} } }
```

## diff

Row-level changeset between two tables. Pass `left` and `right` as input sources and optional `key` columns (omit to compare whole rows). Returns `{ added, removed, changed: [{key, before, after}] }`.

```json
POST /v1/data/diff
{ "left": {"inline":"<b64>"}, "right": {"inputKey":"..."}, "key": ["id"] }
```

## from-xlsx

Parse an Excel workbook into a table. `sheet` (name or index, default the first) picks the sheet; `to` is the output format. The first row is the header, and cell **values** are read — formulas are never evaluated. A workbook over the cell-count cap is rejected pre-charge.

```json
POST /v1/data/from-xlsx
{ "file": {"inputKey":"..."}, "sheet": 0, "to": "json" }
```

## to-xlsx

Write a table to an Excel `.xlsx`. Any cell whose value starts with `= + - @` is written as **text**, so a payload can't become an active formula when the file is opened — formula-injection-safe, and it round-trips cleanly.

```json
POST /v1/data/to-xlsx
{ "file": {"inline":"<b64 csv>"}, "sheetName": "Export" }
```

**Multi-sheet workbooks.** Instead of a single `file`, pass a `sheets` array (≤ 20) — each entry is `{ name, file, from? }` with its own tabular source, written to its own tab. Provide **exactly one** of `file` or `sheets`. Multi-sheet billing sums every sheet's input bytes.

**Styling.** An optional `style` object applies to the workbook: `headerBold`, `freezeHeader`, `columnWidths` (an array by index or an object keyed by column name), and `numberFormats` (per-column Excel format strings like `"#,##0.00"`, `"yyyy-mm-dd"`, `"@"`).

```json
POST /v1/data/to-xlsx
{ "sheets": [
    { "name": "Sales", "file": {"inline":"<b64 csv>"} },
    { "name": "Costs", "file": {"inputKey":"..."}, "from": "json" }
  ],
  "style": { "headerBold": true, "freezeHeader": true, "numberFormats": { "amount": "#,##0.00" } } }
```

The result is binary `.xlsx` in the uniform output envelope — see [Passing & receiving files](/docs/receiving-outputs).

## derive

Add computed columns from a **structured expression** — no formula string, no eval. Each column is `{ name, expr }` where `expr` is `{col}` | `{lit}` | `{op, args}`: arithmetic (`add`/`sub`/`mul`/`div`/`mod`/`abs`/`round`), string (`concat`/`upper`/`lower`/`trim`/`substring`), `coalesce`, and comparisons. Values are literals; ops are an allowlist; nothing is executed.

```json
POST /v1/data/derive
{ "file": {"inline":"<b64>"},
  "columns": [ {"name":"total","expr":{"op":"mul","args":[{"col":"qty"},{"col":"price"}]}} ] }
```

## fillna

Fill empty / null cells. `value` is a literal, or one of `ffill` / `bfill` / `mean` / `median` / `mode`. Restrict to `columns`, or apply to all.

```json
POST /v1/data/fillna
{ "file": {"inline":"<b64>"}, "columns": ["spend"], "value": 0 }
```

## dropna

Drop rows with empty cells. `how: "any"` (default) drops a row if any of the named `columns` is empty; `"all"` only if all are.

```json
POST /v1/data/dropna
{ "file": {"inline":"<b64>"}, "columns": ["email"], "how": "any" }
```

## rename

Rename columns. Each pair is `{ from, to }`; a reserved or duplicate target → 422.

```json
POST /v1/data/rename
{ "file": {"inline":"<b64>"}, "columns": [ {"from":"col1","to":"name"} ] }
```

## slice

Row slicing / sampling — `offset` + `limit`, `head` (first n), `tail` (last n), or `sample` (random n).

```json
POST /v1/data/slice
{ "file": {"inline":"<b64>"}, "head": 100 }
```

## explode

Unnest one cell's array/list into multiple rows (one per element). Default reads a JSON array; pass `separator` to split a delimited string instead.

```json
POST /v1/data/explode
{ "file": {"inline":"<b64>"}, "column": "tags" }
```

## sample

Sample rows from a dataset — pass **exactly one** of `n` (an exact count) or `fraction` (0–1, a share of the rows). `method` is `random` (default), `head` (first n), or `systematic` (every step-th row). Pass a `seed` for **reproducible** random draws — the same seed over the same input returns a byte-identical sample. The result preserves original row order. Billed per MB of input.

```json
POST /v1/data/sample
{ "file": {"inline":"<b64>"}, "fraction": 0.1, "seed": 42 }
```

(`data/slice` also has a bare `sample` parameter for a one-off random count; `data/sample` is the richer tool — fractions, methods, and the reproducible seed.)

## Sample

```bash
curl -X POST https://api.relaystation.ai/v1/data/groupby \
  -H 'X-Payment: <base64 EIP-3009 auth>' \
  -H 'Idempotency-Key: rollup-by-country-20260609' \
  -H 'Content-Type: application/json' \
  -d '{"file":{"inline":"Y291bnRyeSxzcGVuZApVUywxMApVUyw1CkRFLDcK"},"by":["country"],"aggregate":[{"fn":"count","as":"n"},{"column":"spend","fn":"sum","as":"total"}]}'
```

## Errors

- `402 PAYMENT_REQUIRED` — no valid payment.
- `422 DATA_PARSE_FAILED` — malformed input. Rejected **before** any charge.
- `422 UNKNOWN_COLUMN` — a referenced column isn't in the data (the response lists the offenders).
- `422 PREDICATE_TOO_DEEP` — a `filter` `where` nests past the depth cap.
- `422 BAD_AGGREGATE` — an unknown aggregate function, a missing/duplicate output name, or a reserved name.
- `422 BAD_PATTERN` — a `validate` `pattern` isn't a valid bounded regular expression.
- `422 XLSX_TOO_LARGE` — a `from-xlsx` workbook exceeds the cell-count cap (`cputools.data.max_xlsx_cells`).
- `422 BAD_EXPRESSION` — a `derive` expression uses an unknown op or references a missing column.
- `413 OUTPUT_TOO_LARGE` — a `join`/`union`/`groupby`/`pivot` result exceeds the output-byte cap (the cartesian-blowup guard); the charge is refunded.

## Next

[Data — SQL](/docs/data-sql) · [Pipeline](/docs/pipeline) · [CSV tools](/docs/csv-tools) · [Pricing](/pricing) · [API reference](/api-reference)

## /docs/text-tools

# Text tools

Eleven in-process string & document utilities — pure JavaScript, the same open-source libraries you could run yourself ([`jsdiff`](https://github.com/kpdecker/jsdiff), [`node-diff3`](https://github.com/bhousel/node-diff3), [`marked`](https://marked.js.org/), [`sanitize-html`](https://github.com/apostrophecms/sanitize-html), [`html-to-text`](https://github.com/html-to-text/node-html-to-text)). Every op is a `POST https://api.relaystation.ai/v1/text/<op>` and returns a small **JSON object** — there is no file output.

## Inputs

Most ops take **either** an inline `text` string **or** a `file` input source — `{ "inline": "<base64>" }` (≤ 4 MB) or `{ "inputKey": "..." }` (from `POST /v1/cputools/upload-url`, ≤ 50 MB) — exactly one. `diff` takes two strings `a` / `b`; `apply-patch` takes `source` + `patch`; `merge3` takes `base` / `yours` / `theirs`; `template` takes a `template` string + a `data` object.

## Billing

Every op bills **per MB of input** (min 1 MiB) at `cputools.price.text.<op>.per_mb_micros` (launch default $0.0002 / MB — a placeholder the operator tunes). The live `402` challenge is authoritative.

| Op | Billed on | Rate |
|---|---|---|
| `case` | input MB | $0.0002 / MB |
| `slugify` | input MB | $0.0002 / MB |
| `diff` | input MB (a+b) | $0.0002 / MB |
| `apply-patch` | input MB (source+patch) | $0.0002 / MB |
| `merge3` | input MB (base+yours+theirs) | $0.0002 / MB |
| `count` | input MB | $0.0002 / MB |
| `regex-extract` | input MB | $0.0002 / MB |
| `template` | input MB | $0.0002 / MB |
| `markdown-to-html` | input MB | $0.0002 / MB |
| `html-to-text` | input MB | $0.0002 / MB |
| `sanitize-html` | input MB | $0.0002 / MB |

## case

Recase text. `to` is one of `upper` / `lower` / `title` / `camel` / `snake` / `kebab`. Returns `{ result }`.

```json
POST /v1/text/case
{ "text": "hello world", "to": "snake" }
```

## slugify

URL-slugify: lowercase, strip diacritics, collapse non-alphanumeric to the separator (default `-`). Returns `{ slug }`.

```json
POST /v1/text/slugify
{ "text": "Héllo, World!" }
```

## diff

Unified diff of two strings (`a` vs `b`). Returns `{ patch, changed }`.

```json
POST /v1/text/diff
{ "a": "line1\nline2\n", "b": "line1\nLINE2\n" }
```

## apply-patch

The inverse of `diff`: apply a unified diff (`patch`) to a `source` string. Pairs with `text/diff` — `diff` produces the patch, `apply-patch` consumes it. Returns `{ result }`. If the patch doesn't apply cleanly (context mismatch), the call returns `422 PATCH_CONFLICT` and the per-MB charge is refunded.

```json
POST /v1/text/apply-patch
{ "source": "line1\nline2\n", "patch": "--- a\n+++ b\n@@ -1,2 +1,2 @@\n line1\n-line2\n+LINE2\n" }
```

## merge3

Three-way merge of two divergent edits (`yours`, `theirs`) against a common ancestor (`base`) — the same model `git merge` uses. Returns `{ merged, conflict }`. A clean merge returns the combined text with `conflict: false`; overlapping edits return the merged text **with conflict markers** (`<<<<<<<` / `|||||||` / `=======` / `>>>>>>>`) and `conflict: true` — the markers **are** the useful output, not an error.

```json
POST /v1/text/merge3
{ "base": "a\nb\nc\n", "yours": "a\nB\nc\n", "theirs": "a\nb\nC\n" }
```

## count

Count characters / words / lines + reading time. Returns `{ characters, charactersNoSpaces, words, lines, readingTimeMinutes }` (`wpm` default 200).

```json
POST /v1/text/count
{ "text": "one two three" }
```

## regex-extract

Extract regex matches. The pattern is **ReDoS-guarded**: a catastrophic-backtracking pattern is rejected (`422 UNSAFE_REGEX`), the input is byte-capped, and the match count is bounded. Returns `{ matches, count, truncated }`.

```json
POST /v1/text/regex-extract
{ "text": "a1 b2 c3", "pattern": "([a-z])(\\d)" }
```

## template

Render a **logic-less** mustache-subset template — **no eval, no expression evaluation**: `{{var}}` (HTML-escaped), `{{{raw}}}`, `{{#section}}…{{/section}}`, `{{^inverted}}…{{/inverted}}`. Lookups are own-property only (no prototype access). Returns `{ result }`.

```json
POST /v1/text/template
{ "template": "Hi {{name}}", "data": { "name": "Ada" } }
```

## markdown-to-html

Render Markdown (GFM) → HTML, **always run through the whitelist sanitizer** — a `<script>` in your markdown can never reach the output. Returns `{ html }`.

```json
POST /v1/text/markdown-to-html
{ "text": "# Title\n\n**bold**" }
```

## html-to-text

Convert HTML → plain text. Returns `{ text }` (`wordwrap` default 80; pass `false` to disable).

```json
POST /v1/text/html-to-text
{ "text": "<h1>Hi</h1><p>there</p>" }
```

## sanitize-html

Sanitize HTML against a safe whitelist — drops `<script>`, event handlers, and `javascript:`/`data:` schemes (http/https/mailto only). Returns `{ html }`.

```json
POST /v1/text/sanitize-html
{ "text": "<p onclick=\"x()\">ok</p><script>bad()</script>" }
```

## /docs/codes-tools

# Codes tools — decode & color

Two in-process readers that complement the [QR/barcode generators](/docs/cputools-qr-tools). Pure JavaScript ([`jsqr`](https://github.com/cozmo/jsQR) over a [`sharp`](https://sharp.pixelplumbing.com/) decode; color math is plain arithmetic). Each is a `POST https://api.relaystation.ai/v1/codes/<op>` returning a small **JSON object**.

## Billing

Both are **flat** at `cputools.price.codes.<op>.flat_micros` (launch default $0.0002 / call — a placeholder the operator tunes). The live `402` challenge is authoritative.

| Op | Billed on | Rate |
|---|---|---|
| `qr-decode` | per call | $0.0002 flat |
| `color-convert` | per call | $0.0002 flat |

## qr-decode

Read a QR code from an uploaded image. Body: `{ file: <source> }` (inline base64 ≤ 4 MB or an `inputKey` from `/v1/cputools/upload-url`). A non-decodable image is a **paid** `{ found: false }`; a non-image input is a free `422`. Returns `{ found, data?, version? }`.

```json
POST /v1/codes/qr-decode
{ "file": { "inline": "<base64 PNG/JPEG>" } }
```

## color-convert

Convert a color between `hex`, `rgb`, and `hsl` (including alpha forms — `#rrggbbaa`, `rgba()`, `hsla()`). Body: `{ color, to }`. Unrecognized input → `422 COLOR_INVALID`. Returns `{ input, to, result, rgb }`.

```json
POST /v1/codes/color-convert
{ "color": "#ff8800", "to": "hsl" }
```

> **Not yet:** 1D **barcode decoding** is deferred — there's no clean pure-JS Node decoder (the common libraries need a browser DOM or a WASM binary). Barcode **generation** ships today at `/v1/barcode`.

## /docs/data-sql

# Data — SQL

`POST https://api.relaystation.ai/v1/data/sql` runs **full SQL over your uploaded file** — a real [DuckDB](https://duckdb.org/) engine, not a partial dialect. Upload a CSV/JSON, send a `SELECT`, get the result back. The power of a database with the simplicity of one stateless call.

## Sandboxed by design

The engine is the selling point — and so is the cage around it. Your SQL runs against your file and **nothing else**: the engine is locked **read-only with external access disabled** before your query runs, so it cannot read other files, reach the network (no `httpfs` / SSRF), write files, install or load extensions, or attach other databases. Your query sees exactly one table — `input`, loaded from your upload — and the full DuckDB SQL surface over it (joins, window functions, CTEs, aggregates). Powerful *and* safe.

## Inputs and outputs

Body: `{ file, sql, from?, to? }`. The `file` is an **input source** — `{ "inline": "<base64>" }` (≤ 4 MB) or `{ "inputKey": "..." }` (≤ 50 MB, from `POST /v1/cputools/upload-url`). `from` is the input format (`csv` default, `json`, `ndjson`, `parquet`); `to` is the result format (`csv` default, `json`, `parquet`). Your file is loaded as the table **`input`** — write `... FROM input`. The result comes back in the uniform output envelope.

### Parquet, in and out

DuckDB reads [**Parquet**](https://parquet.apache.org/) directly — pass `from: "parquet"` to query a columnar file with the same `SELECT ... FROM input`. And `to: "parquet"` emits a **binary Parquet** result: `csv`/`json` results return as inline text, but Parquet is binary, so it rides the storage-ref output envelope (`{ output: { outputKey, outputUrl, … } }`) — see [Passing & receiving files](/docs/receiving-outputs). The Parquet file is produced by a **safe two-step** that never touches the read-only user-SQL sandbox, so the sandbox guarantees above hold unchanged.

A handy shape: `{ from: "csv", to: "parquet", sql: "SELECT * FROM input" }` is a one-call CSV→Parquet conversion (and `from: "parquet", to: "csv"` the reverse). Gzipped inputs are handled transparently — a gzip-compressed `csv`, `json`, or `ndjson` upload is detected by its magic bytes and decompressed before the query, no extra flag needed.

## Billing

Per-MB of input, **minimum 1 MiB**, at `cputools.price.data.sql.per_mb_micros` (launch default **$0.0005 / MB** — a higher tier than the in-process ops, since the query runs on the vendored DuckDB worker). The live `402` challenge is authoritative.

## Query

```json
POST /v1/data/sql
{ "file": {"inline":"<b64 csv>"},
  "sql": "SELECT country, count(*) AS n, sum(spend) AS total FROM input GROUP BY country ORDER BY total DESC",
  "to": "json" }
```

## Sample

```bash
curl -X POST https://api.relaystation.ai/v1/data/sql \
  -H 'X-Payment: <base64 EIP-3009 auth>' \
  -H 'Idempotency-Key: top-countries-20260609' \
  -H 'Content-Type: application/json' \
  -d '{"file":{"inline":"Y291bnRyeSxzcGVuZApVUywxMApVUyw1CkRFLDcK"},"sql":"SELECT country, sum(spend) AS total FROM input GROUP BY country ORDER BY total DESC","to":"json"}'
```

## Caps

Operator-tunable, enforced per call: a memory limit (`cputools.data.sql.memory_limit_mb`), a wall-clock timeout (`cputools.data.sql.timeout_ms`, default ~25 s — a query that runs long is killed), an output-size cap (`cputools.data.sql.max_output_bytes`, 128 MiB — a larger result returns `413`), a thread cap, and an SQL-length cap. These bound a runaway or oversized query; the engine sandbox (above) bounds what the query can reach.

## Errors

- `402 PAYMENT_REQUIRED` — no valid payment.
- `422 SQL_INVALID` — a SQL syntax/semantic error (the DuckDB message is surfaced; your data is never echoed). Includes any attempt to use a blocked capability (file/network/extension) — the sandbox denies it.
- `413 OUTPUT_TOO_LARGE` — the result exceeds the output cap (incl. a large `to: "parquet"` result).
- A query that exceeds the time or memory limit is terminated and the charge refunded.

## Next

[Data tools](/docs/data-tools) · [Pipeline](/docs/pipeline) · [Pricing](/pricing) · [API reference](/api-reference)

## /docs/pipeline

# Pipeline

`POST https://api.relaystation.ai/v1/pipeline` runs a **sequence of transforms in one call**. Send a file and a list of steps; the pipeline feeds each step's output into the next and returns the final result — no intermediate round-trips, no orchestration on your side. This is what turns the cputools catalog from a list of operations into a composable transform runtime.

## How it works

```json
POST /v1/pipeline
{ "file": {"inline":"<b64>"},
  "steps": [
    { "op": "data.filter",  "args": { "where": {"column":"status","op":"eq","value":"active"} } },
    { "op": "data.groupby", "args": { "by": ["country"], "aggregate": [{"fn":"count","as":"n"}] } },
    { "op": "csv.convert",  "args": { "to": "json" } }
  ],
  "to": "json" }
```

Each step is `{ "op": "<category>.<op>", "args": { ... } }` — the op's normal arguments, minus the `file` (the data is threaded for you). Steps run **in order**, left to right; the final `to` sets the output format.

## The composable op set

The pipeline composes the in-process single-stream ops — tabular **and** binary:

- **csv** — `csv.convert`, `csv.dedupe`, `csv.select`
- **data** — `data.filter`, `data.sort`, `data.groupby`, `data.cast`, `data.pivot`, `data.derive`, `data.fillna`, `data.dropna`, `data.rename`, `data.slice`, `data.explode`, plus the **Excel bridges** `data.from-xlsx` / `data.to-xlsx` (and `data.profile`, `data.validate`, `data.schema-infer` as final, report-producing steps)
- **image** — `image.resize`, `image.convert`, `image.compress`, `image.rotate` (chain image transforms in one call)
- **utils** — `utils.base64`
- **archive** — `archive.gzip`

Steps thread bytes, so a chain stays within a data type — a tabular chain, an image chain, or an **Excel-in/Excel-out** chain (`from-xlsx → … → to-xlsx`). Multi-input ops (`data.join`, `data.union`, `data.diff`), the SQL engine (`data.sql`), and the worker-backed PDF ops aren't composable in a pipeline — use them as standalone calls.

## Billing

One charge: **the sum of the steps**. Each step is priced at its normal per-op rate (read live from the same `cputools.price.*` tunables the standalone ops use), plus an orchestration fee (`cputools.price.pipeline.run.flat_micros`, default $0). A three-step pipeline on a 5 MB file is `Σ (step rate × 5 MiB) + fee`. An unauthenticated `POST` returns the exact summed price as a `402` challenge — quote before you pay.

## Atomic

A pipeline is all-or-nothing: if any step fails (an unknown column, a malformed intermediate, an over-cap result), the whole call fails and the charge is **refunded**. You never pay for a partial run.

## Caps

Operator-tunable: `cputools.pipeline.max_steps` (default 10) bounds the chain length; `cputools.pipeline.max_intermediate_bytes` (128 MiB) bounds the data threaded between steps — a step whose output crosses it returns `413` and refunds.

## Errors

- `402 PAYMENT_REQUIRED` — no valid payment.
- `422 OP_NOT_COMPOSABLE` — a step names an op that isn't in the composable set.
- `422 TERMINAL_STEP_NOT_LAST` — a report op (`data.profile`) appears before the last step.
- `422` (step-level) — a step's own validation error (e.g. `UNKNOWN_COLUMN`) surfaces from that step; the charge is refunded.
- `413 INTERMEDIATE_TOO_LARGE` — a step's output exceeds the intermediate cap.

## Next

[Data tools](/docs/data-tools) · [Data — SQL](/docs/data-sql) · [CSV tools](/docs/csv-tools) · [Pricing](/pricing) · [API reference](/api-reference)

## /docs/cputools-mcp-tools

# MCP tools

**One endpoint, the whole Relaystation toolkit.** Point your MCP client at

```
https://api.relaystation.ai/mcp
```

and your agent sees the entire cputools catalog — 88 tools across PDF, CSV, image, codes, utils, generate, archive, data, text, and pipeline — alongside Relaystation's other primitives (e-sign, ID verification, Courier messaging, chassis), all funded from **one balance** with **one API key** (the shared endpoint surfaces 129 tools in total). No separate endpoint per product; no per-tool signup. Same auth, same per-call prices as the HTTP API — the MCP tool call runs the identical billing path, so you pay exactly what the route charges.

## The cputools tools

Each tool's manifest `description` states its billing unit, the launch price, and its caps, and notes that an unauthenticated probe returns a live `402` price quote — so your agent can choose and budget without leaving the client. Every file-taking tool accepts `{ inline }` base64 (≤ 4 MB) or `{ inputKey }` from `cputools_upload_url` (≤ 50 MB).

**PDF** — `pdf_merge`, `pdf_split`, `pdf_rotate`, `pdf_pages`, `pdf_watermark`, `pdf_form` ($0.001/page); `pdf_extract_text` ($0.002/page); `pdf_metadata` ($0.001 flat); `pdf_encrypt`, `pdf_compress` ($0.001/page); `pdf_render` ($0.001/output page, ≤ 40 pages / ≤ 300 DPI); `pdf_ocr` ($0.003/page, ≤ 5 pages synchronous); `pdf_from_html` ($0.003 flat — HTML→PDF on a sandboxed headless Chromium: no network, no JS, inline assets only); `pdf_from_office` ($0.005 flat — Office→PDF via LibreOffice: docx/xlsx/pptx/odt/ods/odp/rtf/txt/csv, ≤ 30 MB, pay only for a delivered PDF); `pdf_images` ($0.001/page — extract embedded images, ≤ 200), `pdf_diff` ($0.001/page — text compare, billed on both); `pdf_bookmarks`, `pdf_attachments` ($0.001 flat — read outline / list-extract attachments).

**CSV** — `csv_convert`, `csv_dedupe`, `csv_select` ($0.0002/MB, min 1 MiB).

**Image** — `image_resize`, `image_convert`, `image_compress`, `image_rotate`, `image_crop`, `image_blur`, `image_sharpen`, `image_grayscale`, `image_exif_strip`, `image_composite`, `image_contact_sheet` ($0.0003/MP); `image_metadata`, `image_dominant_color` ($0.0005 flat).

**Codes** — `qr_generate`, `barcode_generate`, `codes_qr_decode`, `codes_color_convert` ($0.0002 flat; qr/barcode data ≤ 4096 chars).

**Utils** — `utils_hash`, `utils_hmac`, `utils_base64` ($0.0002/MB, min 1 MiB); `utils_uuid`, `utils_jwt_decode`, `utils_jwt_verify` ($0.0001 flat; uuid count ≤ 1000; jwt-verify is alg-pinned and never logs your key).

**Generate** — `generate_og_image` ($0.0005 flat, one OG template); `generate_mock_data`, `generate_invoice`, `generate_chart`, `generate_qr_logo`, `generate_favicon`, `generate_placeholder`, `generate_identicon` ($0.0002 flat; mock-data rows ≤ 1000 / fields ≤ 50; invoice ≤ 100 line items; chart ≤ 50 points; identicon is deterministic per seed).

**Archive** — `archive_zip`, `archive_unzip`, `archive_gzip` ($0.0002/MB of input, min 1 MiB; `archive_unzip` is zip-bomb-guarded — ≤ 128 MiB uncompressed, encrypted rejected, one level — and bills the compressed input).

**Data** — `data_filter`, `data_sort`, `data_groupby`, `data_join`, `data_union`, `data_profile`, `data_cast`, `data_pivot`, `data_schema_infer`, `data_validate`, `data_diff`, `data_from_xlsx`, `data_to_xlsx`, `data_derive`, `data_fillna`, `data_dropna`, `data_rename`, `data_slice`, `data_explode`, `data_sample` ($0.0002/MB, min 1 MiB; `data_from_xlsx`/`data_to_xlsx` are Excel in/out, `data_to_xlsx` formula-injection-safe; `data_filter`/`data_derive` are structured no-eval; `data_validate`'s pattern is a bounded regex; `data_join`/`data_union`/`data_diff` are output-byte-capped; `data_sample` takes n|fraction with a reproducible seed); `data_sql` ($0.0005/MB — full SQL on a sandboxed **read-only** DuckDB: no filesystem, network, or extension access).

**Text** — `text_case`, `text_slugify`, `text_diff`, `text_count`, `text_regex_extract`, `text_template`, `text_markdown_to_html`, `text_html_to_text`, `text_sanitize_html` ($0.0002/MB, min 1 MiB; `text_regex_extract` is ReDoS-guarded; `text_template` is no-eval; `text_markdown_to_html`/`text_sanitize_html` whitelist-sanitize the HTML — no script/`javascript:`/`data:`).

**Pipeline** — `pipeline_run` (compose a chain of cputools transforms in one call; threaded step-to-step; billed as the **sum of the steps**; atomic — a failed step refunds the whole run).

**Upload** — `cputools_upload_url` (free) mints a presigned POST for the > 4 MB path and returns an `inputKey` to pass to any file-taking tool.

`tools/list` on the endpoint also surfaces Relaystation's chassis + Courier tools, the e-sign (`esigndoc_*`) and ID-verification (`idverify_*`) product tools, and the `relaystation_products` meta-tool (which lists every Relaystation product MCP). One key, one balance, the whole set.

## Auth

A tool call carries your credential one of three ways, and inherits the same billing as the HTTP route (your balance is debited per call):

- **API key** — `Authorization: Bearer rs_live_<key>`, or `?key=rs_live_<key>` on the URL (handy for clients without a header field).
- **x402** — an `X-Payment` header per call (the no-account lodestone path).
- **OAuth agent-login** — the client runs the OAuth consent dance on connect; the resulting token carries the `products:call` scope.

`tools/list` is browsable as soon as any credential is present; billable tool calls debit the resolved customer.

## Install — Claude Code & Claude Desktop

In your config (`~/.config/claude-code/mcp.json`, the workspace `.mcp.json`, or Claude Desktop's `claude_desktop_config.json`), add:

```json
{
  "mcpServers": {
    "relaystation": {
      "url": "https://api.relaystation.ai/mcp",
      "headers": {
        "Authorization": "Bearer rs_live_<your-key>"
      }
    }
  }
}
```

Restart the client; the cputools roster appears alongside the rest of the Relaystation tools. Mint a key at [app.relaystation.ai](https://app.relaystation.ai) or via `POST /v1/account/keys`.

## Install — Cursor, Codex, Cline, Continue

The same MCP server URL applies. Each client has its own config location (Cursor: Settings → MCP; Codex: workspace config; Cline / Continue: extension settings), but the shape is identical — URL `https://api.relaystation.ai/mcp` plus the `Authorization: Bearer rs_live_<key>` header.

## Install — Cowork

In Cowork: **Settings → Connectors → Add connector.** Paste the URL with your key as a query parameter (Cowork's connector flow has no separate header field):

```
https://api.relaystation.ai/mcp?key=rs_live_<your-key>
```

Enable "always allow" and the cputools tools surface in Cowork's picker; tool calls land authenticated and debit your balance.

> **⚠️ Treat the whole URL as sensitive.** The `?key=` query string carries your `rs_live_*` credential, so anywhere the URL ends up — browser history, terminal scrollback, screenshots — is somewhere your key has been. If it leaks, revoke that key from the dashboard and mint a fresh one (your balance and cap are unaffected; only the leaked credential becomes invalid). Per-key daily spend caps bound the exposure.

## Chassis MCP concepts

The MCP protocol, authentication, and discovery model are shared across every Relaystation product and documented on the apex docs:

- [MCP](https://relaystation.ai/docs/mcp) — the Relaystation MCP service, manifest discovery, and the auth header shapes.
- [Authentication](https://relaystation.ai/docs/authentication) — API key, wallet JWT, and x402 per-call paths.
- [x402 wire format](https://relaystation.ai/docs/x402) — the per-call payment authorization.

## Next

[Overview](/docs/cputools-overview) · [PDF tools](/docs/pdf-tools) · [CSV tools](/docs/csv-tools) · [Image tools](/docs/image-tools) · [QR & barcode](/docs/qr-tools) · [Utils tools](/docs/utils-tools) · [Generate tools](/docs/generate-tools) · [Archive tools](/docs/archive-tools) · [Data tools](/docs/data-tools) · [Data — SQL](/docs/data-sql) · [Pipeline](/docs/pipeline) · [Pricing](/pricing) · [API reference](/api-reference)

## /docs/office

# Office tools

Two office surfaces, one engine (LibreOffice via Gotenberg), output always **PDF**:

- **`POST /v1/office/rescue`** — best-effort convert an *exotic or legacy* office format to PDF. The formats LibreOffice can import but you won't reach through the everyday [`from-office`](/docs/pdf-tools) route: Apple iWork, Visio, Publisher, CorelDRAW, WordPerfect, the legacy MS binaries, and flat ODF.
- **`GET /v1/office/formats`** — the free, no-auth roster of what each office route accepts.

The everyday office formats (`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`, `rtf`, `txt`, `csv`) go through [`POST /v1/pdf/from-office`](/docs/pdf-tools). `office/rescue` is the premium best-effort surface for the long-tail formats around it.

> **Fidelity is best-effort.** These are exotic, sometimes proprietary, sometimes very old formats. LibreOffice does its best to import them, and you get a clean PDF — but complex layout, fonts, or vector detail may not survive perfectly. The output is always a faithful-as-possible PDF, never a guarantee of pixel parity. And **office↔office conversion (e.g. docx↔odt) is not offered** — every office route outputs PDF.

## Rescue a legacy or exotic document

```bash
curl -X POST https://api.relaystation.ai/v1/office/rescue \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: rescue-visio-20260612' \
  -H 'Content-Type: application/json' \
  -d '{ "file": { "inline": "<base64 vsdx>" }, "filename": "network-diagram.vsdx" }'
```

Or on the lodestone path — no account, a signed x402 payment instead of an API key:

```bash
curl -X POST https://api.relaystation.ai/v1/office/rescue \
  -H 'X-Payment: <base64 EIP-3009 authorization>' \
  -H 'Idempotency-Key: rescue-visio-20260612' \
  -H 'Content-Type: application/json' \
  -d '{ "file": { "inline": "<base64 vsdx>" }, "filename": "network-diagram.vsdx" }'
```

The `filename` is required — its extension is how the format is recognized. Takes the standard input source (`{ "inline": "<b64>" }` ≤ 4 MB, or `{ "inputKey": "..." }` from [`POST /v1/cputools/upload-url`](/docs/receiving-outputs) for larger files) and returns the standard [output envelope](/docs/receiving-outputs) — a PDF inline when small, a presigned URL when large.

## The rescue roster

The default exotic/legacy roster (operator-tunable, so it can flex without a redeploy):

| Family | Extensions |
|---|---|
| Apple iWork | `pages`, `numbers`, `key` |
| Visio | `vsd`, `vsdx` |
| MS Publisher | `pub` |
| CorelDRAW | `cdr` |
| Flat ODF | `fodt` |
| Legacy MS Office binaries | `doc`, `xls`, `ppt` |
| WordPerfect | `wpd` |

`GET /v1/office/formats` is always authoritative. Free, read-only, no auth:

```bash
curl https://api.relaystation.ai/v1/office/formats
```

It returns the rescue roster and the everyday from-office roster, each with its output (`pdf`), plus a note that office↔office conversion is not offered:

```json
{
  "rescue": { "inputs": ["pages", "numbers", "key", "vsd", "vsdx", "pub", "cdr", "fodt", "doc", "xls", "ppt", "wpd"], "output": "pdf" },
  "fromOffice": { "inputs": ["docx", "xlsx", "pptx", "odt", "ods", "odp", "rtf", "txt", "csv"], "output": "pdf" },
  "note": "office↔office conversion (e.g. docx↔odt) is not offered; all office routes output PDF."
}
```

An extension outside the roster returns a free `422 UNSUPPORTED_FORMAT` that points you at `GET /v1/office/formats`.

## Export controls (from-office and rescue)

Both `POST /v1/pdf/from-office` and `POST /v1/office/rescue` accept an optional `options` object passed straight to LibreOffice's PDF export — absent fields take the engine default:

| Field | Type | Notes |
|---|---|---|
| `pageRanges` | string | a page subset, e.g. `"1-5,8"` |
| `quality` | integer 1–100 | JPEG quality for embedded images |
| `losslessImageCompression` | boolean | use lossless image compression |
| `reduceImageResolution` | boolean | gate for `maxImageResolution` — must be `true` for it to apply |
| `maxImageResolution` | one of `75`, `150`, `300`, `600`, `1200` | DPI ceiling for embedded images (a closed ladder; other values are rejected) |
| `landscape` | boolean | force landscape orientation |

```bash
curl -X POST https://api.relaystation.ai/v1/pdf/from-office \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: print-ready-20260612' \
  -H 'Content-Type: application/json' \
  -d '{ "file": { "inputKey": "<key>" }, "filename": "q3-report.docx",
        "options": { "pageRanges": "1-10", "reduceImageResolution": true, "maxImageResolution": 150, "landscape": true } }'
```

## Billing

| Route | Unit | Price |
|---|---|---|
| `office/rescue` | per call | $0.008 flat |
| `from-office` | per call | $0.005 flat |
| `office/formats` | — | free |

Rescue is priced a step above the everyday `from-office` route — it's heavier, best-effort work. Both are flat per convert (the output page count isn't known before the conversion runs). **Charge-on-attempt** — a convert that reaches the engine and succeeds stands; one that can't be delivered (a corrupt file, an upstream failure) returns `422 CONVERT_FAILED` and the charge is reversed: you pay only for a delivered PDF. Every billable call requires an `Idempotency-Key`; a same-key retry returns the cached result without re-charging.

## MCP tools

Callable over MCP at `https://api.relaystation.ai/mcp`: `office_rescue` (billable) and `office_formats` (free, read-only), plus `pdf_from_office` (the everyday route). Same auth, same prices as the HTTP routes.

## Next

[Quickstart](/docs/quickstart) · [Passing & receiving files](/docs/receiving-outputs) · [PDF tools](/docs/pdf-tools) · [Document conversion](/docs/doc-convert) · [API reference](/api-reference)

## /docs/receiving-outputs

# Passing & receiving files

Every file-taking or file-producing op on Relaystation uses the **same I/O model**. You pick how to pass (or receive) the bytes per call — there is no setup step and no required storage product. Compute is priced per op on the metered input **regardless of where the bytes came from**.

## Passing a file in

Three ways to hand an op its input, picked per call:

- **Inline** — up to **4 MiB** (decoded), pass `{ "inline": "<base64>" }` as the op's file field. Nothing is stored; nothing to clean up.
- **Scratch** — for files over 4 MiB, or whenever you'd rather upload once and reuse:
  1. `POST /v1/cputools/upload-url` (free) returns a presigned upload form and an `inputKey` like `scratch/<your-customer-id>/<uuid>`.
  2. Upload your file (up to **50 MB**) with one multipart POST to that URL.
  3. Pass `{ "inputKey": "..." }` as any op's file field — as many ops, as many times as you like, for **24 hours**.
  Scratch keys are namespaced to your customer identity: another customer's key — even if leaked — resolves to `404` for you, and yours for them. The same gate admits all auth paths (API key, wallet-JWT, or a signed x402 payment), so an account-less agent can use scratch too.
- **A baton** — pass `{ "batonId": "bat_…" }` (optionally `{ "batonId": "bat_…", "entryRef": { "sequenceNumber": N } }` to select one append entry) to read a [baton](https://relaystation.ai/docs/batons) as the op's input. The op's **compute charge** applies exactly as for any other input; the baton's **storage/egress** draw down the **prepaid quota** you bought at create and appear as byte-denominated quota events, never as a second money charge.

> **Baton input works on HTTP and MCP.** `{ "batonId": … }` is a first-class input source on both the HTTP API and the MCP cputools tools (and `deliver` lands an op's output into a baton on both). Ownership is enforced identically on either surface — a baton you don't own resolves to `404`.

## Getting results back

Every binary-producing op returns the same envelope. Small results arrive **inline** (the gate is the base64-encoded size against a 4 MiB threshold — raw outputs up to ~3 MiB, since base64 inflates ~1.37×); larger ones land in your free 24-hour scratch and arrive as a key + a link:

```json
{ "output": { "inline": "<base64>", "sizeBytes": 51234, "contentType": "application/pdf", "filename": "converted.pdf" } }
{ "output": { "outputKey": "scratch/<you>/<uuid>", "outputUrl": "https://…presigned, valid 1 hour…", "sizeBytes": 12023329, "contentType": "image/png" } }
```

Handle both shapes and you handle every op. Recipes per client:

### curl / shell — to disk

```bash
RESP=$(curl -s -X POST https://api.relaystation.ai/v1/pdf/merge \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -d @payload.json)

if echo "$RESP" | jq -e '.output.inline' > /dev/null; then
  echo "$RESP" | jq -r '.output.inline' | base64 -d > result.pdf
else
  curl -s -o result.pdf "$(echo "$RESP" | jq -r '.output.outputUrl')"
fi
```

The `outputUrl` is presigned — no auth header on that GET (and don't send one; it's a direct storage URL, not an API route).

### Code (fetch) — in an agent sandbox

```js
const { output } = await (await fetch(url, opts)).json();
const bytes = output.inline
  ? Buffer.from(output.inline, 'base64')
  : Buffer.from(await (await fetch(output.outputUrl)).arrayBuffer());
```

If your sandbox blocks outbound domains, allow the API host **and** the storage host the `outputUrl` points at (it is a different domain).

### Chat-based clients (MCP) — present the link

In chat clients the tool result is JSON in the conversation; nobody wants 12 MB of base64 there. For large outputs, surface `outputUrl` to the human as a download link — it works in a browser for one hour. If the session outlives the link, re-fetch a fresh one (below) or chain the `outputKey` into a durable [baton](https://relaystation.ai/docs/batons) when the result must persist.

MCP tool results for a stored binary output also carry a **`resource_link`** content block alongside the JSON — `{ "type": "resource_link", "uri": "<presigned URL>", "name": "<filename>", "mimeType": "<contentType>" }` (MCP spec 2025-06). A client that understands resource links can offer the download directly; one that doesn't simply ignores the extra block — the JSON (and `structuredContent`) still carry `outputKey` + `outputUrl`, so nothing is lost.

### Re-fetching a stored output

The `outputUrl` an op returns expires in an hour. To get a **fresh** link for the same object without re-running the op, call:

```bash
curl -s https://api.relaystation.ai/v1/outputs/scratch/<you>/<uuid> \
  -H "Authorization: Bearer $KEY"
# → { "outputKey", "url": "<fresh presigned GET, 1 hour>", "sizeBytes", "contentType", "expiresAt" }
```

This works for as long as the scratch object lives (24 hours), then returns `404`. It is **free**, and ownership-gated: you can only re-fetch keys under your own `scratch/<you>/` namespace — anyone else's key (or an aged-out one) returns `404`, never a hint that it exists. The `url` it returns is the immediate download; `outputUrl` from the original response stays valid for its hour too.

## Chaining: outputKey is an inputKey

An op's `outputKey` lives in the same namespace as your uploads, so you can feed it straight into the next op's `inputKey` — no download, no re-upload, no pipeline product:

```bash
# 1. Upload once (12 MB scan) → inputKey
curl -s -X POST https://api.relaystation.ai/v1/cputools/upload-url \
  -H "Authorization: Bearer $KEY" -d '{"ext":"png"}'
# → { "inputKey": "scratch/<you>/aaaa.png", "url": ..., "fields": {...} }  (multipart-POST the file to url+fields)

# 2. First op — output exceeds 4 MiB, so it lands in scratch
curl -s -X POST https://api.relaystation.ai/v1/image/convert \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"file":{"inputKey":"scratch/<you>/aaaa.png"},"format":"png"}'
# → { "output": { "outputKey": "scratch/<you>/bbbb", ... } }

# 3. Chain — the outputKey IS the next inputKey
curl -s -X POST https://api.relaystation.ai/v1/image/metadata \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"file":{"inputKey":"scratch/<you>/bbbb"}}'
```

Each step is its own pay-per-call op with its own receipt. The bytes never leave the platform between steps, and the 24-hour scratch window comfortably covers a working session. (For chaining the *tabular* ops — filter, sort, join, SQL — in a single call, see [`POST /v1/pipeline`](https://cputools.relaystation.ai/docs/pipeline), which threads bytes step-to-step and bills the sum.)

## Delivering an output into a baton

Instead of receiving the bytes, you can have an op **deliver** its output straight into a [baton](https://relaystation.ai/docs/batons) — durable, shareable, witnessed:

- `"deliver": { "batonId": "bat_…" }` lands the output in an **existing** baton. That's **one** money charge (the op's compute) plus quota events for the storage drawn down — never a second charge for the same byte.
- `"deliver": { "new": { "preset": "drop", "tier": "nano" } }` creates a **fresh** baton (quoted exactly like [`POST /v1/baton`](https://relaystation.ai/docs/batons)) and lands the output in it. That's **two ledger lines** — the op's compute charge *and* the baton-create charge — both real, shown distinctly. The whole thing is one idempotent unit: a retried call with the same `Idempotency-Key` returns the original result *and* the original baton id, never a second baton or a second charge.

## Lifetimes

How long each thing lives:

- **`outputUrl`** (a presigned download link) — valid **1 hour** from the response.
- **`outputKey` / `inputKey`** (the scratch object behind it) — lives **24 hours**, then auto-deletes. Reusable across as many ops as you like inside that window.
- **Inline** bytes — never stored; they exist only for the one call.
- **A baton** — lives for the duration you configured at create. When a result must outlive the day — be **durable**, **shareable** (handed to another agent or a human via a token), or **witnessed** (tamper-evident, provable) — that's the baton tier, a paid product with its own quoted price, lifecycle, and trust options. Batons are optional, always: no op requires one, and the [lodestone path](https://relaystation.ai/docs/lodestone) never gains a mandatory storage step.

## Shared: cputools-faq

# cputools FAQ

### What is cputools?

A pay-per-call utility API for the CPU work your agent shouldn't host itself. PDF tools are live today — merge, split, rotate, page edits, watermark, form fill/flatten, text extraction, and metadata. Your agent sends a file and a payment, gets a result back, and never created an account. The roster grows over time: QR & barcodes, OCR, render-to-image, and Office→PDF are next.

### Do I need an account?

No. The lodestone path is one HTTPS call with an `X-Payment` header carrying an x402 (EIP-3009) authorization — no signup, no email, no deposit. The wallet that signs the payment is your identity, so your transaction history is there if you come back. If you'd rather fund from a prepaid balance, sign in via Google or GitHub and use a `Bearer rs_live_*` API key instead.

### How does pricing work — will I get a surprise bill?

You won't. Most PDF ops are $0.001 per page (extract-text $0.002, OCR $0.003, metadata $0.001 flat); CSV ops are $0.0002 per MB of input; image ops are $0.0003 per megapixel (metadata $0.0005 flat); QR and barcode are $0.0002 flat. Per-unit ops bill a minimum of one (one page / one MiB / one megapixel). There's no subscription, no minimum, and no commitment — you pay only for the calls you make, debited from your Relaystation balance, and an unauthenticated `POST` returns the exact price for a call before you pay. When the balance hits zero, calls return a `402` response — no overdraft, no auto-charge.

### How do I send a file bigger than 4 MB?

Inline base64 is capped at 4 MB (it travels in the JSON request body). For larger files, `POST /v1/cputools/upload-url` to mint a one-time, customer-scoped presigned upload; it returns `{ url, fields, inputKey, ... }`. Upload the bytes with a multipart/form-data `POST` to `url` (send every `fields` entry plus a `file` part), then pass `{"inputKey":"..."}` as the file instead of `{"inline":"..."}`. Results above the threshold come back the same way — as a presigned `outputUrl` instead of inline base64.

### What's the egress surcharge?

A small per-MB charge ($0.0002/MB) that applies **only** when an output is delivered by storage reference — the large-file presigned-GET path. It covers the AWS egress cost on big outputs. Inline outputs (≤ 4 MB, returned through the API) don't incur it. It's the only place cputools meters by size rather than by page.

### Can I call cputools over MCP?

Yes. The full cputools catalog — 24 tools (the 23 ops plus `cputools_upload_url`) — is callable over MCP at `https://api.relaystation.ai/mcp`, the same endpoint that carries Relaystation's Courier and chassis tools, all funded from one balance with one key. Drop the URL into Claude Code/Desktop, Cursor, Codex, Cline, Continue, or Cowork with a `Bearer rs_live_*` key. See the [MCP tools page](/docs/cputools-mcp-tools) for per-client config.

### What are the tools built on?

Open-source [pdf-lib](https://pdf-lib.js.org/) (manipulation) and [pdf.js](https://mozilla.github.io/pdf.js/) (text extraction) — pure JavaScript, no native binaries. These are tools you could self-host; cputools just runs them so you don't have to maintain the infrastructure, the Lambda layers, or the cold-start tax.

### How does cputools relate to the rest of Relaystation?

It's one product on the Relaystation chassis. One balance funds cputools, Courier, Baton, and every other Relaystation product — top up once via x402, Stripe, or a crypto wallet, and spend it anywhere. Same wallet-as-identity, same transparent ledger, same pay-per-call promise — no subscription, no minimum. [Relaystation docs →](https://relaystation.ai/docs)

### Is my file content private?

cputools is stateless: a file goes in, a result comes out, and scratch objects for the large-file path are short-lived and customer-scoped. We don't retain your documents to train anything or scan their contents for upsell targeting — that's forbidden regardless of revenue payoff, the same privacy stance as the rest of the Relaystation family.