File handling

PDF As You Go is designed so an agent never has to push large files through a model’s context window. Documents go in by reference or upload, and results come out as short-lived download URLs.

Inputs

An operation accepts its source document(s) in one of three ways:

1. By URL (recommended)

Pass a publicly reachable URL and the service fetches it:

{ "file": "https://example.com/report.pdf" }

This is the best option for agents — nothing large travels through the model. The URL must be reachable by the service for the duration of the request. If it can’t be fetched, the operation fails and isn’t charged.

2. By upload

For files you hold locally, upload the bytes. Two forms are supported:

• Multipart upload — send the file as part of a multipart/form-data request.
• Pre-signed upload URL — request a one-time upload URL, PUT the bytes to it, then reference the uploaded object in your operation call.

Uploads are the right choice when the document isn’t already hosted somewhere the service can reach.

3. Inline base64 (small files only, discouraged)

A small file may be sent as a base64 string. This is supported for convenience but discouraged — base64 inflates payloads ~33% and, for agents, burns model context. Prefer URL or upload.

{ "file": { "base64": "JVBERi0xLjcK..." } }

Tip

Operations that take multiple inputs (like merge) accept an ordered array, and you can mix forms — e.g. one URL and one uploaded file in the same call.

Outputs

The result of an operation is returned as a short-lived download URL, alongside light metadata:

{
  "output": {
    "url": "https://files.pdfasyougo.com/o/3f9a…?token=…",
    "expires_at": "2026-06-29T12:00:00Z",
    "pages": 24,
    "bytes": 184320
  }
}

• url — a signed, single-purpose download link. No auth header is needed to fetch it; the token in the URL grants access.
• expires_at — when the link stops working. After expiry the file is gone (see Privacy & retention).
• pages / bytes — basic facts about the output.

Fetch or hand off the file before it expires (preview default: 60 minutes). If you need the bytes directly in the response instead of a URL, streamed output is on the Roadmap.

Practical notes

• Size: the flat price applies regardless of size, but very large files take longer to fetch and process and are subject to a request timeout. See Conventions.
• Page references: operations that act on specific pages use a shared page-range syntax (for example 1-3,5,9-).
• Privacy: inputs and outputs are processed transiently and deleted after the retention window — details in Privacy & retention.