Skip to navigation
API referenceCatalogue

Preview a catalogue Variant revision

Renders one draft or approved revision — active or not — on an uploaded input, as a makeup job you poll like any other. Nothing about the variant moves: its availability, active_revision and generation are what they were. The body is inputs and, for a variant with more than one application, the application_id to render. The job’s resolution carries purpose: "preview" and a target naming the revision and its authored_intent_digest. A rejected revision answers 409 REVISION_DECIDED; a retired variant 409 VARIANT_RETIRED. Both refuse a new preview only: a retry of one already admitted replays it. Send an Idempotency-Key: a retry with the same key and the same request answers 200 with the same job. The preview’s identity includes the revision’s authored intent, so the same key naming another revision, or a try-on, answers 409 IDEMPOTENCY_KEY_REUSED. Requires the catalogue.preview scope, which your account operator provisions; no other catalogue scope implies it, and it needs no makeup.apply. 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
revisionstringRequired

Headers

Idempotency-Keystring or nullOptional

Request

A preview of one variant revision (P3 F3.3; F0.2 §8): the input, and which of the revision’s application definitions to render when it declares more than one. The revision in the path supplies everything else.

inputslist of objectsRequired
application_idstring or nullOptional

Response headers

Cache-ControlstringOptional
API responses are private to the caller and not cacheable
Idempotency-ReplayedenumOptional
True when this response reuses an existing job
Allowed values:
LocationstringOptional
Relative URL of the created or replayed job
RateLimitstringOptional

The state of each policy in RateLimit-Policy: "submit";r=59;t=1, r remaining and t seconds until whole again.

RateLimit-LimitintegerOptional

Quota of the most restrictive policy (draft-07 form).

RateLimit-PolicystringOptional

The limits this request consumed, as an RFC 8941 list (draft-ietf-httpapi-ratelimit-headers): "submit";q=60;w=60. Policies are submit, upload and daily. Sent only while rate-limit headers are on.

RateLimit-RemainingintegerOptional

Remaining quota of the most restrictive policy (draft-07 form).

RateLimit-ResetintegerOptional
Seconds until the most restrictive policy is whole again.
Retry-AfterstringOptional

Delay before retrying, expressed as delta-seconds

X-Request-IdstringOptional
Request correlation identifier

Response

Idempotent replay of the job the first submission created
completed_atdatetime or null
created_atdatetime
errorobject or null
expires_atdatetime or null
idstring
inputslist of objects
operationenum

What a job does: the operation’s authorization scope.

An operation is not its output’s type: OPERATION_OUTPUT_TYPE is the one place the two meet.

Allowed values:
outputobject or null
statusenum
Allowed values:
updated_atdatetime
livemodebooleanOptional
resolutionobjectOptional

JobV1.resolution: how a job’s custom applications were resolved.

Fixed at admission, so an exact retry and every later read answer the profile versions the job was admitted under, whatever the declaration says now.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
410
Gone Error
413
Content Too Large Error
429
Too Many Requests Error
503
Service Unavailable Error