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

Status	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal 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

Plan	Limit
Pro	300 requests/minute
Agency	1,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?

Browse the Quick Start Guide
Check n8n Integration for automation
Join our Discord for support

​API Reference

​Base URL

​Authentication

​Request Format

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Pagination

​Rate Limits

​Idempotency

​Available Endpoints