Graphics API

The Graphics API exposes LiveWing's broadcast graphics system over HTTP. You can list graphics, read their scene graphs, update field defaults, publish/unpublish, and send prompts to the AI graphics agent.

All endpoints require authentication via a workspace API key. See CMS API for authentication details.

Read Endpoints

These endpoints require an API key with read permission.

List Graphics

GET /api/graphics

Returns all graphics in the workspace. Optionally filter by status.

Query parameters:

Parameter	Type	Description
`status`	`"draft"` \| `"published"`	Optional. Filter by graphic status.

Example request:

curl -H "Authorization: Bearer lw_YOUR_KEY" \
  "https://ideal-heron-677.convex.site/api/graphics?status=published"

Example response:

{
  "graphics": [
    {
      "_id": "k57abc123def456",
      "name": "Lower Third",
      "status": "published",
      "revision": 3,
      "publishedAt": 1711900000000,
      "updatedAt": 1711900000000,
      "canvas": { "width": 1920, "height": 1080 },
      "fieldCount": 2,
      "nodeCount": 5
    }
  ]
}

Get Graphic Metadata

POST /api/graphics/get

Get detailed metadata for a specific graphic, including canvas size, field definitions, and node/asset counts.

Request body:

{
  "graphicId": "k57abc123def456"
}

Example response:

{
  "_id": "k57abc123def456",
  "name": "Lower Third",
  "status": "published",
  "revision": 3,
  "publishedAt": 1711900000000,
  "updatedAt": 1711900000000,
  "canvas": { "width": 1920, "height": 1080 },
  "fields": [
    {
      "key": "name",
      "label": "Name",
      "type": "text",
      "defaultValue": "John Doe"
    },
    {
      "key": "title",
      "label": "Title",
      "type": "text",
      "defaultValue": "Producer"
    }
  ],
  "nodeCount": 5,
  "assetCount": 1
}

Get Field Definitions

POST /api/graphics/fields

Returns just the field definitions for a graphic. Fields define what dynamic data the graphic expects (text, images, colors, etc.) and are mapped to CMS collection data in productions.

Request body:

{
  "graphicId": "k57abc123def456"
}

Example response:

{
  "_id": "k57abc123def456",
  "name": "Lower Third",
  "fields": [
    {
      "key": "name",
      "label": "Name",
      "type": "text",
      "defaultValue": "John Doe"
    },
    {
      "key": "title",
      "label": "Title",
      "type": "text",
      "defaultValue": "Producer"
    },
    {
      "key": "teamLogo",
      "label": "Team Logo",
      "type": "image"
    }
  ]
}

Get Full Document (Scene Graph)

POST /api/graphics/document

Returns the complete GaggleDocument for a graphic: the full scene graph including all nodes, assets, canvas dimensions, field definitions, and transitions. This is the internal document format used by the LiveWing graphics renderer.

Request body:

{
  "graphicId": "k57abc123def456"
}

Example response:

{
  "_id": "k57abc123def456",
  "name": "Lower Third",
  "status": "published",
  "revision": 3,
  "document": {
    "id": "uuid-here",
    "schemaVersion": 1,
    "name": "Lower Third",
    "canvas": { "width": 1920, "height": 1080 },
    "nodes": [
      {
        "id": "node-1",
        "type": "shape",
        "zIndex": 0,
        "rect": { "x": 0, "y": 860, "width": 1920, "height": 220 },
        "props": { "shape": "rect", "fill": "#1a1a2e" }
      },
      {
        "id": "node-2",
        "type": "text",
        "zIndex": 1,
        "rect": { "x": 60, "y": 880, "width": 800, "height": 60 },
        "props": {
          "content": "{name}",
          "fontFamily": "Inter",
          "fontSize": 48,
          "fontWeight": 700,
          "color": "#FFFFFF"
        }
      }
    ],
    "fields": [
      { "key": "name", "label": "Name", "type": "text", "defaultValue": "John Doe" }
    ],
    "assets": [],
    "transitions": {
      "in": { "type": "slideUp", "duration": 400, "easing": "ease-out" },
      "out": { "type": "slideDown", "duration": 300, "easing": "ease-in" }
    }
  }
}

Write Endpoints

These endpoints require an API key with readwrite permission.

Create Graphic

POST /api/graphics/create

Create a new graphic with the default lower-third template.

Request body:

{
  "name": "Game Scorebug"
}

Example response (201):

{
  "_id": "k57newgraphic...",
  "name": "Game Scorebug",
  "status": "draft"
}

Graphic names must be unique within the workspace.

Delete Graphic

POST /api/graphics/delete

Permanently delete a graphic.

Request body:

{
  "graphicId": "k57abc123def456"
}

Example response:

{
  "ok": true
}

Update Field Defaults

POST /api/graphics/fields/update

Update the default values for a graphic's fields. This changes what data is shown when no production override is active. Only updates default values, not the field definitions themselves.

Request body:

{
  "graphicId": "k57abc123def456",
  "fields": {
    "name": "Jane Smith",
    "title": "Director"
  }
}

Example response:

{
  "updated": ["name", "title"]
}

Unknown field keys will return a 400 error. Only keys present in the fields object are updated; omitted fields keep their current defaults.

Publish Graphic

POST /api/graphics/publish

Publish a graphic, making it available for device sync and live production use. Increments the revision number.

Request body:

{
  "graphicId": "k57abc123def456"
}

Example response:

{
  "status": "published",
  "revision": 4
}

Unpublish Graphic

POST /api/graphics/unpublish

Revert a published graphic back to draft status. The graphic will no longer be available on devices.

Request body:

{
  "graphicId": "k57abc123def456"
}

Example response:

{
  "status": "draft"
}

Returns a 400 error if the graphic is already a draft.

AI Agent Endpoint

Send Agent Message

POST /api/graphics/agent

Send a natural language prompt to the AI graphics agent for a specific graphic. The agent can read and modify the graphic's scene graph, add/remove nodes, change styles, create layouts, and manage animations.

Requires readwrite permission. Messages are limited to 4,000 characters.

Request body:

{
  "graphicId": "k57abc123def456",
  "message": "Add a red accent bar on the left side of the lower third, 8px wide"
}

Example response:

{
  "response": "Added a red accent bar (8px wide) on the left edge of the lower third background."
}

The agent maintains conversation history per graphic. Subsequent messages to the same graphic continue the existing conversation thread, so you can iterate:

{ "message": "Make it blue instead" }

{ "message": "Now add a 200ms slide-in animation with stagger on each text element" }

The agent has access to tools for:

Reading the current scene graph (nodes, fields, assets)
Creating layouts using CSS flexbox semantics
Batch editing node properties (position, size, color, font, etc.)
Managing animations (transitions and timed cues)
Adding fields for dynamic CMS data binding

Data Model Notes

Graphics

Each graphic is a self-contained broadcast overlay with:

Canvas — fixed dimensions (typically 1920x1080)
Nodes — the visual elements: text, shapes, images, and groups. Each has a position (rect), z-order, and type-specific properties.
Fields — data slots that can be populated by CMS collections during a production (e.g., player name, team logo, score)
Assets — referenced images and fonts
Transitions — animation definitions for how the graphic appears/disappears
Status — draft (editing) or published (available on devices)
Revision — incremented each time the graphic is published

Field Types

Fields define what dynamic data a graphic expects. Supported types:

Type	Description
`text`	Single-line text
`longText`	Multi-line text
`number`	Numeric value
`boolean`	True/false toggle
`select`	Single choice from options
`multiSelect`	Multiple choices from options
`color`	Hex color value
`image`	Image asset reference

Node Types

Type	Description
`text`	Text element with font, size, color, alignment
`shape`	Rectangle, ellipse, triangle, or line with fill/border
`image`	Image with fit mode (cover, contain, fill)
`group`	Container for child nodes, optional clipping

Error Codes

Status	Meaning
`400`	Bad request (missing params, invalid field key, graphic already draft)
`401`	Missing or invalid API key
`403`	API key has read-only permission for a write endpoint
`404`	Graphic not found or does not belong to this workspace
`500`	Internal error (agent failure, server issue)

Graphics API

On this page