Skip to main content

​
API Reference

Welcome to the Ringyo AI API reference. This documentation covers all available endpoints for integrating Ringyo AI into your applications.

​
Base URL

All API requests should be made to: 
https://api.ringyo.ai/v1

​
Authentication

All requests require an API key in the Authorization header: 
Authorization: Bearer vb_live_YOUR_API_KEY
See Authentication for details on creating and managing API keys.

​
Request Format

  • All requests must include Content-Type: application/json
  • Request bodies should be JSON-encoded
  • All timestamps are in ISO 8601 format

​
Response Format

All responses are JSON with the following structure:

​
Success Response

{
  "data": {
    // Response data
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

​
Error Response

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {}
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

​
HTTP Status Codes

StatusDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

​
Pagination

List endpoints return paginated results: 
{
  "data": [...],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
Use limit and offset query parameters to paginate: 
GET /v1/calls?limit=20&offset=40

​
Rate Limits

PlanLimit
Pro300 requests/minute
Agency1,000 requests/minute
Rate limit headers are included in every response: 
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1705312800

​
Idempotency

For POST requests, you can include an Idempotency-Key header to ensure the request is only processed once: 
curl https://api.ringyo.ai/v1/calls \
  -X POST \
  -H "Authorization: Bearer vb_live_YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"to": "+1234567890", "agent_id": "agent_xyz"}'

​
Available Endpoints

Calls

Initiate, list, and manage phone calls.

Agents

Create and configure voice agents.

Phone Numbers

Manage your phone numbers.

Webhooks

Configure real-time event notifications.

​
SDKs & Libraries

Official SDKs coming soon:
  • Node.js / TypeScript
  • Python
  • Go
In the meantime, use any HTTP client with the REST API.

​
Need Help?