---
title: "Upload a branding asset (Basic+)"
method: POST
path: "/api/v1/files/{uuid}/assets"
tags: ["Files"]
---

# Upload a branding asset (Basic+)

`POST /api/v1/files/{uuid}/assets`

## Request

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

Stores an encrypted auxiliary image for the file and returns its `assetId`, which `viewerSettings.logo.assetId`, `viewerSettings.background.assetId` and `viewerSettings.gate.imageAssetId` then reference - the settings PUT rejects an assetId that does not belong to the same file, so upload before you configure. `logo`, `background` and `gate-image` are singletons: a second upload of the same kind replaces and deletes the first. PNG/JPEG/WebP up to 5MB (`hotspot-audio` accepts MP3 up to 10MB); max 10 per file. A `gate-image` (the sign-in card's logo or banner, Pro) is the one asset readers can fetch before passing the password and email gates, while the owner is Pro.

## Query parameters

- `kind` 'logo' | 'background' | 'hotspot-image' | 'hotspot-audio' | 'gate-image', required

## Response `200`

Stored

- object
  - `assetId` string, uuid

## Other responses

- `400`: Invalid `kind`, malformed multipart, missing `file`, or an unsupported media type for that kind.
- `401`: No or invalid API key, OAuth token, manage token or claim token (code `missing_token` or `invalid_token`).
- `403`: Not the owner, a plan below Basic, or the per-file asset cap (10) reached.
- `404`: Unknown id, or a file you do not own on routes where 404 replaces 403 (code `not_found`).
- `413`: The asset is over its cap (5MB images, 10MB audio) (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)