Public Share Links
These are the visitor‑facing surfaces a recipient hits when they open a pack, track, or split‑sheet share link. They power the public web client; a visitor interacts without a token. There are two shapes:
- Authenticated pack‑link views under
/v1/pack-links/:slug— served to a signed‑in owner or grantee (the Clerk actor is optional); access‑code aware. - Public twins under
/v1/public/*— no auth at all. The public surface can only read (GET) and record share events (POST); it cannot mutate.
All run native→proxy. Public/track DTOs strip ownerId and storage URIs
(gs://…) — see Data Contracts.
Pack links
| Method | Path | Purpose | Auth | Request | Response |
|---|---|---|---|---|---|
GET | /v1/pack-links/:slug (or /presentation) | Pack presentation; records pack.viewed | Clerk actor (optional) | ?accessCode | clientPackPresentationResponseSchema |
POST | /v1/pack-links/:slug/share-events | Record a share | Clerk actor (optional) | recordPackShareRequestSchema | { ok: true } |
GET | /v1/pack-links/:slug/tracks/:trackId/playback-url | Signed stream; records track.played | Clerk actor (optional) | — | playback DTO (storage URI stripped) |
GET | /v1/pack-links/:slug/tracks/:trackId/download-url | Signed download; records track.downloaded | Clerk actor (optional) | — | download DTO |
Public twin (no auth) — /v1/public/pack-links/:slug/… exposes the same
GET presentation, POST /share-events, and GET tracks/:trackId/{playback-url, download-url}. Only GET and POST exist on the public route; the public
surface cannot mutate.
Access‑code behavior: a code‑gated link returns 403 access_code_required until
the visitor supplies ?accessCode=…. Download attempts when the owner has
disableDownloads set return 403 downloads_disabled.
Track links (public)
| Method | Path | Purpose | Auth | Request | Response |
|---|---|---|---|---|---|
GET | /v1/public/track-links/:token | Track share payload | Public | — | track share DTO |
GET | /v1/public/track-links/:token/playback-url | Signed stream (storage URI stripped) | Public | — | playback DTO |
POST | /v1/public/track-links/:token/share-events | Record a share | Public | recordTrackShareRequestSchema | { ok: true } |
A revoked or expired token resolves to 404 track_link_unavailable.
Split sheets (public)
| Method | Path | Purpose | Auth | Request | Response |
|---|---|---|---|---|---|
GET | /v1/public/split-sheets/:token | Split‑sheet share payload | Public | — | { link, splitSheet } |
The token is hashed server‑side; revoked links (revoked_at) and expired links
(expires_at) resolve to 404. The link envelope carries display metadata
(name, status, tokenPreview, trackId, timestamps, optional expiresAt);
splitSheet is the resolved sheet payload.
GET /v1/public/pack-links/:slug
Fetches the public presentation for a share slug. No token. Supply ?accessCode
for a gated link, and the visitor/session params below so unique‑visitor counting
works.
curl -s "https://app.swayzio.com/api/swayzio/v1/public/pack-links/:slug?visitorId=v_abc&sessionId=s_123&source=twitter"A 403 access_code_required means the link is gated — re‑request with
&accessCode=….
GET /v1/public/track-links/:token
Resolves a single‑track share link to its public payload. The storage URI is
stripped; use the companion …/playback-url for a signed stream.
curl -s https://app.swayzio.com/api/swayzio/v1/public/track-links/:tokenVisitor, session & analytics counting
The public web client appends three query params to the engagement surfaces
(presentation, playback, download), each trimmed to 120 chars:
visitorId— stable per‑visitor identifiersessionId— drives theuniqueVisitorscount in pack analyticssource— attribution (e.g.twitter,pack_link); defaults topack_link
Owner self‑previews are not counted. When the resolved actor’s owner matches the link owner, engagement events are skipped — opening your own share link never inflates your analytics. Recording is best‑effort: a failed analytics write never breaks the share page.
See Pack Sharing for creating these links and Analytics for the aggregated metrics.