Documentation

API Reference

HTTP API for integrating Chalkboard into your stack. Includes SSE streaming for live pipeline progress.

Setup

Starting the server

python run_server.py            # http://localhost:8000
python run_server.py --reload   # dev mode (auto-reload on file changes)
python run_server.py --port 9000 # custom port

The server holds jobs in memory; they are lost on restart. Each job runs the full pipeline (script → Manim → render → QA) in a background task. The SERVER_PORT env var sets the default port; --port overrides it at runtime.

Reference

Endpoints

Method Path Description
POST /api/jobs Create a job from a JSON body (no file uploads)
POST /api/jobs/upload Create a job with file uploads (multipart form)
GET /api/jobs List all jobs in this server session
GET /api/jobs/{id} Get a job by ID. Poll for status and output file list.
GET /api/jobs/{id}/events SSE stream. One event per pipeline node update, then {"done": true}.
GET /api/jobs/{id}/files/{filename} Download an output file (final.mp4, captions.srt, etc.)

Jobs

Creating a job

JSON (no files)

Send a JSON body to POST /api/jobs. Returns 202 immediately; the pipeline runs in the background.

Minimal

curl -s -X POST http://localhost:8000/api/jobs \
  -H "Content-Type: application/json" \
  -d '{"topic": "explain recursion", "effort": "low"}' | python3 -m json.tool

All options

curl -s -X POST http://localhost:8000/api/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "topic":         "explain recursion",
    "effort":        "high",
    "audience":      "beginner",
    "tone":          "casual",
    "theme":         "chalkboard",
    "template":      "algorithm",
    "speed":         1.25,
    "burn_captions": true,
    "quiz":          true,
    "qa_density":    "normal",
    "urls":          ["https://en.wikipedia.org/wiki/Recursion"],
    "github":        ["nicglazkov/Chalkboard"]
  }' | python3 -m json.tool

Multipart with file uploads

Send a multipart form to POST /api/jobs/upload to include local files as source material. All the same fields are available as form fields. Per-file size limits: text/code 2 MB · images 5 MB · PDFs 20 MB · DOCX 10 MB · 24 MB total.

curl -s -X POST http://localhost:8000/api/jobs/upload \
  -F "topic=explain this codebase" \
  -F "effort=medium" \
  -F "files=@./README.md" \
  -F "files=@./main.py" | python3 -m json.tool

Streaming

Live progress (SSE)

Connect to GET /api/jobs/{id}/events to receive a server-sent event stream. One event is emitted per pipeline node update. The stream ends with {"done": true} when the job reaches a terminal state.

curl -s http://localhost:8000/api/jobs/<id>/events

Example event

data: {"node": "script_agent", "updates": {"script": "...", "script_segments": [...]}}

data: {"node": "fact_validator", "updates": {"fact_feedback": null}}

data: {"node": "manim_agent", "updates": {"manim_code": "..."}}

data: {"done": true}

Pipeline stages in order: init → research_agent (high effort only) → script_agent → fact_validator → manim_agent → code_validator → render_trigger.

Output

Downloading output

After a job completes, output_files in the job response lists the filenames available for download.

# Download the video
curl -o final.mp4 http://localhost:8000/api/jobs/<id>/files/final.mp4

# Download captions
curl -o captions.srt http://localhost:8000/api/jobs/<id>/files/captions.srt

# Download the quiz
curl -o quiz.json http://localhost:8000/api/jobs/<id>/files/quiz.json

Output files

File Contents
final.mp4 Full HD video with embedded chapter atoms
captions.srt SRT subtitle file (one entry per script segment)
script.txt Full narration script as plain text
scene.py Generated Manim Python source
segments.json Per-segment text and actual audio durations
quiz.json Comprehension questions (only when quiz: true)
manifest.json Run metadata: run ID, topic, quality, timestamp

Schema

Job response

All job endpoints return this shape:

{
  "id":           "uuid",
  "status":       "pending | running | completed | failed",
  "topic":        "explain recursion",
  "events":       [{"node": "script_agent", "updates": {...}}, ...],
  "error":        null,
  "output_files": ["final.mp4", "captions.srt", "script.txt"]
}

status transitions: pending → running → completed or failed. When failed, error contains the exception message. When the render fails but the pipeline succeeded, error is "render failed; pipeline output preserved" and status is still completed.

Interface

Web UI

The server includes a built-in web interface at http://localhost:8000 with a job creation form, live progress view, and video library. No build step required. See the Guide for a full walkthrough.