MAP Audio Music API

Three steps from an invite to a WAV file. You need a terminal with curl and jq.

1. Get access and a key

Access is invite-only while the API is in preview. Sign in at map.audio/music with your map.audio account and request access; we email you when it is ready. Then sign in there again, accept the prototype terms and create an API key. The key is shown once, so put it straight into an environment variable:

export MAP_API_KEY=sk_test_your_key

2. Render a loop

Prefer: wait=30 holds the request open for up to 30 seconds, so a short render comes back finished.

curl -sS https://api.map.audio/v1/renders \
  -H "Authorization: Bearer $MAP_API_KEY" \
  -H "Map-Version: 2026-11-01" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=30" \
  -d '{"source":{"preset":"pam:factory/313-disco"},"bars":8,"seed":42}' > job.json
jq '{id, status, seed: .result.seed}' job.json

The answer is the job. succeeded means the audio is ready. queued or running, with status 202, means it is still working; fetch it again every few seconds until it ends:

JOB_ID=$(jq -r .id job.json)
curl -sS "https://api.map.audio/v1/jobs/$JOB_ID" -H "Authorization: Bearer $MAP_API_KEY" > job.json

3. Download the audio

Each output carries a signed url that works for one hour.

curl -sSL --fail-with-body -o loop.wav "$(jq -r '.result.outputs[0].url' job.json)"

Eight bars of this 120 BPM preset are 16 seconds of audio: about a quarter of a render-minute, out of the 30 the free plan has each month. Keep the seed. The same request with the same seed renders the same audio.

When a call fails, its JSON error names the field at fault (param), says whether a retry can succeed (retryable) and links to the code's entry in the error catalogue. Quote the Request-Id response header when you write to support@map.audio.

Request access

The API is invite-only while it is in preview. Sign in at map.audio/music with your map.audio account (a new email address creates one), add a line about what you are building and send the request. We email you when your access is ready. An app holding a map.audio access token for the account can send the same request with POST /v1/access-requests. Until access is ready, calls answer 403 not_invited, with the account's customer id and the state of its request in details.

API keys

The account holder creates and revokes keys at map.audio/music. A key is shown once, when it is created: keep it in a secret store or an environment variable, never in a web page or a repository. Send it on every call as Authorization: Bearer $MAP_API_KEY. An account holds at most 10 active keys.

Revoke a key as soon as it may have leaked; the next call with it is refused. A webhook endpoint whose secret that key last set stops receiving events until you rotate its secret.

OAuth

An app can act for a map.audio account with an OAuth access token instead of a key: scope audio, resource https://api.map.audio. Such a token can read the account and render with its render-minutes. Creating or revoking keys and buying plans or render-minutes need the account holder signed in at map.audio/music; an API key and other apps are refused. Webhook endpoints take an API key or that sign-in. The account holder can disconnect an app at any time under Connected apps on map.audio/account#connected-apps.

Terms

Every account accepts the prototype terms before its first render. The map.audio/music page asks for that when you create your first key. With a key or token, send POST /v1/account/terms with {"accept":"<version>"}, where the version is currentTerms from GET /v1/account.

A key is either sk_test_ or sk_live_ followed by its secret; you pick the mode when you create it. Today the two modes differ only a little. Both render real audio on the same servers, spend the same render-minutes, count against the same limits and see the same jobs, files and webhook endpoints. What differs: idempotency keys are kept apart per mode, each job records its mode in livemode, and a render made with a test key carries a test licence id (ending _test) in its provenance record.

There is no free sandbox yet. Keep test renders short, and use a test key while you build so that its jobs are marked as tests.

A job is charged for the audio it returns: one render-minute per minute of each rendered file, at least 0.1 per file. Stems and MIDI files are not charged, and neither are calls that render nothing chargeable: preset search, plans, arrangements, analysis, drum hits and patterns. A failed or cancelled job is not charged, except for a preview it already delivered.

Extra render-minutes cost $0.03 each, at least 334 at a time, and stay valid for 365 days; jobs draw on the monthly allowance first. The account holder buys plans and render-minutes signed in at map.audio/music, and an API key cannot buy anything. GET /v1/credits shows what is left. Audio rendered on the free plan is for evaluating the API: its terms grant no commercial use.

Every call that runs the engine creates a job. Renders (POST /v1/renders) and the longer engine commands answer 202 with the job at once; short commands wait up to 30 seconds for it. Send Prefer: wait=N, from 0 to 60 seconds, to choose how long a call holds on: when the job ends in time, the answer is 200 with the finished job. The Preference-Applied header says which wait the API used.

A job goes from queued to running to succeeded, failed or cancelled. It turns expired when retention deletes its files; the record and its provenance stay. There are three ways to follow one:

• Poll GET /v1/jobs/{id} no faster than every 2 seconds. A 202 answer carries Retry-After and the job's Location.
• Read GET /v1/jobs/{id}/events, a stream of server-sent events: job.queued, job.started, job.progress, job.preview, then the outcome. Reconnect with Last-Event-ID to resume where you left off; each connection closes after 10 minutes.
• Register a webhook endpoint and receive job.succeeded, job.failed and job.cancelled.

Cancel a job you no longer need with POST /v1/jobs/{id}/cancel. A job that has already finished keeps its outcome.

Retrying safely

Send an Idempotency-Key header (8 to 128 letters, digits or _.:-) with a POST that starts a job. The same key and body return the same job for 24 hours, even one that failed, and the answer carries Idempotent-Replayed: true. The same key with a different body is refused with idempotency_key_reused. After a failed job, retry with a new key. The reference marks each operation that takes the header.

Results

A finished job's result.outputs lists its files, each with its role (master, stem, midi, preset or preview), file id, url, sha256, format and durationSeconds. With stems: true, a render adds up to eight stem files, one per PAM cell (cell 1 to 8), in the same format as the master. An output's url works for one hour; GET /v1/files/{id}/content signs a fresh one. Rendered files are kept 7 days on the free plan and longer on paid plans, and expiresAt on GET /v1/files/{id} says when a file goes. Download what you want to keep before then.

A webhook endpoint receives an HTTPS POST when a job ends, so a long render needs no polling. Create one with an API key: POST /v1/webhook-endpoints with its url and the events it wants. The default is job.succeeded, job.failed and job.cancelled; job.preview, job.expired and webhook.test are also available, and * takes them all. The answer holds the endpoint's signing secret, whsec_ followed by base64, and shows it only once. An account can have 10 endpoints.

Each delivery is a JSON object: id, type, createdAt, apiVersion and data. For job.succeeded, job.failed, job.cancelled and job.expired, data.object is the job as it stands when the event is delivered; a job.preview carries data.jobId and the preview's data.outputs; a webhook.test carries data.object, the endpoint. Deliveries are signed as Standard Webhooks describes, so any of its libraries can check them. In Node, with the raw request body as a string:

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyWebhook(secret, headers, body) {
  const signed = `${headers['webhook-id']}.${headers['webhook-timestamp']}.${body}`
  const expected = createHmac('sha256', Buffer.from(secret.slice('whsec_'.length), 'base64')).update(signed).digest('base64')
  const fresh = Math.abs(Date.now() / 1000 - Number(headers['webhook-timestamp'])) < 300
  return fresh && headers['webhook-signature'].split(' ').some(entry => {
    const [version, signature] = entry.split(',')
    return version === 'v1' && signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  })
}

Answer with any 2xx status within 15 seconds; a redirect counts as a failure. A failed delivery is retried with backoff for about two and a half days. When three deliveries in a row run out of retries, the endpoint is disabled; rotating its secret with POST /v1/webhook-endpoints/{id}/rotate-secret enables it again. After a rotation the old secret also signs for 24 hours, so webhook-signature can hold two signatures. POST /v1/webhook-endpoints/{id}/test sends a signed webhook.test event.

Every job that makes audio returns result.provenance, a record of what made it, signed by MAP Audio. It names the engine build, the presets and the seed, and every input and output file with its SHA-256. It also states that no AI model made the audio: aiModels is empty and audioByModel is false. Anyone holding a record's id can fetch it from GET /v1/provenance/{id} without a key.

The record's license says what the audio may be used for. Renders on the free plan are for evaluating the API: the prototype terms grant no commercial use (commercialUse: false) and require attribution to MAP Audio where the audio is shown.

The signature is Ed25519 over the record's JSON with its keys sorted and signature left out, written as ed25519: and the base64url signature. The public keys are at api.map.audio/.well-known/jwks.json, where kid names the one that signed. In Node:

import { createPublicKey, verify } from 'node:crypto'

const sorted = value => Array.isArray(value) ? value.map(sorted)
  : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(key => [key, sorted(value[key])])) : value

export async function verifyProvenance(record) {
  const { keys } = await (await fetch('https://api.map.audio/.well-known/jwks.json')).json()
  const { signature, ...signed } = record
  const key = createPublicKey({ key: keys.find(entry => entry.kid === record.kid), format: 'jwk' })
  return verify(null, Buffer.from(JSON.stringify(sorted(signed))), key, Buffer.from(signature.slice('ed25519:'.length), 'base64url'))
}

MCP server

The API's operations are also MCP tools, at https://api.map.audio/mcp (Streamable HTTP). It takes the same credentials as the REST API: map.audio OAuth, which an MCP client that supports sign-in starts on its own, or an API key as a bearer token. In Claude Code:

claude mcp add --transport http map-audio https://api.map.audio/mcp

With a key instead of a sign-in:

claude mcp add --transport http map-audio https://api.map.audio/mcp --header "Authorization: Bearer $MAP_API_KEY"

A tool that renders waits up to 45 seconds and returns the job; poll it with the job tool when it is still running. The table below lists every tool. Operations missing from it are REST only.

Skill

The map-music-api skill teaches an agent the workflow: finding presets, rendering, waiting, downloading, what renders cost and what each error means. Install it for any agent that reads skills:

npx skills add https://map.audio --skill map-music-api

For claude.ai or Claude Desktop, download map-music-api.zip and upload it under Customize > Skills. Without Node, copy the file into the folders Claude Code, Codex and Cursor read:

for dir in ~/.claude/skills ~/.agents/skills; do
  mkdir -p "$dir/map-music-api"
  curl -fsSL https://map.audio/.well-known/agent-skills/map-music-api/SKILL.md -o "$dir/map-music-api/SKILL.md"
done

The skill holds no credentials. It reads the key from MAP_API_KEY.

The API is versioned by date. The current version is 2026-11-01. Every JSON response carries it in the Map-Version header, as do webhook deliveries (apiVersion) and provenance records (contracts.api). Send Map-Version: 2026-11-01 with a request to pin it: a version the API does not serve is refused with version_unsupported.

While the API is in preview, its prototype terms allow changes without notice, and each change is listed here. Within a version, operations, optional fields, enum values, event types and error codes can be added. Write clients that ignore fields they do not know and handle an unknown error code by its type and retryable.

Changelog

• 2026-11-02, under 2026-11-01: errors and docs pass. Route and method resolve before auth (404 route_not_found, 405 method_not_allowed with Allow; HEAD is served); a JSON route answers 415 unsupported_media_type for another media type; unknown query parameters and Map-Version values are refused; non-job POSTs refuse Idempotency-Key (idempotency_key_unsupported); a wrong terms version is terms_version_mismatch; dj_variation_empty became variation_not_found (400), pack_license_required from the API's own check became preset_not_served, quality_unavailable is 400; hosted MCP tools list_presets and dj_set were renamed search_presets and render_dj_set, and get_account and accept_terms were added; POST /v1/access-requests was added; every docUrl points at the errors page.
• 2026-11-01: the first version.