Getting Started

Base URL

Environment	Base URL
Production	`https://app.swayzio.com/api/swayzio`
Versioned surface	`https://app.swayzio.com/api/swayzio/v1`
AI chat	`https://app.swayzio.com/api/ai`

All examples below use the production host. Every product endpoint is under /api/swayzio/v1; health sits at /api/swayzio/health.

Make your first calls

Check the API is up

curl -s https://app.swayzio.com/api/swayzio/health

{ "status": "ok", "service": "swayzio-core", "runtime": "vercel", "timestamp": "2026-06-10T…Z" }

Get a token

Authenticated requests carry a Clerk session JWT as a bearer token. In the browser the web app obtains it via window.Clerk.session.getToken(); server side, mint one with the Clerk backend SDK. See Authentication for the full resolution order.

Call an authenticated endpoint

curl -s https://app.swayzio.com/api/swayzio/v1/tracks?limit=10 \
  -H "Authorization: Bearer $SWAYZIO_TOKEN"

const res = await fetch(
  "https://app.swayzio.com/api/swayzio/v1/tracks?limit=10",
  { headers: { authorization: `Bearer ${token}` } },
);
const { records } = await res.json();

const token = await window.Clerk.session.getToken();
const res = await fetch("/api/swayzio/v1/tracks?limit=10", {
  headers: { authorization: `Bearer ${token}` },
});

Request & response basics

Content type: JSON. Send Content-Type: application/json on requests with a body.
Responses are JSON DTOs. Owner IDs, storage URIs (gs://…), and provider internals are stripped from client responses — see Data Contracts.
Caching: all responses set Cache-Control: no-store by default.
No CORS preflight handlers are defined; the API is designed for same‑origin (the web app) and server‑to‑server use.

Status codes at a glance

Code	Meaning
`200` / `201` / `202` / `204`	Success (created / accepted / no content)
`400`	Validation error or malformed JSON
`401`	Missing or invalid credentials
`403`	Authenticated but not entitled (plan gate) or access denied
`404`	Resource not found (or owner mismatch)
`405`	Method not allowed on that resource
`409`	Conflict (name clash, reorder mismatch, delete-original)
`422`	Structural validation failed (e.g. split‑sheet totals)
`429`	Rate limited (e.g. analytics)
`501`	Native route not implemented (proxy disabled)
`502` / `503`	Provider error / dependency unavailable

See Conventions for the full error model and response headers.

This API powers a first‑party web client. There is no public app‑registration or API‑key issuance flow today; access is via a Clerk session token for a real account, or a server‑to‑server secret for the internal surfaces.

Introduction Authentication