limbo/Beat — API Integration Guide#

This guide is for developers integrating with the limbo/Beat API. It assumes you have already received your access credentials (API key, dashboard user/password, webhook signing secret) from the Limbo team. If you have not, contact us before continuing.

Do not share your API key, do not commit it to source control.

1. Overview#

1.1 What this API does#

The limbo/Beat API performs automated quality-assurance analysis on a music release (album + tracks). You submit the album metadata and asset URLs; the API runs a series of checks (images, metadata, audio) and returns a structured report indicating whether the release is ready to ship, has warnings, or has blocking issues.

The pipeline is asynchronous. The submission endpoint returns immediately; the result is delivered either via webhook (recommended) or by polling.

1.2 Base URL#

Hostnames for your environment are provided at provisioning. The /v1 path prefix and HTTPS-only requirement are the same across all environments.

1.3 Authentication#

Every API request must include your API key in the x-api-key header:

x-api-key: <YOUR_API_KEY>

The API key is shown only once when your access is provisioned. Store it securely on your side.

There is no OAuth, no Bearer token, no rotating credential flow. The API key is the single secret used to authenticate.

The dashboard uses a separate username/password. API integrations only ever use x-api-key.

1.4 The dashboard#

The dashboard is a web UI where your operator can:

• See the history of every QA run you have submitted
• Open the full report for any run
• Edit your qa_config defaults (which checks are enabled, severity, thresholds)
• Send a test payload to your webhook endpoint without consuming quota

You log in with the username/password you received when your access was provisioned.

2. API Reference#

The API exposes three endpoints. All require the x-api-key header.

2.1 POST /qa/album#

Submit one album with its tracks for QA analysis. The response is 202 Accepted with a qa_run_id you can use to retrieve the result.

POST /qa/album
Host: <api-host>

Headers#

Top-level body parameters#

album object parameters#

tracks[] object parameters#

Required:

Optional:

Example request body#

{
  "album_id": "MY-LABEL-RELEASE-00042",
  "callback_url": "https://my-app.example.com/webhooks/limbo-qa",
  "album": {
    "title": "Sample Album Title",
    "main_artist": ["Example Artist"],
    "label": "My Label Records",
    "genre_1": "World Music",
    "genre_2": "Folk",
    "release_date": "2025-06-15",
    "upc": "1234567890128",
    "language": "en",
    "production_line": "2025 My Label Records",
    "version": null,
    "cover_image_url": "https://my-cdn.example.com/covers/00042.jpg",
    "producer": ["John Doe"],
    "composer": ["Example Artist"],
    "lyricist": ["Example Artist"]
  },
  "tracks": [
    {
      "track_id": "MY-LABEL-RELEASE-00042-01",
      "title": "Sample Album Title",
      "main_artist": ["Example Artist"],
      "isrc": "USXXX2500001",
      "track_number": 1,
      "disc_number": 1,
      "duration_seconds": 245.3,
      "language": "en",
      "explicit": false,
      "is_cover": false,
      "is_remix": false,
      "audio_url": "https://my-cdn.example.com/audio/00042-01.flac",
      "lyrics": "Sample lyrics line one\nSample lyrics line two...",
      "genre_1": "World Music",
      "genre_2": "Folk",
      "production_line": "2025 My Label Records",
      "composer": ["Example Artist"],
      "lyricist": ["Example Artist"],
      "producer": ["John Doe"]
    }
  ]
}

Response — 202 Accepted#

{
  "album_id": "MY-LABEL-RELEASE-00042",
  "qa_run_id": "QA-7m3pXkQwF2A9",
  "status": "QUEUED",
  "status_url": "/qa/album/MY-LABEL-RELEASE-00042/status?qa_run_id=QA-7m3pXkQwF2A9",
  "report_url": "/qa/album/MY-LABEL-RELEASE-00042/report?qa_run_id=QA-7m3pXkQwF2A9"
}

• qa_run_id — unique handle for this submission. Store it.
• status — always QUEUED for new submissions. See §5.1 for the full lifecycle.
• status_url / report_url — relative paths you can poll, both already qualified with the right qa_run_id.

Response — 202 Accepted (idempotent replay)#

When you POST the same Idempotency-Key again and the previous request already finished, you receive the cached response with an extra flag:

{
  "album_id": "...",
  "qa_run_id": "...",
  "status": "QUEUED",
  "status_url": "...",
  "report_url": "...",
  "idempotent_replay": true
}

The submission is not processed again. Quota is not charged again.

Response — 400 Bad Request#

Response — 403 Forbidden#

Response — 409 Conflict#

{ "error": "request_in_flight" }

Another POST with the same Idempotency-Key is still being processed. Poll the same key; do not retry until it returns.

Response — 422 Unprocessable Entity#

{
  "error": "idempotency_key_reuse",
  "message": "Idempotency-Key was already used with a different request body. Use a fresh Idempotency-Key for a new request, or resend the exact same body to replay."
}

You sent the same Idempotency-Key you used before, but the request body is not byte-identical to the original. We block this to prevent your client from accidentally receiving back the qa_run_id of a different submission. Either:

• Generate a fresh Idempotency-Key for the new submission, OR
• Resend the exact original body byte-for-byte to replay the cached response.

Quota is not charged on this response.

Response — 500 Internal Server Error#

Transient failure. Quota is not consumed on this failure; retry with the same Idempotency-Key is safe.

2.2 GET /qa/album/{albumId}/status#

Lightweight poll. Returns the pipeline state and a summary of check counts. Use this when you only need to know whether a run finished — not the full report.

GET /qa/album/{albumId}/status?qa_run_id={qa_run_id}
Host: <api-host>

Path parameters#

Query parameters#

Headers#

Response — 200 OK#

{
  "album_id": "MY-LABEL-RELEASE-00042",
  "qa_run_id": "QA-7m3pXkQwF2A9",
  "status": "COMPLETED",
  "overall_status": "WARNING",
  /* additional pipeline timestamps and echoed input metadata */
  "callback_url": "https://my-app.example.com/webhooks/limbo-qa",
  "summary": {
    "total_checks": "9",
    "passed": "7",
    "failed": "0",
    "errors": "0",
    "warnings": "2"
  }
}

Field meanings:

• status — pipeline state. See §5.1.
• overall_status — the verdict your business logic should branch on. See §5.5.
• summary.* — integer counts, returned as strings in this endpoint. Cast to int on your side.

Response — 404 Not Found#

{ "error": "Not Found", "message": "No QA run found for album_id=MY-LABEL-RELEASE-00042" }

A 404 is returned both when the album does not exist AND when it exists but belongs to a different account — by design, the API never leaks the existence of records that are not yours.

2.3 GET /qa/album/{albumId}/report#

Returns the complete JSON report with every check result, per-track findings, the AI executive review, and your effective qa_config. Use this when you did not set a callback_url and need to pull the result, or when you need to fetch the report again after the webhook.

GET /qa/album/{albumId}/report?qa_run_id={qa_run_id}
Host: <api-host>

Path parameters#

Query parameters#

Headers#

Response — 200 OK#

The response is a structured JSON report. The top-level shape is what your integration branches on:

{
  "album_id": "MY-LABEL-RELEASE-00042",
  "qa_run_id": "QA-7m3pXkQwF2A9",
  "upc": "1234567890128",
  "timestamp": "2025-05-22T01:16:02.114553+00:00",
  "overall_status": "WARNING",
  "summary": {
    "total_checks": 9,
    "passed": 7,
    "warnings": 2,
    "failed": 0,
    "errors": 0
  },
  "blocking_issues": [ /* FAIL-severity findings */ ],
  "warnings":        [ /* WARNING-severity findings */ ],
  "album_checks":    { /* per-check structured results for album-level checks */ },
  "track_checks":    { /* keyed by track_id, per-check structured results per track */ },
  "track_info":      { /* keyed by track_id, the input track metadata echoed back */ },
  "album_metadata":  { /* the input album metadata echoed back */ },
  "ai_review":       { /* AI executive review across all findings */ },
  "qa_config":       { /* the effective config used for this run */ }
}

Integration branches on overall_status (see §5.5) and iterates blocking_issues[] / warnings[] to surface findings. Each finding entry carries at minimum check, severity, and detail, plus check-specific extra fields.

Response — 200 OK (still in progress)#

{ "status": "RUNNING", "message": "QA is still in progress" }

The run exists but the final report is not yet ready. Poll again shortly.

Response — 400 Bad Request#

{ "error": "Missing albumId path parameter" }

The URL was malformed.

Response — 403 Forbidden#

Same shapes as POST /qa/album (auth issues).

Response — 404 Not Found#

{ "error": "Not Found", "message": "QA run not found" }

No such run, or it belongs to a different account.

{ "error": "Not Found", "message": "Report not yet available" }

The run exists but the report has not been written yet and status is not RUNNING. Rare; retry once.

2.4 POST /qa/vocal-content#

Classifies a batch of individual tracks as carrying sung words or not. Unlike §2.1 this is not an album: the tracks are unrelated to each other, and nothing about a release is required or returned.

Analysis is asynchronous and takes minutes. This endpoint answers immediately with a job_id; poll §2.5 for the result.

POST /qa/vocal-content
Host: <api-host>
Content-Type: application/json

Headers#

Request body#

{
  "tracks": [
    { "track_id": "ISRC-AAAAA0000001", "audio_url": "https://cdn.example.com/01.wav" },
    { "track_id": "ISRC-AAAAA0000002", "audio_url": "https://cdn.example.com/02.wav" },
    { "track_id": "ISRC-AAAAA0000003", "audio_url": "https://cdn.example.com/03.wav" },
    { "track_id": "ISRC-AAAAA0000004", "audio_url": "https://cdn.example.com/04.wav" },
    { "track_id": "ISRC-AAAAA0000005", "audio_url": "https://cdn.example.com/05.wav" }
  ]
}

Response — 202 Accepted#

{
  "job_id": "vc-4f2a91c8e5b74d03a6f1c2e8b9d47a05",
  "status": "accepted",
  "track_count": 5,
  "poll_url": "/qa/vocal-content/vc-4f2a91c8e5b74d03a6f1c2e8b9d47a05"
}

• job_id — generated on our side. Keep it: it is the only handle to this job.
• status — always accepted here. It means the batch was queued, not that anything was analysed yet. The analysis statuses are in §2.5.
• track_count — how many tracks were accepted, and therefore how much of your allowance this job spends. See §5.4.
• poll_url — path to poll, relative to your API host. The result carries, per track, the vocal / instrumental verdict, the vocal time ranges, and the detected words themselves (accepted_words). See §2.5.

A replay of the same Idempotency-Key with the same body returns the original job_id and adds "idempotent_replay": true. It does not start a second analysis and does not consume quota again.

Errors#

Nothing is consumed by a rejected request.

2.5 GET /qa/vocal-content/{jobId}#

Poll for the result of a job submitted through §2.4.

GET /qa/vocal-content/{jobId}
Host: <api-host>

Path parameters#

Headers#

Response — 200 OK, still working#

{ "job_id": "vc-4f2a91…", "track_count": 5, "status": "pending" }

status is one of:

Poll no more often than every 30 seconds. A batch typically takes several minutes.

Response — 200 OK, finished#

{
  "job_id": "vc-4f2a91…",
  "status": "completed",
  "track_count": 5,
  "completed_count": 5,
  "tracks": [
    {
      "track_id": "ISRC-AAAAA0000001",
      "status": "completed",
      "classification": "vocal",
      "audio_duration_seconds": 214.5,
      "vocal_time_seconds": 98.2,
      "vocal_time_ratio": 0.4578,
      "accepted_word_count": 42,
      "vocal_segments": [ { "start": 12.4, "end": 41.9 } ],
      "accepted_words": [
        { "word": "tonight", "start": 13.1, "end": 13.6, "probability": 0.94 }
      ]
    },
    {
      "track_id": "ISRC-AAAAA0000002",
      "status": "completed",
      "classification": "instrumental",
      "audio_duration_seconds": 187.0,
      "vocal_time_seconds": 0.0,
      "vocal_time_ratio": 0.0,
      "accepted_word_count": 0,
      "vocal_segments": []
    }
  ]
}

Field meanings:

• classification — the answer. vocal means sung words were detected; instrumental means they were not. Branch on this.
• vocal_time_seconds / vocal_time_ratio — how much of the track carries vocal content, absolute and as a fraction of duration.
• accepted_word_count — words detected inside vocal regions.
• vocal_segments — time ranges, in seconds, where vocal content was found.
• accepted_words — the words the verdict actually rests on, each with its position and the recogniser's confidence. One word is enough to make a track vocal, so this is how you check whether that word is a lyric or a false positive on an instrument. Empty for an instrumental track, and occasionally absent — see below.
• A track with status: "error" carries no classification. The rest of the batch is still returned.

accepted_words is omitted, rather than shown empty, when the classifier's calibration has changed since a job ran: the words that produced that verdict can no longer be identified with certainty. accepted_word_count is always present and always the count the job itself recorded.

instrumental covers both silence and wordless vocal sound (humming, ad-libs, vocal textures). The distinction this endpoint makes is sung words or no sung words, not "voice or no voice".

Response — 404 Not Found#

{ "error": "Not Found", "message": "No vocal-content job vc-4f2a91…" }

As in §2.2, a 404 is returned both when the job does not exist AND when it belongs to a different account.

3. Webhook Callbacks#

Polling works, but the recommended way to receive the result is to set callback_url in your submission. We will POST the final report to that URL.

3.1 How it works#

• The webhook fires once per run, after the full analysis finishes.
• It waits until all checks are complete — you receive one final webhook.
• The body is the same JSON as GET /qa/album/{albumId}/report (§2.3), with one extra field only present on webhooks: original_request, an echo of the body you originally submitted.

Headers we send#

Content-Type: application/json
X-QA-Signature: <hex-hmac-sha256>
X-QA-Timestamp: <epoch-seconds-as-string>

Recognizing a test fire#

When you trigger a webhook from the dashboard's Test webhook button (§3.3), the payload includes an extra top-level marker:

{ "test": true, ... }

This field is never present on real production callbacks. Treat it as a hard signal in your receiver: when the top-level test field is true, acknowledge the request (return 2xx) and stop processing. Do not write to your QA database, do not alert your team, do not advance the album's release state. Everything else in the payload — headers, signature scheme, body shape, field names, nesting — is identical to a real callback, so the rest of your code path (signature validation, JSON parsing) still gets exercised end-to-end.

3.2 Signature verification#

We sign every webhook with HMAC-SHA256 using your signing secret (delivered when your access was provisioned). You MUST verify the signature on every received webhook. Unverified callers can spoof requests against your endpoint otherwise.

The signing recipe is:

signed_content = X-QA-Timestamp + "." + raw_request_body
signature      = HMAC-SHA256(signing_secret, signed_content).hex()

Compare the result against the X-QA-Signature header using a constant-time comparison.

Critical pitfalls#

1. Use the RAW request body bytes, not a re-stringified version of the parsed JSON. Parsing + re-stringifying re-orders keys and changes whitespace; the HMAC will not match. Read the bytes BEFORE parsing.
2. Constant-time compare. Use your language's constant-time HMAC comparison primitive. A plain == leaks the secret one byte at a time via timing.
3. Check the timestamp. Reject requests where X-QA-Timestamp is older than ~5 minutes — this prevents replay attacks where an attacker who once observed a valid request keeps sending it forever.
4. TLS only. Your callback_url must be HTTPS. We will not connect to plain HTTP.

3.3 Testing your endpoint from the dashboard#

The dashboard has a Test webhook button that fires a synthetic payload with the same headers, signature scheme, and body shape as a real callback. Use it to validate your verification code before going live. The synthetic payload sets "test": true at the top level (see §3.1). Rate-limited; the current cooldown and daily cap are visible in your dashboard.

3.4 Webhook response expectations#

We expect any 2xx response from your endpoint. We do not currently retry failed deliveries. If your endpoint is down at the moment of delivery, you can still pull the report via GET /qa/album/{albumId}/report — results remain available via GET within the run's defined access window.

4. Tutorial — End-to-end workflow#

A complete integration is composed of a small handful of HTTP exchanges. This section walks through the typical flow.

4.1 Submit the album#

Generate one Idempotency-Key for this logical submission (a UUID v4 is the standard choice). Persist it on your side. If a retry fires, reuse the same key — never generate a new one for a retry (see §5.2).

POST /qa/album
Host: <api-host>
Content-Type: application/json
x-api-key: <YOUR_API_KEY>
Idempotency-Key: <UNIQUE_KEY_PER_SUBMISSION>

{ ...album payload as in §2.1... }

The response (§2.1) returns a qa_run_id. Store it — you will use it to retrieve the result.

If callback_url was included, you can stop here and wait for the webhook (§4.2 → option A). Otherwise you need to poll (§4.2 → option B).

4.2 Wait for the result#

Option A — Webhook (recommended). We will POST the report to your callback_url once the analysis is complete (§3). Make sure your endpoint verifies the HMAC signature (§3.2) before trusting the payload.

Option B — Polling. Call the status endpoint:

GET /qa/album/{albumId}/status?qa_run_id={qa_run_id}
Host: <api-host>
x-api-key: <YOUR_API_KEY>

Repeat until the response shows "status": "COMPLETED". See §5.1 for the full lifecycle of status.

4.3 Fetch the full report#

Once the run is complete, retrieve the report:

GET /qa/album/{albumId}/report?qa_run_id={qa_run_id}
Host: <api-host>
x-api-key: <YOUR_API_KEY>

The body is described in §2.3.

If you used a webhook, you already have the same body — this step is only needed if you missed the callback or want to fetch the report again.

4.4 Interpret the verdict#

Branch your business logic on overall_status. The four values map to four different actions; see §5.5 for the decision table.

The lists of findings live in blocking_issues[] (FAIL-severity) and warnings[] (WARNING-severity).

5. Concepts#

5.1 Status lifecycle#

QUEUED  ──►  RUNNING  ──►  COMPLETED

• QUEUED — submission accepted, awaiting analysis.
• RUNNING — analysis is in progress.
• COMPLETED — all checks done. The webhook fires now (if callback_url is set).

When polling, treat any value that is not COMPLETED as "still running" — wait and poll again. GET /status is the cheap call; GET /report is the expensive one. Use status to know when the report is ready, then fetch the report once.

5.2 Idempotency#

POST /qa/album requires an Idempotency-Key header. We use it to deduplicate retries:

Each key is bound to the body it was first used with. Same key + byte-identical body = replay. Same key + any body change = 422. This protects you from cross-submission data leaks caused by accidental key reuse on your side.

Recommended practice: generate one UUID v4 per logical submission attempt on your side. Persist it next to the album record. If your retry logic fires, send the same UUID with the same body, never a new key for the same body and never the same key for a different body.

If you omit the header you get a 400 missing_idempotency_key.

5.3 qa_config#

Your account has a saved qa_config (set via the dashboard or by your operator). Any submission can override individual fields by sending a partial qa_config in the body. The merge is deep — what you do not send is inherited from your saved default.

Top-level shape:

{
  "qa_config": {
    "checks_enabled": { "<check_name>": true },
    "thresholds":     { "<threshold_key>": 0 },
    "sub_checks": {
      "<check_name>": {
        "<sub_finding>": { "enabled": true, "severity": "FAIL" }
      }
    },
    "exceptions":     { "<check_name>": [] }
  }
}

• checks_enabled — boolean toggle per QA check. Whole checks can be turned off for an account or for a single submission.
• thresholds — numeric or string knobs that tune individual checks (minimum scores, minimum dimensions, duration floors, sensitivity levels, etc.). Each threshold key is a stable identifier; the catalog is visible in your dashboard.
• sub_checks — per-check tree of {enabled, severity} toggles for individual sub-findings. severity is WARNING or FAIL. WARNING never blocks; FAIL marks the run as overall FAIL.
• exceptions — per-check allowlists (for example, words a textual check should ignore for your catalog).

Per-request override example#

The values you send are deep-merged on top of your saved config. Use it to tweak a single threshold or disable a single sub-check for one submission without changing your default:

{
  "qa_config": {
    "thresholds":     { "<threshold_key>": <value> },
    "checks_enabled": { "<check_name>": false }
  }
}

The merged config is validated. A malformed override returns 400 invalid_qa_config_override.

5.4 Quota#

Your account has a lifetime cap configured at provisioning and visible in the dashboard. Each POST /qa/album consumes a number of units determined by your plan. If a submission would exceed the cap, it is rejected and nothing is consumed.

The dashboard shows used / limit live. When you are out:

{ "error": "quota_exhausted", "used": 200, "limit": 200, "unit": "<plan-specific>", "requested": 14 }

• unit — string identifying the counter your plan uses. Treat as opaque (informational only — do not hardcode values).
• requested — the amount this submission would have consumed. Lets you tell 0 left apart from a partial shortfall (e.g. you only had 13 left and asked for 14).

The vocal-content endpoint (§2.4) has a separate allowance, counted in tracks. It is not shared with the album counter above: spending one does not affect the other. A batch either fits in the remaining allowance in full or is rejected whole.

Contact the Limbo team to raise either cap.

5.5 Status semantics — overall_status#

overall_status is the verdict your business logic should branch on. The four values map to four different actions — they are NOT interchangeable:

The key distinction is ERROR vs FAIL. - ERROR means we could not finish the analysis — retry the submission. - FAIL means we analyzed the release and it has problems you must fix — do not ship.

Treating them the same will either block valid releases (treating ERROR as FAIL) or ship broken ones (treating FAIL as ERROR). Always branch on the exact value.

Related fields:

• summary.{passed,warnings,failed,errors} — check-level rollups (how many individual checks landed in each bucket).
• blocking_issues[] — list of FAIL-severity findings. Surface these when overall_status == "FAIL".
• warnings[] — list of WARNING-severity findings.

5.6 Status semantics — individual checks#

Every entry inside album_checks and track_checks carries its own status. It is not the same field as overall_status and it takes one extra value:

SKIP is not a PASS. A PASS means we looked and found nothing. A SKIP means we did not look — because the check is turned off for your account, or because the submission did not carry the data that check needs. Reading it as a pass turns "not verified" into "verified clean", which is the one mistake this field exists to prevent.

When a check is skipped for lack of input, the entry carries a skip_reason string. Treat it as opaque (informational only — do not hardcode values). If a check matters to you and you see it skipped, the fix is usually to include the missing field in your submission.

Two consequences worth knowing:

• Skipped and incomplete checks are counted in summary.total_checks but land in no bucket, so passed + warnings + failed + errors can be less than total_checks. Do not derive one from the other.
• A skipped check never changes overall_status. An album whose every check was skipped still reports PASS at the top level — the individual entries are the only place that distinction is visible.

6. Limits#

7. Troubleshooting#

8. Support#

Talk to engineering at info@limbomusic.com for any of the following:

• Integration & onboarding — full response specification, sample payloads, the complete check / threshold / sub-finding catalog, signing-secret and API-key provisioning.
• Account operations — lost credentials, quota bumps, account suspension or reactivation.
• API issues & bug reports — please include qa_run_id, the request Idempotency-Key, and the timestamp range of the incident. With those three values we can pin down the run in seconds.