Skip to main content

​
Public endpoints

A small set of endpoints is intentionally unauthenticated and safe to call from anywhere:
  • GET /v1/voices — list the available TTS voices.
Every other endpoint in this reference requires a session cookie.

​
Session cookies

The Zeptar API authenticates requests with a session cookie set by better-auth. The cookie is named better-auth.session_token and is established when the user signs in through the web app. A browser visiting app.zeptar.com and the API at api.zeptar.com share the cookie automatically — they live on the same parent domain.

​
From the browser

No setup required. fetch('/v1/...') from a logged-in page already carries the cookie:

​
From a server (SSR, scripts)

Forward the inbound Cookie header to the API. The apiFetch helper in apps/web/lib/zeptar-api-client.ts does this automatically when called from a Server Component or Server Action.

​
From a curl session (development)

Copy the session cookie out of your browser’s devtools and pass it explicitly:

​
Unauthenticated responses

A request without a valid session cookie returns:
Web clients should treat 401 as a signal to redirect to /sign-in. The apps/web server helpers (getOrganizations, getPendingWorkspaceInvites, etc.) do this automatically.

​
Permission errors

Endpoints that require a specific role (e.g. removing a member from an organization requires admin) return:
The error field is a stable machine-readable code. The message field, when present, is intended for end users.

​
API keys

Server-side clients — CI pipelines, backend services, SDK integrations — authenticate with an API key instead of a session cookie. Issue a key via POST /v1/api-keys (session required; see the API keys overview for the full lifecycle). Pass the key in the Authorization header using the Bearer scheme:
Keys start with the prefix zsk_ and are shown once at creation time — store them securely before closing the response. Each key carries per-resource scopes (agents, conversations, knowledge_base, voices, workspace) at level none, read, or write; a request that exceeds the key’s scope returns 403 insufficient_scope. API-key management endpoints (create, list, update, revoke) are session-only — a Bearer key cannot be used to manage other keys.