Sync and pitching

A supervisor sends a brief. You want the five best matches from a roster and a link to send back, without opening the app.

Flow

1. Search. Call POST /tracks/search with the brief as query. Move hard requirements into constraints: duration window, instrumental, BPM range, key.
2. Read the interpretation. If interpretation.genres or moods is off, name the genre in the query and search again. Put tracks you have already pitched into excludeTrackIds.
3. Make the playlist. Call POST /playlists with the top ids and suggestedName from the search. The response includes publicLink.
4. Send the link. Anyone can listen without an account.
5. Track it. GET /tracks/submissions shows every brief a track went to if you also log the pitch as a brief submission in the app.

Example

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": "uplifting indie-folk with handclaps for a travel ad, builds to a big chorus",
    "limit": 10,
    "constraints": { "durationRange": [60, 150], "hasVocals": true, "language": "en" }
  }'

Then:

curl -X POST https://api.postal.music/api/v1/playlists \
  -H "X-API-Key: $POSTAL_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Travel ad shortlist", "trackIds": ["cm1x…","cm1y…","cm1z…"], "dedupe": true }'

Cost

Each search is one credit. Listing and playlist calls are free. A typical pitch is two or three searches.

With an assistant instead

The same flow is one sentence in a connected MCP client: "Find five uplifting indie-folk tracks with vocals, 60–150 seconds, for a travel ad, and make me a playlist link." See Example prompts.