Reference•REST · JSON

API Reference

The Resomix Partner API is a small, predictable REST surface for catalog search and audio similarity. Every endpoint is partner-scoped, returns JSON, and can be tried live from the Playground.

Base URL

https://api.resomix.com

This is an illustrative host. Your dedicated base URL and partner key are issued during onboarding.

Authentication

All partner endpoints require your secret key in the X-Api-Key header (or as an Authorization: Bearer rmx_… token). Keys are environment-scoped — never expose them in client-side code.

GET/api/v1/search_tracks/search:read

Search the track catalog

Full-text search across your partner catalog by title and/or artist. Returns matching tracks with their stable track IDs — use a returned id with the similarity endpoint to find similar tracks.

Parameters

Name	In	Type	Description
`query`req	query	string	Search term (1–200 chars).
`mode`	query	'artist' \| 'title' \| 'auto'	Field to match. Defaults to 'auto' (both title and artist).

Request

curl

curl "https://api.resomix.com/api/v1/search_tracks/?query=midnight&mode=auto" \
  -H "X-Api-Key: rmx_your_partner_key"

Response 200

json

{
  "success": true,
  "data": {
    "tracks": [
      {
        "id": "710ce777-...",
        "title": "Midnight Drive",
        "artist": "Nova Lux",
        "duration": 214
      }
    ]
  }
}

POST/api/v1/similarity/searchsearch:read

Find similar tracks by ID

Given a track ID from your catalog, return the most acoustically similar tracks, ranked by similarity score (0–1). Search is scoped to your partner catalog.

Parameters

Name	In	Type	Description
`track_id`req	body	string	The catalog track ID to find neighbours for.
`top_sk`	body	integer	How many results to return (10, 20, 50, or 100). Defaults to 20.

Request

curl

curl -X POST "https://api.resomix.com/api/v1/similarity/search" \
  -H "X-Api-Key: rmx_your_partner_key" \
  -H "Content-Type: application/json" \
  -d '{"track_id": "710ce777-...", "top_sk": 20}'

Response 200

json

{
  "success": true,
  "data": {
    "queried_track": { "id": "710ce777-...", "title": "Midnight Drive" },
    "similar_tracks": [
      {
        "id": "5a5810b2-...",
        "title": "Neon Highway",
        "artist": "Nova Lux",
        "rank": 1,
        "score": 0.92
      }
    ]
  }
}

POST/api/v1/similarity/uploadsearch:read

Find similar tracks by audio upload

Upload an audio file and get the most similar tracks from your catalog. The upload is embedded as a one-shot probe — it is not added to your catalog or index. Max 100 MB.

Parameters

Name	In	Type	Description
`file`req	formData	file (multipart)	The audio file to analyse (FLAC, WAV, MP3 — max 100 MB).
`top_sk`	query	integer	How many results to return (10, 20, 50, or 100). Defaults to 20.

Request

curl

curl -X POST "https://api.resomix.com/api/v1/similarity/upload?top_sk=20" \
  -H "X-Api-Key: rmx_your_partner_key" \
  -F "file=@/path/to/track.flac"

Response 200

json

{
  "success": true,
  "data": {
    "queried_track": { "duration": 198 },
    "similar_tracks": [
      {
        "id": "5a5810b2-...",
        "title": "Neon Highway",
        "rank": 1,
        "score": 0.88
      }
    ]
  }
}