HTTP API
Use vozo’s HTTP API when a service needs to connect directly to workspace data or workflows. The API is organized under /api; the MCP endpoint at /mcp is a separate interface for tool-using clients.
Base URL and authentication
Use the API origin configured for your vozo deployment. Organization routes require an authenticated app session and the active organization context. The platform does not currently document a general-purpose API key for these routes. Use MCP credentials for external MCP clients rather than passing a browser session to an assistant.
Send JSON with Content-Type: application/json. Responses use JSON unless an endpoint explicitly returns CSV or no content. Errors have an error field. Organization-scoped endpoints only operate on the active organization and still enforce the caller’s permission.
Core endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/agents | List agents in the active organization. |
POST | /api/agent-import/preview | Validate and preview a supported provider configuration. |
POST | /api/agent-import | Import a supported configuration as a vozo agent. |
GET | /api/agent-import/connections | List connected import providers. |
PUT | /api/agent-import/connections/{provider} | Connect an import provider using its API key. |
GET | /api/agent-import/connections/{provider}/agents | List agents in a connected provider account. |
POST | /api/mcp-access-tokens | Create an organization-scoped MCP credential. |
GET | /api/mcp-access-tokens | List credential metadata for the active organization. |
DELETE | /api/mcp-access-tokens/{id} | Revoke a credential. |
GET | /api/costs/summary | Get organization call costs and customer margin for a date range. |
GET | /api/costs/calls/{callId} | Get a call’s cost breakdown. |
GET | /api/costs/export | Export cost rows as CSV. |
GET | /api/latency | Get turn timing and latency for a date range. |
GET | /api/phone-numbers | Read configured phone numbers. |
GET | /api/monitors | Read configured real-call monitors and statuses. |
The exact request and response schemas live in the shared API package. Routes and permissions can change as the platform evolves; use the implementation schemas as the source of truth when generating a client.
Manage MCP credentials
MCP credentials are managed through the authenticated organization API. Creating and revoking credentials requires organization edit access.
POST /api/mcp-access-tokens
Content-Type: application/json
Cookie: <authenticated vozo session>
{
"name": "Operations assistant",
"expiresInDays": 30
}The response includes the credential secret once. Save it directly in the MCP client’s secret store. Expiry can be from 1 to 90 days, and an organization can have up to ten active credentials. Listing returns credential metadata, not the secret. Deleting a credential revokes it.
Import example
Preview an export before creating an agent. The import body follows the provider-specific schema in @workspace/shared/api/agent-import/schemas.
POST /api/agent-import/preview
Content-Type: application/json
Cookie: <authenticated vozo session>
{
"provider": "vapi",
"agent": { "...": "provider export fields" }
}If the preview returns warnings, review them before calling POST /api/agent-import. Creating an agent requires agents.create access. A configuration import does not transfer historical calls.
Cost and latency queries
GET /api/costs/summary accepts from and to date query parameters. GET /api/latency accepts date bounds, optional agent IDs, and a time zone. Check the shared schemas for required formatting and range validation.
Versioning
The current API is versioned with the vozo platform release. Pin generated clients to the schemas in the same release you deploy, and review the changelog before upgrading.