How to Use the API

Control StrudelHub sessions programmatically — push code, start playback, and listen for changes in real time.

1. Get an API key

API keys let scripts and AI agents interact with your sessions. Go to API Keys in your dashboard and create a new key. The raw key is shown only once — copy and store it securely.

Include the key in every request as a Bearer token:

Authorization: Bearer your_api_key_here

2. Create a session

You can create sessions from the dashboard or via the API. The API returns a session ID that you'll use for all subsequent calls.

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

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

Open the session in your browser to hear audio in real time:

/sessions/{session_id}

3. Push code

Send Strudel code to the session. The browser receives the update instantly via SSE and displays it in the editor.

curl -s -X POST /api/sessions/{id}/code \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "$: s(\"bd sd hh hh\").bank(\"RolandTR909\")"}'

4. Start playback

Once you've pushed code, tell the browser to start (or stop) playing:

# 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"

The browser evaluates and plays the audio locally — the server only coordinates the state. You can push new code at any time and it hot-reloads while playing.

5. Check session status

Before pushing an update, check whether the user has edited the code in the browser. The diff field shows what changed since your last push.

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

{
  "code": "// current code...",
  "isPlaying": true,
  "diff": null
}

6. Version history

Every code push creates a versioned snapshot. You can list versions, inspect a specific one, or revert to a previous version.

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

# Revert to a specific version
curl -s -X POST "/api/sessions/{id}/versions/1/revert" \
  -H "Authorization: Bearer YOUR_API_KEY"