canonical: https://jentic.com/apis/ringg.ai/ringg

# Ringg AI API Documentation

The Ringg AI API places outbound phone calls with Ringg's voice AI agents, one at a time or as large campaigns from an uploaded contact list. It creates and edits voice agents with a prompt, task, language, voice, intro message, and attached knowledge base, rents and releases phone numbers, and manages sub workspaces called Ringg Spaces with their own concurrency and credit allocations. Call history can be filtered by status, call_type, agent, and number, and each call's details include analysis and metrics. Analytics endpoints report call volume, connectivity, agent performance, latency, concurrency, and cohort breakdowns.

## For AI agents

Place outbound calls with Ringg AI voice agents, run contact-list campaigns, build agents with knowledge bases, rent numbers, and read call history and analytics.

## Scope

Does not send SMS, email, or chat outside Ringg, and does not host a CRM. Use for running Ringg AI voice agents, calls, campaigns, and their analytics only.

## Capabilities

- Place a single outbound call with a voice agent to a mobile_number, from a fixed number or a number pool
- Upload a campaign contact list and start a campaign, or terminate in-flight calls by call_ids or mobile_numbers
- Create voice agents with a prompt, task, primary_language, voice_id, and intro_message, and edit settings such as voice, knowledge base, or inbound number
- Create and edit knowledge bases from files, URLs, and FAQs and attach them to an agent
- Filter call history by status, call_type, agent_id, and date range, and fetch one call's analysis and metrics
- Rent and release workspace phone numbers by country_code and prefix
- Allocate concurrency and credit limits across Ringg Spaces, and report volume, connectivity, and latency analytics

## Use cases

### Agent-triggered calls with a narrow permission set

A developer's CRM agent should be able to ring a fresh lead with a Ringg voice agent, and nothing more. Through Jentic the agent searches by intent, gets the initiateIndividualCall operation with its input schema, and calls it with the X-API-KEY injected at execution time. The developer's rule allows that call operation and the call-details read, so the agent cannot buy numbers, delete agents, or start a whole campaign.

Example prompt: Call POST `/calling/outbound/individual` with name 'Priya Shah', mobile_number '+919876543210', and the sales agent_id, then poll GET `/calling/call-details` with the returned call id and send_analysis true

### Outbound campaigns from a contact list

Collections, reminders, and lead qualification often mean calling hundreds of people with the same script. POST `/campaign/save` uploads a contact file with a variables_map, agent_id, call_config, country_code, campaign_name, and start and end times, and POST `/campaign/start` or POST `/campaign/v2/start` launches it from fixed numbers or a number pool. PATCH `/campaign/terminate` stops calls in flight.

Example prompt: Upload a CSV via POST `/campaign/save` with campaign_name 'November renewals', the agent_id, country_code '+91', a variables_map, and campaign_start_time and campaign_end_time, then start it via POST `/campaign/v2/start` with the list_id and number_pool_id

### Building and tuning voice agents

Teams iterate on voice agents as scripts change. POST `/public/agent` creates an agent with agent_name, introduction_and_objective, response_guidelines, task, primary_language, voice_id, and intro_message, while PATCH `/agent/v1` applies one targeted change per call through its operation field, such as edit_prompt, edit_voice, attach_kb, or attach_inbound_number. GET `/agent/voices` lists voices by language.

Example prompt: Create a knowledge base via POST `/external/kb` with kb_name 'Refund policy' and a policy URL, then call PATCH `/agent/v1` with operation 'attach_kb', the agent_id, and the new kb_id

### Call quality and performance reporting

Operations leads want to know how calls are going without exporting spreadsheets. GET `/calling/history` filters by status values such as completed, failed, or forwarded and by call_type such as inbound or outbound, and POST `/calling/history/download` exports the same view. The analytics endpoints report volume, connectivity, agent performance, latency, and concurrency over a date range, optionally per Ringg Space.

Example prompt: Call GET `/analytics/v4/connectivity` and GET `/analytics/v4/agent-performance` with start_date and end_date for last week and the agent_id, then list failed calls via GET `/calling/history` with status ['failed']

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/calling/outbound/individual` | Initiate an individual call |
| GET | `/calling/history` | Get call history |
| GET | `/calling/call-details` | Get call details |
| POST | `/campaign/save` | Upload a campaign contact list |
| POST | `/campaign/v2/start` | Start a campaign from a number pool |
| POST | `/public/agent` | Create a voice agent |
| PATCH | `/agent/v1` | Edit agent settings |
| POST | `/external/kb` | Create a knowledge base |

## Key resources

- **Calls** — Place individual outbound calls, read and export call history, and fetch call details with analysis
- **Campaigns** — Upload contact lists, start campaigns from fixed numbers or number pools, check balance, and terminate calls
- **Agents and voices** — Create, read, update, edit settings on, and delete voice agents, and list voices by language
- **Knowledge bases** — Create, edit, read, list, and delete knowledge bases built from files, URLs, and FAQs
- **Workspace and numbers** — Workspace info and users, rented numbers, Ringg Spaces, concurrency, and credit allocation
- **Analytics** — Volume, connectivity, agent performance, latency, concurrency, cohort, and chat analytics

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 66 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 78 / 100
  - AI-Readiness & Agent Experience: 51 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 72 / 100
- **View full report:** https://jentic.com/apis/ringg.ai/ringg/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Ringg AI by hand means sending the X-API-KEY header on each call, picking between fixed numbers and number pools, and handling multipart contact-list uploads for campaigns. Through Jentic you install once, import Ringg AI from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Ringg AI carries the agent, contact, and campaign in the request body for calls and campaigns, so rules bound which operations your agent may call, not which agent or contact list. Limit it to the operations it needs, such as placing one call and reading call details, so ones like buying a number or deleting an agent are not included unless you add them.
- **Credential handling:** Your Ringg AI API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'place an outbound call with a voice agent' or 'get call history', and Jentic returns the matching Ringg AI operation with its input schema, including required fields like mobile_number and agent_id.

## Related APIs

- **Retell AI API** — Voice AI agent platform for inbound and outbound phone calls
- **Bland AI API** — AI phone calling API for automated outbound and inbound calls
- **Twilio REST API** — Programmable telephony, SMS, and phone numbers

## FAQ

### What authentication does the Ringg AI API use?

The Ringg AI API authenticates with an API key sent in the X-API-KEY request header, as declared in its OpenAPI spec under ApiKeyAuth. Through Jentic the key is stored by your own Jentic One instance and added to each call at execution time, so the agent never sees it.

### Can I place a single call with the Ringg AI API without a campaign?

Yes. POST `/calling/outbound/individual` places one call and needs name, mobile_number with country code, and agent_id. POST `/calling/v2/outbound/individual` does the same from a number pool via number_pool_id. You can pass custom_args_values for the agent's variables and a call_deadline or call_validity_hours to bound when the call may run.

### What are the rate limits for the Ringg AI API?

The OpenAPI spec does not specify request rate limits. Call throughput is governed by workspace concurrency, which you can allocate per Ringg Space with PATCH `/workspace/sub/{sub_workspace_id}/concurrency.` Check https://docs.ringg.ai for current limits.

### Is there a Ringg AI MCP server?

You don't need an MCP server to give your agent Ringg AI. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the calling, campaign, and analytics operations on demand without another server's tool definitions in its context.

### How do I place a Ringg AI call through Jentic?

Search Jentic for 'place an outbound call with a voice agent', load the initiateIndividualCall operation, and execute POST `/calling/outbound/individual` with the contact's name, mobile_number, and your agent_id. Then read GET `/calling/call-details` for the outcome. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Ringg AI API?

Yes. Write a rule that allows only POST `/calling/outbound/individual` and GET `/calling/call-details.` Your agent can ring one contact at a time and check how the call went, but it cannot launch a campaign, buy or release numbers, or delete a voice agent, and every call it makes is logged.

### How do I change one setting on a Ringg AI voice agent?

Call PATCH `/agent/v1` with agent_id and an operation value such as edit_prompt, edit_voice, attach_kb, or edit_intro_message. Each operation reads only its own fields, so you send the field for that change and leave the rest of the agent untouched.
