API Reference

Base URL: https://persona-labsvoice-api-production.up.railway.app/v1

All endpoints require Authorization: Bearer plabs_... unless noted otherwise.

Endpoints

Agents

Method	Path	Description
POST	/v1/agents	Create agent
GET	/v1/agents	List agents
GET	/v1/agents/:id	Get agent
PUT	/v1/agents/:id	Update agent
DELETE	/v1/agents/:id	Delete agent
POST	/v1/agents/provision	Provision agent + collection
POST	/v1/agents/:id/chat	Chat with agent
POST	/v1/agents/:id/speak	Agent TTS
POST	/v1/agents/:id/sync	Sync agent to external platform

Agent Tools

Method	Path	Description
POST	/v1/agents/:id/tools	Create tool
GET	/v1/agents/:id/tools	List tools
PUT	/v1/agents/:id/tools/:toolId	Update tool
DELETE	/v1/agents/:id/tools/:toolId	Delete tool
POST	/v1/agents/:id/tools/:toolId/test	Test tool
POST	/v1/agents/:id/tools/discover-mcp	Discover MCP tools

Agent Instances

Method	Path	Description
POST	/v1/agents/:id/instances	Create instance
GET	/v1/agents/:id/instances	List instances
PUT	/v1/agents/:id/instances/:instanceId	Update instance
DELETE	/v1/agents/:id/instances/:instanceId	Delete instance

Audience Groups

Method	Path	Description
POST	/v1/audience-groups	Create group
GET	/v1/audience-groups	List groups
PUT	/v1/audience-groups/:id	Update group
DELETE	/v1/audience-groups/:id	Delete group

Agent Tasks

Method	Path	Description
POST	/v1/agents/:id/tasks	Dispatch outbound call
GET	/v1/agents/:id/tasks	List tasks
GET	/v1/agents/:id/tasks/:taskId	Get task detail

Testing

Method	Path	Description
POST	/v1/agents/:id/tests	Create test case
GET	/v1/agents/:id/tests	List test cases
POST	/v1/agents/:id/tests/run-selfplay	Run self-play test
POST	/v1/agents/:id/tests/run-selfplay/stream	Run self-play (SSE stream)
POST	/v1/agents/:id/tests/run-synthetic	Run synthetic test

Text-to-Speech

Method	Path	Description
POST	/v1/synthesize	Synthesize speech
GET	/v1/voices	List voices
GET	/v1/voices/:id	Get voice
POST	/v1/voices/clone	Clone voice
DELETE	/v1/voices/:id	Delete voice

Speech-to-Text

Method	Path	Description
POST	/v1/transcribe	Transcribe audio
POST	/v1/transcribe/async	Start async transcription
GET	/v1/transcribe/:jobId	Get transcription job

OpenAI-Compatible

Method	Path	Description
POST	/v1/audio/speech	OpenAI-compatible TTS
POST	/v1/audio/transcriptions	OpenAI-compatible STT
GET	/v1/audio/models	List available audio models

Collections (RAG)

Method	Path	Description
POST	/v1/collections	Create collection
GET	/v1/collections	List collections
GET	/v1/collections/:id	Get collection
DELETE	/v1/collections/:id	Delete collection
POST	/v1/collections/:id/ingest	Ingest content
POST	/v1/collections/:id/search	Search collection
DELETE	/v1/collections/:id/documents/:docId	Delete document

Sessions

Method	Path	Description
POST	/v1/sessions/twilio	Create Twilio session
WS	/v1/sessions/twilio/stream	Twilio media stream
WS	/v1/agents/:id/session	Direct agent WebSocket

Observability

Method	Path	Description
GET	/v1/observability/sessions	List session traces
GET	/v1/observability/sessions/:id	Get session detail
GET	/v1/observability/sessions/:id/root-cause	Root cause analysis
GET	/v1/observability/sessions/interruption-quality	Interruption quality metrics
GET	/v1/observability/calls/:callId	Get call detail
GET	/v1/observability/calls/:callId/root-cause	Call root cause analysis
GET	/v1/recordings/:callId	Get call recording

Conversations

Method	Path	Description
GET	/v1/conversations	List conversations
GET	/v1/conversations/:id	Get conversation detail

Keys & Billing

Method	Path	Description
POST	/v1/keys	Create API key
GET	/v1/keys	List keys
DELETE	/v1/keys/:id	Revoke key
POST	/v1/keys/:id/rotate	Rotate key
GET	/v1/usage	Get usage stats
GET	/v1/billing/subscription	Get subscription
POST	/v1/billing/checkout	Create checkout session
POST	/v1/billing/portal	Billing portal

Provider Keys

Method	Path	Description
POST	/v1/provider-keys	Store provider key
GET	/v1/provider-keys	List stored keys
POST	/v1/provider-keys/:provider/verify	Verify key
DELETE	/v1/provider-keys/:provider	Delete stored key

Evaluation

Method	Path	Description
POST	/v1/eval/transcripts/rate-batch	Batch rate transcripts

Other

Method	Path	Description
GET	/health	Health check (no auth)
GET	/ready	Readiness check (no auth)
GET	/openapi.json	OpenAPI specification (no auth)
GET	/v1	API version and endpoint listing

Pagination

List endpoints use cursor-based pagination:

# First page
curl "https://persona-labsvoice-api-production.up.railway.app/v1/agents?limit=20"

# Next page
curl "https://persona-labsvoice-api-production.up.railway.app/v1/agents?limit=20&cursor=agent_last_id"

Response shape:

{
  "data": [...],
  "nextCursor": "agent_xyz",
  "hasMore": true
}

Error Format

{
  "code": "NOT_FOUND",
  "message": "Agent not found",
  "requestId": "req_abc123"
}

Common codes: NOT_FOUND, VALIDATION_ERROR, UNAUTHORIZED, RATE_LIMITED, PROVIDER_UNAVAILABLE, INTERNAL_ERROR.