API Reference

Creates a new user account. Returns a JWT token and sends a welcome email.

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "email": "you@example.com",
    "credits": 1
  }
}

curl -X POST https://your-domain.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"securepass"}'

Authenticates with email and password. Returns a JWT token valid for 7 days.

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "user": { "id": 1, "email": "you@example.com", "credits": 5 }
}

Sends a password-reset email if the address is registered. Always returns 202 to prevent email enumeration.

{ "message": "If that email is registered, you will receive a reset link shortly." }

Consumes a one-time reset token (expires 1 hour after issue) and sets the new password.

{
  "id": 1,
  "email": "you@example.com",
  "credits": 5,
  "is_admin": false,
  "member_since": "2026-01-15T10:30:00"
}

Upload an audio file for instrument identification. Returns the result synchronously, or a job ID if async_mode=true.

{
  "analysis_id": 42,
  "filename": "track.wav",
  "credits_remaining": 4,
  "result": {
    "analysis": {
      "instruments": [
        { "model": "Fender Precision Bass", "confidence_pct": 94.2,
          "family": "bass", "role_in_mix": "rhythm" }
      ],
      "genre": [
        { "genre": "Rock", "confidence_pct": 100 },
        { "genre": "Blues / Soul", "confidence_pct": 72 }
      ],
      "mood": { "label": "Energetic & Upbeat", "energy": 78, "valence": 70,
               "danceability": 65, "acousticness": 42 },
      "tonality": { "key": "A", "mode": "minor", "tempo_bpm": 120 }
    }
  }
}

{ "job_id": "a1b2c3d4...", "status": "pending" }

curl -X POST "https://your-domain.com/api/analyze?mode=offline&rights_attested=true" \
  -H "X-API-Key: msk_xxxxxx" \
  -F "file=@track.wav"

Analyzes multiple files in a single call. Defaults to offline mode to protect credits.

{
  "total": 3,
  "ok": 3,
  "credits_used": 0,
  "credits_remaining": 5,
  "results": [...]
}

Returns the status of an async job. Poll until status is done or failed.

{
  "job_id": "a1b2c3...",
  "status": "done",  // "pending" | "processing" | "done" | "failed"
  "filename": "track.wav",
  "analysis_id": 42,        // only when done
  "result": { ... }         // full result object when done
}

{
  "analyses": [
    {
      "id": 42,
      "filename": "track.wav",
      "primary_instrument": "Fender Precision Bass",
      "created_at": "2026-04-18T10:30:00"
    }
  ],
  "total": 1,
  "page": 1,
  "has_next": false
}

Generates a public URL for sharing results without authentication. Idempotent — calling it twice returns the same URL.

{ "share_url": "/r/abc123xyz", "token": "abc123xyz" }

Returns the full analysis result for a share token. No authentication required — suitable for embedding in other apps.

{
  "id": 1,
  "key": "msk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "msk_xxxxxxxx",
  "label": "My Server",
  "created_at": "2026-04-18T10:00:00",
  "warning": "Save this key now — it will not be shown again."
}

{
  "keys": [
    {
      "id": 1,
      "prefix": "msk_xxxxxxxx…",
      "label": "My Server",
      "is_active": true,
      "requests_count": 142,      // lifetime total
      "requests_today": 7,        // resets at midnight UTC
      "daily_limit": 1000,
      "last_used_at": "2026-04-18T09:45:00",
      "created_at": "2026-04-01T12:00:00"
    }
  ]
}

Deactivates the key. Any subsequent requests using this key will return 401.

{
  "id": 1,
  "url": "https://your-server.com/webhooks/maestro",
  "secret": "your_signing_secret",  // shown ONCE
  "events": "analysis.complete",
  "created_at": "2026-04-18T10:00:00"
}

{
  "webhooks": [
    {
      "id": 1,
      "url": "https://your-server.com/webhooks/maestro",
      "events": "analysis.complete",
      "is_active": true,
      "last_triggered_at": "2026-04-18T09:00:00",
      "last_status_code": 200
    }
  ]
}

Fires a webhook.test event to verify your endpoint is reachable.

{ "delivered": true, "status_code": 200 }

Returns every collection owned by the authenticated user, ordered by most recently updated.

[
  {
    "id": 1,
    "name": "My Album Session",
    "description": "Tracking for the new LP",
    "color": "#EF4444",
    "item_count": 12,
    "created_at": "2026-04-10T09:00:00",
    "updated_at": "2026-04-18T15:22:00"
  }
]

{
  "id": 10,
  "name": "My Album Session",
  "description": null,
  "color": "#EF4444",
  "item_count": 0,
  "created_at": "2026-04-19T10:00:00"
}

curl -X POST https://your-domain.com/api/collections \
  -H "X-API-Key: msk_xxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Album Session","color":"#EF4444"}'

{
  "id": 10,
  "name": "My Album Session",
  "description": null,
  "color": "#EF4444",
  "item_count": 2,
  "analyses": [
    {
      "id": 42,
      "filename": "track01.wav",
      "primary_instrument": "Fender Precision Bass",
      "primary_genre": "Rock",
      "added_at": "2026-04-18T10:30:00"
    }
  ]
}

Adds an existing analysis owned by the caller to the given collection. Idempotent — adding the same analysis twice is a no-op.

{
  "collection_id": 10,
  "analysis_id": 42,
  "added_at": "2026-04-19T10:01:00"
}

Removes the link between an analysis and a collection. The analysis itself is not deleted.

Returns a rolled-up summary of the authenticated user's analysis history — top instruments, genres, mood distribution and tonality distribution. Useful for dashboards.

{
  "total": 87,
  "top_instruments": [
    { "label": "Fender Precision Bass", "count": 31 },
    { "label": "Gibson Les Paul",       "count": 14 }
  ],
  "top_genres": [
    { "label": "Rock",  "count": 40 },
    { "label": "Blues", "count": 12 }
  ],
  "mood_distribution": {
    "Energetic & Upbeat": 22,
    "Chill":              18
  },
  "tonality_distribution": {
    "A minor": 12,
    "C major": 9
  }
}