Skip to navigation
API referenceCatalogue

Revise a catalogue Variant

Writes the next revision of the variant as a draft: its whole colour and application definitions, never a patch, compiled like a create. A draft changes nothing that renders; it is approved, then published. An earlier revision never changes, so a job already admitted keeps what it was admitted as. A retired variant takes no revision (409 VARIANT_RETIRED). Send an Idempotency-Key: a retry with the same key and the same request answers the first response, byte for byte, with Idempotency-Replayed: true, so a response you did not receive is safe to retry. Requires the catalogue.write scope, which your account operator provisions; no other catalogue scope implies it. Served only where the catalogue is enabled for your environment.

Authentication

X-API-Keystring

API key for one environment of your account. Keep server-side; never expose in browser clients.

Path parameters

variant_idstringRequired

Headers

Idempotency-Keystring or nullOptional

Request

A new revision of a variant: its whole display colour and application definitions, never a patch. It is written as a draft and changes nothing that renders until it is approved and published.

appearance left out is {"display_color": ...}; when sent, its display_color is the revision’s, and each field sent is asserted by the partner. default_application_id is the definition a request that names none renders, and may be left out only with one definition.

applicationslist of objectsRequired
display_colorstringRequired
appearanceobject or nullOptional

How a shade presents (Foundation V1 D4). display_color left out is the revision’s, and when sent must be. Who says each field is never sent: the server records a partner write’s fields as source: partner (D20).

default_application_idstring or nullOptional

Response

The new revision, a draft
appearancemap from strings to any
applicationslist of objects
approved_snapshot_digeststringformat: "^sha256:[0-9a-f]{64}$"
authored_intent_digeststringformat: "^sha256:[0-9a-f]{64}$"
created_atdatetime
decided_atdatetime or null
decision_stateenum
Allowed values:
default_application_idstring
digest_versionenum
Allowed values:
display_colorstringformat: "^#[0-9A-F]{6}$"
revisioninteger>=1
variant_idstring

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
503
Service Unavailable Error