---
title: "List your files"
method: GET
path: "/api/v1/files"
tags: ["Files"]
---

# List your files

`GET /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:read`)

Every active file the caller owns, newest first, with share identifiers (`uuid`, `shortId`, `slug` when set) and current settings. Trashed files are excluded, and `revisions` is never included in the list (fetch one file for its replacement history). Scope `files:read`. Unpaginated.

## Response `200`

The caller's files, newest first

- File[]
  - `uuid` string, uuid
  - `shortId` string: Short share-URL alias; absent on files created before short IDs.
  - `slug` string: Vanity link name (Pro); absent unless set. Resolves only on the owner's custom domain.
  - `originalName` string
  - `size` integer: Bytes
  - `mimeType` string
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `deleteAt` string, date-time: Absent when the file never expires.
  - `viewCount` integer
  - `totalPages` integer
  - `viewerMode` 'standard' | 'flipbook' | 'swipe' | 'magazine'
  - `protected` boolean: True if a password is set.
  - `allowDownload` boolean
  - `requireEmail` boolean
  - `notifyOnView` boolean
  - `commentsEnabled` boolean: Reader feedback notes are on (Pro to enable).
  - `commentsAllowPublic` boolean: Commenters may opt into public display of their note.
  - `notifyOnComment` boolean: The owner is emailed (throttled) when a note arrives.
  - `askReceipt` boolean: Viewers are asked to confirm receipt (Basic+ to enable).
  - `showExpiry` boolean: Readers see a live "Expires in" countdown next to Download (default true, every plan). When false the public share-link metadata omits the expiry instant entirely.
  - `marksEnabled` boolean: Proofing page marks are on (Pro to enable).
  - `annotationsEnabled` boolean: Proofing annotations are on (Pro to enable).
  - `viewLimit` integer: Self-destruct cap (Basic+). Absent when unlimited.
  - `viewsConsumed` integer: Views consumed against `viewLimit` (always present, 0 when no limit).
  - `burnedAt` string, date-time: Present once the view-limit sweep destroyed the blob; the row and its readership survive, and content replacement un-burns it.
  - `gateDomains` string[]: Email-gate domain allowlist (Pro). Absent when any domain is accepted.
  - `gateFields` GateField[]: The stored lead-capture form definition (Pro). Absent when the gate is the plain email prompt.
    - `key` string, required: Unique snake_case key; submitted values and captured responses are keyed by it.
    - `label` string, required
    - `type` 'text' | 'email' | 'phone' | 'company' | 'select', required: `select` is a drop-down: the viewer picks exactly one of `options`. Text, phone and company values are capped at 500 characters.
    - `required` boolean
    - `options` string[]: The drop-down choices (type `select` only; unique). Omitted for every other type.
  - `gateHeading` string: The owner's heading for the gate card readers see before the document opens (Pro). Absent when the default wording applies.
  - `gateMessage` string: The owner's explanatory line on the gate card (Pro). Absent when the default wording applies.
  - `watermark` boolean: Viewer pages are stamped with the reader identity (Pro).
  - `viewerSettings` object: The stored appearance/behaviour blob exactly as saved (see the FileSettings.viewerSettings description); `{}` when never customised. Always present for the owner regardless of current plan.
  - `shareDomain` string: The owner's verified Pro custom domain that share links and embeds are built on. Absent when links use everypage.co.
  - `folderId` string, uuid: UUID of the folder the file is filed in. Absent when unfiled.
  - `anonShareable` boolean: True for owner-less files that are public-by-link (browser anonymous uploads, Canva imports). Always false once claimed.
  - `revisions` Revision[]: Replacement history - superseded content versions, newest first. Populated only by GET /api/v1/files/{uuid}; absent in the list and when the content was never replaced.
    - `version` integer: The content version this entry was (1 = the original upload).
    - `originalName` string
    - `size` integer: Bytes
    - `totalPages` integer
    - `createdAt` string, date-time: When this version was uploaded.
  - `pageRange` PageRange: A non-owner page window, 1-based and inclusive. `{"from":0,"to":0}` is the explicit "no range" value (clears the file-level range; as a variant override it serves the full document through that variant).
    - `from` integer: First shared page (1-based).
    - `to` integer: Last shared page (inclusive; must be >= from).
  - `contentVersion` integer: Counts in-place content replacements (1 = the original upload).
  - `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.
  - `canvaDesignId` string: The Canva design this file was published from. Absent on files with no design binding (including after a detach).
  - `canvaUpdatesEnabled` boolean: Whether a Canva-side republish of the bound design may replace this file's bytes (see the setting). Present only alongside canvaDesignId.

## Other responses

- `401`: No or invalid API key, OAuth token, manage token or claim token (code `missing_token` or `invalid_token`).
- `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`.

---

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