Sessions endpoints

The sessions family is the center of the Local API.

Main routes

• GET /api/v1/sessions
• POST /api/v1/sessions
• GET /api/v1/sessions/{id}
• PATCH /api/v1/sessions/{id}
• DELETE /api/v1/sessions/{id}

Filtering and search

The list route supports:

• q
• kind
• daw as an alias for kind
• tags
• recent
• sort
• limit
• offset

Session object highlights

Important fields you will use frequently:

• id
• title
• kind
• status
• tags
• notes
• projectPath
• previewStatus
• previewAudioUrl

Write strategy

If your tool edits only one narrow field, prefer the field-specific endpoints where available:

• notes: /sessions/{id}/notes
• tags: /sessions/{id}/tags

Use PATCH /sessions/{id} for broader metadata updates.

Example: create a draft session

curl \
  -X POST \
  -H "Authorization: Bearer $SESSIONDOCK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New idea",
    "kind": "Ableton",
    "status": "draft",
    "tags": ["ideas", "writing"]
  }' \
  "$SESSIONDOCK_BASE_URL/sessions"

Example: patch notes and status together

curl \
  -X PATCH \
  -H "Authorization: Bearer $SESSIONDOCK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Print a brighter synth stem for revision B.",
    "status": "in-progress"
  }' \
  "$SESSIONDOCK_BASE_URL/sessions/session_123"

Jump to the generated API reference for schema-level details.