Skip to main content
A Variant’s tokens are not a DTCG document. They are a flat map of dotted path to value — the values this Variant changes, and nothing else. All paths are under /public/v1/environments/{environmentID}/themes/{themeID}.

​
Why the shape differs from a Theme’s

The Theme owns the structure: the tree, the names, $type, $description, $extensions. A Variant owns $value and nothing else. That is not a simplification of the API — it is the model. A Variant cannot add a token, cannot rename one, cannot retype one, and cannot describe one. Overriding a path the Theme does not have is silently ignored, because there is nothing for the override to apply to. See Variants.
If you want a token’s type or description, ask the Theme. It is the only place that can answer without two sources being able to disagree.

​
Read the overrides

​
integer
Read a specific published version. Remember that a Variant version number is a Theme version number.
​
boolean
default:"false"
Response 200
The envelope is deliberately identical to a Theme’s, so a client reading both surfaces reads one shape. What differs is that groups is always empty and a token carries only path and value. type, resolvedType and description are always null, and inferred is always false — there is no type here that could have been inferred.

​
Edit the overrides

Two operations over a dotted path, where a Theme takes five over a JSON Pointer. There is no tree to address into, nothing to escape, and no move to express.
The path is the token path as the Theme spells it — color.brand.primary, not /color/brand/primary. Returns the whole override set, with the new etag.

​
Publish the overrides

No body. Returns the Variant.
A Variant can be published only once per Theme version.A Variant version number is the Theme version its overrides are addressed against. The publish writes a version file numbered with the Theme’s current version; publishing again against the same Theme version finds that file already written and answers 409 conflict.Re-reading and retrying will not clear it. Publish the Theme first, then the Variant.

​
Discard the draft

Throws the draft away and returns the Variant. Published versions are untouched.

​
After the Theme publishes

When its Theme publishes a version, every Variant beneath it is automatically migrated: keys the Theme renamed are renamed here, and keys it removed — or retyped past fitting — are dropped. That migration writes each Variant’s draft. It does not publish. So after a Theme publish, expect hasUnpublishedChanges: true on Variants nobody touched; read the draft, check it, and publish.
A rename is only reliably tracked when the Theme’s edit used a move operation. A remove-and-add pair has to be inferred by matching removed content against added content, which can lose an override when the rename also changed the value, or when two identically valued tokens are renamed in the same publish.