Branding API
7 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.
Endpoints
GET /api/v1/admin/branding
Get branding settings
Global admins only. Effective values plus the configured defaults and which fields are runtime overrides.
Responses
| Status | Description | Body |
|---|---|---|
200 | Branding state | application/json: BrandingAdmin |
403 | Admin access required | - |
PUT /api/v1/admin/branding
Update branding settings
Global admins only. Runtime overrides win over the branding.* configuration until reset.
Request body (required)
application/json: BrandingUpdate
Responses
| Status | Description | Body |
|---|---|---|
200 | Branding state | application/json: BrandingAdmin |
400 | Invalid value | application/json: Error |
403 | Admin access required | - |
DELETE /api/v1/admin/branding
Reset branding to the defaults
Global admins only. Removes every runtime override, including uploaded images.
Responses
| Status | Description | Body |
|---|---|---|
200 | Branding state | application/json: BrandingAdmin |
403 | Admin access required | - |
PUT /api/v1/admin/branding/{asset}
Upload a branding image
Global admins only. The raw request body is the image: Content-Type image/png or image/svg+xml, at most 512 KiB (PNG at most 2048x2048). SVG is sanitised (scripts, event handlers, external references, foreignObject and anything outside an allowlist are removed) and rejected when it cannot be made safe.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
asset | path | string | yes | One of: logo-light, logo-dark, favicon. |
Request body (required)
image/png: string (binary)
image/svg+xml: string (binary)
Responses
| Status | Description | Body |
|---|---|---|
200 | Branding state | application/json: BrandingAdmin |
400 | Not a valid PNG or SVG, or the SVG is unsafe | application/json: Error |
403 | Admin access required | - |
404 | The addressed resource was not found | application/json: Error |
413 | Image larger than 512 KiB | application/json: Error |
DELETE /api/v1/admin/branding/{asset}
Remove an uploaded branding image
Global admins only. Falls back to the configured file, else the built-in image.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
asset | path | string | yes | One of: logo-light, logo-dark, favicon. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Branding state | application/json: BrandingAdmin |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
403 | Admin access required | - |
404 | The addressed resource was not found | application/json: Error |
GET /api/v1/branding
Get branding
Unauthenticated: the login page needs it before sign-in. Answers ETag/304; shared caches may store it only for requests that carry no credentials.
Authentication: none (public endpoint).
Responses
| Status | Description | Body |
|---|---|---|
200 | Effective branding Headers: ETag. | application/json: Branding |
304 | Not modified | - |
GET /api/v1/branding/{asset}
Get a branding image
The effective logo-light, logo-dark or favicon (PNG or sanitised SVG). 404 when none is configured. Served with a restrictive Content-Security-Policy and nosniff.
Authentication: none (public endpoint).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
asset | path | string | yes | One of: logo-light, logo-dark, favicon. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Image | image/png: string (binary); image/svg+xml: string (binary) |
304 | Not modified | - |
400 | Invalid request, including a NUL byte in the URL or the body | application/json: Error |
404 | No image configured | application/json: Error |