API Documentation

Quick Start

Get your first voice agent running in minutes. This guide walks you through authentication, creating a workflow, and initiating your first call.

account_tree

Workflows

Design conversation flows with our visual builder or API.

phone_in_talk

Telephony

Initiate outbound calls or handle inbound with any provider.

campaign

Campaigns

Run batch calling campaigns with progress tracking.

record_voice_over

Voices

Choose from ElevenLabs, Deepgram, Cartesia, and more.

Authentication

All API requests require authentication. Ring AI supports two authentication methods.

Bearer Token

Use your access token in the Authorization header.

Authorization: Bearer your_token

API Key

Pass your API key in the X-API-Key header.

X-API-Key: your_api_key

warning Keep your credentials secure

Never expose API keys in client-side code or public repositories. Use environment variables and server-side requests.

Getting Your API Key

Generate API keys from your dashboard or via the API:

POST /api/v1/user/api-keys

Create a new API key for your account.

GET /api/v1/user/api-keys

List all API keys associated with your account.

Your First Call

Follow these steps to create a workflow and initiate your first AI-powered phone call.

1. Create a Workflow

Workflows define your agent's behavior, voice, and conversation flow.

cURL

curl -X POST https://api.ringai.com/api/v1/workflow/create/definition \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Customer support workflow",
    "nodes": [...],
    "voice_provider": "elevenlabs",
    "voice_id": "rachel"
  }'

2. Initiate a Call

Use the telephony endpoint to start an outbound call with your workflow.

cURL

curl -X POST https://api.ringai.com/api/v1/telephony/initiate-call \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_abc123",
    "phone_number": "+14155551234",
    "context": {
      "customer_name": "John",
      "account_id": "12345"
    }
  }'

check_circle That's it!

The call will be initiated within seconds. Your AI agent will handle the conversation based on your workflow configuration.

Workflows

Workflows are the core building blocks of Ring AI. They define how your voice agent behaves, what it says, and how it responds.

POST /api/v1/workflow/create/definition

Create a new workflow from a node definition.

POST /api/v1/workflow/create/template

Create a workflow from a pre-built template.

GET /api/v1/workflow/fetch

List all workflows in your account.

GET /api/v1/workflow/fetch/{workflow_id}

Get details of a specific workflow.

PUT /api/v1/workflow/{workflow_id}

Update an existing workflow.

POST /api/v1/workflow/{workflow_id}/validate

Validate workflow nodes before deployment.

Workflow Runs

Track individual executions of your workflows.

POST /api/v1/workflow/{workflow_id}/runs

Create a new workflow run.

GET /api/v1/workflow/{workflow_id}/runs

List all runs for a workflow (paginated).

Telephony

Initiate calls, handle inbound calls, and manage provider integrations. Supports Twilio, Vonage, and other major providers.

Outbound Calls

POST /api/v1/telephony/initiate-call

Initiate an outbound call with a workflow.

Inbound Calls

POST /api/v1/telephony/inbound/{workflow_id}

Handle incoming calls with multi-provider support.

POST /api/v1/telephony/inbound/fallback

Fallback endpoint with audio message.

Provider Webhooks

Configure status callbacks for your telephony provider. Ring AI supports Twilio, Vonage, and other major providers.

POST /api/v1/telephony/{provider}/status-callback/{run_id}

Receive status updates for call events (started, ringing, answered, completed).

Campaigns

Run batch calling campaigns with scheduling, progress tracking, and pause/resume controls.

POST /api/v1/campaign/create

Create a new calling campaign.

GET /api/v1/campaign/

List all campaigns.

POST /api/v1/campaign/{campaign_id}/start

Start campaign execution.

POST /api/v1/campaign/{campaign_id}/pause

Pause a running campaign.

POST /api/v1/campaign/{campaign_id}/resume

Resume a paused campaign.

GET /api/v1/campaign/{campaign_id}/progress

Get campaign statistics and progress.

Phone Numbers

Search, purchase, and manage phone numbers for your voice agents.

GET /api/v1/phone-numbers/search

Search available phone numbers by area code and country.

POST /api/v1/phone-numbers/purchase

Purchase a phone number.

GET /api/v1/phone-numbers/

List all phone numbers in your organization.

POST /api/v1/phone-numbers/{phone_id}/assign

Assign a phone number to an agent.

Voices & TTS

Ring AI integrates with multiple text-to-speech providers for natural-sounding voice agents.

graphic_eq

ElevenLabs

Ultra-realistic voices with emotion.

waves

Deepgram

Low-latency streaming TTS.

mic

Cartesia

Fast, expressive synthesis.

GET /api/v1/user/configurations/voices/{provider}

Get available voices for a TTS provider.

Supported providers: elevenlabs, deepgram, cartesia

Integrations

Connect Ring AI to your existing tools and services.

GET /api/v1/integration/

List all integrations.

POST /api/v1/integration/session

Create an integration session.

PUT /api/v1/integration/{integration_id}

Update an integration.

Webhooks & Credentials

Configure webhook credentials for secure callbacks.

GET /api/v1/credentials/

List all webhook credentials.

POST /api/v1/credentials/

Create a new webhook credential.

PUT /api/v1/credentials/{credential_uuid}

Update a credential.

DELETE /api/v1/credentials/{credential_uuid}

Delete a credential.

Custom Tools

Extend your agent's capabilities with custom tools and functions.

GET /api/v1/tools/

List tools (filter by status, category).

POST /api/v1/tools/

Create a custom tool.

PUT /api/v1/tools/{tool_uuid}

Update a tool.

DELETE /api/v1/tools/{tool_uuid}

Archive a tool.

API Keys

Manage API keys and service keys for authentication.

API Keys

GET /api/v1/user/api-keys

List all API keys.

POST /api/v1/user/api-keys

Create a new API key.

DELETE /api/v1/user/api-keys/{api_key_id}

Archive an API key.

Usage & Analytics

Track usage, view reports, and monitor your organization's activity.

GET /api/v1/organizations/usage/current-period

Get current billing period usage.

GET /api/v1/organizations/usage/daily-breakdown

Get daily usage statistics.

GET /api/v1/organizations/reports/daily

Get daily report by date and timezone.

GET /api/v1/organizations/reports/daily/runs

Get detailed runs with CSV export.

Organization

Configure organization-wide settings including telephony providers.

GET /api/v1/organizations/telephony-config

Get telephony configuration (credentials masked).

POST /api/v1/organizations/telephony-config

Save telephony provider configuration.

Supported providers: twilio, vonage

Embed Widget

Embed a voice agent directly on your website.

POST /api/v1/public/embed/init

Initialize an embed session.

GET /api/v1/public/embed/config/{token}

Get embed configuration.

POST /api/v1/workflow/{workflow_id}/embed-token

Create or update embed token for a workflow.

Public Agent Trigger

POST /api/v1/public/agent/{uuid}

Trigger a call via public API (requires X-API-Key).

Build with the Ring AI API

Quick Start

Workflows

Telephony

Campaigns

Voices

Authentication

Bearer Token

API Key

Getting Your API Key

Your First Call

1. Create a Workflow

2. Initiate a Call

Workflows

Workflow Runs

Telephony

Outbound Calls

Inbound Calls

Provider Webhooks

Campaigns

Phone Numbers

Voices & TTS

ElevenLabs

Deepgram

Cartesia

Integrations

Webhooks & Credentials

Custom Tools

API Keys

API Keys

Usage & Analytics

Organization

Embed Widget

Public Agent Trigger

Ready to build with Ring AI?