Skip to main content

​
API Overview

The Voicy API provides RESTful endpoints for managing voice agent calls.

​
Base URL

https://api.voicy.co

​
Versioning

All endpoints are prefixed with /v1/. We maintain backwards compatibility within a version.

​
Endpoints

​
Calls

MethodEndpointDescription
POST/v1/create-phone-callInitiate an outbound call
GET/v1/get-call/{call_id}Get call details
POST/v1/list-callsList calls with filters
PATCH/v1/update-call/{call_id}Update call metadata
DELETE/v1/delete-call/{call_id}Delete a call

​
Request Format

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

​
Response Format

All responses are JSON-encoded. Successful responses return the requested data directly. Error responses follow this format: 
{
  "error": "Description of what went wrong"
}

​
HTTP Status Codes

CodeMeaning
200Success
201Created (for POST requests that create resources)
204No Content (for successful DELETE requests)
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Access denied to resource
404Not Found - Resource doesn’t exist
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error

​
Pagination

The /v1/list-calls endpoint supports cursor-based pagination: 
{
  "limit": 50,
  "pagination_key": "last_call_id_from_previous_page"
}

​
Filtering

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