API Reference

Workshop exposes a production API for deterministic motion graphics. Most routes live under /api/* and require either an org-scoped API key or a signed bearer token.

Use https://demo.ws.video for the hosted demo/staging environment unless your account has a dedicated base URL.

bash

export WORKSHOP_URL="https://demo.ws.video"
export WORKSHOP_API_KEY="sk_live_..."

bash

curl "$WORKSHOP_URL/api/health" \
  -H "x-api-key: $WORKSHOP_API_KEY"

Start Here

Authentication - API keys, bearer tokens, org scoping, OAuth metadata, and demo mode
Compile - turn .ws source into a RenderGraph
Render - queue renders, poll jobs, and download MP4s
Error Handling - status codes and diagnostics

Production Resources

Assets - upload images, logos, audio, video, fonts, and supporting files
Sources and Clips - long-form source media, preprocessing, candidate clips, and clip documents
Templates - reusable video structures and template renders
Themes - ThemePack CRUD and validation
Moods - built-in moods, aliases, and mood profiles
Documents - persisted .ws documents, versions, locks, annotations, edits, and renders

Agent And Integration Surfaces

AI Authoring - prompt-to-.ws generation with compiler validation
Prompt Generation - optional prompts for external video model scenes
Principals and Tokens - DB-backed API principals and short-lived bearer tokens
MCP - streamable HTTP MCP transport and HTTP gateway tools
OpenAPI and Postman - machine-readable contracts and client collections

Public Routes

These routes do not require API authentication:

Route	Purpose
`GET /health`	Public server health check
`GET /assets/{id}`	Read uploaded asset media by ID
`GET /sources/{id}/media`	Read registered source media by ID
`GET /sources/{id}/thumbnails/{thumbnailId}`	Read generated source thumbnails
`GET /.well-known/oauth-protected-resource`	OAuth protected-resource metadata
`GET /.well-known/oauth-authorization-server`	OAuth authorization-server metadata
`POST /oauth/token`	OAuth client-credentials token issuance

Current Surface Area

The public API includes compile, validate, render, queue, assets, sources, clips, templates, themes, moods, documents, authoring, MCP, principals, bearer tokens, health, and OAuth discovery. The OpenAPI contract in this docs set is the canonical route inventory for generated clients.