API reference · API 1.0.0

Brand

This platform's branding.

get /api/v1/brand

This platform's brand

Operation brand_get · bearer token

The one brand of this platform. attribution and first_party are read-only and computed. The ETag response header carries version for If-Match. PUT /brand is a FULL replacement: to change one field, send back every writable field of this answer, the unchanged ones included. A field left out is refused (422 naming it), and null for an asset id clears that asset.

Responses

  • 200

    The brand.

    application/json → Brand
    Headers: ETag, X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No brand is configured (brand_not_configured).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
put /api/v1/brand

Replace the brand

Operation brand_put · bearer token

Replaces every v1 field: a FULL replacement, never a partial update. All are required, so a field left out is a 422 naming it and is never reset; the asset ids may be null, which CLEARS the asset. To change one field, read the brand and send every field back. attribution and first_party cannot be sent (422). The fields v1 does not manage (the sidebar tagline, the sign-in title and subtitle, the footer links) keep their stored values. With If-Match: "<version>" the replace happens only while the brand is still at that version (412 version_mismatch otherwise); without it the last write wins, as in the portal's Brand Center. A replace that changes nothing returns the brand as it is: version is not bumped and no audit row is written. The change applies to every tenant and user of this platform, the sign-in page included. There is no delete.

Parameters

NameInTypeDescription
If-Match header string | null

The version last read, as an entity tag ("7"); * matches any.

Request bodyrequired

application/json

Schema BrandPut

FULL REPLACEMENT of the v1 fields, never a partial update: every member is required. A member that is missing is refused with 422 validation_failed naming it in field (and in errors), so nothing is ever reset by omission; null for an asset id is a value and clears that asset. Send back every field of GET /brand, changed or not. Extra members — attribution and first_party among them — are refused with 422.

NameTypeDescription
brand_colorrequired string

Six-digit hex colour; returned lower-case.

pattern ^#[0-9a-fA-F]{6}$
favicon_asset_idrequired string | null

A brand asset of kind favicon; null keeps the built-in one. In a PUT, null is a value that CLEARS the favicon, not "leave as is".
logo_asset_idrequired string | null

A brand asset of kind logo; null shows the built-in logo. In a PUT, null is a value that CLEARS the logo, not "leave as is".
logo_offset_xrequired integer

Horizontal nudge of the logo, in pixels.

min -40 · max 40
logo_sizerequired string

The sidebar logo size preset.

one of compact, medium, regular, large
page_titlerequired string

The browser-tab title.

min length 1 · max length 60
product_namerequired string

The wordmark in the sidebar and on the sign-in page.

min length 2 · max length 32
product_name_accentrequired string

A part of product_name rendered in brand_color. Empty colours the whole name.

max length 32

Responses

  • 200

    The brand after the replace.

    application/json → Brand
    Headers: ETag, X-Request-ID
  • 400

    If-Match is not a version (invalid_if_match).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No brand is configured (brand_not_configured).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 412

    If-Match names another version (version_mismatch); current_version is the stored one.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 422

    An asset id does not exist (asset_not_found) or is the wrong kind (asset_wrong_kind), with field; or the body is invalid (validation_failed, field naming the first offending member): a required field left out, or attribution / first_party sent.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
get /api/v1/brand/assets

List brand assets

Operation brand_assets_list · bearer token

The brand assets uploaded to this platform, in id order, filtered by kind and by the exact sha256 of a file (to find out whether it is already uploaded). Assets are never deleted: one that no brand field names any more is still listed.

Parameters

NameInTypeDescription
kind query string | null
one of logo, favicon
sha256 query string | null

Exact sha256 (lower-case hex) of the file.

pattern ^[0-9a-f]{64}$
limit query integer

Page size.

min 1 · max 200 · default 50
cursor query string | null

next_cursor from the previous page; omit it for the first page. A cursor this list did not issue is a 400 invalid_cursor.

Responses

  • 200

    One page of brand assets.

    application/json → BrandAssetPage
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
post /api/v1/brand/assets

Upload a brand asset

Operation brand_assets_create · bearer token

Accepts multipart/form-data with file and kind (as the portal's Brand Center sends) or application/json with kind and content_base64; both are validated the same way: PNG, WebP or SVG for a logo (120-2000 px wide), PNG, SVG or ICO for a favicon, at most 512 KB, SVG without active content. Assets are content-addressed: uploading bytes that are already stored as the same kind returns that asset with 200 and writes nothing; the same bytes as the other kind are a 409. Everything uploaded is readable WITHOUT signing in at url (the sign-in page shows it), so upload nothing that is not public. There is no delete. Send an Idempotency-Key to make a retry safe: a retry with the same key and request gets the first answer and changes nothing.

Parameters

NameInTypeDescription
Idempotency-Key header string

Makes a retry safe: for 24 hours, the same key with the same request (method, path, query and body) answers with the stored response (Idempotent-Replayed: true) instead of doing the work again. The same key with a different request is a 409 idempotency_key_reused; while the first request is still running it is a 429 idempotency_request_in_progress with Retry-After. 1-255 printable characters without spaces (400 invalid_idempotency_key otherwise); a UUID is a good key. Keys are scoped to the calling account.

min length 1 · max length 255 · pattern ^[!-~]+$

Request bodyrequired

application/json

Schema BrandAssetUpload

The JSON form of an upload. Multipart (file + kind), as the portal screen sends, is accepted on the same operation.

NameTypeDescription
content_base64required string

The file, standard base64; at most 512 KB decoded. Its type is read from the bytes; no content type is sent.

min length 1 · max length 699058
filename string

The original file name, kept for display only: the asset is addressed by its content (sha256).

max length 200 · default ""
kindrequired string

What the asset is for: a logo or a favicon.

one of logo, favicon
multipart/form-data
NameTypeDescription
filerequired string (binary)
kindrequired string
one of logo, favicon

Responses

  • 200

    These bytes are already stored as this kind: the existing asset. Nothing new is written (a missing stored object is stored again).

    application/json → BrandAsset
    Headers: Idempotent-Replayed, X-Request-ID
  • 201

    The asset was stored.

    application/json → BrandAsset
    Headers: Idempotent-Replayed, X-Request-ID
  • 400

    An application/json body that is not valid JSON (bad_request).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 409

    These bytes are already stored as the OTHER kind (asset_kind_conflict); existing_asset_id and existing_kind name it.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 415

    Neither multipart/form-data nor application/json (unsupported_media_type).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 422

    The file is refused (asset_invalid: type, size, SVG content, logo width), content_base64 is not base64, or the body is invalid.

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    Object storage is not configured, so a new asset cannot be stored (storage_unavailable). Also: the platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
get /api/v1/brand/assets/{asset_id}

One brand asset

Operation brand_assets_get · bearer token

One brand asset by id. The file itself is at its url, readable without signing in.

Parameters

NameInTypeDescription
asset_idrequired path string

The asset's id (id on a brand asset).

Responses

  • 200

    The brand asset.

    application/json → BrandAsset
    Headers: X-Request-ID
  • 401

    Not authenticated: no Authorization: Bearer header (not_authenticated), or the credential is refused (token_invalid, token_expired, token_revoked, principal_disabled, token_ip_not_allowed).

    application/jsonapplication/problem+json → Problem
    Headers: WWW-Authenticate, X-Request-ID
  • 403

    The caller lacks a permission the operation needs (forbidden; required lists the keys, any one of which would do), or the licence refuses a change (licence_locked, licence_restricted, licence_required, with state and remedy; never retry a licence_* code).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 404

    No such asset (brand_asset_not_found).

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID
  • 429

    More than 600 requests in a minute with this token (rate_limited), or the first request with this Idempotency-Key is still running (idempotency_request_in_progress). Retry after Retry-After.

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • 503

    The platform cannot answer right now (unavailable; retry after Retry-After), or API tokens are not configured on it (api_tokens_unconfigured; an operator must act).

    application/jsonapplication/problem+json → Problem
    Headers: Retry-After, X-Request-ID
  • default

    Problem details (RFC 9457)

    application/jsonapplication/problem+json → Problem
    Headers: X-Request-ID

Rendered from openapi-v1.json, platform release 1.0.187. Your installation serves the contract of its own version at /api/v1/openapi.json.