---
title: "Update a link variant"
method: PUT
path: "/api/v1/files/{uuid}/variants/{variantUuid}"
tags: ["Variants"]
---

# Update a link variant

`PUT /api/v1/files/{uuid}/variants/{variantUuid}`

## Request

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

Update the label and/or overrides, or revoke/un-revoke the variant. Omitted fields keep their current values; `label: ""` clears the label. An `overrides` object replaces the stored override set as a whole (see VariantUpdate) - include every override you want to keep. A revoked variant's link answers 404 to viewers (without revealing that a canonical link exists) until un-revoked. A redacted variant's label can never be set again (409).

## Request body

- VariantUpdate: All fields optional; omitted fields keep their current value. One exception in granularity: `overrides`, when present, REPLACES the stored override set as a whole object - it is never merged key by key. Send every override you want to keep: `{"overrides": {"allowDownload": true}}` also removes a stored `pageRange` override, `{"overrides": {}}` removes all overrides, and only omitting `overrides` entirely leaves the stored set untouched.
  - `label` string: New label; empty string clears it. Rejected (409) on a redacted variant.
  - `overrides` VariantOverrides: Per-variant setting overrides applied to viewers arriving through this variant. Omitted keys inherit the file's settings. On update the object is stored exactly as sent (whole-object replace, never a per-key merge).
    - `allowDownload` boolean: Override the file's explicit-download permission for this variant's viewers.
    - `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).
  - `revoked` boolean: true revokes (viewers get 404), false un-revokes.

## Response `200`

The updated variant

- Variant: A per-recipient child link of a file.
  - `uuid` string, uuid
  - `shortId` string: The variant's own share-URL alias.
  - `url` string: The full shareable link (the owner's custom domain when one is verified).
  - `label` string: Recipient tag. Absent when never set - and, permanently, after redaction.
  - `overrides` VariantOverrides: Per-variant setting overrides applied to viewers arriving through this variant. Omitted keys inherit the file's settings. On update the object is stored exactly as sent (whole-object replace, never a per-key merge).
    - `allowDownload` boolean: Override the file's explicit-download permission for this variant's viewers.
    - `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).
  - `revoked` boolean: A revoked variant's link answers 404 to viewers until un-revoked.
  - `redactedAt` string, date-time: Present after GDPR redaction (the label is gone for good).
  - `createdAt` string, date-time

## 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`).
- `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)