# Logos

A logo is a PNG or SVG file uploaded for a brand, as a primary or a reversed version. Runs use whichever stands out more on the artwork. Logos belong to brands.

A logo is a PNG or SVG file uploaded for a brand, as a primary or a reversed version. Runs use whichever stands out more on the artwork. Logos belong to brands.

## The Logo object

The logo object describes an uploaded logo file; the file itself is retrieved separately.

- `variant` (string, required): `primary` or `reversed`. One of: `primary`, `reversed`.
- `contentType` (string, required): `image/png` or `image/svg+xml`. One of: `image/png`, `image/svg+xml`.
- `size` (integer, required): Bytes, at most 2097152.
- `sha256` (string, required): The file's SHA-256, in lower-case hex. Also the `ETag` of the file.
- `updatedAt` (string (date-time), required): When this logo was last uploaded.

```json
{
  "variant": "primary",
  "contentType": "image/png",
  "size": 48213,
  "sha256": "9f2c4e6a8b0d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a",
  "updatedAt": "2027-08-14T02:31:07Z"
}
```

## Retrieve a logo

`GET /api/v1/sites/{key}/logos/{variant}`

Permission: Brand · Read.

Returns the site's logo as an image file (PNG or SVG). The answer carries an `ETag` (the file's SHA-256, in quotes) and is cached privately for five minutes; send the `ETag` back in `If-None-Match` to get a `304` when nothing changed.

### Parameters

- `key` (string, required): The document's key (a brand's code).
- `variant` (string, required): Which logo. One of: `primary`, `reversed`.

### Returns

The logo.

### Errors

- 304: `If-None-Match` (any of its lines) names the current `ETag` (weak comparison, or `*`); no body, with the 200's `ETag`, `Cache-Control`, `Content-Security-Policy`, `X-Content-Type-Options` and `Vary`.
- 400: “The logo variant must be primary or reversed.”
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 404: “No logo has been uploaded for that.”
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: “could not read logos” or “could not check token”.
- 501: “Logos aren't set up on this server.”

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/sites/string/logos/primary \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## List all logos

`GET /api/v1/sites/{key}/logos`

Permission: Brand · Read.

Returns the logos uploaded for a site, the primary one first, then the reversed one. The list is empty when none has been uploaded. Use Retrieve a logo to download one.

### Parameters

- `key` (string, required): The document's key (a brand's code).

### Returns

One entry per uploaded variant; `[]` when none (or no such brand).

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403: “Your role (\<role>) can't \<action>.” (the role is below the route's minimum) or “Choose an organisation first.” (the session has no organisation).
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.
- 500: “could not read logos” or “could not check token”.
- 501: “Logos aren't set up on this server.”

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/sites/string/logos \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```
