HTTP API

The hosted tier is a plain HTTP API — usable from any language today, which is also how future R, Julia, and TypeScript clients will work. Base URL: https://api.attachments.dev/v1. No key needed on the free tier.

POST /process — file in, Artifact out

$ curl -s -X POST https://api.attachments.dev/v1/process \ -F "file=@scan.pdf" -F 'ocr=true'

Send the file as multipart; send options as extra form fields, JSON-encoded so types survive (true, 3, "1-4"). The response is one Artifact — {text, images, audio, video, meta} — with images as bytes_b64. Errors come back inside the artifact as meta.error with a typed code, exactly like the library.

The other endpoints

Endpoint	What it does
`POST /v1/unpack`	Archive bytes or `{"url": …}` in; the contained files out (`data_b64`). For exploding zips/repos before processing.
`GET /v1/health`	Status, version, and which features this server has installed (ocr, audio, …).
`GET /v1/formats`	Every extension the server can process.
`GET /v1/options`	The full DSL option schema, as JSON — the same data behind the DSL reference.

Free-tier limits, stated plainly: 25 MB per file, 10 POST requests per minute per IP (HTTP 429 beyond that), files processed in memory and never stored. Need more? Pricing.

Self-hosting — you can leave at any time

The hosted service runs the same MIT-licensed server you can run yourself. Same endpoints, same artifacts; point the library at it with configure(service_url=…) and nothing else changes.

$ pip install attachments[server] && attachments-server # production: gunicorn "attachments.server:create_app()" -b 0.0.0.0:8000 -w 4 # or the full TLS + rate-limit stack: deploy/ in the repo, docker compose up

ATTACHMENTS_SERVER_KEY — set to require Authorization: Bearer on POSTs; leave empty for an open server.
ATTACHMENTS_MAX_UPLOAD — upload cap in bytes (default 256 MB).
No telemetry, no database, nothing stored — the server is stateless.