Tagging

Live MusiTag audio tagging from S3 and stored tagging lookup.

Use the audio tagging endpoints for MusiTag taxonomy results from audio files. These endpoints analyse audio signal metadata — not lyrics text.

S3 URI only

Live endpoints accept only s3_file_uri. They do not accept remote HTTP URLs, YouTube links, multipart uploads, or raw file bytes through the gateway.

OAuth scopes

  • audio.tagging.write — run live MusiTag audio tagging from an authorised S3 object.
  • audio.tagging.read — read stored audio tagging for catalogued tracks.
  • audio.features.write — optional live low-level audio features (not MusiTag taxonomy).
  • Request the scopes your integration needs when exchanging client credentials.

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"
  }'

Upload the file with the returned presigned PUT URL, then call live tagging with the full S3 URI.

Inbound files and catalogue ingestion

Files uploaded under your organisation inbound/ prefix remain there until you delete them. If you later run an s3_scan ingestion, those objects may be picked up for catalogue ingestion.

  • Use a dedicated subfolder such as inbound/live-tests/ or inbound/tmp/ for experiments.
  • Delete temporary live-tagging objects when you do not want them ingested.
  • Leave the object in place only when you intend to ingest it later.

Live MusiTag audio tagging

curl -X POST "https://api.musimap.com/v1/audio/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 immediate final MusiTag taxonomy tags in the MusiMap envelope. The public contract includes only customer-facing output: final tags with scores and labels, taxonomy version, and safe source metadata. It does not expose pipeline internals such as raw analyser values, intermediate features, integration-rule traces, or debug metadata. The source.persisted field is false: live tagging does not create or update a catalogued track record.

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 audio tagging lookup

After catalogue ingestion and analysis, read stored tagging for a catalogued track. Provide exactly one lookup parameter. 

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

Supported query parameters:

  • track_id — MusiMap track UUID.
  • outer_id — your client outer ID from catalogue membership.
  • isrc — track ISRC within the accessible catalogue.

Returns 404 Not Found when no accessible stored tagging exists.

Optional live audio features

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

Returns lower-level audio analysis features (tempo, loudness, spectral metrics, and similar). This is not MusiTag taxonomy tagging.