Edit through REST
The REST API changes a working Rive graphic one operation at a time. Each operation locks the graphic for the request. Inside an edit session, it uses the lock of the session. It validates the whole configuration, saves, and publishes a live update to open builder tabs.
All routes sit under /rest/v2/themes/{themeId}/rive-graphics/{graphicId}. Write routes need themes:write.
Each write returns updatedAt, entityId, and the full stateMachine.
Optimistic concurrency
Section titled “Optimistic concurrency”Send ifUnchangedSince with the updatedAt you last read. A changed draft answers 409 TARGET_CHANGED.
The dashboard Graphics Builder takes the graphic’s edit lock on the first edit, not when it opens.
It releases the lock after 5 minutes with no edit, or when its tab closes.
While a builder holds the lock, every REST write answers 409 LOCKED. Retry after the builder releases it.
The ligr CLI sends ifUnchangedSince for you and retries once. See Command line.
Errors
Section titled “Errors”An error body has message and code. A 4xx answer can also have details, an array with one entry for each problem.
| Field | Content |
|---|---|
code | The error code, for example INVALID_CONFIGURATION, UNKNOWN_REFERENCE or INVALID_EXPRESSION. |
details[].field | The path of the value that failed. The path points into the request body or into the graphic configuration, for example controlVariables[stage].defaultValue or dataBindings[Main.homeScore].expression. |
details[].reason | What is wrong with the value, for example must be a JSON number. |
{ "message": "INVALID_CONFIGURATION", "code": "INVALID_CONFIGURATION", "details": [{ "field": "controlVariables[stage].defaultValue", "reason": "must be a JSON number" }]}A 500 answer has only message. The ligr CLI prints each detail on its own line as field: reason.
422 UNKNOWN_REFERENCE has one detail for each unknown $v or $u reference, so you can fix all of them before the next request.
Control variables
Section titled “Control variables”api POST "themes/$THEME_ID/rive-graphics/$GRAPHIC_ID/control-variables" \ --data '{"name":"stage","type":"enum","options":["GROUP A","FINAL"],"defaultValue":"GROUP A"}'api PATCH "themes/$THEME_ID/rive-graphics/$GRAPHIC_ID/control-variables/$CONTROL_ID" --data '{"defaultValue":"FINAL"}'api DELETE "themes/$THEME_ID/rive-graphics/$GRAPHIC_ID/control-variables/$CONTROL_ID?force=true"Types: string, number, boolean, enum, and the entity types team, player, match, fact, stat, teamStat, period, set, round, court.
Entity types carry a server-derived dataSchema in the response. hide is reserved.
A control variable default must have the JSON type of the variable. Send 0, not "0".
Removing a variable that an expression references answers 422 UNKNOWN_REFERENCE; force=true blanks those expressions.
Data bindings
Section titled “Data bindings”URL-encode each binding id in the path. For example, Main.players[] becomes Main.players%5B%5D.
B="themes/$THEME_ID/rive-graphics/$GRAPHIC_ID/data-bindings"api PATCH "$B/Main.homeScore" --data '{"expression":"$d.1.score"}'api PUT "$B/Main.badge/exposure" --data '{"name":"Home badge","expression":"$d.1.id","required":true,"entityType":"team"}'api PUT "$B/Main.badge/image-transform" --data '{"fit":"cover","outWidth":256,"outHeight":256}'api PUT "$B/Main.players%5B%5D/source-array" --data '{"arrayPath":"1.lineup"}'api POST "$B/Main.players%5B%5D/elements"api DELETE "$B/Main.players%5B%5D/elements/0"api PUT "$B/Main.players%5B%5D/elements/order" --data '{"order":[1,0]}'Change many bindings in one save with a batch. The API checks every change first; if one fails, it saves none. This route is in beta.
api PATCH "$B" --data '{"changes":[{"id":"Main.homeScore","expression":"$d.1.score"},{"id":"Main.awayScore","expression":"$d.2.score"},{"id":"Main.title","defaultValue":null}]}'Each change names one binding id once and sets expression, defaultValue, or both. A defaultValue of null clears it.
Exposure and image transforms apply to image bindings only. A source array applies to one list binding per graphic.
A source array is a path into the match data without the $d prefix, for example 1.lineup for team one’s lineup.
Enum bindings that read a theme variable
Section titled “Enum bindings that read a theme variable”A binding on a Rive enum property can read an enum theme variable, for example $t.Typeface.
Rive takes only the values of its enum. It ignores any other value, so on air the property keeps its last value.
If some options of the theme variable are not values of the Rive enum, the write still succeeds.
The response then has enumMismatches, with one entry for each such binding:
| Field | Content |
|---|---|
bindingId | The data binding, for example Main.Typeface. |
themeVariable | The theme variable that the expression reads, for example Typeface. |
optionsNotInEnum | The options of the theme variable that the Rive enum does not list. |
enumValuesNotInOptions | The values of the Rive enum that no option of the theme variable sets. |
Each write lists every such binding of the draft, not only the binding that it changed.
The API checks only an expression that reads one theme variable and nothing else, such as $t.Typeface or $t['Theme Colour'].
To remove the warning, make the options of the theme variable and the values of the Rive enum the same, or change the expression.
Inputs, assets, user expressions, schemas, settings
Section titled “Inputs, assets, user expressions, schemas, settings”G="themes/$THEME_ID/rive-graphics/$GRAPHIC_ID"api PATCH "$G/inputs/$INPUT_ID" --data '{"expression":"!$v.hide.value"}'api PATCH "$G/assets/crest.png" --data '{"expression":"$d.1.logo.url"}'api PUT "$G/assets/crest.png/exposure" --data '{"name":"Crest","required":true,"entityType":"team"}'api POST "$G/user-expressions" --data '{"name":"leader","expression":"$d.1.score > $d.2.score ? 1 : 2"}'api PATCH "$G/user-expressions/$EXPRESSION_ID" --data '{"name":"lead"}'api PUT "$G/schemas/tennisRankings"api PATCH "$G/settings" --data '{"renderer":"canvas","scale":0.5,"name":"Scorebug","sports":["football"]}'api PATCH "$G/settings" --data '{"layer":300}'layer is an integer from -100000 to 100000. When several graphics are on air, a higher layer covers a lower one.
A Rive graphic without a layer has depth 100. A code graphic without a layer has depth 200.
{"layer":300} puts the graphic in front of both. Send null to clear it.
GET $G returns it as stateMachine.layer and leaves it out when unset. GET $G also returns organizationId, the organization that owns the theme.
A rename sends name alone and answers 200. Expressions that read the old name stay as they are. The response lists them in staleReferences. Update each one to the new name.
A write never fails on a reference that was already unknown before the write. A reference to a new unknown name answers 422 UNKNOWN_REFERENCE.
Revisions and thumbnail
Section titled “Revisions and thumbnail”api GET "$G/revisions"api GET "$G/files/runtime?version=working&revisionId=$REVISION_ID"api PUT "$G/thumbnail" --data '{"fileId":123}'GET $G/revisions lists every runtime revision, newest first. A revisionId downloads that exact revision.
version is still required on the file route. If you send revisionId, it wins.
Upload the thumbnail with POST themes/$THEME_ID/rive-graphics/images first. Send the fileId that the upload returns. Use a PNG, JPEG or WebP image of at most 5 MB.
While an edit session is open, send x-ligr-edit-session on publish, replace and thumbnail requests.
Edit sessions
Section titled “Edit sessions”An edit session keeps the edit lock for your API key across many requests. Use one for a series of changes.
SESSION=$(api POST "$G/edit-sessions" --data '{"agentLabel":"Claude Code"}' | jq -er '.sessionToken')api PATCH "$G/settings" -H "x-ligr-edit-session: $SESSION" --data '{"scale":0.5}'api PUT "$G/edit-sessions/$SESSION/heartbeat"api DELETE "$G/edit-sessions/$SESSION?outcome=keep"- Start the session. If another editor holds the graphic, the API answers
409 LOCKED. - Send the
sessionTokenin thex-ligr-edit-sessionheader on every write. This includes publish, replace and thumbnail requests. - Each write extends the lock by 60 seconds. When you make no writes, send a heartbeat every 20 seconds.
- End the session.
outcome=keepkeeps the draft as it is.outcome=discardrestores the draft as it was at the session start, or at the last publish, replace or thumbnail in the session.
During the session, the open builder is read-only and shows each change live.
A person can take the graphic back in the builder. Then the next write or heartbeat answers 409 SESSION_INVALID.
Graphic lifecycle
Section titled “Graphic lifecycle”api GET "themes/$THEME_ID/rive-graphics"api POST "$G/duplicate" --data '{"name":"Scorebug copy"}'api DELETE "$G"Delete is refused with 409 TARGET_NOT_EMPTY while the active theme version pins a published version of the graphic.
Publish, theme snapshots and activation are unchanged; read Import through REST step 6.