Getting Started Connect with Claude MusicXML Import How to Use the API API Reference Strudel Basics

API Reference

All endpoints are under /api. Agent endpoints require an API key via the Authorization: Bearer header.

Method	Endpoint	Description
POST	/api/sessions	Create a new session
POST	/api/sessions/{id}/code	Push new code
GET	/api/sessions/{id}/status	Get current state + diff
POST	/api/sessions/{id}/play	Start playback
POST	/api/sessions/{id}/stop	Stop playback
GET	/api/sessions/{id}/events	SSE stream (real-time)
GET	/api/sessions/{id}/versions	List version history
GET	/api/sessions/{id}/versions/{v}	Get specific version
POST	/api/sessions/{id}/versions/{v}/revert	Revert to version

Create a Session

bash

curl -s -X POST /api/sessions \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 201

{ "id": "772a700d-050b-4b3a-93bb-80b0db269b99", "visibility": "private" }

Push Code

Pushes new code to the session. Creates a new version and broadcasts to all connected browsers via SSE.

bash

curl -s -X POST /api/sessions/{id}/code \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "YOUR_STRUDEL_CODE"}'

Response 200

{ "code": "...", "isPlaying": false, "version": 5 }

Check Status

Returns the current code, playback state, and a unified diff showing any browser edits since your last push. Always check status before pushing updates to avoid overwriting user edits.

bash

curl -s /api/sessions/{id}/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "code": "// current code...",
  "isPlaying": true,
  "diff": "--- agent (v2)\n+++ current\n@@ ...\n-old line\n+new line"
}

The diff field is null when the code hasn't changed since your last push.

Play / Stop

bash

# Start playback
curl -s -X POST /api/sessions/{id}/play \
  -H "Authorization: Bearer YOUR_API_KEY"

# Stop playback
curl -s -X POST /api/sessions/{id}/stop \
  -H "Authorization: Bearer YOUR_API_KEY"

SSE Events

The browser connects to the SSE endpoint to receive real-time updates. On connection, the current state is sent immediately. Each subsequent code push or play/stop triggers a new event.

Event format

data: {"code": "// strudel code...", "isPlaying": true}

data: {"code": "// updated code...", "isPlaying": true}

: keepalive

All events use the default SSE message event type. Keepalives are sent every 30 seconds.

Version History

Every code push (from the API or browser) creates a versioned snapshot. You can list versions, view a specific version's code, and revert to any previous version.

bash

# List versions (newest first)
curl -s "/api/sessions/{id}/versions?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get specific version
curl -s "/api/sessions/{id}/versions/2" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Revert to version (creates a new version, non-destructive)
curl -s -X POST "/api/sessions/{id}/versions/1/revert" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON Escaping

The code field is parsed as JSON. Invalid escape sequences (like \s, \d) will cause errors. For complex patterns, write to a file and use jq to auto-escape:

bash

# Write code to a file, then POST with jq for safe escaping
curl -s -X POST "/api/sessions/{id}/code" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg code "$(cat track.js)" '{code: $code}')"