Conventions

These rules apply across every endpoint. Each operation page documents only what’s specific to it and refers back here for the shared parts.

Requests

• Method: POST for all operations.
• Content type:
  • application/json — when inputs are URLs or base64.
  • multipart/form-data — when you upload file bytes directly. Send the JSON parameters as a params form field and each file as its own part.
• Payment: every request is paid over x402 via the X-PAYMENT header. See The 402 flow.

Responses

A successful response is 200 OK with this envelope:

{
  "output": {
    "url": "https://files.pdfasyougo.com/o/3f9a…?token=…",
    "expires_at": "2026-06-29T12:00:00Z",
    "pages": 12,
    "bytes": 98304
  },
  "operation": "pages.extract",
  "cost": "0.05 USDC"
}

• output.url — short-lived signed download URL.
• output.expires_at — ISO-8601 expiry (preview default: 60 minutes out).
• output.pages / output.bytes — facts about the produced file.
• operation — the operation that ran.
• cost — what settled for this call.

Errors use a different envelope and a non-200 status — see Errors.

File inputs

The file (single) or files (ordered array) parameters accept any of:

Form	Example
URL	"https://example.com/report.pdf"
Uploaded object	a part in a multipart/form-data request
Inline base64 (small, discouraged)	{ "base64": "JVBERi0xLjcK..." }

Full guidance — including pre-signed uploads and why URLs are preferred — is in File handling.

Page ranges

Operations that act on specific pages (extract, remove, rotate) share one page-range syntax, a string of comma-separated terms:

Term	Meaning
5	A single page (pages are 1-indexed).
2-6	An inclusive range.
8-	From page 8 to the end.
-3	From the start to page 3.
1-3,5,9-	Combine terms; evaluated left to right.

{ "file": "https://example.com/report.pdf", "pages": "1-3,5,9-" }

Note

Page numbers are 1-indexed. A range that falls entirely outside the document (e.g. "50-60" on a 10-page file) is an input error and isn’t charged. A range that partially overlaps is clamped to the document.

Idempotency

Operations are deterministic given the same inputs, but because each call is paid, you generally don’t want to silently retry a 200. To make retries safe across network blips, send an Idempotency-Key header with a unique value per logical operation:

-H "Idempotency-Key: 6f9d…unique"

If a request with the same key is replayed (for example after a dropped connection), the original result is returned without charging again. Keys are honored within the output retention window.

Timeouts

The flat price applies regardless of file size, but each request has a processing timeout. Very large or page-heavy documents may approach it; if an operation times out it returns a 5xx and isn’t charged. Prefer passing files by URL from fast origins.

Versioning

The API is versioned in the path (/v1). Breaking changes will ship under a new version prefix; additive changes (new optional fields, new operations) may appear within /v1. During preview, treat the surface as stable-but-evolving and watch the Changelog.