Swayzio Core API v1 — base path /api/swayzio/v1
Introduction
Core API · v1

The API behind Swayzio

One owner‑scoped, schema‑validated HTTP interface for the entire platform — catalog, packs, sharing, search, rights, analytics, billing, and the agent‑tooling surface. Everything the app does, you can do too.

Get started Authentication Data contracts
Tracks & CatalogList, search, and manage tracks with lyrics, stems, versions, and rights.Packs & SharingBundle tracks, create share links, and grant scoped collaborator access.SearchKeyword, structured, and audio‑embedding similarity over your catalog.AnalyticsClick, geo, device, and conversion rollups for every shared link.Agent ToolsGoverned, owner‑scoped read/write tools with approval‑gated mutations.BillingStripe checkout, plan changes, portal sessions, and subscription status.WebhooksSignature‑verified inbound events from Stripe, Dub, and Resend.AuthenticationThe actor model, owner‑scoping guarantees, and entitlement gates.

How the API is shaped

  • REST‑ish, JSON in / JSON out. Predictable resource paths, standard HTTP verbs, and a single uniform error envelope ({ "error": "<machine_code>" }).
  • Owner‑scoped by construction. Every authenticated request resolves to an owner (your account); the server keys every read and write on that owner. You can never address another account’s data by guessing an ID — see Authentication.
  • Two implementations, one contract. The same /v1 surface is served natively by Next.js route handlers on Vercel and, for any path not yet ported, proxied to a Fastify Core API service — transparently. See Architecture.
  • Schema‑validated. Every request body and query is validated against a Zod schema from the shared @swayzio/domain package; responses are redacted DTOs (owner IDs, storage URIs, and provider internals are stripped at the boundary).

A first request

curl -s https://app.swayzio.com/api/swayzio/health
# { "status": "ok", "service": "swayzio-core", "runtime": "vercel", "timestamp": "…" }

Authenticated calls carry a Clerk session token as a bearer:

curl -s https://app.swayzio.com/api/swayzio/v1/tracks \
  -H "Authorization: Bearer <CLERK_SESSION_JWT>"
⚠️

This is first‑party API documentation. Endpoints, auth requirements, and redaction rules reflect the verified state of the codebase. Stub/placeholder endpoints are explicitly flagged where they exist.

Getting Started