Variable Collections

CRUD for variable collections — the document-level API for design tokens.

Type reference

// Variable collections group design tokens and define their modes (e.g. Light/Dark, Desktop/Mobile).
// All ID params accept both IDs and display names.
// ---
// valuesByMode: values keyed by mode name, e.g. {"Light": "#FFF", "Dark": "#111"}.
// Aliases: {type: "VARIABLE_ALIAS", name: "other/variable"}.
// scopes: see variables endpoint for full list.
// Deleting a collection deletes all variables inside it.
// The default mode cannot be removed. Use add_mode/remove_mode for additional modes.

8 methods available.

list

read

List variable collections

Parameter	Type	Required	Description
fields	string[]	✗	Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.
offset	number	✗	Skip N items for pagination (default 0) (default: 0)
limit	number	✗	Max items per page (default 100) (default: 100)

Response

Field	Type	Description
totalCount	number	Total matching items
returned	number	Items in this page
offset	number
limit	number
items	object[]
↳ id	string
↳ name	string
↳ modes	string[]	Mode names
↳ variableCount	number	Number of variables

get

read

Get collection with all variables and values (full document)

Parameter	Type	Required	Description
id	string	✓	Collection ID or name
fields	string[]	✗	Property whitelist. Identity fields (id, name, type) always included. Omit for stubs on list, full on get. Pass ["*"] for all.

Response

Field	Type	Description
id	string
name	string
modes	string[]	Mode names (e.g. ['Light', 'Dark'])
variables	object[]	All variables in this collection
↳ name	string
↳ type	string	COLOR | FLOAT | STRING | BOOLEAN
↳ valuesByMode	object	Values keyed by mode name
↳ scopes	string[]
↳ description	string

create

create

Create a collection with modes and variables in one call

Parameter	Type	Required	Description
items	object[]	✓	Array of collection documents
↳ name	string	✓	Collection name
↳ modes	string[]	✗	Mode names (e.g. ['Light', 'Dark']). Omit for single-mode collection.
↳ variables	object[]	✗	Variables to create inside this collection
↳ name	string	✓	Variable name (unique within collection)
↳ type	"COLOR" | "FLOAT" | "STRING" | "BOOLEAN"	✓	Variable type
↳ value	any	✗	Sets all modes to this value. Use valuesByMode for per-mode control.
↳ valuesByMode	object	✗	Values keyed by mode name (e.g. {"Light": "#FFF", "Dark": "#111"})
↳ description	string	✗
↳ scopes	string[]	✗	Restrict where variable can be applied (default: ALL_SCOPES)

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string

update

edit

Rename collections

Parameter	Type	Required	Description
items	object[]	✓	Array of {id, name}
↳ id	string	✓	Collection ID or name
↳ name	string	✓	New name

Response

Field	Type	Description
results	any[]	Array of "ok" or {error} per item

delete

edit

Delete collections

Parameter	Type	Required	Description
id	string	✗	Collection ID or name
items	object[]	✗	Batch: [{id}, ...]
↳ id	string	✓

Response

Field	Type	Description
results	string[]	Array of "ok" per item

add_mode

create

Add a mode to a collection

Parameter	Type	Required	Description
items	object[]	✓	Array of {collectionId, name}
↳ collectionId	string	✓	Collection ID or name
↳ name	string	✓	Mode name

Response

Field	Type	Description
results	object[]	One entry per input item
↳ modeId	string

rename_mode

edit

Rename a mode

Parameter	Type	Required	Description
items	object[]	✓	Array of {collectionId, modeId, name}
↳ collectionId	string	✓	Collection ID or name
↳ modeId	string	✓	Mode ID or name (e.g. "Dark")
↳ name	string	✓	New name

Response

Field	Type	Description
results	any[]	Array of "ok" or {error} per item

remove_mode

edit

Remove a mode from a collection

Parameter	Type	Required	Description
items	object[]	✓	Array of {collectionId, modeId}
↳ collectionId	string	✓	Collection ID or name
↳ modeId	string	✓	Mode ID or name (e.g. "Dark")

Response

Field	Type	Description
results	string[]	Array of "ok" per item