Swayzio Core API v1 — base path /api/swayzio/v1
Core APIPack Sharing

Pack Sharing

Three layers control who can reach a pack and how:

  • Share settings — the access level and per‑pack capability toggles (can visitors download, save, add to library, see splits/stems/versions).
  • Access grants — explicit per‑recipient invitations (listener / collaborator / admin) addressed by user id or email.
  • Tracking links — Dub‑backed go.swayzio.com short links that carry click/visitor analytics.

All endpoints are under /api/swayzio/v1, require a Clerk actor who owns the pack, and run native→proxy. Responses strip ownerId and provider internals via clientPack* DTOs — see Data Contracts. The public viewer side of these links lives on Public Share Links.

Share settings

MethodPathPurposeAuthRequestResponse
GET/v1/packs/:packId/share-settingsRead current settingsClerk actor—clientPackShareSettingsSchema
PUT / PATCH/v1/packs/:packId/share-settingsUpdate settings+ packs.shareupdatePackShareSettingsRequestSchemaclientPackShareSettingsSchema

updatePackShareSettingsRequestSchema (all fields optional):

  • accessLevel — private | public_view | public_collaborate
  • disableDownloads, disableAddToLibrary, disableSocials, disableSaving
  • hideSplits, hideStems, hideVersions
  • accessCode — 4..128 chars, or null to clear

The stored DTO exposes hasAccessCode (a boolean) rather than the code itself.

Access grants

MethodPathPurposeAuthRequestResponse
GET/v1/packs/:packId/access-grantsList grantsClerk actor—{ records: PackAccessGrant[] }
POST/v1/packs/:packId/access-grantsInvite a recipient+ collaborators.invitecreatePackAccessGrantRequestSchema{ grant, emailDelivery } 201
PATCH/v1/packs/:packId/access-grants/:grantIdChange access / invite statusClerk actorupdatePackAccessGrantRequestSchemaPackAccessGrant
DELETE/v1/packs/:packId/access-grants/:grantIdRevoke a grantClerk actor—204
POST/v1/packs/:packId/access-grants/:grantId/resendRe‑send the invite emailClerk actor—{ grant, emailDelivery }

createPackAccessGrantRequestSchema requires one of targetUserId or email, plus accessType ∈ listener | collaborator | admin. revoked is not a valid input — use DELETE (or PATCH with inviteStatus: "revoked").

⚠️

Invite email is a stub in native mode. The native (Vercel) route does not send invite email: POST …/access-grants and …/resend return emailDelivery: { "status": "skipped", "reason": "email_not_configured" }. The Fastify Core API (proxy) is the surface that actually delivers via Resend. Treat a skipped status as “the grant was created/updated, but no email went out from this runtime.”

Tracking links

MethodPathPurposeAuthRequestResponse
GET/v1/packs/:packId/tracking-linksList tracking linksClerk actor—{ records: PackTrackingLink[] }
POST/v1/packs/:packId/tracking-linksCreate a tracking link+ packs.sharecreatePackTrackingLinkRequestSchemaPackTrackingLink 201
PATCH/v1/packs/:packId/tracking-links/:linkIdRename / set access code / disableClerk actorupdatePackTrackingLinkRequestSchemaPackTrackingLink
DELETE/v1/packs/:packId/tracking-links/:linkIdDisable (soft‑delete) the linkClerk actor—204

Tracking links are the Dub‑synced go.swayzio.com short links. The response shareUrl is the copy‑ready URL — the stored external short URL when synced, otherwise built from the public app URL as /pack-links/:slug; relativePath gives the host‑less path for callers composing their own origin. clientPackTrackingLinkSchema strips ownerId and the trackingProvider / trackingSyncStatus internals.

PUT /v1/packs/:packId/share-settings

Flips the pack public and disables downloads in one call. Gated by packs.share.

curl -s -X PUT https://app.swayzio.com/api/swayzio/v1/packs/:packId/share-settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "accessLevel": "public_view", "disableDownloads": true }'

POST /v1/packs/:packId/access-grants

Invites a collaborator by email. Gated by collaborators.invite.

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/packs/:packId/access-grants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "writer@example.com", "accessType": "collaborator" }'

Returns { grant, emailDelivery } (201). See the stub note above for emailDelivery behavior in native mode.

POST /v1/packs/:packId/tracking-links

Creates a Dub‑backed short link. name defaults to "Share link"; slug is an optional custom slug (≤96); accessCode (4..128) gates the link; isDefault marks the pack’s primary link. Gated by packs.share.

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/packs/:packId/tracking-links \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "IG bio", "isDefault": false }'

The returned shareUrl is ready to paste; click and visitor metrics flow into Analytics and the pack analytics rollup.

PacksPublic Share Links