HumMatch Partner API

1. Get a sandbox key

No signup form, no approval wait. POST /api/v1/sandbox-key issues a key instantly. The full key is only ever shown in this one response, so save it right away.

curl -X POST https://hummatch.me/api/v1/sandbox-key \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","name":"Your Company"}'

Response:

{
  "apiKey": "hm_sandbox_3f9a1c2b7d8e4f5061a2b3c4d5e6f708",
  "keyPrefix": "hm_sandbox_3",
  "mode": "sandbox",
  "rateLimitPerMinute": 30
}

Every call below sends that key back as the X-API-Key header.

2. Normalize a vocal profile

POST /api/v1/vocal-profile turns a range (note names or MIDI numbers) into a normalized profile you can reuse in the next two calls.

curl -X POST https://hummatch.me/api/v1/vocal-profile \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"rangeLow":"D3","rangeHigh":"C5"}'

3. Rank the whole catalog for that voice

POST /api/v1/recommendations is the endpoint most integrations want: one voice in, the catalog ranked for that voice out. You get a flat matcheslist plus the named buckets HumMatch itself uses, which carry meaning a flat list loses. A “risky pick to avoid” is not simply a low-scoring match.

curl -X POST https://hummatch.me/api/v1/recommendations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"rangeLow":"D3","rangeHigh":"C5","limit":12}'

4. Look up a song, or resolve a slug

GET /api/v1/songs/search searches by title or artist. Its main job is turning a song name into the catalog slug the next endpoint needs. Add a profile to score and rank every hit for a specific voice instead of by catalog relevance.

curl -G https://hummatch.me/api/v1/songs/search \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode 'q=someone like you adele' \
  --data-urlencode 'profile={"rangeLow":"D3","rangeHigh":"C5"}'

5. Score a specific song against that profile

GET /api/v1/songs/{slug}/fittakes a real catalog slug and a URL-encoded profile, and returns a real match score plus the same “why it fits” explanation HumMatch shows on the site. This example uses a real slug from the live catalog, love-is-a-game-adele.

curl -G https://hummatch.me/api/v1/songs/love-is-a-game-adele/fit \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode 'profile={"rangeLow":"D3","rangeHigh":"C5"}'

6. Find shared-range songs for a group

POST /api/v1/group-fittakes 2+ profiles and returns the group’s shared vocal range plus ranked candidate songs, using the same logic behind HumMatch’s SquadMatch feature, run entirely in-memory against the profiles you send. No group is created on our side.

curl -X POST https://hummatch.me/api/v1/group-fit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"profiles":[{"id":"singer-1","rangeLow":"C3","rangeHigh":"E4"},{"id":"singer-2","rangeLow":"A3","rangeHigh":"G5"}]}'

Using HumMatch from an AI agent

HumMatch runs a remote MCP server at https://hummatch.me/api/mcp, exposing the same engine as the REST endpoints above. It is stateless Streamable HTTP: POST JSON-RPC, no session to manage. Five read-only tools are available: recommend_songs, search_songs, check_song_fit, group_song_fit, and get_vocal_profile.

No API key is required to try it: keyless callers get the same free tier as the website, capped at the top 3 scored results and 5 scored lookups a day. Send your X-API-Key header to lift both.

curl -X POST https://hummatch.me/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A compact, agent-readable reference lives at /api.md.

Also listed on .