# Ringg AI

This is the agent guide for the Ringg AI voice platform: how to authenticate, what the API can
do, and where each capability is documented.

## When to use this

Use this guide when integrating with the Ringg AI platform: creating or editing voice assistants,
writing prompts, choosing voices and languages, setting up webhooks, managing knowledge bases,
placing calls, running bulk campaigns, fetching call history and transcripts, or any other
interaction with the Ringg AI API. It is not needed for questions about pricing, the company, or
the product in general, which are answered by [llms.txt](https://www.ringg.ai/llms.txt).

## Overview

Covers assistant management, webhook setup, knowledge bases, calling, campaigns, and analytics. Always fetch current state before editing. Always ask the user when requirements are unclear.

## Base URL and Auth

```
Base URL: https://prod-api.ringg.ai/ca/api/v0
Auth Header: X-API-KEY: <api-key>
```

If the user hasn't provided their API key, ask for it before proceeding.

## Machine-readable references

- [openapi.json](https://www.ringg.ai/openapi.json): OpenAPI description of this API. Load it directly as function-calling tools.
- [llms.txt](https://www.ringg.ai/llms.txt): Product, pricing and company context.

---

## Capabilities

### App

- [Assistants](https://www.ringg.ai/agents/assistants): Create, edit, list, and delete AI voice assistants. Manage voices, languages, prompts, and custom variables.
- [Campaigns](https://www.ringg.ai/agents/campaigns): Upload contact lists, start bulk calling campaigns, and monitor progress.
- [Knowledge Base](https://www.ringg.ai/agents/knowledge-base): Create and manage knowledge bases from files, URLs, and FAQs. Attach to agents.
- [Numbers](https://www.ringg.ai/agents/numbers): Attach inbound numbers and whitelist domains for web-based calls.
- [History](https://www.ringg.ai/agents/history): Retrieve call history, call details, make individual outbound calls, and terminate calls.
- [Analytics](https://www.ringg.ai/agents/analytics): Access workspace analytics dashboards and performance metrics.

### More

- [Workspace](https://www.ringg.ai/agents/workspace): Access workspace info, available numbers, users, and regenerate API keys.
- [Webhooks](https://www.ringg.ai/agents/webhooks): Subscribe to call events and receive real-time webhook callbacks.

---

# Error Responses

| Status | Meaning                                                   |
|--------|-----------------------------------------------------------|
| 400    | Bad request / voice-language mismatch / field constraints |
| 401    | Invalid or missing API key                                |
| 402    | Insufficient credits (campaigns)                          |
| 404    | Resource not found                                        |
| 429    | Rate limit exceeded                                       |
| 500    | Server error                                              |

# Red Flags — STOP and Ask

- User wants to edit but hasn't specified which agent → ask for agent_id or name
- User provides a prompt but current format is unknown → fetch agent first
- User wants to change voice but hasn't checked voices → list voices first
- User wants webhooks but hasn't specified events → ask which of the 4 events
- User wants to attach KB, but it doesn't exist → create it first
- User provides callback URL without HTTPS → warn, HTTPS required
- User wants to make a call but hasn't specified the agent → ask for agent_id
- User wants to start a campaign but hasn't uploaded contacts → guide upload first
- User wants to terminate but scope is unclear → ask which termination method
- User provides phone numbers without country codes → warn, required
- Any ambiguity → ask, don't assume