Variant

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/everypage-co/json-schema/everypage-co-variant-schema.json",
  "title": "Variant",
  "description": "A per-recipient child link of a file.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/everypage-co-variants-api-openapi.yml#/components/schemas/Variant",
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string",
      "format": "uuid"
    },
    "shortId": {
      "type": "string",
      "description": "The variant's own share-URL alias."
    },
    "url": {
      "type": "string",
      "description": "The full shareable link (the owner's custom domain when one is verified)."
    },
    "label": {
      "type": "string",
      "description": "Recipient tag. Absent when never set - and, permanently, after redaction."
    },
    "overrides": {
      "$ref": "#/$defs/VariantOverrides"
    },
    "revoked": {
      "type": "boolean",
      "description": "A revoked variant's link answers 404 to viewers until un-revoked."
    },
    "redactedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Present after GDPR redaction (the label is gone for good)."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "$defs": {
    "PageRange": {
      "type": "object",
      "description": "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).\n",
      "properties": {
        "from": {
          "type": "integer",
          "minimum": 0,
          "description": "First shared page (1-based)."
        },
        "to": {
          "type": "integer",
          "minimum": 0,
          "maximum": 20000,
          "description": "Last shared page (inclusive; must be >= from)."
        }
      }
    },
    "VariantOverrides": {
      "type": "object",
      "description": "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).",
      "properties": {
        "allowDownload": {
          "type": "boolean",
          "description": "Override the file's explicit-download permission for this variant's viewers."
        },
        "pageRange": {
          "allOf": [
            {
              "$ref": "#/$defs/PageRange"
            }
          ],
          "description": "Override the file-level page range for this variant's viewers: a valid pair (1 <= from <= to; file at most 100MB) replaces the file's range outright, and the explicit `{\"from\":0,\"to\":0}` serves the FULL document through this variant even when the file has a range. Omitted, the file-level range (if any) applies. The variant-effective window is what the variant's public metadata advertises and what its viewers' bytes are trimmed to; like the file-level range it keeps enforcing after a Pro downgrade.\n"
        }
      }
    }
  }
}