Packs

A pack is an owner‑scoped collection of tracks — the unit you curate, present, and share. This page covers core CRUD plus the track membership, presentation, analytics, and media‑asset surfaces. Sharing (settings, access grants, tracking links) lives on Pack Sharing; the public viewer surfaces are on Public Share Links.

Every endpoint is under /api/swayzio/v1 and requires a Clerk actor. Responses strip ownerId (and storage URIs) via the clientPack* DTO variants — see Data Contracts. Runtime is native→proxy (see Conventions).

Endpoints

Collections & saved/shared

Method	Path	Purpose	Auth	Request	Response
`GET`	`/v1/packs`	List packs you own	Clerk actor	—	`{ records: PackListRecord[] }`
`POST`	`/v1/packs`	Create a pack	+ `packs.create`	`createPackRequestSchema`	`Pack` `201`
`GET`	`/v1/packs/shared-with-me`	Packs shared with you (via accepted grant)	Clerk actor	—	`{ records: PackAccessGrant[] }`
`GET`	`/v1/packs/saved`	Packs you’ve saved	Clerk actor	—	`{ records: SavedPack[] }`

A single pack

Method	Path	Purpose	Auth	Request	Response
`GET`	`/v1/packs/:packId`	Pack detail	Clerk actor	—	`Pack`
`PATCH`	`/v1/packs/:packId`	Update (≥1 field)	Clerk actor	`updatePackRequestSchema`	`Pack`
`DELETE`	`/v1/packs/:packId`	Delete	Clerk actor	—	`204`

Tracks within a pack

Method	Path	Purpose	Auth	Request	Response
`GET`	`/v1/packs/:packId/tracks`	List pack tracks	Clerk actor	—	`{ records: PackTrack[] }`
`POST`	`/v1/packs/:packId/tracks`	Add a track	Clerk actor	`addPackTrackRequestSchema`	`PackTrack`
`DELETE`	`/v1/packs/:packId/tracks/:trackId`	Remove a track	Clerk actor	—	`204`
`PUT`	`/v1/packs/:packId/tracks/order`	Reorder tracks	Clerk actor	`reorderPackTracksRequestSchema`	`{ records: PackTrack[] }`
`GET`	`/v1/packs/:packId/tracks/:trackId/playback-url`	Signed streaming URL	Clerk actor	—	playback DTO
`GET`	`/v1/packs/:packId/tracks/:trackId/download-url`	Signed download URL	Clerk actor	—	download DTO
`POST`	`/v1/packs/:packId/tracks/:trackId/library`	Copy track into one of your libraries	Clerk actor	`addPackTrackToLibraryRequestSchema`	library record

Presentation, analytics, media & engagement

Method	Path	Purpose	Auth	Request	Response
`GET`	`/v1/packs/:packId/presentation`	Owner‑side presentation payload	Clerk actor	—	`clientPackPresentationResponseSchema`
`GET`	`/v1/packs/:packId/analytics`	Engagement rollups	Clerk actor	—	`packAnalyticsResponseSchema`
`GET`	`/v1/packs/:packId/media-assets`	Signed pack media assets	Clerk actor	—	media‑assets DTO
`POST`	`/v1/packs/:packId/banner/uploads`	Cover‑image upload intent (alias: `…/cover/uploads`)	Clerk actor	`packBannerUploadRequestSchema`	upload intent `201`
`PUT`	`/v1/packs/:packId/save`	Save a pack	Clerk actor	—	`SavedPack`
`DELETE`	`/v1/packs/:packId/save`	Unsave a pack	Clerk actor	—	`204`
`POST`	`/v1/packs/:packId/share-events`	Record a client‑side share	Clerk actor	`recordPackShareRequestSchema`	`{ ok: true }`

The cover segment is the current product term for the pack image; banner is kept as a backwards‑compatible alias (the underlying storage kind is still banner_image). Both …/banner/uploads and …/cover/uploads accept the same packBannerUploadRequestSchema payload.

`POST /v1/packs`

Creates an owner‑scoped pack. The name is trimmed and 1..160 chars; description is optional (≤2000, defaults to ""); type is standard or collaborative (default standard); imageAssetId is an optional reference to an already‑uploaded asset. Gated by the packs.create entitlement.

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/packs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Summer Demos", "description": "WIP cuts", "type": "standard" }'

Returns the created Pack (201) with ownerId stripped.

`POST /v1/packs/:packId/tracks`

Adds a track you own to the pack. position is optional (≥0); omit it to append.

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

Returns the created PackTrack. A missing pack yields 404 pack_not_found; a missing track yields 404 track_not_found.

`PUT /v1/packs/:packId/tracks/order`

Reorders the whole pack in one call. trackIds must be the exact set already in the pack, in the new order — a mismatch returns 409 track_set_mismatch.

curl -s -X PUT https://app.swayzio.com/api/swayzio/v1/packs/:packId/tracks/order \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "trackIds": ["trk_3", "trk_1", "trk_2"] }'

Returns the reordered { records: PackTrack[] }.

Analytics shape

GET /v1/packs/:packId/analytics returns packAnalyticsResponseSchema:

totals — views, plays, downloads, externalClicks, saves, shares, trackingLinkOpens, uniqueVisitors.
eventsByType — [{ type, count }] keyed by event type.
tracks — per‑track { trackId, title, artist, plays, downloads, shares }.
updatedAt.

uniqueVisitors is driven by the sessionId the public share client sends, and owner self‑previews are never counted — see Public Share Links and Analytics.

Search Pack Sharing