---
title: "Upload a document"
method: POST
path: "/api/v1/files"
tags: ["Files"]
---

# Upload a document

`POST /api/v1/files`

## Request

- Base URL: `https://everypage.co`
- URL: `https://everypage.co/api/v1/files`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://everypage.co/oauth/authorize`, token URL `https://everypage.co/oauth/token`, scopes: `files:write`)

Upload a document as multipart form-data (field `file`) and get a trackable share link. Returns the new file's UUID, short ID and ready-to-send `shareUrl` (`https://everypage.co/{shortId}`; the UUID form works too). PDFs are stored as sent; Word (.docx) and PowerPoint (.pptx/.ppt) files are converted to PDF server-side (legacy .doc is rejected with 400). A single `.html`/`.htm` file or a `.zip` static site (with `index.html` at the top level) is hosted live in a sandbox; that needs a user account, not an anonymous lane, and is capped at 10MB unpacked on Free, 50MB on Basic and 100MB on Pro, up to 1,000 files. Scope `files:write`; uses one of your plan's file slots - 3 Free, 100 Basic, unlimited Pro - and is capped at your plan's size. The file starts with no expiry and no gates.

## Response `200`

Uploaded

- UploadResult
  - `uuid` string, uuid
  - `shortId` string: The file's short share-URL alias.
  - `shareUrl` string: The ready-to-send share link, built server-side so clients need neither a second round trip nor a copy of the construction rule (which also has to know whether the owner has a verified custom domain). Always the durable short-id form - a just-created file has no vanity slug.
  - `message` string

## Other responses

- `400`: Malformed body or multipart, or an invalid value (code `validation_error`).
- `401`: No or invalid API key, OAuth token, manage token or claim token (code `missing_token` or `invalid_token`).
- `403`: Your plan's file limit is reached (3 Free / 100 Basic) - delete a file or upgrade, then retry (code `forbidden`; limit-reached 403s are not `plan_required`).
- `413`: The upload (or the PDF a Word/PowerPoint file converted to) is above your plan's size cap - 20MB Free, 200MB Basic, 2GB Pro - or a JSON body is over its fixed cap (1MB for settings and hotspots, 64KB for variants and claims) (code `payload_too_large`).
- `422`: A Word or PowerPoint file could not be converted to PDF (code `unprocessable`).
- `429`: Over the limit - 120 requests per minute per Authorization value on /api/v1 (webhook test 10/min; the Canva lane 30/min per IP). Code `rate_limited`; wait for `Retry-After`.
- `503`: A dependency (document converter, Canva key verification) is unavailable - retry with backoff (code `service_unavailable`).

---

[API](https://skmtc.dev/everypage/apis/everypage-api.md) · [All operations](https://skmtc.dev/everypage/apis/everypage-api/llms.txt) · [OpenAPI document](https://skmtc.dev/everypage/apis/everypage-api/revisions/e6674f903456?raw)