Generate a presigned PUT URL for a brand-theme asset.

POST

/brands/me/theme/assets/upload-url

• Production
• Staging
• Local dev

Returns a presigned S3 PUT URL for uploading a logo or favicon.

Request body (POL-709 — field names are authoritative):

• slot — one of logo_light, logo_dark, favicon.
• contentType — MIME type of the bytes the client is about to PUT. Logo slots accept image/png, image/svg+xml, image/webp; the favicon slot accepts image/png, image/svg+xml.
• byteSize — size in bytes (integer, ≤ 2 MiB).

Response: { uploadUrl, key, publicUrl, expiresIn, method, headers }. publicUrl is the canonical CloudFront URL the theme row should reference (there is no separate cdnUrl field). After the upload completes, PATCH /brands/me/theme with the returned publicUrl in the matching slot (logoLightUrl, logoDarkUrl, or faviconUrl). POL-648 extends the pipeline with server-side image processing + sanitisation; the response contract here is forward-compatible.

Authorizations

• bearerAuth

Parameters

Header Parameters

X-Polst-Idempotency-Key

required

string

>= 8 characters <= 255 characters

Idempotency key, 8–255 URL-safe chars.

Request Body ^required

object

slot

required

string

Allowed values: logo_light logo_dark favicon

contentType

required

string

Allowed values: image/png image/svg+xml image/webp

byteSize

required

integer

> 0 <= 2097152

Responses

200

Presigned URL.

object

data

required

object

uploadUrl

required

string format: uri

key

required

string

publicUrl

required

string format: uri

expiresIn

required

integer

> 0 <= 9007199254740991

method

required

string

Allowed value: PUT

headers

required

object

key

additional properties

string

400

Missing idempotency key.

401

Missing or invalid bearer token.

403

Bearer token lacks manage scope or brand context.

422

Request body failed validation.