Skip to main content

​
API Overview

The Voicy API provides RESTful endpoints for managing calls.

​
Base URL

https://api.voicy.co/functions/v1
Each endpoint is an individual edge function at {base_url}/{function-name}.

​
Endpoints

​
Calls

MethodEndpointDescription
POST/call-dialInitiate an outbound call
GET/call-get/{call_id}Get call details with transcript, recording, and variables
POST/call-listList calls with filters, sorting, and pagination

​
Agents

MethodEndpointDescription
GET/agent-listList the agents in your account
GET/agent-get/{agent_id}Get an agent and its variable contract
POST/agent-createCreate a prompt-based agent (deployed immediately)
PATCH/agent-modify/{agent_id}Update a prompt-based agent

​
Authentication

Include your API key in the Authorization header: 
Authorization: Bearer voicy_sk_your_api_key

​
Request Format

  • Use Content-Type: application/json for request bodies
  • Include Authorization: Bearer <api_key> header
  • Send JSON-encoded request bodies

​
Response Format

Successful responses return the requested data directly as JSON. Error responses: 
{
  "status": "error",
  "message": "Description of what went wrong"
}

​
HTTP Status Codes

CodeMeaning
200Success
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found
422Unprocessable Entity
500Internal Server Error

​
Pagination

/call-list supports cursor-based pagination: 
{
  "limit": 50,
  "pagination_key": "last_call_id_from_previous_page"
}
The response includes total_count for displaying total results.

​
Filtering

Filter calls by various criteria: 
{
  "filter_criteria": {
    "agent_id": ["uuid1", "uuid2"],
    "call_status": ["ended"],
    "direction": ["incoming", "outgoing"],
    "start_timestamp": {
      "lower_threshold": 1704067200000,
      "upper_threshold": 1704153600000
    }
  }
}