API reference

Base URL

• Production: https://getvoxy.ai/v1
• Local dev: http://localhost:4000/v1

Authentication

Three flavours, scoped to where the route lives.

• Browser / workspace — HTTP-only refresh cookie + short-lived access token. Login via POST /auth/login; refresh is silent on 401 retry.
• API keys — per-workspace bearer tokens. Create at /workspace/settings/developer. Send asAuthorization: Bearer voxy_live_...
• Internal shared-secret — used by the voice-bridge for /v1/internal/*. Not exposed.

Envelope

Every response has the shape:

{
  "success": true,
  "data": { ... }
}
// or
{
  "success": false,
  "error": "human-readable message",
  "code": "ERROR_CODE",
  "details": { ... }
}

Surfaces

• /v1/auth/* — login, signup, MFA, sessions.
• /v1/workspaces/:id/* — per-workspace routes (agents, calls, kb, flows, leads, webhooks, ...).
• /v1/admin/* — platform-admin only.
• /v1/public/* — unauthenticated (signup, pricing, web-agent captcha, form submit).

Pagination

All list endpoints are cursor-paginated: ?cursor=<ulid>&limit=25. The response includes nextCursor (null when at the end).

Rate limits

• Default authenticated traffic: 60 req/min per IP.
• Auth-strict (signup, password-reset, magic-link): 5 req/hour per IP.
• Public web-agent endpoints: 30 req/min per IP.

OpenAPI spec

The full OpenAPI 3 spec is committed at apps/api/openapi.json in the repo. Auto-generated docs rendering on this page is the v2 polish.