API Reference
Voice Projects
Endpoints for managing voice projects and project-based voice links.
Projects
Create, list, read, and update voice projects owned by the authenticated user.
Endpoints
- GET /v1/projects — list all projects (scope: projects:read)
- POST /v1/projects — create a new project (scope: projects:write)
- GET /v1/projects/{projectId} — get one project (scope: projects:read)
- PATCH /v1/projects/{projectId} — update a project (scope: projects:write)
Create project body (POST /v1/projects)
- name: string (required)
- prompt: string (required)
- description: string (optional; defaults to "")
- landingPageTitle: string (optional; defaults to "")
- landingPageInfo: string (optional; defaults to "")
- timeLimitMinutes: number (optional; defaults to 5)
- evaluator: object (optional)
- prompt: string (required if evaluator provided)
- questions: array (required if evaluator provided)
- each question: { id: string, label: string, type: "text" | "number" }
Update project body (PATCH /v1/projects/{projectId})
Same shape as creation, but supports setting evaluator to null to remove it.
- name: string (required)
- prompt: string (required)
- Optional fields: description, landingPageTitle, landingPageInfo, timeLimitMinutes, evaluator (object | null)
Project-based voice links
Manage voice links under a project.
Endpoints
- GET /v1/projects/{projectId}/links — list all links for a project (scope: projects:read)
- POST /v1/projects/{projectId}/links — create one or more project links (scope: projects:write)
- POST /v1/projects/links/{linkId}/cancel?projectId=... — cancel an active project link (scope: projects:write)
Create project links body (POST /v1/projects/{projectId}/links)
- labels: string[] (required; 1+)
- expiryPreset: "1_day" | "1_week" | "1_month" (required)
Response includes computed url per link: ${NEXT_PUBLIC_APP_URL}/link/{token} (falls back to http://localhost:3000).
Cancel project link (POST /v1/projects/links/{linkId}/cancel)
- Path param: linkId (required)
- Query param: projectId (required)
- Success message: "Link cancelled successfully"
Link statuses
The status field applies to both project-based and instant links. Treat unknown values as not active.
- "active": usable
- "used": consumed (a session has been started)
- "expired": no longer usable (expiresAt has passed)
- "cancelled": manually cancelled