API Reference · v1

DistroShield API

REST API for pre-upload music quality control. Each /v1/analyze request runs four modules in parallel — AI detection, duplicate check, metadata validation, and recording fingerprint — returning a combined recommendation (pass / review / block) before your track reaches any DSP. Built for distributors' ingest pipelines.

Authentication

Every request (except GET /health) requires a Bearer API key issued by DistroShield. Keep your key secret — it's your client identity and billing binding.

Authorization: Bearer ds_YOUR_API_KEY_HERE

Keys are provisioned manually during onboarding. Missing or invalid key → 401 unauthorized.

Quickstart

Minimal call that analyzes a track and returns classification. Replace YOUR_API_KEY and AUDIO_URL.

curl -X POST https://api.distroshield.com/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "AUDIO_URL",
    "metadata": { "title": "Song A", "artist": "Artist A" },
    "client_track_id": "internal-123"
  }'

Typical latency: 3–6 seconds (audio download + inference). For high throughput, use POST /v1/batch.

Analyze a track

Synchronously analyze one audio URL. Returns classification, AI score, and the derived recommendation (pass / review / block).

Request body

Example

POST https://api.distroshield.com/v1/analyze
Authorization: Bearer ds_...
Content-Type: application/json

{
  "audio_url": "https://firebasestorage.googleapis.com/.../track.wav?token=...",
  "metadata": {
    "title": "Mi Bello Puerto",
    "artist": "Juan Pérez",
    "isrc": "USRC17607839",
    "duration_seconds": 187
  },
  "client_track_id": "mhm-2026-03296"
}

Response 200 OK

The response combines four independent quality signals — AI detection, duplicate check, metadata validation, and recording fingerprint — into a single recommendation. Details on each module below.

{
  "analysis_id": "an_8_2HwDlNC1f_",
  "db_id": 42,

  // ---- Module 1: AI detection ----
  "ai_score": 0.0655,
  "classification": "human",
  "classification_origin": "human",       // mirrors classification when not ai
  "origin_confidence": 0.9775,
  "confidence": 0.9775,
  "signals": {
    "local_score": 0.15,
    "local_reasons": ["missing_artist"],
    "model_score": 0.0373,
    "weights": { "local": 0.25, "model": 0.75 }
  },
  "model_version": "distroshield-v7c",
  "attribution_model_version": null,      // populated only when classification == "ai"

  // ---- Module 2: Duplicate check (only if metadata.isrc or title+artist given) ----
  "duplicate_score": 0,
  "duplicate_matches": [],
  "sources_checked": ["spotify", "deezer", "youtube"],

  // ---- Module 3: Metadata validation (only if metadata given) ----
  "metadata_validation": {
    "score": 0.95,
    "summary": { "high": 0, "medium": 0, "low": 1 },
    "issues": [
      { "severity": "low", "type": "ddex_missing_recommended",
        "detail": "Recommended field \"genre\" is missing" }
    ]
  },

  // ---- Module 4: Recording fingerprint (only if audio_url given) ----
  "recording_fingerprint": {
    "matched": false,
    "matches": [],
    "highest_score": 0,
    "distinct_artists_at_perfect_score": 0,
    "submitted_isrc_matched": false,
    "submitted_artist_matched": false,
    "review_reason": null
  },

  // ---- Combined decision ----
  "recommendation": "pass",
  "analyzed_at": "2026-04-24T16:27:01.742Z"
}

Response fields

Response modules

Each /v1/analyze response is produced by four independent quality-control modules running in parallel. Each module is optional — fields appear only when the module ran:

Module 2 · Duplicate check

Checks whether the track already exists in major public music sources. Executes when metadata.isrc OR both metadata.title and metadata.artist are provided. Skipped otherwise.

Sources

Scoring

• Exact ISRC match on any source → match_score: 1.0
• Fuzzy title+artist match (≥0.5) → match_score: 0.5–1.0
• duplicate_score is the top match's score + 5% boost per additional source that also matched

Example match

{
  "source": "spotify",
  "match_type": "isrc",        // or "title_artist"
  "match_score": 1.0,
  "id": "7qiZfU4dY1lWllzX7mPBI3",
  "title": "Shape of You",
  "artist": "Ed Sheeran",
  "url": "https://open.spotify.com/track/7qiZfU4dY1lWllzX7mPBI3"
}

Module 3 · Metadata validation

Validates the declared metadata across four dimensions. Runs locally (<10 ms) when metadata is provided.

Checks performed

Issue structure

{
  "severity": "high",          // high | medium | low
  "type": "isrc_identity_artist_mismatch",
  "detail": "ISRC is registered on spotify as artist 'The Weeknd' but you declared 'Mi Artista'",
  "registered": {              // present on identity-mismatch only
    "source": "spotify",
    "artist": "The Weeknd",
    "title": "Blinding Lights",
    "url": "https://open.spotify.com/track/..."
  }
}

Scoring

metadata_validation.score starts at 1.0 and subtracts penalties: high -0.40, medium -0.15, low -0.05. Clamped to [0, 1]. Any high severity issue upgrades the overall recommendation from pass to review.

Module 4 · Recording fingerprint

Hashes the submitted audio and matches it against a catalog of 70M+ commercial recordings. Catches the case other modules are structurally blind to: a fraudster re-uploading someone else's exact recording with the metadata changed.

Executes when an audio_url is provided. Skipped otherwise.

Fields

Routing

• • A single match at score ≥80 sets review_reason to recording_fraud_match and upgrades recommendation from pass to review.
• • Two or more matches at score ≥95 with different artists takes precedence and sets review_reason to cross_distributor_recording_fraud — the highest-confidence form of fraud the API surfaces.
• • The signal never auto-blocks. Human-in-the-loop is mandatory.

Batch analyze (async)

Submit many tracks at once. Returns a batch ID immediately; tracks are processed asynchronously by the worker queue. Results delivered via webhook (recommended) or polled via GET /v1/batch/:id.

Request body

{
  "tracks": [
    { "audio_url": "...", "metadata": {...}, "client_track_id": "..." },
    { "audio_url": "...", "metadata": {...}, "client_track_id": "..." }
  ],
  "webhook_url": "https://your-server.com/distroshield-webhook"
}

Response 200 OK

{
  "batch_id": 17,
  "track_count": 2,
  "status": "queued"
}

Each track result is POSTed to webhook_url with HMAC-SHA256 signature in X-DistroShield-Signature header.

Retrieve a single analysis

Fetch a full analysis row by its db_id. Scoped to your client — you can only fetch analyses for tracks you own.

GET https://api.distroshield.com/v1/analysis/42
Authorization: Bearer ds_...

→ {
  "id": 42,
  "track_id": 58,
  "ai_score": "0.0655",
  "classification": "human",
  "confidence": "0.9775",
  "signals_json": "{...}",
  "model_version": "distroshield-v7c",
  "review_status": "none",
  "review_verdict": null,
  "reviewer_email": null,
  "reviewed_at": null,
  "review_notes": null,
  "analyzed_at": "2026-04-24T16:27:01.000Z",
  "client_id": 1
}

List analyses (review queue)

Paginated list of analyses for your client. Use the status query param to filter — this is how your review queue UI fetches pending items.

Query parameters

Example

GET /v1/analyses?status=pending&classification=hybrid&limit=20
Authorization: Bearer ds_...

→ {
  "count": 20,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "id": 42,
      "ai_score": "0.5231",
      "classification": "hybrid",
      "model_version": "distroshield-v7c",
      "review_status": "pending",
      "analyzed_at": "2026-04-24T16:27:01.000Z",
      "track_id": 58,
      "title": "Track title",
      "artist": "Artist",
      "source_url": "https://..."
    },
    ...
  ]
}

Record human verdict

After a reviewer decides whether a flagged track is actually AI or human, persist their verdict. These labels feed into future model retraining.

Request body

PATCH https://api.distroshield.com/v1/analyses/42/review
Authorization: Bearer ds_...
Content-Type: application/json

{
  "verdict": "human",
  "notes": "Heavy autotune but definitely human — female reggaeton vocal",
  "reviewer_email": "j@mhmusik.com"
}

→ {
  "analysis_id": 42,
  "original_classification": "ai",
  "human_verdict": "human",
  "review_status": "overridden",
  "reviewer_email": "j@mhmusik.com",
  "reviewed_at": "2026-04-24T17:30:12.000Z"
}

review_status becomes overridden when the verdict disagrees with the model's original classification, else reviewed.

Register a webhook

DistroShield will POST async analysis results to your URL. The secret returned is used to sign each delivery with HMAC-SHA256 — verify signatures to reject forgeries.

POST /v1/webhooks
Authorization: Bearer ds_...

{
  "url": "https://your-server.com/distroshield-webhook",
  "events": ["analysis.completed", "batch.completed"]
}

→ {
  "webhook_id": 3,
  "secret": "whsec_abc...",   // shown ONCE — store it securely
  "url": "https://...",
  "events": [...]
}

Each delivery retries with exponential backoff (30s → 4d, up to 8 attempts) until your endpoint responds 2xx.

Usage metrics

Current period API usage for your client. Use to monitor your quota.

GET /v1/usage
Authorization: Bearer ds_...

→ {
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "requests": { "analyze": 312, "batch": 4, "total": 316 },
  "analyses_by_classification": {
    "human": 287, "hybrid": 18, "ai": 11
  }
}

Error codes

Errors return JSON with an error code. Some include additional context.

Rate limits

Default: 300 requests per minute per API key. Response headers expose your current state:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 60

Exceeding returns 429 rate_limited. Need higher limits? Contact us for Pro/Enterprise tiers.

Detection model

Current production version: distroshield-v7c. Trained on a curated mix of: real distributor-verified AI tracks, Suno / MusicGen-generated samples, and over 1,500 human tracks from a real distributor catalog spanning reggaetón, latin pop, dembow, regional mexicano, cristiano/gospel, electronic, hip-hop, bachata, cumbia, folk and other Latin American styles. Continuously improved from production review verdicts.

Scores are probabilistic. Human-in-the-loop review is mandatory. Never auto-block tracks without a human override path — the API is a gate, not a judge.