Understand the API Structure & Concepts

The Ringg AI API lets your backend do what the dashboard does for day-to-day calling: pick an agent, place calls, run campaigns, read call logs and analytics, and receive results by webhook. Building and editing agents is mostly done in the dashboard; the API covers creating an agent from a prompt and changing selected settings.

Base URL and version

https://prod-api.ringg.ai/ca/api/v0

The version (v0) is part of the base URL. Some endpoints have a newer variant with its own path, for example POST /calling/v2/outbound/individual next to POST /calling/outbound/individual.

Resources

Group	What you can do
Workspace	Check the key, read balance, members and the workspaces you can access
Ringg Spaces	Create client or team workspaces and allocate concurrency or money to them
Agents	List, read and create agents, list voices, change settings and webhook subscriptions
Knowledge bases	Create and update knowledge bases from files, URLs and FAQs
Numbers	List the caller numbers in the workspace
Calling	Place one outbound call
Campaigns	Upload a calling list, start it, and track campaigns
Termination	Stop queued and retry calls by campaign, agent, call ID or number
Call history	List calls, fetch one call’s transcript and recording, export to CSV
Analytics	Aggregate call metrics by campaign, number, duration and outcome

Requests

Send the API key in X-API-KEY on every request (see Authentication). Request and response bodies are JSON; set Content-Type: application/json on POST and PATCH requests with a JSON body. Endpoints that take a file (campaign CSVs, knowledge-base documents) use multipart/form-data. Let your HTTP client set that Content-Type so it includes the boundary; setting it by hand breaks the upload.

IDs to store

ID	Where you get it	Where you use it
`agent_id`	`GET /agent/all`, or the agent page in the dashboard	Calls, campaigns, agent settings
`from_number_id`	`GET /workspace/numbers`	Caller ID on individual calls and campaigns
`number_pool_id`	The Number pools page in the dashboard	Caller ID from a pool
`list_id` / `bulk_list_id`	The campaign upload response	Starting the campaign; filtering history and analytics. It is also the campaign’s ID
`call_id`	The call response, call history, webhook payloads	Call details, deduplicating webhooks, support requests

Errors

Failed requests return a 4xx or 5xx status and a JSON body with the reason in message:

{ "message": "Provide either from_number_id or from_number, not both" }

Some endpoints add keys beside message, such as code on Create agent (for example VOICE_LANGUAGE_MISMATCH). A 429 may carry its reason in error instead. Log the status code and the whole body.

Status	Meaning
`400`	The request is invalid, for example a campaign that already started or a caller number that is not in the workspace
`401`	The API key is missing or invalid: `{"message": "Invalid credentials"}`
`402`	The balance, or the available credit limit, does not cover the call or campaign
`403`	The workspace or key cannot use this endpoint
`404`	The agent, call, campaign or knowledge base was not found in this workspace
`409`	The same request is already being processed, for example a call history export
`422`	A field is missing or failed validation; `message` names the problem
`429`	Rate limit hit; retry later with backoff. Endpoint pages list their limits
`5xx`	Server-side failure; retry with backoff and log the request and any `call_id`

Paging

Paging differs by endpoint:

Endpoint	`limit`	`offset`
Get call history	Default `10`, maximum `200` (more returns `400`)	Default `0`
Get all campaigns	Default `10`	Default `0`
List agents	Leave it out to get every agent	Default `0`
List workspace numbers	Not paged: every number comes back	Not paged

Typical integration order

Check the key with GET /workspace.
Pick an agent with GET /agent/all and a caller number with GET /workspace/numbers.
Place one test call with POST /calling/outbound/individual.
Subscribe the agent to webhook events so results reach your server without polling.
Move to campaigns for lists of people, and to call history and analytics for reporting.

Introduction

Agents

Inventory

Calling

Monitoring

Account

API Overview

Base URL and version

Resources

Requests

IDs to store

Errors

Paging

Typical integration order

Next steps

Make your first call

Run a campaign by API

​Base URL and version

​Resources

​Requests

​IDs to store

​Errors

​Paging

​Typical integration order

​Next steps

Make your first call

Run a campaign by API

Base URL and version

Resources

Requests

IDs to store

Errors

Paging

Typical integration order

Next steps