Quickstart

You need an API key. Export it once:

export POSTAL_API_KEY="YOUR_API_KEY"

1. Count your tracks

curl https://api.postal.music/api/v1/tracks/count \
  -H "X-API-Key: $POSTAL_API_KEY"

Response

{
  "status": 200,
  "messageCode": 200,
  "message": "Operation was successful",
  "data": { "count": 1284 }
}

Every successful response is wrapped like this. Your result is always under data. See Conventions.

2. List the newest tracks

curl "https://api.postal.music/api/v1/tracks?limit=5&sort=-created_at&fields=id,name,createdAt,audio_profile,link" \
  -H "X-API-Key: $POSTAL_API_KEY"

Response (data)

{
  "data": [
    {
      "id": "cm1x…",
      "name": "Night Drive v3.wav",
      "createdAt": "2026-09-01T10:12:44.000Z",
      "audio_profile": { "title": "Night Drive", "artist": "…", "bpm": 92, "key": "Am", "…": "…" },
      "link": "https://postal.music/song/8f2k…"
    }
  ],
  "paging": { "limit": 5, "next_cursor": "cm1w…" }
}

Pass cursor=<next_cursor> to get the next page. It is null on the last page.

3. Find a track by describing it

curl -X POST https://api.postal.music/api/v1/tracks/search \
  -H "X-API-Key: $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "warm downtempo instrumental for a coffee ad",
    "limit": 5,
    "constraints": { "hasVocals": false, "bpmRange": [80, 100] }
  }'

Response (data, trimmed)

{
  "query": "warm downtempo instrumental for a coffee ad",
  "count": 5,
  "results": [
    {
      "id": "cm1x…",
      "title": "Night Drive",
      "artists": ["…"],
      "bpm": 92,
      "key": "Am",
      "genres": ["Downtempo"],
      "moods": ["Warm"],
      "score": 0.87,
      "reason": ["Matches the relaxed, warm brief", "Instrumental, 92 BPM"]
    }
  ],
  "interpretation": {
    "briefParsed": true,
    "summary": "Warm, relaxed instrumental around 90 BPM",
    "genres": ["Downtempo", "Chillhop"],
    "moods": ["Warm", "Relaxed"],
    "bpmRange": [80, 100],
    "vocalPreference": "instrumental"
  },
  "suggestedName": "Coffee Ad Shortlist",
  "searchId": "…"
}

This endpoint runs an AI ranking pass and costs one credit per call. The interpretation block shows how your words were read, so you can tighten the query or move a requirement into constraints. Details in Search.

Conventions

Envelope, errors, pagination, rate limits.

Tracks

Upload, list, update, duplicates.

Webhooks

Get told when a track or composer changes.

Use cases

Catalogue sync, tagging pipelines, reporting.