Swayzio Core API v1 — base path /api/swayzio/v1
Core APISearch

Search

Catalog search over your own tracks — keyword, structured filters, semantic (text embeddings), hybrid, and audio similarity. Every search route is owner‑scoped and requires the search.private entitlement on top of a valid Clerk actor.

Base path: /api/swayzio/v1. Runtime: native→proxy.

All three routes return the same shape — globalTrackSearchResponseSchema — so a client can render keyword, semantic, and similarity results identically.

Endpoints

MethodPathPurposeAuthRequestResponse
POST/v1/search/tracksKeyword / structured / semantic / hybrid / similar searchClerk actor + search.privateglobalTrackSearchRequestSchemaglobalTrackSearchResponseSchema
POST/v1/tracks/audio-searchText → audio semantic search (MuLan)Clerk actor + search.privateaudioTextSearchRequestSchemaglobalTrackSearchResponseSchema (mode: "semantic")
POST/v1/tracks/audio-similarAudio similar‑tracks (MuQ vectors)Clerk actor + search.privateaudioSimilarTracksRequestSchemaglobalTrackSearchResponseSchema (mode: "similar")

POST /v1/search/tracks

The general‑purpose search endpoint. One mode drives keyword, semantic, hybrid, and similar retrieval; scope narrows the corpus to your whole catalog, a library, a pack, shared‑with‑you, or saved.

Auth: Clerk actor + search.private entitlement.

Request: globalTrackSearchRequestSchema. Key fields:

  • query — free text, ≤ 1000 chars.
  • mode — auto (default) · keyword · semantic · hybrid · similar. similar requires similarToTrackId.
  • scope — catalog (default) · library · pack · shared · saved. library requires libraryId; pack requires packId.
  • limit — 1–50, default 20.
  • minSimilarity — -1–1 floor for semantic/similar matches.
  • Structured filters (same vocabulary as track listing): artist, genre, mood, instrument, songType, userTag, vocalGender, vocalType, musicalKey, machineTagType + machineTagValue, minBpm/maxBpm.
  • includeFacets — return facet aggregates alongside results.

You must supply at least one of: a query, a similarToTrackId, or a structured filter (else 400).

Response: globalTrackSearchResponseSchema — { query, mode, resolvedMode, scope, embedding?, records[] }. Each record is { track, rank, score, keywordScore?, semanticScore?, distance?, matchedFields[], matchReasons[], accessContext }.

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/search/tracks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"warm analog house","mode":"hybrid","scope":"catalog","limit":20,"includeFacets":true}'

POST /v1/tracks/audio-search

Text → audio semantic search. The query string is embedded with MuLan into the shared audio space and matched against your tracks’ audio vectors — so you can describe a sound (“dreamy lo‑fi guitar, slow”) and get audio‑relevant hits rather than metadata matches. This is Layer‑1 audio retrieval.

Auth: Clerk actor + search.private entitlement.

Request: audioTextSearchRequestSchema — { query (1–1000), limit (1–50, default 20) }.

Response: globalTrackSearchResponseSchema with mode and resolvedMode both "semantic" and scope: "catalog". If the embedding step fails, returns 503 { "error": "audio_text_search_unavailable" }.

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/tracks/audio-search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"dreamy lo-fi guitar, slow tempo","limit":20}'

POST /v1/tracks/audio-similar

Audio similar‑tracks: given a seed track, return your other tracks with the closest MuQ audio embeddings — “more like this” by sound.

Auth: Clerk actor + search.private entitlement.

Request: audioSimilarTracksRequestSchema — { trackId, limit (1–50, default 20) }.

Response: globalTrackSearchResponseSchema with mode and resolvedMode both "similar" and scope: "catalog".

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/tracks/audio-similar \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trackId":"trk_123","limit":20}'

The Fastify Core API also exposes POST /v1/tracks/search/semantic (semanticTrackSearchRequestSchema) for text‑embedding semantic search. It is proxy‑only — there’s no native web implementation. The native surface uses audio-search and audio-similar (MuLan/MuQ) for audio‑space retrieval instead.

Related

UploadsPacks