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

Tracks

The catalog core. A track is the unit everything else hangs off — versions, stems, lyrics, artwork, split sheets, share links, and search all reference a track id. Every route here is owner‑scoped: the server resolves your owner from the verified credential and only ever returns your own tracks. See Authentication.

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

There is no POST /v1/tracks creation route. A track is created as a side effect of the upload flow — see Uploads. Track sub‑resources (tags, peaks, lyrics, stems, versions, media assets, split sheets, share links, metadata edits) live on the Track Resources page.

Endpoints

MethodPathPurposeAuthRequestResponse
GET/v1/tracksList your tracks (paged, filtered); each row carries a signed artworkUrlClerk actorlistTracksRequestSchema (query){ records: Track[], totalCount, nextCursor? }
GET/v1/tracks/:trackIdTrack detail with signed artworkUrlClerk actor—Track
DELETE/v1/tracks/:trackIdSoft‑delete a trackClerk actor—deletedTrackResponseSchema

Field‑level detail for every schema named here lives in Data Contracts.

GET /v1/tracks

Lists the authenticated owner’s tracks with paging and a rich filter set. Cover art is attached per row as a short‑lived signed artworkUrl (the same V4‑signed URL the catalog grid, player, and inspector all render); artwork signing is best‑effort and a failure returns the records unchanged rather than failing the read.

Auth: Clerk actor.

Request: listTracksRequestSchema as query parameters. The ownerId is injected server‑side from your credential — never send it. Notable params:

  • limit — 1–100, default 50.
  • cursor — opaque pagination cursor; pass back nextCursor from the previous page.
  • query — free‑text title/artist match.
  • sort — created_desc (default) · created_asc · title_asc · title_desc.
  • Facet filters: artist, genre, mood, instrument, songType, userTag, vocalGender, vocalType, musicalKey (each accepts one value or repeats for several).
  • Machine‑tag filters: machineTagType + machineTagValue.
  • BPM range: minBpm, maxBpm (minBpm must be ≤ maxBpm, else 400).
  • libraryId — restrict to a single library.

Response: { records: Track[], totalCount, nextCursor? }. Each Track is the client DTO (owner id and storage URIs stripped) with an added artworkUrl?.

curl -s "https://app.swayzio.com/api/swayzio/v1/tracks?limit=20&genre=house&sort=created_desc" \
  -H "Authorization: Bearer $TOKEN"

GET /v1/tracks/:trackId

Returns one track by id, with a signed artworkUrl attached the same way as the list route. A track that doesn’t exist (or isn’t yours) returns 404 { "error": "track_not_found" } — owner mismatch is indistinguishable from not‑found by design.

Auth: Clerk actor.

Response: Track (client DTO).

curl -s https://app.swayzio.com/api/swayzio/v1/tracks/trk_123 \
  -H "Authorization: Bearer $TOKEN"

DELETE /v1/tracks/:trackId

Soft‑deletes a track. The row is marked deleted (not hard‑removed) and drops out of listings and search. Returns 404 track_not_found if the id isn’t yours.

Auth: Clerk actor.

Response: deletedTrackResponseSchema — { "id": "trk_123", "status": "deleted" }.

curl -s -X DELETE https://app.swayzio.com/api/swayzio/v1/tracks/trk_123 \
  -H "Authorization: Bearer $TOKEN"

Editing a track

Metadata edits are a PATCH against the track‑resources dispatcher, not a route on this page:

Related

  • Uploads — the only way to create a track.
  • Track Resources — versions, stems, lyrics, artwork, split sheets, share links, processing status, metadata edits.
  • Search — keyword, semantic, hybrid, and audio‑similarity search over your catalog.
  • Conventions · Data Contracts
OverviewTrack Resources