---
title: "Import a PDF from an export URL"
method: POST
path: "/api/v1/files/import"
tags: ["Files"]
---

# Import a PDF from an export URL

`POST /api/v1/files/import`

## Request

- Base URL: `https://everypage.co`
- URL: `https://everypage.co/api/v1/files/import`
- 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`)

Create a file by server-side download of an allowlisted HTTPS export URL (e.g. a Canva design export). PDF only, redirect-free, capped at your plan's size; uses a file slot (403 when full). Returns `uuid`, `shortId`, `shareUrl` and an optional advisory `palette`. Scope `files:write`.

The response may include `palette` - colour swatches extracted from the imported document during the import (see the Palette schema). The palette is advisory and best-effort: extraction reads the first page's embedded images with a short time budget, so vector-only documents (and any extraction failure or timeout) simply omit the field. A missing palette is normal, never an error, and never fails the import.

**Canva design lane (republish-in-place):** sending a verified `canvaUserToken` AND `designToken` pair binds the import to the Canva design. When a live file of yours is already bound to that design, the import REPLACES its bytes in place - same UUID, short id, QR and readership history - and the response reports `republished: true` with the new `contentVersion`. Works on every plan (unlike the /content endpoint), and a republish consumes no file-limit slot; the owner can switch the lane off per file (`canvaUpdatesEnabled`) or sever it permanently (`detachCanvaDesign`) via the settings endpoint. A `designToken` WITHOUT a valid `canvaUserToken` is ignored (the import proceeds as a plain create), as is any token that fails verification - a bad optional token never fails a publish.

## Request body

- object
  - `url` string, uri, required: Plain HTTPS export URL on the import host allowlist.
  - `filename` string: Display name for the new file. Defaults to design.pdf.
  - `canvaUserToken` string: Canva Apps SDK user JWT (verified against Canva's JWKS). Required for the design lane; travels in the body because the Authorization header already carries your EveryPage credential.
  - `designToken` string: Canva design token (contentMetadata.designToken) binding the publish to a design. Ignored unless canvaUserToken is present and verifies.

## Response `200`

Imported (or republished in place - see `republished`)

- ImportResult
  - `uuid` string, uuid
  - `shortId` string
  - `shareUrl` string
  - `republished` boolean: True when the Canva design lane replaced an existing file's bytes in place (the uuid/shortId are the EXISTING link's); false/absent on a plain create.
  - `contentVersion` integer: The file's content version after a republish (present only when republished is true; increments on every in-place replacement).
  - `palette` string[]: Colour palette extracted from the document at import time: hex swatches ("#rrggbb"), dominant colour first, at most 6. ADVISORY ONLY - extraction is best-effort (first-page embedded raster images, short time budget), so the field is simply absent for vector-only documents, for files uploaded through non-import paths, for files created before the feature, and whenever extraction fails or times out. Absence is normal, never an error; use the palette for theming (e.g. styling a share card), never for logic.

## 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`: The URL's host is not an allowed import source, your plan's file limit is reached, or (design lane) updates from Canva are switched off for the bound file.
- `409`: Design lane only - the document was changed by another connection mid-replace. Retry.
- `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`).
- `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`.
- `502`: The export source could not be fetched or returned an error.

---

[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)