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

Libraries

A library is an owner‑scoped, named bucket of tracks — your personal collections, separate from packs. Libraries can be shared with collaborators (viewer / editor / admin) through accepted shares.

Every endpoint is under /api/swayzio/v1, requires a Clerk actor, and runs native→proxy. Responses strip ownerId via the clientLibrary* DTOs — see Data Contracts.

Endpoints

Libraries

MethodPathPurposeAuthRequestResponse
GET/v1/librariesList libraries you ownClerk actor—{ records: LibraryListRecord[] }
POST/v1/librariesCreate a libraryClerk actorcreateLibraryRequestSchemaLibrary 201
GET/v1/libraries/shared-with-meLibraries shared with youClerk actor—{ records: Library[] }
GET/v1/libraries/:libraryIdLibrary detail (+ counts)Clerk actor—LibraryListRecord
PATCH/v1/libraries/:libraryIdRename (≥1 field)Clerk actorupdateLibraryRequestSchemaLibrary
DELETE/v1/libraries/:libraryIdDeleteClerk actor—204
GET/v1/libraries/:libraryId/presentationPresentation payloadClerk actor—LibraryListRecord

createLibraryRequestSchema is { name } (1..120, trimmed). A duplicate name returns 409 library_name_conflict (same on PATCH).

Tracks

MethodPathPurposeAuthRequestResponse
POST/v1/libraries/:libraryId/tracksAdd a trackClerk actoraddLibraryTrackRequestSchemalibrary track record
DELETE/v1/libraries/:libraryId/tracks/:trackIdRemove a trackClerk actor—204

addLibraryTrackRequestSchema is { trackId }. A missing library yields 404 library_not_found; a missing track yields 404 track_not_found.

Shares

MethodPathPurposeAuthRequestResponse
GET/v1/libraries/:libraryId/sharesList sharesClerk actor—{ records: LibraryShare[] }
POST/v1/libraries/:libraryId/sharesInvite a collaborator+ collaborators.invitecreateLibraryShareRequestSchemaLibraryShare 201
PATCH/v1/libraries/:libraryId/shares/:shareIdChange access / acceptClerk actorupdateLibraryShareRequestSchemaLibraryShare
DELETE/v1/libraries/:libraryId/shares/:shareIdRevoke a shareClerk actor—204

createLibraryShareRequestSchema requires one of targetUserId or email, plus accessType ∈ viewer | editor | admin (revoked is not a valid input). DELETE revokes by setting both accessType and inviteStatus to revoked.

POST /v1/libraries

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/libraries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Reference Tracks" }'

Returns the created Library (201). A name clash returns 409 library_name_conflict.

POST /v1/libraries/:libraryId/tracks

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

POST /v1/libraries/:libraryId/shares

Invites a collaborator to the library. Gated by collaborators.invite.

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/libraries/:libraryId/shares \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "collab@example.com", "accessType": "editor" }'

A shared library is reachable by the recipient only through an accepted share, graded server‑side. Listing your own libraries (GET /v1/libraries) never returns libraries shared with you — use GET /v1/libraries/shared-with-me for those. See Authentication for the owner‑scoping and grant model.

Public Share LinksCollaborators