Tagging

Use the tagging endpoints for MusiTag taxonomy results from audio files. Live tagging is POST /v1/tagging. Stored results, taxonomy, and matrix live under /v1/tagging/*. These endpoints analyse audio signal metadata, not lyrics text.

OAuth scopes

• tagging.write: run live MusiTag tagging (optional persist).
• tagging.read: stored results, taxonomy, and matrix.
• audio.write: optional live low-level audio features via POST /v1/audio/features (not MusiTag taxonomy).

Upload an audio file first

Upload audio to your organisation inbound area with storage presigned uploads, then pass the resulting s3://… URI to live tagging.

curl -X POST "https://api.musimap.com/v1/storage/inbound/uploads" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "object_key": "live-tests/demo.wav",
    "content_type": "audio/wav"
  }'

Live MusiTag tagging

curl -X POST "https://api.musimap.com/v1/tagging" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "s3_file_uri": "s3://your-org-bucket/inbound/live-tests/demo.wav"
  }'

The response returns final MusiTag taxonomy tags with scores and labels, taxonomy version, and source metadata including source.persisted. Without persist, the result is immediate and is not written to Workspace (source.persisted is false). Live tagging consumes tagging credits.

Optional persist (live + catalogue)

Set persist: true to also enqueue Workspace ingestion/analysis for the same audio. When both live tagging and persisted analysis run, the combined cost is two credits (one for live tagging, one for persisted analysis).

Link to existing Workspace entities

Prefer structured metadata so persistence can bind the track to known Workspace artist and release rows without fuzzy name matching. Use Workspace entity UUIDs (/v1/workspace/…), customer outer_id values, and industry identifiers the catalogue already resolves (ISRC on tracks, ISNI via external_references on artists, UPC on releases). Atlas-plane IDs are rejected.

curl -X POST "https://api.musimap.com/v1/tagging" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "s3_file_uri": "s3://your-org-bucket/inbound/live-tests/demo.wav",
    "persist": true,
    "catalog_id": "0190…",
    "idempotency_key": "live-persist-demo-1",
    "metadata": {
      "track": {
        "outer_id": "client-track-42",
        "title": "Easy On Me",
        "isrc": "GBUM71904911"
      },
      "artist": {
        "id": "0190…-workspace-artist-uuid"
      },
      "release": {
        "outer_id": "client-album-30",
        "title": "30",
        "upc": "602438791174"
      }
    }
  }'

• Provide catalog_id when your token does not already carry catalogue context.
• Identifier precedence: Workspace id (authoritative) → ISRC / UPC / external references → customer outer_id → name/title fallback.
• If id is supplied, it must belong to your Workspace catalogue. Conflicting identifiers (for example id and ISRC that resolve to different entities) fail persistence with a public error instead of silently choosing one.
• Flat aliases (outer_id, title, artist, isrc) still work and map into the nested shape.
• Optional idempotency_key (or request_id) stabilises retries.

Persistence response

The live tagging result remains the primary payload. When persistence is accepted, persistence includes the ingestion reference and any entity references that were already known synchronously (typically caller-supplied Workspace UUIDs that passed validation). Newly created entity IDs appear later on GET /v1/ingestions/{id}/entities — they are not invented in the live response.

If live tagging succeeds but persistence fails, the API still returns HTTP 200 with the live tagging result and a persistence object describing the failure (status, error_code, message). On success, source.persisted becomes true.

Live tagging response shape

{
  "status": 200,
  "message": "OK",
  "data": {
    "source": {
      "s3_file_uri": "s3://your-org-bucket/inbound/live-tests/demo.wav",
      "persisted": false
    },
    "audio_tagging": {
      "status": "completed",
      "taxonomy_version": "v2.2",
      "tags": {
        "moods": [
          { "uid": "mood-123", "score": 82, "name": "Happy" }
        ]
      }
    }
  }
}

Stored tagging results

curl "https://api.musimap.com/v1/tagging/results?outer_id=client-track-42" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Pass exactly one of track_id, outer_id, or isrc (optional catalog_id). Scope: tagging.read.

Taxonomy

Stable tag IDs for MusiSearch filters: GET /v1/tagging/taxonomy.

Scoring matrix

GET /v1/tagging/matrix returns MusiTag scoring matrix metadata used when interpreting tag scores across categories. Scope: tagging.read. Optional query filters include catalog_id and ingestion_id.

curl "https://api.musimap.com/v1/tagging/matrix" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Use the matrix together with stored results for a catalogue track or after an ingestion completes analysis. Pair it with taxonomy for human-readable category and tag names.

Audio features

POST /v1/audio/features extracts low-level audio features from an authorised s3_file_uri. It is not MusiTag taxonomy tagging. Scope: audio.write.