---
title: "Update a file's settings"
method: PUT
path: "/api/v1/files/{uuid}/settings"
tags: ["Files"]
---

# Update a file's settings

`PUT /api/v1/files/{uuid}/settings`

## Request

- Base URL: `https://everypage.co`
- URL: `https://everypage.co/api/v1/files/{uuid}/settings`
- 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`)
  - HTTP bearer

Update a file's sharing settings: viewer mode, password, downloads, expiry (`deleteAt` or `neverExpire`), view limit, email gate, vanity slug, watermark, page range, appearance. Omitted fields keep their value. Owner via `files:write`, or the file's manage token while anonymous. 403 above plan, 409 slug in use, 410 dead link.

Besides an API key or OAuth token (files:write), this endpoint accepts a **manage token** as the bearer credential: anonymous uploads return a `manageToken` bound to the new file, valid for 30 days and only while the file remains unclaimed (a claimed file answers 404 to token callers). Manage-token callers are limited to the free plan's settings; plan-gated fields return 403. The `claimToken` from the same response is a different credential (it attaches the file to an account) and is never accepted here.

## Request body

- FileSettings: All fields optional; omitted fields keep their current value.
  - `viewerMode` 'standard' | 'flipbook' | 'swipe' | 'magazine'
  - `password` string: Non-empty to protect (Basic+); empty string to clear.
  - `allowDownload` boolean
  - `requireEmail` boolean: Gate viewing behind an email (Pro).
  - `notifyOnView` boolean: Email you on each read (Basic+).
  - `deleteAt` string, date-time: Fixed expiry. Uncapped for signed-in accounts on every plan (null = never expires); manage-token callers on an anonymous file are capped at 7 days. Set through a MANAGE TOKEN on an anonymous file, it also marks the expiry as deliberately chosen, so a Canva republish keeps it instead of re-basing to the 365-day default - a one-way mark (the token lane has no way to hand expiry back to the system).
  - `neverExpire` boolean: Permanent link, available to every signed-in plan (not through a manage token). Overrides deleteAt.
  - `viewLimit` integer: Self-destruct after this many views (Basic+). 0 clears the limit; omit to keep. A burned link keeps its row and readership - un-burn it via content replacement.
  - `gateDomains` string[]: Email-gate domain allowlist (Pro to set a non-empty list; [] clears on any plan).
  - `gateFields` GateField[], nullable: Lead-capture form definition shown instead of the plain email prompt (Pro to set; null or [] clears on any plan). A non-empty form forces requireEmail on.
    - `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: Heading on the gate card readers see before the document opens (Pro to set; "" clears back to the default wording on any plan; omit to keep). Trimmed; plain text, no line breaks. Shown only while requireEmail is on.
  - `gateMessage` string: Explanatory line under the gate heading (Pro to set; "" clears on any plan; omit to keep). Trimmed; plain text, no line breaks. Shown only while requireEmail is on.
  - `askReceipt` boolean: Ask viewers to confirm receipt (Basic+ to enable).
  - `showExpiry` boolean: Show readers a live "Expires in" countdown next to Download (default true; any plan, either direction; omit to keep). False also withholds the expiry instant from the public share-link metadata. Moot while the link never expires.
  - `commentsEnabled` boolean: Reader feedback notes (Pro to enable).
  - `commentsAllowPublic` boolean: Let commenters opt into public display.
  - `notifyOnComment` boolean: Email you (throttled) when a note arrives.
  - `marksEnabled` boolean: Proofing page marks (Pro to enable).
  - `annotationsEnabled` boolean: Proofing annotations (Pro to enable).
  - `watermark` boolean: Stamp viewer pages (Pro). Watermarked downloads are limited to files up to 100MB (400 above that).
  - `slug` string: Vanity link name on your custom domain (Pro): lowercase letters, digits, and hyphens; "" clears. 409 when another of your files already uses it.
  - `canvaUpdatesEnabled` boolean: May a Canva-side republish of the bound design replace this file's bytes? Defaults true; only meaningful on files with a canvaDesignId. Un-gated on every plan in both directions - it is a safety control, not a feature.
  - `detachCanvaDesign` boolean: True permanently severs the file from the Canva design that published it: no future publish of the design can update this link (the next publish creates a fresh one). One-way - there is no re-bind through settings - and un-gated on every plan. No-op on unbound files.
  - `viewerSettings` object: The viewer appearance/behavior blob. Blocks: `background` (type solid|gradient|image with color/gradient preset/assetId, fit, blur 0-20, dim 0-80), `logo` (assetId, position tl|tr|bl|br, size s|m|l|xl, linkUrl, hideBadge), `page` (shadow 0-3, rounded 0-3, edges, coverAlone), `flip` (speedMs 200-1200, sound, rtl, layout adaptive|single|double), `swipe` (autoAdvance, intervalMs 3000-30000), `protect` (contextMenu/print/select Basic+; blurOnLeave Pro), `ga4Id` (Pro), `brand` (accentColor, toolbarTheme, badgePosition; Pro), `cta` (label 1-40 chars, https url, style, color, position; Pro), `watermarkStyle` (opacity 0.05-0.5, density sparse|normal|dense; Pro), and `gate` (the sign-in card readers see before the email or password gate: backgroundColor and buttonColor #RRGGBB, imageAssetId of a `gate-image` asset, imageStyle logo|banner; Pro). Any deviation from the defaults requires Basic+; unknown fields are dropped and out-of-range values clamped. Tier gates are re-applied at serve time, so a downgraded plan's Pro styling stops rendering for viewers immediately.
  - `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).

## Response `200`

Settings applied (empty body).

## 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`: Not the owner (code `forbidden`), an OAuth token missing the required scope (`insufficient_scope`, with a `WWW-Authenticate` challenge naming it), a feature above your plan (`plan_required`), a plan limit reached such as file slots or the per-file asset cap (`forbidden`), or - on the two manage-token operations - a token acting at the free tier on a plan-gated field.
- `404`: Unknown id, or a file you do not own on routes where 404 replaces 403 (code `not_found`).
- `409`: Slug already in use, redacted label re-set, file claimed by another account, or a concurrent replace (code `conflict`).
- `410`: Dead link - expired or burned (code `gone`). Settings cannot revive it; a burned link un-burns via content replacement.
- `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`.

---

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