Quickstart

Your first tagging call in 5 minutes — copy/paste friendly.

This guide takes you from zero to MusiTag taxonomy tags in about five minutes. You will obtain an access token, upload a WAV file to your organisation inbound storage, and run live tagging with POST /v1/audio/tagging.

Before you start

A MusiMap client ID and client secret from the developers dashboard.
A short audio file (for example demo.wav) to upload via presigned PUT.

S3 only in V1

Live tagging accepts only s3_file_uri. Remote HTTP URLs, YouTube links, multipart uploads, and raw file bytes through the gateway are not supported. See Tagging for the full contract.

1Get your credentials

Export your OAuth client credentials as environment variables:

{% include "msm_ui/components/code_block.html" with code="MUSIMAP_CLIENT_ID=your-client-id MUSIMAP_CLIENT_SECRET=your-client-secret" language="bash" %}

2Obtain an access token

Exchange client credentials for a bearer token at POST /oauth/token. Request scopes for storage upload and live tagging.

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=audio.tagging.write storage.write'

import os
import requests

response = requests.post(
    'https://api.musimap.com/oauth/token',
    data={
        'grant_type': 'client_credentials',
        'client_id': os.environ['MUSIMAP_CLIENT_ID'],
        'client_secret': os.environ['MUSIMAP_CLIENT_SECRET'],
        'scope': 'audio.tagging.write storage.write',
    },
)
response.raise_for_status()
access_token = response.json()['access_token']

const params = new URLSearchParams({
  grant_type: "client_credentials",
  client_id: process.env.MUSIMAP_CLIENT_ID!,
  client_secret: process.env.MUSIMAP_CLIENT_SECRET!,
  scope: "audio.tagging.write storage.write",
});

const response = await fetch("https://api.musimap.com/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: params,
});
const { access_token } = await response.json();

3Upload audio to inbound storage

Request a presigned PUT URL, upload your file, then note the full s3://… URI for tagging. Details are in Storage.

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

PUT the file bytes to the returned upload_url, then continue with the S3 URI from the response.

4Run live MusiTag tagging

Call POST /v1/audio/tagging with your authorised S3 URI. The response returns final taxonomy tags immediately. Live results are not persisted as catalogue tracks.

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

import requests

response = requests.post(
    'https://api.musimap.com/v1/audio/tagging',
    headers={'Authorization': f'Bearer {access_token}'},
    json={'s3_file_uri': 's3://your-org-bucket/inbound/live-tests/demo.wav'},
)
response.raise_for_status()
tags = response.json()['data']['audio_tagging']['tags']

const response = await fetch("https://api.musimap.com/v1/audio/tagging", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    s3_file_uri: "s3://your-org-bucket/inbound/live-tests/demo.wav",
  }),
});
const { data } = await response.json();
const tags = data.audio_tagging.tags;

That is your first API call

For catalogue workflows, continue with Ingestions and read stored tags with GET /v1/audio/tagging/results. Browse the full contract in OpenAPI.

Quickstart

1Get your credentials

2Obtain an access token

3Upload audio to inbound storage

4Run live MusiTag tagging

Where to go next

Ingestions

Catalogue search

Profiling

OpenAPI