Documents

Documents make .ws source durable. Use them when a video artifact needs collaboration, version history, review metadata, locks, annotations, or repeat rendering.

Create Document

POST/api/documents

Create document

Persists a .ws source document for the current org.

bash

curl -X POST "$WORKSHOP_URL/api/documents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $WORKSHOP_API_KEY" \
  -d '{
    "name": "Quarterly Results",
    "source": "Film "Quarterly Results"
  mood: precision

Scene "Intro"
  show "Q2 revenue grew 18%."
    size: hero",
    "metadata": { "owner": "finance" }
  }'

Document CRUD

Route	Purpose
`GET /api/documents`	List documents
`GET /api/documents/{id}`	Read a document
`PUT /api/documents/{id}`	Update source or metadata
`DELETE /api/documents/{id}`	Delete a document
`GET /api/documents/{id}/versions`	List document versions

Render Document

POST/api/documents/{id}/render

Render persisted document

Queues a render using the document's current source.

Structured Edits

POST/api/documents/{id}/edit

Apply structured edits

Applies targeted edits to a document. Useful for operators, agents, and form-driven UIs.

The document API is a natural foundation for future operator forms: teams can expose controlled fields for copy, color, timing, asset choices, or personalization variables while preserving source history and review flow.

Locks

Route	Purpose
`POST /api/documents/{id}/lock`	Acquire edit lock
`GET /api/documents/{id}/lock`	Read lock status
`DELETE /api/documents/{id}/lock`	Release edit lock

Annotations

Route	Purpose
`POST /api/documents/{id}/annotations`	Add annotation
`GET /api/documents/{id}/annotations`	List annotations
`DELETE /api/documents/{id}/annotations/{annotationId}`	Delete annotation

Publication Boundary

A document can be valid and rendered without being published. Workshop supports the production artifact; your workflow should still decide who approves the artifact and who decides it is published.

Next Steps

Compile - validate source before saving or rendering
Render - job model and MP4 output
MCP - document tools for agents