Integration guide

End-to-end walkthrough for a production integration.

This guide explains how the implemented V1 endpoints fit together in real products. It is not a duplicate of every endpoint page — use the linked guides and the OpenAPI spec for request and response details.

Three main V1 workflows

1. Live tagging workflow

Analyse audio immediately without persisting results in your catalogue. Typical for pre-release checks, A/B listening tools, or one-off enrichment.

  1. Obtain an OAuth access token with storage.write and audio.tagging.write.
  2. Request a presigned upload URL and PUT the audio file to organisation-managed inbound storage.
  3. Call POST /v1/audio/tagging with the authorised s3_file_uri.
  4. Receive immediate MusiTag taxonomy tags. The result is not persisted.

See Quickstart and Tagging.

2. Catalogue ingestion workflow

Persist catalogue metadata and audio in MusiMap so tracks become searchable, taggable from storage, and available for profiling.

  1. Upload files or metadata to inbound storage (presigned URLs or optional storage credentials).
  2. Create an ingestion with POST /v1/ingestions (api_json, s3_csv, s3_ddex, or s3_scan).
  3. Poll ingestion status, entities, and items until delivery completes.
  4. Inspect delivered rows through inventory endpoints (/v1/tracks, artists, releases, works).
  5. Read stored tagging with GET /v1/audio/tagging once analysis has run.

See Storage and Ingestions.

3. Search and profile workflow

Discover tracks in an analysed catalogue and build aggregate listener profiles.

  1. Fetch the MusiTag taxonomy with GET /v1/taxonomies/tags.
  2. Build MusiSearch filters using stable tag_id values (not display labels).
  3. Call POST /v1/search/tracks for discovery.
  4. Pass resolved track identifiers to POST /v1/profiling/tracks for aggregate profiles.

See Taxonomy, Catalogue search, and Profiling.

  1. Create an OAuth client in the developer dashboard.
  2. Exchange client credentials for an access token (Authentication).
  3. Call GET /v1/me to confirm principal, organisation, default catalogue, and granted scopes.
  4. List catalogues with GET /v1/catalogs (Catalogues).
  5. Upload audio or metadata through presigned storage (Storage).
  6. Either run live MusiTag or create an ingestion, depending on whether you need persistence.
  7. After catalogue content is analysed, use taxonomy + search for discovery.
  8. Call profiling when you need aggregate listener profiles for a track set.

Integration boundaries

  • No direct file upload through the gateway. Upload to organisation-managed inbound storage first, then reference objects by URI or key.
  • No remote URL ingestion. The API does not fetch audio from arbitrary HTTP URLs on your behalf.
  • Live tagging is not persisted. Use ingestion when results must remain in your catalogue.
  • Ingestion is the persistence path. Stored tagging lookup requires a catalogued track.
  • Search uses tag_id, not labels. Resolve IDs from the taxonomy endpoint before building filters.
  • Profiling returns aggregate profiles. Per-track raw scores and resolver internals are not exposed.
  • Configure OAuth scopes on your client. Each endpoint documents its intended scope in OpenAPI (Scopes).

Minimal curl flow (live tagging)

A condensed version of the quickstart — token, upload, tag:

# 1. Token
curl -X POST https://api.musimap.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'scope=storage.write audio.tagging.write'

# 2. Presigned upload (then PUT your file to the returned URL)
curl -X POST https://api.musimap.com/v1/storage/uploads \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"object_key":"uploads/demo.wav","content_type":"audio/wav"}'

# 3. Live MusiTag
curl -X POST https://api.musimap.com/v1/audio/tagging \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"s3_file_uri":"s3://YOUR_BUCKET/inbound/uploads/demo.wav"}'