/rpc methods: calls with an API key
/rpc is the JSON-RPC 2.0 API behind the dashboard. Your backend calls it with a project API key: one POST per call, no session. Below are the methods an integration needs most; every one also exists as an MCP tool, and the “API” section shows the /rpc name under each method.
POST https://apiagent.ringostat.com/rpc
X-API-Key: <YOUR_API_KEY>
Content-Type: application/json
{ "jsonrpc":"2.0", "id":1, "method":"getCampaignStats",
"params":{ "projectID":217, "campaignID":799 } }
→ 200 { "jsonrpc":"2.0", "id":1, "result":{ … } }
→ 200 { "jsonrpc":"2.0", "id":1,
"error":{ "code":-32603, "message":"Internal error",
"data":"unauthorized access to project" } }Send projectID yourself: a key opens only its own project, and most methods do not fill it in (addNumbers and uploadNumbersCSV do). A method error comes back with HTTP 200 and error.code -32603; the reason is in error.data. An unknown method is -32601. No key or an invalid one gets HTTP 401 with a plain-text body; more than 60 requests per second from one IP and key gets HTTP 429 for a minute. A request is at most 20 MB, a list page at most 1000 rows; batches (an array of requests) are not supported.
getProjects — the key's project: ID, name, balance in USD and the concurrent calls limit. This is where your projectID comes from.
{ "jsonrpc":"2.0", "id":1, "method":"getProjects",
"params":{} }
→ "result": { "projects":[ { "ID":217, "Name":"My project",
"CurrentBalance":34.44, "MaxConcurrentCalls":3, … } ] }getCampaignStatus — the project's campaigns with their settings and number counters (stats). The result is an array, also for one campaignID. Without limit it returns every campaign: on a large project page with limit and offset (up to 1000) and ask for fields: "summary". A campaign is dialing when started is true and paused and isArchived are false.
{ "jsonrpc":"2.0", "id":1, "method":"getCampaignStatus",
"params":{ "projectID":217, "campaignID":799 } }
→ "result": [ { "id":799, "name":"Order confirmation", "type":"aisdr",
"started":true, "paused":false, "isArchived":false,
"stats":{ "total":120, "pending":80, "completed":31, "failed":4, … }, … } ]uploadCampaign — creates a campaign (no campaignID) or changes several of its fields (with campaignID: the keys you send overwrite, the rest stays). type: simple (“Informational Call”), aisdr (“Voice Agent”) or multi_question_dtmf (“Interactive Survey”). A new campaign is active at once and dials numbers as soon as they are added, so create it with "pause": true. retryDelay is in minutes.
{ "jsonrpc":"2.0", "id":1, "method":"uploadCampaign",
"params":{ "projectID":217, "name":"Order confirmation",
"type":"aisdr", "language":"en-US", "timezone":"Europe/Kyiv",
"pause":true } }
→ "result": { "id":799, "started":true, "paused":true, … }
# change several fields of an existing campaign
{ … "method":"uploadCampaign",
"params":{ "projectID":217, "campaignID":799, "simultaneousCalls":3 } }updateCampaignField — changes one field. Start and stop with the paused field (false / true); archiving (isArchived: true) needs a paused campaign. Starting (paused: false) runs the compliance check, which can take a few seconds or refuse.
{ "jsonrpc":"2.0", "id":1, "method":"updateCampaignField",
"params":{ "projectID":217, "campaignID":799,
"field":"paused", "value":false } }
→ "result": { "message":"…", "campaign":{ "id":799, "paused":false, … } }addNumbers — adds numbers to the queue; projectID is taken from the key. phone in international format; customFields reach the bot and the webhook, and their values must be strings; scheduledTime (Unix seconds) delays the call. Invalid, blocked and duplicate numbers are skipped and listed in rejected.
{ "jsonrpc":"2.0", "id":1, "method":"addNumbers",
"params":{ "campaignID":799, "numbers":[
{ "phone":"+14155550123", "customFields":{ "name":"John" } } ] } }
→ "result": { "message":"Successfully added 1 numbers to campaign 799",
"numbers":[ { "ID":1001, "PhoneNumber":"+14155550123", "Status":"pending", … } ],
"rejected":[] }uploadNumbersCSV — the same from CSV text: a phone column (spelled exactly), an optional scheduledTime, every other column becomes a custom field. Every row needs as many columns as the header.
{ "jsonrpc":"2.0", "id":1, "method":"uploadNumbersCSV",
"params":{ "campaignID":799,
"csvContent":"phone,name\n+14155550123,John\n" } }
→ "result": { "message":"…", "count":1, "rejected":[] }removeNumber removes a number from the campaign (numberID, or phoneNumber: every row with that phone); a number in a call is refused. clearPendingNumbers stops the queue: pending and retry numbers become abandoned, the campaign itself keeps running.
{ "jsonrpc":"2.0", "id":1, "method":"removeNumber",
"params":{ "projectID":217, "campaignID":799, "numberID":1001 } }
→ "result": { "message":"Number removed successfully", … }
{ … "method":"clearPendingNumbers",
"params":{ "projectID":217, "campaignID":799 } }
→ "result": { "message":"…", "updatedCount":80, … }getCampaignStats — one campaign's counters by status, call durations in seconds, DTMF answers and spend (approxCostUSD is approximate).
{ "jsonrpc":"2.0", "id":1, "method":"getCampaignStats",
"params":{ "projectID":217, "campaignID":799 } }
→ "result": { "campaignID":799,
"stats":{ "total":120, "completed":31, "failed":4, "voicemail":6, … },
"durationStats":{ "avgConnectedDuration":48, … },
"spend":{ "unitsConsumed":52000, "approxCostUSD":5.2, … } }getCampaignNumbers — the call log: numbers with status, times (Unix seconds), custom fields, DTMF answers and AI reports. Filters: status, dates, search, durations; pages with limit (default 50, up to 1000) and offset, total is the count before paging. fields: "summary" leaves out the reports.
{ "jsonrpc":"2.0", "id":1, "method":"getCampaignNumbers",
"params":{ "projectID":217, "campaignID":799,
"status":"completed", "limit":100, "offset":0 } }
→ "result": { "total":31, "limit":100, "offset":0,
"numbers":[ { "ID":1001, "PhoneNumber":"+14155550123", "Status":"completed",
"StartTime":1760437400, "Duration":56, "CustomFields":{ "name":"John" },
"StructuredReports":[ … ], … } ] }campaign.getCallDetail — one call: the number row, the transcript, the AI report, the recording and the webhook deliveries. The recording file is at GET /audio/recording/{number_id} on the same host, with the same X-API-Key.
{ "jsonrpc":"2.0", "id":1, "method":"campaign.getCallDetail",
"params":{ "project_id":217, "number_id":1001 } }
→ "result": { "number":{ … },
"messages":{ "messages":[ { "role":"assistant", "content":"…" }, … ] },
"structured_report":{ … }, "recording":{ "duration_seconds":56, … },
"webhook":{ "attempts":[ … ] } }campaign.getStructuredReport — the AI report of one call (number_id) or the latest one of a campaign (campaign_id): outcome and detailed_report with the fields from the campaign's report settings. Only AI-agent calls have reports.
{ "jsonrpc":"2.0", "id":1, "method":"campaign.getStructuredReport",
"params":{ "number_id":1001 } }
→ "result": { "campaign_id":799, "number_id":1001,
"outcome":"…", "detailed_report":{ "summary":"…", … } }campaign.resendCallWebhook — sends a finished call's report to the campaign webhook again (the key's creator must be a project admin). It is a real request to your endpoint: the result has its statusCode and success.
{ "jsonrpc":"2.0", "id":1, "method":"campaign.resendCallWebhook",
"params":{ "project_id":217, "number_id":1001 } }
→ "result": { "statusCode":200, "success":true, "requestBody":"…", … }webCall.create — a one-time web call token for a site visitor (the “Web calls” guide). It works only with a “Web calls only” key: a full key is refused. clientIp is the visitor's public IP address; the token lives 20 seconds and works once, and the browser connects to wsUrl with it. A refusal comes with its code in error.data.code (busy, rate_limited, insufficient_funds and so on) and the matching HTTP status.
{ "jsonrpc":"2.0", "id":1, "method":"webCall.create",
"params":{ "campaignId":799, "clientIp":"203.0.113.7" } }
→ "result": { "token":"wct1.…",
"wsUrl":"wss://apiagent.ringostat.com/ws/web-call",
"expiresIn":20, "maxDurationSec":180, "callId":"…" }