{ "openapi": "3.0.0", "info": { "title": "Ringg AI API Documentation", "description": "This is the documentation for the Ringg AI APIs. The Ringg AI API follows RESTful principles, making it intuitive and easy to integrate with your applications. All API requests should be made to the base URL. The API accepts and returns data in JSON format. Ensure your requests include the appropriate Content-Type header for POST and PATCH requests.", "version": "2.0.0" }, "servers": [ { "url": "https://prod-api.ringg.ai/ca/api/v0" } ], "tags": [ { "name": "workspace", "description": "Endpoints for managing your workspace." }, { "name": "agent", "description": "Endpoints for managing agents." }, { "name": "calling", "description": "Endpoints for making and managing calls." }, { "name": "campaign", "description": "Endpoints for managing campaigns." }, { "name": "analytics", "description": "Endpoints for accessing call analytics and performance metrics." }, { "name": "termination", "description": "Endpoints for terminating active calls using different methods." }, { "name": "knowledgebase", "description": "Endpoints for managing knowledge bases." } ], "paths": { "/workspace": { "get": { "tags": [ "workspace" ], "summary": "Get Workspace Info", "x-mint": { "metadata": { "title": "Get Workspace Info | Ringg AI", "og:title": "Get Workspace Info | Ringg AI" } }, "description": "Retrieves information about your current workspace.", "operationId": "getWorkspaceInfo", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "responses": { "200": { "description": "Successful Response: Information about the current workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_info": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-000000000112" }, "name": { "type": "string", "example": "Acme Lending" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-12-16T13:03:29.947147+00:00" }, "credits": { "type": "integer", "example": 3025 }, "locked_credits": { "type": "integer", "example": 0 } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/workspace/users": { "get": { "tags": [ "workspace" ], "summary": "List Workspace Users", "x-mint": { "metadata": { "og:title": "List Workspace Users | Ringg AI" } }, "description": "Retrieves a list of all users in your current workspace.", "operationId": "listWorkspaceUsers", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "limit", "in": "query", "description": "Number of items to return.", "schema": { "type": "integer", "default": 10, "example": 50 } }, { "name": "offset", "in": "query", "description": "Number of items to skip (default: 0).", "schema": { "type": "integer", "default": 0, "example": 20 } } ], "responses": { "200": { "description": "Successful Response: A list of users in the workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-000000000111" }, "username": { "type": "string", "example": "priya.sharma" }, "email": { "type": "string", "example": "user@example.com" }, "role": { "type": "string", "example": "member" }, "invite_status": { "type": "string", "example": "success" } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/workspace/numbers": { "get": { "tags": [ "workspace" ], "summary": "Get Workspace Numbers", "x-mint": { "metadata": { "og:title": "Get Workspace Numbers | Ringg AI" } }, "description": "Retrieves every phone number in your workspace, newest first. The list is not paged.", "operationId": "getWorkspaceNumbers", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "telephony_account_id", "in": "query", "required": false, "description": "(Optional) A connected telephony account's ID to list only its numbers, or `ringg` for numbers provided by Ringg, including the shared test numbers. Leave it out for every number.", "schema": { "type": "string", "example": "ringg" } }, { "name": "inbound_enabled", "in": "query", "required": false, "description": "(Optional) `true` for numbers that can receive inbound calls, `false` for the rest.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful Response: A list of available phone numbers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_numbers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-000000000109" }, "number": { "type": "string", "example": "+919876540001" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-12-16T13:03:29.947147+00:00" }, "call_count": { "type": "integer", "example": 0 }, "agent": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-0000000000a1" }, "agent_display_name": { "type": "string", "example": "Sales Assistant" } } }, "is_inbound_enabled": { "type": "boolean", "example": true }, "is_test_number": { "type": "boolean", "example": false }, "is_relay": { "type": "boolean", "description": "`true` for a WhatsApp Relay number.", "example": false }, "tags": { "type": "array", "items": { "type": "string" }, "example": [] }, "is_spam": { "type": "boolean", "example": false }, "spam_message": { "type": "string", "nullable": true, "example": null }, "provider": { "type": "string", "nullable": true, "example": "ringg", "description": "Telephony provider; `ringg` for numbers on Ringg's own account." }, "display_name": { "type": "string", "nullable": true, "example": "Sales Line" }, "owner": { "type": "string", "enum": [ "ringg", "customer" ], "description": "`ringg` for a number on Ringg's account, `customer` for one on your own telephony account.", "example": "ringg" }, "is_custom_number": { "type": "boolean", "example": false }, "telephony_id": { "type": "string", "nullable": true, "example": "00000000-0000-4000-8000-000000000113" }, "number_pool_id": { "type": "string", "nullable": true, "example": "00000000-0000-4000-8000-000000000113" } } } } } } } } }, "400": { "description": "Bad Request - `telephony_account_id` is not a UUID or `ringg`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid telephony_account_id: abc" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/payment/number/checkout": { "post": { "tags": [ "payment" ], "summary": "Buy Number", "x-mint": { "metadata": { "title": "Buy Number | Ringg AI", "og:title": "Buy Number | Ringg AI" } }, "description": "Purchases a phone number and adds it to the current workspace.", "operationId": "buyNumber", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "description": "Specific phone number to buy. If present, Ringg attempts to buy this number.", "example": "+919876500000" }, "prefix": { "type": "string", "description": "Optional number prefix. If number is omitted, Ringg searches for the first available number with this prefix.", "example": "80" }, "country_code": { "type": "string", "enum": [ "CA", "IN", "US" ], "default": "IN", "description": "Country where the number should be purchased.", "example": "IN" }, "region": { "type": "string", "description": "Optional region code or region name supported for the selected country/provider.", "example": "KA" }, "telephony_account_id": { "type": "string", "format": "uuid", "description": "Optional workspace telephony account ID. When supplied, Ringg buys through that account's credentials.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "provider": { "type": "string", "enum": [ "plivo", "exotel", "twilio", "asterisk", "custom", "convox", "vobiz", "mcube", "tatatele", "ozonetel", "whatsapp", "knowlarity" ], "description": "Optional provider to use when telephony_account_id is omitted. Exotel purchases are currently disabled.", "example": "plivo" }, "app_id": { "type": "string", "description": "Optional provider application ID to attach after purchase.", "example": "app-123" } }, "example": { "country_code": "IN", "region": "KA", "prefix": "80", "provider": "plivo" } } } } }, "responses": { "200": { "description": "Number bought successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Number bought successfully!" }, "id": { "type": "string", "description": "Number ID to use as from_number_id in calling APIs.", "example": "00000000-0000-4000-8000-000000000109" }, "number": { "type": "string", "example": "+919876500000" }, "region": { "type": "string", "nullable": true, "example": "KA" }, "country": { "type": "string", "example": "IN" }, "provider": { "type": "string", "example": "plivo" } } } } } }, "400": { "description": "Bad Request - Invalid provider, region, or no matching number available.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "402": { "description": "Payment Required - Workspace does not have enough credits or billing limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Not Found - Workspace or telephony account credentials were not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error - Number purchase or billing failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/workspace/number/{number_id}": { "delete": { "tags": [ "workspace" ], "summary": "Unrent Number", "x-mint": { "metadata": { "title": "Unrent Number | Ringg AI", "og:title": "Unrent Number | Ringg AI" } }, "description": "Removes a number from the current workspace and archives the workspace-number association.", "operationId": "unrentNumber", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "number_id", "in": "path", "description": "Workspace number ID returned by GET /workspace/numbers or POST /payment/number/checkout.", "required": true, "schema": { "type": "string", "example": "00000000-0000-4000-8000-000000000109" } } ], "responses": { "200": { "description": "Number deallocated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Number deallocated successfully!" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "403": { "description": "Forbidden - Protected test numbers cannot be deallocated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Not Found - Number does not exist in the workspace or has already been deallocated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error - Provider deallocation or archive operation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/workspace/all": { "get": { "tags": [ "workspace" ], "summary": "Get All User Workspaces", "x-mint": { "metadata": { "og:title": "Get All User Workspaces | Ringg AI" } }, "description": "Retrieves a list of all workspaces accessible to the current user.", "operationId": "getAllUserWorkspaces", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "responses": { "200": { "description": "Successful Response: A list of user workspaces.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-000000000112" }, "name": { "type": "string", "example": "Acme Lending" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-12-16T13:03:29.947147+00:00" }, "role": { "type": "string", "example": "owner" }, "parent_workspace_id": { "type": "string", "nullable": true, "description": "Set when the workspace is a Ringg Space: the id of its primary. null for a standalone workspace and for a primary itself.", "example": null }, "credits": { "type": "integer", "example": 3025 }, "locked_credits": { "type": "integer", "example": 0 } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/workspace/sub": { "post": { "tags": [ "workspace" ], "summary": "Create Ringg Space", "x-mint": { "metadata": { "og:title": "Create Ringg Space | Ringg AI" } }, "description": "Creates a new Ringg Space under the primary workspace that owns the API key. The Ringg Space is a full workspace (own agents, numbers, campaigns, call history, members) that starts with zero balance or credit limit and zero concurrency; allocate to it afterwards. Every member of the primary is given inherited access to it. The first Ringg Space turns the primary into a family in individual billing mode.", "operationId": "createSubWorkspace", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) The API key of the PRIMARY workspace. A Ringg Space's own key is refused (403, or 400 if Ringg Spaces are enabled on it).", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "(Required) Display name of the new Ringg Space, 1-100 characters. Surrounding whitespace is trimmed.", "example": "Mumbai Collections" } } }, "example": { "name": "Mumbai Collections" } } } }, "responses": { "200": { "description": "Successful Response: The new Ringg Space.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspace Mumbai Collections created successfully" }, "sub_workspace": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-000000000101" }, "name": { "type": "string", "example": "Mumbai Collections" }, "parent_workspace_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000107" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-18T06:41:12.884312+00:00" }, "concurrency": { "type": "integer", "example": 0 }, "limit_concurrency": { "type": "integer", "example": 0 } } } } }, "example": { "message": "Sub-workspace Mumbai Collections created successfully", "sub_workspace": { "id": "00000000-0000-4000-8000-000000000101", "name": "Mumbai Collections", "parent_workspace_id": "00000000-0000-4000-8000-000000000107", "created_at": "2026-09-18T06:41:12.884312+00:00", "concurrency": 0, "limit_concurrency": 0 } } } } }, "400": { "description": "Bad Request - The name is blank, or the API key belongs to a Ringg Space that has Ringg Spaces enabled (no nesting).", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspaces cannot have their own sub-workspaces." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "403": { "description": "Forbidden - Ringg Spaces are not enabled for this workspace (also what a Ringg Space's own key gets), or the caller is not an active member of the primary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspaces are not enabled for this workspace." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } }, "get": { "tags": [ "workspace" ], "summary": "Get Ringg Spaces", "x-mint": { "metadata": { "og:title": "Get Ringg Spaces | Ringg AI" } }, "description": "Returns the whole family in one call: the primary's summary, one row per active Ringg Space with its allocation, members and month-to-date usage, and the family totals. Works on a primary that has no Ringg Spaces yet (empty list).", "operationId": "getSubWorkspaces", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) The API key of the PRIMARY workspace. A Ringg Space's own key is refused (403, or 400 if Ringg Spaces are enabled on it).", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "responses": { "200": { "description": "Successful Response: The family overview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "primary": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-000000000107" }, "name": { "type": "string", "example": "Acme Collections HQ" }, "concurrency": { "type": "integer", "example": 50 }, "limit_concurrency": { "type": "integer", "example": 50 }, "member_count": { "type": "integer", "description": "Direct members of the primary.", "example": 4 }, "billing": { "type": "object", "description": "Money block of one workspace. Prepaid: account_type, currency, total_available_credits. Postpaid: account_type, currency, credit_limit, utilized_limit (both null for a sub in a common-billing family, whose charges pool on the primary).", "properties": { "account_type": { "type": "string", "enum": [ "prepaid", "postpaid" ], "example": "postpaid" }, "currency": { "type": "string", "enum": [ "INR", "USD" ], "example": "INR" }, "total_available_credits": { "type": "number", "nullable": true, "description": "Prepaid only: the workspace's own wallet.", "example": 5000.0 }, "credit_limit": { "type": "number", "nullable": true, "description": "Postpaid only.", "example": 200000.0 }, "utilized_limit": { "type": "number", "nullable": true, "description": "Postpaid only.", "example": 34210.5 } } }, "usage_this_period": { "type": "number", "example": 0 } } }, "sub_workspaces": { "type": "array", "description": "Active Ringg Spaces, oldest first.", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-000000000101" }, "name": { "type": "string", "example": "Mumbai Collections" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-09-01T06:41:12.884312+00:00" }, "concurrency": { "type": "integer", "description": "Concurrent calls allocated to this Ringg Space.", "example": 20 }, "limit_concurrency": { "type": "integer", "description": "The Ringg Space's ceiling: its own allocation in an individual-billing family, the family total in a common-billing family.", "example": 20 }, "member_counts": { "type": "object", "properties": { "direct": { "type": "integer", "example": 2 }, "inherited": { "type": "integer", "example": 4 } } }, "billing": { "type": "object", "description": "Money block of one workspace. Prepaid: account_type, currency, total_available_credits. Postpaid: account_type, currency, credit_limit, utilized_limit (both null for a sub in a common-billing family, whose charges pool on the primary).", "properties": { "account_type": { "type": "string", "enum": [ "prepaid", "postpaid" ], "example": "postpaid" }, "currency": { "type": "string", "enum": [ "INR", "USD" ], "example": "INR" }, "total_available_credits": { "type": "number", "nullable": true, "description": "Prepaid only: the workspace's own wallet.", "example": 5000.0 }, "credit_limit": { "type": "number", "nullable": true, "description": "Postpaid only.", "example": 200000.0 }, "utilized_limit": { "type": "number", "nullable": true, "description": "Postpaid only.", "example": 34210.5 } } }, "usage_this_period": { "type": "number", "description": "Charges for completed calls this calendar month (Asia/Kolkata), in the workspace's billing currency.", "example": 34210.5 } } } }, "family": { "type": "object", "description": "Family totals. Always: the concurrency keys and is_individual_entity. Postpaid families add credit_limit, utilized_total, available_total. Prepaid individual families add available_pot, allocated_balance_total, family_available_total. Prepaid common families add available_pot and family_available_total.", "properties": { "concurrency_capacity": { "type": "integer", "description": "Concurrent calls the family owns (bought on the primary).", "example": 50 }, "concurrency_allocated": { "type": "integer", "description": "Sum of the Ringg Spaces' allocations.", "example": 20 }, "concurrency_available": { "type": "integer", "example": 30 }, "is_individual_entity": { "type": "boolean", "description": "true = individual billing (each sub has its own wallet or limit); false = common billing (one pool on the primary).", "example": true }, "credit_limit": { "type": "number", "nullable": true, "description": "Postpaid: the family total.", "example": 500000.0 }, "utilized_total": { "type": "number", "nullable": true, "description": "Postpaid: primary + Ringg Spaces utilized.", "example": 46710.5 }, "available_total": { "type": "number", "nullable": true, "description": "Postpaid: credit_limit - utilized_total.", "example": 453289.5 }, "available_pot": { "type": "number", "nullable": true, "description": "Prepaid: the primary's unallocated balance.", "example": 12000.0 }, "allocated_balance_total": { "type": "number", "nullable": true, "description": "Prepaid individual: sum of the Ringg Spaces' wallets.", "example": 8000.0 }, "family_available_total": { "type": "number", "nullable": true, "description": "Prepaid: pot + allocated wallets.", "example": 20000.0 } } } } }, "example": { "primary": { "id": "00000000-0000-4000-8000-000000000107", "name": "Acme Collections HQ", "concurrency": 50, "limit_concurrency": 50, "member_count": 4, "billing": { "account_type": "postpaid", "currency": "INR", "credit_limit": 500000.0, "utilized_limit": 12500.0 }, "usage_this_period": 0 }, "sub_workspaces": [ { "id": "00000000-0000-4000-8000-000000000101", "name": "Mumbai Collections", "created_at": "2026-09-01T06:41:12.884312+00:00", "concurrency": 20, "limit_concurrency": 20, "member_counts": { "direct": 2, "inherited": 4 }, "billing": { "account_type": "postpaid", "currency": "INR", "credit_limit": 200000.0, "utilized_limit": 34210.5 }, "usage_this_period": 34210.5 } ], "family": { "concurrency_capacity": 50, "concurrency_allocated": 20, "concurrency_available": 30, "is_individual_entity": true, "credit_limit": 500000.0, "utilized_total": 46710.5, "available_total": 453289.5 } } } } }, "400": { "description": "Bad Request - The API key belongs to a Ringg Space that has Ringg Spaces enabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspaces cannot have their own sub-workspaces." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "403": { "description": "Forbidden - Ringg Spaces are not enabled for this workspace (also what a Ringg Space's own key gets), or the caller is not an active member of the primary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspaces are not enabled for this workspace." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/workspace/sub/members": { "get": { "tags": [ "workspace" ], "summary": "List Family Members", "x-mint": { "metadata": { "og:title": "List Family Members | Ringg AI" } }, "description": "Lists every person with access anywhere in the family and where that access comes from: members of the primary (who inherit access to every Ringg Space) and people added directly to one or more Ringg Spaces.", "operationId": "listFamilyMembers", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) The API key of the PRIMARY workspace. A Ringg Space's own key is refused (403, or 400 if Ringg Spaces are enabled on it).", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "responses": { "200": { "description": "Successful Response: The family member matrix.", "content": { "application/json": { "schema": { "type": "object", "properties": { "primary_workspace_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000107" }, "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000106" }, "email": { "type": "string", "example": "ops.head@acme-lending.example" }, "username": { "type": "string", "example": "Ops Head" }, "role": { "type": "string", "enum": [ "owner", "member" ], "example": "owner" }, "scope": { "type": "string", "enum": [ "primary", "sub" ], "description": "primary = member of the primary, inherits access to every Ringg Space; sub = added directly to Ringg Spaces only.", "example": "primary" }, "sub_workspace_ids": { "type": "array", "description": "Ringg Spaces the person was added to directly (inherited access is not listed).", "items": { "type": "string" }, "example": [] }, "permissions_by_workspace": { "type": "object", "description": "Effective permissions per workspace id, inherited rows included.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "00000000-0000-4000-8000-000000000107": [ "agents", "numbers", "api_keys" ], "00000000-0000-4000-8000-000000000101": [ "agents", "numbers", "api_keys" ] } }, "invite_status": { "type": "string", "nullable": true, "enum": [ "success", "pending" ], "example": "success" } } } } } }, "example": { "primary_workspace_id": "00000000-0000-4000-8000-000000000107", "members": [ { "user_id": "00000000-0000-4000-8000-000000000106", "email": "ops.head@acme-lending.example", "username": "Ops Head", "role": "owner", "scope": "primary", "sub_workspace_ids": [], "permissions_by_workspace": { "00000000-0000-4000-8000-000000000107": [ "agents", "numbers", "api_keys" ], "00000000-0000-4000-8000-000000000101": [ "agents", "numbers", "api_keys" ] }, "invite_status": "success" }, { "user_id": "00000000-0000-4000-8000-00000000010c", "email": "mumbai.lead@acme-lending.example", "username": "mumbai.lead", "role": "member", "scope": "sub", "sub_workspace_ids": [ "00000000-0000-4000-8000-000000000101" ], "permissions_by_workspace": { "00000000-0000-4000-8000-000000000101": [ "agents" ] }, "invite_status": "pending" } ] } } } }, "400": { "description": "Bad Request - The API key belongs to a Ringg Space that has Ringg Spaces enabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspaces cannot have their own sub-workspaces." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "403": { "description": "Forbidden - Ringg Spaces are not enabled for this workspace (also what a Ringg Space's own key gets), or the caller is not an active member of the primary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspaces are not enabled for this workspace." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/workspace/sub/{sub_workspace_id}/concurrency": { "patch": { "tags": [ "workspace" ], "summary": "Allocate Concurrency to a Ringg Space", "x-mint": { "metadata": { "og:title": "Allocate Concurrency to a Ringg Space | Ringg AI" } }, "description": "Sets how many concurrent calls one Ringg Space may run, taken from the family's capacity (bought on the primary). Allocations across all Ringg Spaces cannot exceed the capacity. In an individual-billing family the allocation is also the Ringg Space's hard ceiling; in a common-billing family the ceiling is the family total, so idle capacity flows to whichever Ringg Space is busy.", "operationId": "allocateSubWorkspaceConcurrency", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) The API key of the PRIMARY workspace. A Ringg Space's own key is refused (403, or 400 if Ringg Spaces are enabled on it).", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "sub_workspace_id", "in": "path", "required": true, "description": "(Required) ID of the Ringg Space.", "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000101" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "concurrency" ], "properties": { "concurrency": { "type": "integer", "minimum": 0, "description": "(Required) Concurrent calls to allocate to this Ringg Space. 0 stops it from calling.", "example": 20 } } }, "example": { "concurrency": 20 } } } }, "responses": { "200": { "description": "Successful Response: The new allocation and the family totals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Mumbai Collections now has 20 concurrent calls" }, "sub_workspace_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000101" }, "concurrency": { "type": "integer", "example": 20 }, "limit_concurrency": { "type": "integer", "description": "The persisted ceiling: equals concurrency in an individual-billing family, the family total in a common-billing family.", "example": 20 }, "primary": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-000000000107" }, "name": { "type": "string", "example": "Acme Collections HQ" } } }, "family": { "type": "object", "properties": { "parent_concurrency": { "type": "integer", "description": "Family capacity.", "example": 50 }, "allocated_total": { "type": "integer", "description": "Sum of all Ringg Space allocations after this change.", "example": 20 } } } } }, "example": { "message": "Mumbai Collections now has 20 concurrent calls", "sub_workspace_id": "00000000-0000-4000-8000-000000000101", "concurrency": 20, "limit_concurrency": 20, "primary": { "id": "00000000-0000-4000-8000-000000000107", "name": "Acme Collections HQ" }, "family": { "parent_concurrency": 50, "allocated_total": 20 } } } } }, "400": { "description": "Bad Request - The allocation does not fit the family's capacity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Only 30 concurrent calls are available to allocate from the parent workspace (capacity 50, 20 already allocated to other sub-workspaces)." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "403": { "description": "Forbidden - Ringg Spaces are not enabled for this workspace (also what a Ringg Space's own key gets), or the caller is not an active member of the primary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspaces are not enabled for this workspace." } } } } } }, "404": { "description": "Not Found - No active Ringg Space with this id under the primary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspace not found" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/workspace/sub/credit-limits": { "patch": { "tags": [ "workspace" ], "summary": "Reallocate Credit Limits", "x-mint": { "metadata": { "og:title": "Reallocate Credit Limits | Ringg AI" } }, "description": "Postpaid, individual-billing families only. Sets every active Ringg Space's credit limit in one call and optionally the family total. The map must name every active Ringg Space exactly once; a slice cannot drop below what that Ringg Space has already used this month, the slices cannot exceed the family total, and what remains for the primary must cover its own usage. Not applicable to common-billing families, where credit is pooled on the primary.", "operationId": "reallocateSubWorkspaceCreditLimits", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) The API key of the PRIMARY workspace. A Ringg Space's own key is refused (403, or 400 if Ringg Spaces are enabled on it).", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "allocations" ], "properties": { "allocations": { "type": "object", "description": "(Required) sub_workspace_id -> new credit limit. Must include every active Ringg Space exactly once. Values >= 0, two decimals. Values may be JSON numbers (`200000`) or numeric strings (`\"200000.00\"`).", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } }, "parent_credit_limit": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "(Optional) New family total (the primary's credit limit). Omit to keep the current total. A JSON number or a numeric string, >= 0.", "example": 500000.0 } } }, "example": { "parent_credit_limit": 500000.0, "allocations": { "00000000-0000-4000-8000-000000000101": 200000.0, "00000000-0000-4000-8000-000000000114": 150000.0 } } } } }, "responses": { "200": { "description": "Successful Response: The applied limits. Amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_workspace_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000107" }, "parent_credit_limit": { "type": "string", "description": "The family total, as a decimal string.", "example": "500000.00" }, "allocations": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "00000000-0000-4000-8000-000000000101": "200000.00", "00000000-0000-4000-8000-000000000114": "150000.00" } }, "primary": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-000000000107" }, "name": { "type": "string", "example": "Acme Collections HQ" } } } } }, "example": { "parent_workspace_id": "00000000-0000-4000-8000-000000000107", "parent_credit_limit": "500000.00", "allocations": { "00000000-0000-4000-8000-000000000101": "200000.00", "00000000-0000-4000-8000-000000000114": "150000.00" }, "primary": { "id": "00000000-0000-4000-8000-000000000107", "name": "Acme Collections HQ" } } } } }, "400": { "description": "Bad Request - Wrong billing mode, an incomplete map, or an allocation the family cannot cover.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "This family uses common billing; per-sub credit limits do not exist." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "403": { "description": "Forbidden - Ringg Spaces are not enabled for this workspace (also what a Ringg Space's own key gets), or the caller is not an active member of the primary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspaces are not enabled for this workspace." } } } } } }, "404": { "description": "Not Found - The primary has no Ringg Spaces yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Workspace is not a sub-workspace family parent." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/workspace/sub/credit-balances": { "patch": { "tags": [ "workspace" ], "summary": "Reallocate Credit Balances", "x-mint": { "metadata": { "og:title": "Reallocate Credit Balances | Ringg AI" } }, "description": "Prepaid, individual-billing families only. Sets every active Ringg Space's wallet to an absolute balance; the net difference moves from or to the primary's unallocated pot, which must be able to cover it. Top up on the primary first, then allocate. Not applicable to common-billing families, where the wallet is shared on the primary.", "operationId": "reallocateSubWorkspaceCreditBalances", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) The API key of the PRIMARY workspace. A Ringg Space's own key is refused (403, or 400 if Ringg Spaces are enabled on it).", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "allocations" ], "properties": { "allocations": { "type": "object", "description": "(Required) sub_workspace_id -> the Ringg Space's NEW absolute balance (not a delta). Must include every active Ringg Space exactly once. Values >= 0, two decimals. Values may be JSON numbers (`200000`) or numeric strings (`\"200000.00\"`).", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } } } }, "example": { "allocations": { "00000000-0000-4000-8000-000000000101": 5000.0, "00000000-0000-4000-8000-000000000114": 3000.0 } } } } }, "responses": { "200": { "description": "Successful Response: The applied balances. Amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_workspace_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000107" }, "parent_available_balance": { "type": "string", "description": "The primary's unallocated pot after the move, as a decimal string.", "example": "12000.00" }, "allocations": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "00000000-0000-4000-8000-000000000101": "5000.00", "00000000-0000-4000-8000-000000000114": "3000.00" } }, "primary": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-000000000107" }, "name": { "type": "string", "example": "Acme Collections HQ" } } } } }, "example": { "parent_workspace_id": "00000000-0000-4000-8000-000000000107", "parent_available_balance": "12000.00", "allocations": { "00000000-0000-4000-8000-000000000101": "5000.00", "00000000-0000-4000-8000-000000000114": "3000.00" }, "primary": { "id": "00000000-0000-4000-8000-000000000107", "name": "Acme Collections HQ" } } } } }, "400": { "description": "Bad Request - Wrong billing mode, an incomplete map, or more than the primary's pot can cover.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "These allocations need 9000.00 from the primary's pot, which only holds 4000.00. Lower the allocations or add balance to the primary workspace first." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "403": { "description": "Forbidden - Ringg Spaces are not enabled for this workspace (also what a Ringg Space's own key gets), or the caller is not an active member of the primary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Sub-workspaces are not enabled for this workspace." } } } } } }, "404": { "description": "Not Found - The primary has no Ringg Spaces yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Workspace is not a sub-workspace family parent." } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/agent/all": { "get": { "tags": [ "agent" ], "summary": "List Agents", "x-mint": { "metadata": { "og:title": "Get Assistants | Ringg AI" } }, "description": "Retrieves the agents in your workspace. Without `limit`, every agent is returned.", "operationId": "getAssistants", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "search", "in": "query", "description": "Filter agents by name.", "schema": { "type": "string", "example": "EMI" } }, { "name": "limit", "in": "query", "description": "Number of agents to return. Leave it out to get every agent.", "schema": { "type": "integer", "minimum": 1, "example": 50 } }, { "name": "offset", "in": "query", "description": "Number of items to skip (default: 0).", "schema": { "type": "integer", "default": 0, "minimum": 0, "example": 0 } } ], "responses": { "200": { "description": "Successful Response: A list of agents.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-0000000000a1" }, "agent_display_name": { "type": "string", "example": "EMI reminder" }, "agent_type": { "type": "string", "enum": [ "inbound", "outbound", "outbound_inbound", "whatsapp" ], "example": "outbound" }, "orchestration_mode": { "type": "string", "description": "`single_node` for a single-prompt agent, `multi_node` for a multi-prompt agent.", "example": "single_node" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-04-15T10:30:00.000000+00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-04-16T09:12:00.000000+00:00" }, "template_name": { "type": "string", "nullable": true }, "template_label": { "type": "string", "nullable": true }, "template_icon": { "type": "string", "nullable": true }, "template_source": { "type": "string", "nullable": true }, "template_type": { "type": "string", "nullable": true, "example": "outbound" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version_id": { "type": "string", "example": "00000000-0000-4000-8000-0000000000d1" }, "version_slug": { "type": "string", "example": "v1" }, "is_archived": { "type": "boolean", "example": false } } } }, "voice_avatar": { "type": "string", "nullable": true }, "call_frequency_cap": { "type": "object", "nullable": true, "description": "The agent's call limit, if set." } } } }, "workspace_call_frequency_cap": { "type": "object", "nullable": true, "description": "The workspace's call limit, if set." } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/agent/voices": { "get": { "tags": [ "agent" ], "summary": "List Voices", "x-mint": { "metadata": { "og:title": "Get Assistant Voices | Ringg AI" } }, "description": "Retrieves a list of available voices for agents, optionally filtered by language.", "operationId": "getAssistantVoices", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "language", "in": "query", "description": "Filter voices by language (e.g., 'en-US', 'hi-IN'). Multiple languages can be comma-separated.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful Response: A list of available voices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "3b5c7d2a-8e9f-4a1b-9c6d-2e5f8a7b3c4d" }, "name": { "type": "string", "example": "Sarah" }, "languages": { "type": "array", "items": { "type": "string" }, "example": [ "en-US", "en-GB" ] }, "voice_previews": { "type": "object", "properties": { "en-US": { "type": "string", "format": "uri", "example": "https://example.com/voice-preview-en-us.mp3" } } }, "image_url": { "type": "string", "format": "uri", "example": "https://example.com/voice-avatar.jpg", "nullable": true }, "gender": { "type": "string", "example": "female" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-12-16T13:03:29.947147+00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-12-16T13:03:29.947147+00:00" } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Failed to fetch agent voices" } } } } } } } } }, "/agent/v1": { "patch": { "tags": [ "agent" ], "summary": "Edit Agent Settings", "x-mint": { "metadata": { "og:title": "Edit Assistant | Ringg AI" } }, "description": "Updates one setting of an existing agent per request. Each operation requires specific fields. Without `version_id`, the change applies to the agent's active version.", "operationId": "editAssistant", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operation", "agent_id" ], "properties": { "operation": { "type": "string", "enum": [ "attach_inbound_number", "remove_inbound_number", "attach_kb", "remove_kb", "edit_custom_vars", "edit_voice", "edit_prompt", "edit_call_config", "edit_noise_settings", "edit_agent_display_name", "edit_intro_message", "edit_query_phrases", "edit_dtmf_settings", "edit_vad_settings", "edit_agent_whitelisted_domains", "edit_voice_speed", "edit_vocab", "edit_chat_settings", "edit_event_subscriptions" ], "example": "edit_agent_display_name", "description": "The setting to change. Each operation reads only its own fields; see the field descriptions." }, "agent_id": { "type": "string", "example": "00000000-0000-4000-8000-0000000000a1" }, "version_id": { "type": "string", "description": "(Optional) Agent version to change. Without it, the active version is changed; when an A/B test is live, the most recently updated version. Must belong to the agent, or the request returns 404.", "example": "00000000-0000-4000-8000-0000000000d1" }, "agent_display_name": { "type": "string", "example": "Updated Sales Assistant", "description": "Used with `edit_agent_display_name`." }, "language": { "type": "string", "enum": [ "en-US", "en-IN", "hi-IN", "ta-IN", "te-IN", "kn-IN", "mr-IN", "gu-IN", "ar-AE" ], "example": "en-US", "description": "Used with `edit_voice`: the voice's language. The voice must support it." }, "voice_id": { "type": "string", "example": "3b5c7d2a-8e9f-4a1b-9c6d-2e5f8a7b3c4d", "description": "Used with `edit_voice`." }, "secondary_voice_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000102", "description": "Used with `edit_voice`: a second voice. Send an empty string to remove it." }, "agent_prompt": { "oneOf": [ { "type": "string", "example": "You are a helpful sales assistant." }, { "type": "object", "properties": { "prompt_sections": { "type": "array", "items": { "type": "object", "properties": { "section_title": { "type": "string" }, "section_content": { "type": "string" } } } } } } ], "description": "Used with `edit_prompt`. Replaces the whole prompt: send every section, because a section you leave out is deleted. Variables are written `@{{name}}` or `{{name}}`." }, "custom_variables": { "type": "array", "items": { "type": "string" }, "example": [ "callee_name", "mobile_number", "company", "lead_source" ], "description": "Used with `edit_custom_vars`. Replaces the whole list. An outbound agent must keep `callee_name` and `mobile_number`, or the request returns 403." }, "number_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000109", "description": "Used with `attach_inbound_number` and `remove_inbound_number`." }, "kb_id": { "type": "string", "example": "7a9c2d5e-4f6b-1a2b-3c4d-5e6f7a8b9c0d", "description": "Used with `attach_kb` and `remove_kb`." }, "whitelisted_domains": { "type": "array", "items": { "type": "string" }, "example": [ "https://www.ringg.ai", "https://example.com" ], "description": "Used with `edit_agent_whitelisted_domains`. Replaces the list; it must keep `https://www.ringg.ai`." }, "voice_speed": { "type": "number", "example": 1.2, "description": "Used with `edit_voice_speed`." }, "chat_settings": { "type": "object", "description": "Used with `operation: \"edit_chat_settings\"`. `whatsapp_session` sets how long a WhatsApp agent's chats stay open. Fields you leave out keep their current values.", "properties": { "whatsapp_session": { "type": "object", "description": "WhatsApp chat session timeouts. Send both fields: one you leave out is reset to its default. The maximum length must be at least the idle timeout. Applies to chats that open after the change.", "properties": { "idle_timeout_minutes": { "type": "integer", "minimum": 5, "maximum": 1440, "default": 180, "description": "End the chat after this many minutes with no message from the customer.", "example": 1440 }, "max_duration_minutes": { "type": "integer", "minimum": 60, "maximum": 10080, "default": 1440, "description": "Start a new chat once a chat is this many minutes old.", "example": 4320 } } } } }, "event_subscriptions": { "type": "array", "description": "Used with `operation: \"edit_event_subscriptions\"`. The agent's complete list of webhook subscriptions. The list you send replaces the existing one, so include every subscription you want to keep.", "items": { "type": "object", "properties": { "event_type": { "type": "array", "description": "Events delivered to this callback URL. An event type can have up to 4 subscriptions on one agent. `call_started`, `call_ringing`, `call_ongoing`, `call_completed` and `recording_completed` apply to voice agents and `chat_completed` to WhatsApp agents; subscribing an agent to an event its channel never sends returns 400.", "items": { "type": "string", "enum": [ "call_started", "call_ringing", "call_ongoing", "call_completed", "chat_completed", "recording_completed", "platform_analysis_completed", "client_analysis_completed", "all_processing_completed" ] }, "example": [ "all_processing_completed" ] }, "callback_url": { "type": "string", "description": "HTTPS endpoint that receives the events.", "example": "https://api.example.com/webhooks/ringg" }, "method_type": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH" ], "description": "HTTP method Ringg uses when calling your endpoint.", "example": "POST" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Headers Ringg sends to your endpoint with every event, for example a token your receiver checks.", "example": { "Authorization": "Bearer your-webhook-receiver-token" } } } } }, "intro_message": { "type": "string", "description": "Used with `edit_intro_message`: the first message. Replaces the current one.", "example": "Hello, this is Asha from Acme Lending." }, "mute_during_intro": { "type": "boolean", "description": "Used with `edit_noise_settings` (required there): `true` stops the caller interrupting the first message.", "example": false }, "mute_while_bot_speaking": { "type": "boolean", "description": "Used with `edit_noise_settings` (required there): `true` stops the caller interrupting the agent at any time.", "example": false }, "vocab": { "type": "array", "items": { "type": "string" }, "description": "Used with `edit_vocab`: words the agent should recognise. Replaces the list; at most 100 words in total.", "example": [ "Acme", "EMI" ] }, "pre_query_response_phrases": { "type": "array", "items": { "type": "string" }, "description": "Used with `edit_query_phrases`: phrases the agent may say while it looks something up. Replaces the list.", "example": [ "One moment, let me check." ] }, "pre_query_phrase_probability": { "type": "number", "minimum": 0, "maximum": 1, "description": "Used with `edit_query_phrases` (optional): how often a phrase is said, from 0 to 1.", "example": 0.5 }, "vad_settings": { "type": "object", "description": "Used with `edit_vad_settings`. Replaces the current settings.", "properties": { "interruption_sensitivity": { "type": "string", "enum": [ "default", "sensitive", "strict" ], "example": "default" } } }, "call_config": { "type": "object", "description": "Used with `edit_call_config`. Merged into the agent's call settings: only the keys you send change, and nested objects such as `voicemail` merge key by key. Takes the same keys as `call_config` on Create Agent, such as `call_time`, `max_call_length`, `idle_timeout_warning`, `idle_timeout_end` and `voicemail`. `idle_timeout_warning` must stay below `idle_timeout_end`.", "example": { "voicemail": { "detect": true, "action": "end" }, "max_call_length": 300 } } } } } } }, "responses": { "200": { "description": "Successful Response: Agent updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Agent updated successfully!" }, "agent_id": { "type": "string", "example": "00000000-0000-4000-8000-0000000000a1" } } } } } }, "400": { "description": "Bad Request - Invalid parameters or request format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Selected voice does not support the specified language" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "403": { "description": "Forbidden - For example, `edit_custom_vars` without `callee_name` or `mobile_number` on an outbound agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "These variables cannot be removed: callee_name, mobile_number" } } } } } }, "404": { "description": "Not Found - Agent or agent version not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Agent not found" } } } } } }, "422": { "description": "Validation Error - An unknown operation, or a field missing or of the wrong type for the operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Failed to edit agent" } } } } } } } } }, "/agent/{agent_id}": { "get": { "tags": [ "agent" ], "summary": "Get Agent", "x-mint": { "metadata": { "og:title": "Get Assistant By ID | Ringg AI" } }, "description": "Retrieves one agent. Agent-level fields are on `agents`; each version's settings are under `agents.version_details`, keyed by version ID.", "operationId": "getAssistantById", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "agent_id", "in": "path", "description": "(Required) ID of the agent to retrieve.", "required": true, "schema": { "type": "string", "example": "00000000-0000-4000-8000-0000000000a1" } }, { "name": "type", "in": "query", "description": "(Optional) Send `inbound` to get the inbound settings of an outbound-inbound agent.", "required": false, "schema": { "type": "string", "enum": [ "inbound" ] } } ], "responses": { "200": { "description": "Successful Response: Detailed information about the agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "object", "properties": { "id": { "type": "string", "example": "00000000-0000-4000-8000-0000000000a1" }, "agent_display_name": { "type": "string", "example": "EMI reminder" }, "agent_type": { "type": "string", "enum": [ "inbound", "outbound", "outbound_inbound", "whatsapp" ], "example": "outbound" }, "orchestration_mode": { "type": "string", "example": "single_node" }, "form_fields": { "type": "array", "items": { "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "inbound_number_id": { "type": "string", "nullable": true }, "telephony_id": { "type": "string", "nullable": true }, "template_id": { "type": "string", "nullable": true }, "template_name": { "type": "string", "nullable": true }, "template_label": { "type": "string", "nullable": true }, "template_icon": { "type": "string", "nullable": true }, "template_type": { "type": "string", "nullable": true }, "is_ab_live": { "type": "boolean", "description": "An A/B test between versions is live.", "example": false }, "active_agent_version_id": { "type": "string", "nullable": true, "example": "00000000-0000-4000-8000-0000000000d1" }, "ab_versions": { "type": "array", "items": {} }, "derived_analytics_keys": {}, "classification_labels": { "type": "array", "items": { "type": "string" } }, "previous_call_summary": { "description": "Whether a returning caller's previous call summary is passed to the agent." }, "webcall_public_key": { "type": "string", "nullable": true }, "version_details": { "type": "object", "description": "Settings per version, keyed by version ID. A multi-prompt agent returns only `custom_variables`, `tools` and `additional_languages` here.", "additionalProperties": { "type": "object", "properties": { "language": { "type": "string", "example": "en-IN" }, "voice": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "example": "Asha" }, "voice_preview": { "type": "string", "format": "uri" }, "image_url": { "type": "string", "format": "uri" } } }, "secondary_voice_id": { "type": "string", "nullable": true }, "secondary_language": { "type": "string", "nullable": true }, "additional_languages": { "type": "array", "items": { "type": "string" } }, "agent_config": { "type": "object", "description": "The prompt and runtime settings, with `intro_message`, `custom_variables` and `interruption_sensitivity`.", "example": { "agent_prompt": { "prompt_sections": [ { "section_title": "Introduction and Objective", "section_content": "You are Asha, calling Acme Lending customers about an upcoming EMI." } ] }, "intro_message": "Hello, this is Asha from Acme Lending.", "custom_variables": [ "callee_name", "mobile_number" ] } }, "tools": { "type": "array", "items": { "type": "object" } }, "pre_call_tools": { "type": "array", "items": { "type": "object" } }, "on_call_tools": { "type": "array", "items": { "type": "object" } }, "post_call_tools": { "type": "array", "items": { "type": "object" } }, "knowledge_bases": { "type": "array", "items": { "type": "object" } }, "call_config": { "type": "object" }, "chat_config": { "type": "object", "nullable": true }, "event_subscriptions": { "type": "array", "items": { "type": "object" } }, "custom_analysis_prompt": { "type": "string", "nullable": true }, "client_analysis": { "type": "object", "nullable": true }, "whitelisted_domains": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "404": { "description": "Not Found - Resource doesn't exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } }, "delete": { "tags": [ "agent" ], "summary": "Delete Agent", "x-mint": { "metadata": { "og:title": "Delete Assistant | Ringg AI" } }, "description": "Deletes an agent by archiving it (soft delete).", "operationId": "deleteAssistant", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "agent_id", "in": "path", "description": "(Required) ID of the agent to delete.", "required": true, "schema": { "type": "string", "example": "00000000-0000-4000-8000-0000000000a1" } } ], "responses": { "200": { "description": "Successful Response: Agent deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Agent deleted successfully!" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "404": { "description": "Not Found - Agent not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/calling/outbound/individual": { "post": { "tags": [ "calling" ], "summary": "Initiate Individual Call", "x-mint": { "metadata": { "og:title": "Initiate Individual Call | Ringg AI" } }, "description": "Starts one outbound call to a recipient. Send `from_number_id` or `from_number` as the caller number, not both. Both may be left out when the agent version has its own outbound numbers; those numbers also take precedence over the request's caller number.", "operationId": "initiateIndividualCall", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "mobile_number", "agent_id" ], "properties": { "name": { "type": "string", "description": "The name of the person to call", "example": "John Doe" }, "mobile_number": { "type": "string", "description": "The phone number to call (must include country code, e.g., +91 for India)", "example": "+1234567890" }, "agent_id": { "type": "string", "description": "UUID of the agent that will handle the call", "example": "00000000-0000-4000-8000-0000000000a1" }, "from_number": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Caller phone number, or array of caller phone numbers, with country code. Send either `from_number` or `from_number_id`, not both (422).", "example": "+1987654321" }, "custom_args_values": { "type": "object", "description": "Custom variables that will be replaced in the agent's prompt using @{{variable_name}} syntax", "properties": { "company_name": { "type": "string", "description": "Company name for context", "example": "XYZ Corp" }, "appointment_date": { "type": "string", "description": "Appointment date", "example": "2025-01-20" }, "product_name": { "type": "string", "description": "Product name for sales calls", "example": "Premium Service" } }, "example": { "company_name": "XYZ Corp", "appointment_date": "2025-01-20", "product_name": "Premium Service" } }, "smart_formatter": { "type": "object", "description": "(Optional) Smart formatting for callee name — supports first name extraction and dictionary-based transliteration", "properties": { "extract_first_name": { "type": "boolean", "description": "Extract the first actual name from the full name, skipping common prefixes (Mr, Mrs, Dr, etc.)", "default": false, "example": true }, "transliteration": { "type": "boolean", "description": "Transliterate the extracted name to the target language using a local dictionary. When enabled, extract_first_name is automatically applied.", "default": false, "example": true }, "transliteration_language": { "type": "object", "description": "Language configuration for transliteration", "properties": { "source": { "type": "string", "description": "Source language code (default: en)", "default": "en", "example": "en" }, "target": { "type": "string", "description": "Target language code (default: hi)", "default": "hi", "example": "hi" } }, "example": { "source": "en", "target": "hi" } } }, "example": { "extract_first_name": true, "transliteration": true, "transliteration_language": { "source": "en", "target": "hi" } } }, "call_config": { "type": "object", "description": "(Optional) Override default call configuration", "properties": { "idle_timeout_warning": { "type": "integer", "description": "Seconds before idle warning (default: 5)", "default": 5, "example": 10 }, "idle_timeout_end": { "type": "integer", "description": "Seconds before call termination (default: 10)", "default": 10, "example": 15 }, "max_call_length": { "type": "integer", "description": "Maximum call duration in seconds (default: 240)", "default": 240, "example": 300 }, "call_retry_config": { "type": "object", "description": "Retry configuration for failed calls", "properties": { "retry_count": { "type": "integer", "description": "Number of retry attempts", "example": 3 }, "retry_busy": { "type": "integer", "description": "Minutes to wait if busy (default: 30)", "example": 30 }, "retry_not_picked": { "type": "integer", "description": "Minutes to wait if not picked (default: 30)", "example": 30 }, "retry_failed": { "type": "integer", "description": "Minutes to wait if failed (default: 30)", "example": 30 } }, "example": { "retry_count": 3, "retry_busy": 30, "retry_not_picked": 30, "retry_failed": 30 } }, "call_time": { "type": "object", "description": "Time window configuration for calls", "properties": { "call_start_time": { "type": "string", "description": "When calls can start (default: 00:00)", "default": "00:00", "example": "00:00" }, "call_end_time": { "type": "string", "description": "When calls must end (default: 23:00)", "default": "23:00", "example": "23:00" }, "timezone": { "type": "string", "description": "Timezone for call times (default: Asia/Kolkata)", "default": "Asia/Kolkata", "example": "Asia/Kolkata" }, "scheduled_at": { "type": "string", "nullable": true, "description": "Schedule the call: a local date and time without an offset, `YYYY-MM-DDTHH:MM:SS`, read in `timezone` (the agent's timezone when `timezone` is not sent). It must be in the future. A time outside `call_start_time`–`call_end_time` moves to the next opening.", "example": "2026-10-18T15:30:00" } }, "example": { "call_start_time": "00:00", "call_end_time": "23:59", "timezone": "Asia/Kolkata" } } }, "example": { "idle_timeout_warning": 10, "idle_timeout_end": 15, "max_call_length": 300, "call_retry_config": { "retry_count": 3, "retry_busy": 30, "retry_not_picked": 30, "retry_failed": 30 }, "call_time": { "call_start_time": "00:00", "call_end_time": "23:59", "timezone": "Asia/Kolkata" } } }, "from_number_id": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Workspace number ID, or array of workspace number IDs, from List workspace numbers. Send either `from_number_id` or `from_number`, not both (422).", "example": "from-number-id" }, "version_id": { "type": "string", "description": "Optional agent version ID. Defaults to the active version.", "example": "00000000-0000-4000-8000-0000000000d1" }, "call_category": { "type": "string", "description": "Optional category for internal reporting or workflow grouping.", "example": "renewal_reminder" }, "parent_call_id": { "type": "string", "description": "Optional parent call ID for follow-up or chained-call flows.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "purpose": { "type": "string", "nullable": true, "description": "Send `transactional` so the workspace and agent [call limits](/documentation/manage-account/call-limits) do not apply to this call. Leave it out for other calls.", "example": "transactional" }, "call_validity_hours": { "type": "number", "nullable": true, "description": "Hours the call may wait before it is cancelled with sub-status `DEADLINE_PASSED`, counted from when the call is created, or from `call_config.call_time.scheduled_at` when it is scheduled. When both this and `call_deadline` are sent, the earlier one applies. A call held by a call limit waits until its deadline; a call with no deadline is cancelled when a limit blocks it (`FREQUENCY_CAPPED`).", "example": 6 }, "call_deadline": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest time the call may be placed. After it the call is cancelled with sub-status `DEADLINE_PASSED`. See `call_validity_hours`.", "example": "2026-10-18T18:00:00+05:30" } }, "oneOf": [ { "required": [ "from_number_id" ] }, { "required": [ "from_number" ] } ], "example": { "name": "John Doe", "mobile_number": "+919876543210", "agent_id": "00000000-0000-4000-8000-0000000000a1", "from_number_id": "from-number-id", "custom_args_values": { "callee_name": "John", "order_id": "ORD-1042" } } } } } }, "responses": { "200": { "description": "Successful Response: Details about the initiated call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "call_id": { "type": "string", "example": "00000000-0000-4000-8000-00000000010b" }, "call_direction": { "type": "string", "example": "outbound" }, "call_status": { "type": "string", "description": "The current status of the call", "enum": [ "registered", "ongoing", "retry", "error", "completed", "failed", "cancelled", "forwarded" ], "example": "ongoing" }, "initiated_at": { "type": "string", "format": "date-time", "example": "2025-11-24T07:33:49.629642" }, "agent_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000115" }, "custom_args_values": { "type": "object", "description": "Custom variables passed in the request", "example": { "callee_name": "Priya", "mobile_number": "+919876543210", "transfer_to": "+919876543211" } } } }, "message": { "type": "string", "example": "Call initiated successfully" } } } } } }, "400": { "description": "Bad Request - For example, no caller number and no outbound numbers on the agent version, a Ringg test number used as the caller number, a DND number, or a missing variable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Either from_number_id or from_number must be provided, or configure default outbound numbers on the agent version" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "402": { "description": "Payment Required - The workspace balance (or available credit limit) does not cover the call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Your current balance is insufficient to initiate this call!" } } } } } }, "422": { "description": "Validation Error - A field is missing or has the wrong type, or both `from_number_id` and `from_number` were sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Provide either from_number_id or from_number, not both" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/calling/v2/outbound/individual": { "post": { "tags": [ "calling" ], "summary": "Initiate Individual Call (Number Pool)", "x-mint": { "metadata": { "og:title": "Initiate Individual Call (Number Pool) | Ringg AI" } }, "description": "Starts one outbound call to a recipient using a number pool or an explicit caller number. Send at least one of `number_pool_id`, `from_number_id` or `from_number`. With a pool, Ringg picks the caller number from it and ignores the other two.", "operationId": "initiateIndividualCallV2", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "mobile_number", "agent_id" ], "properties": { "name": { "type": "string", "description": "The name of the person to call.", "example": "John Doe" }, "mobile_number": { "type": "string", "description": "The phone number to call (must include country code).", "example": "+1234567890" }, "agent_id": { "type": "string", "description": "UUID of the agent that will handle the call.", "example": "00000000-0000-4000-8000-0000000000a1" }, "number_pool_id": { "type": "string", "nullable": true, "description": "Number pool ID. Ringg picks the caller number from the pool, rotating numbers and skipping ones flagged as spam. When it is sent, `from_number_id` and `from_number` are ignored.", "example": "00000000-0000-4000-8000-0000000000b1" }, "from_number_id": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Workspace number ID, or array of workspace number IDs. Used when no `number_pool_id` is sent. Send either `from_number_id` or `from_number`, not both (422).", "example": "from-number-id" }, "from_number": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Caller phone number, or array of caller phone numbers, with country code. Used when no `number_pool_id` is sent. Send either `from_number` or `from_number_id`, not both (422).", "example": "+1987654321" }, "custom_args_values": { "type": "object", "description": "Custom variables replaced in the agent's prompt using @{{variable_name}} syntax.", "example": { "company_name": "XYZ Corp", "appointment_date": "2025-01-20", "product_name": "Premium Service" } }, "smart_formatter": { "type": "object", "description": "(Optional) Smart formatting for callee name — supports first name extraction and transliteration.", "properties": { "extract_first_name": { "type": "boolean", "description": "Extract the first actual name from the full name, skipping common prefixes (Mr, Mrs, Dr, etc.).", "default": false, "example": true }, "transliteration": { "type": "boolean", "description": "Transliterate the extracted name using a local dictionary. Automatically applies extract_first_name.", "default": false, "example": true }, "transliteration_language": { "type": "object", "properties": { "source": { "type": "string", "default": "en", "example": "en" }, "target": { "type": "string", "default": "hi", "example": "hi" } } } }, "example": { "extract_first_name": true, "transliteration": true, "transliteration_language": { "source": "en", "target": "hi" } } }, "call_config": { "type": "object", "description": "(Optional) Override default call configuration.", "properties": { "idle_timeout_warning": { "type": "integer", "default": 5, "example": 10 }, "idle_timeout_end": { "type": "integer", "default": 10, "example": 15 }, "max_call_length": { "type": "integer", "default": 240, "example": 300 }, "call_retry_config": { "type": "object", "properties": { "retry_count": { "type": "integer", "example": 3 }, "retry_busy": { "type": "integer", "default": 30, "example": 30 }, "retry_not_picked": { "type": "integer", "default": 30, "example": 30 }, "retry_failed": { "type": "integer", "default": 30, "example": 30 } } }, "call_time": { "type": "object", "properties": { "call_start_time": { "type": "string", "default": "00:00", "example": "00:00" }, "call_end_time": { "type": "string", "default": "23:00", "example": "23:00" }, "timezone": { "type": "string", "default": "Asia/Kolkata", "example": "Asia/Kolkata" }, "scheduled_at": { "type": "string", "nullable": true, "description": "Schedule the call: a local date and time without an offset, `YYYY-MM-DDTHH:MM:SS`, read in `timezone` (the agent's timezone when `timezone` is not sent). It must be in the future. A time outside `call_start_time`–`call_end_time` moves to the next opening.", "example": "2026-10-18T15:30:00" } } } } }, "voice_id": { "type": "string", "nullable": true, "description": "Optional AgentVoice ID for this call. Overrides the agent version's default voice.", "example": "voice-uuid-here" }, "version_id": { "type": "string", "nullable": true, "description": "Optional agent version ID. Defaults to the active version.", "example": "00000000-0000-4000-8000-0000000000d1" }, "call_category": { "type": "string", "nullable": true, "description": "Optional category for internal reporting or workflow grouping.", "example": "renewal_reminder" }, "parent_call_id": { "type": "string", "nullable": true, "description": "Optional parent call ID for follow-up or chained-call flows.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "purpose": { "type": "string", "nullable": true, "description": "Send `transactional` so the workspace and agent [call limits](/documentation/manage-account/call-limits) do not apply to this call. Leave it out for other calls.", "example": "transactional" }, "call_validity_hours": { "type": "number", "nullable": true, "description": "Hours the call may wait before it is cancelled with sub-status `DEADLINE_PASSED`, counted from when the call is created, or from `call_config.call_time.scheduled_at` when it is scheduled. When both this and `call_deadline` are sent, the earlier one applies. A call held by a call limit waits until its deadline; a call with no deadline is cancelled when a limit blocks it (`FREQUENCY_CAPPED`).", "example": 6 }, "call_deadline": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest time the call may be placed. After it the call is cancelled with sub-status `DEADLINE_PASSED`. See `call_validity_hours`.", "example": "2026-10-18T18:00:00+05:30" } }, "description": "Send at least one of `number_pool_id`, `from_number_id` or `from_number`. `from_number_id` and `from_number` cannot both be set. When `number_pool_id` is sent, the pool wins." } } } }, "responses": { "200": { "description": "Successful Response: Details about the initiated call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "call_id": { "type": "string", "example": "00000000-0000-4000-8000-00000000010b" }, "call_direction": { "type": "string", "example": "outbound" }, "call_status": { "type": "string", "enum": [ "registered", "ongoing", "retry", "error", "completed", "failed", "cancelled", "forwarded" ], "example": "ongoing" }, "initiated_at": { "type": "string", "format": "date-time", "example": "2025-11-24T07:33:49.629642" }, "agent_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000115" }, "custom_args_values": { "type": "object", "example": { "callee_name": "Priya", "order_id": "ORD-1042" } } } }, "message": { "type": "string", "example": "Call initiated successfully" } } } } } }, "400": { "description": "Bad Request - For example, the pool does not exist or has no usable number, or a Ringg test number was used as the caller number.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Number pool has no available numbers" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "402": { "description": "Payment Required - The workspace balance (or available credit limit) does not cover the call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Your current balance is insufficient to initiate this call!" } } } } } }, "422": { "description": "Validation Error - No caller number source, both `from_number_id` and `from_number`, an empty `number_pool_id`, or a field with the wrong type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Provide at least one of: number_pool_id, from_number_id, from_number" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/calling/history": { "get": { "tags": [ "calling" ], "summary": "Get Call History", "x-mint": { "metadata": { "og:title": "Get Call History | Ringg AI" } }, "description": "Retrieves the history of calls made through the Ringg AI platform with optional filtering and pagination.", "operationId": "getCallHistory", "x-code-samples": [ { "lang": "curl", "label": "cURL", "source": "curl --request GET \\\n --url 'https://prod-api.ringg.ai/ca/api/v0/calling/history?start_date=2025-09-25T00:00:00%2B05:30&end_date=2025-09-25T23:59:59%2B05:30&limit=50&offset=20&agent_id=00000000-0000-4000-8000-0000000000a1&status=completed&bulk_list_id=123e4567-e89b-12d3-a456-426614174000' \\\n --header 'X-API-KEY: '" } ], "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "start_date", "in": "query", "description": "Filter calls starting from this date (ISO 8601 format with timezone).", "schema": { "type": "string", "format": "date-time", "example": "2025-09-25T00:00:00+05:30" } }, { "name": "end_date", "in": "query", "description": "Filter calls up to this date (ISO 8601 format with timezone).", "schema": { "type": "string", "format": "date-time", "example": "2025-09-25T23:59:59+05:30" } }, { "name": "limit", "in": "query", "description": "Maximum number of calls to return. More than 200 returns 400.", "schema": { "type": "integer", "default": 10, "maximum": 200, "example": 50 } }, { "name": "offset", "in": "query", "description": "Number of calls to skip (default: 0).", "schema": { "type": "integer", "default": 0, "example": 20 } }, { "name": "agent_id", "in": "query", "description": "Filter by agent ID. Repeat the parameter to filter by several agents.", "schema": { "type": "array", "items": { "type": "string" }, "example": [ "00000000-0000-4000-8000-0000000000a1" ] } }, { "name": "status", "in": "query", "description": "Filter by call status. Repeat the parameter to filter by several.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "registered", "ongoing", "retry", "error", "completed", "failed", "cancelled", "forwarded" ] }, "example": [ "completed" ] } }, { "name": "bulk_list_id", "in": "query", "description": "Filter by campaign (`bulk_list_id`). Repeat the parameter to filter by several campaigns.", "schema": { "type": "array", "items": { "type": "string" }, "example": [ "123e4567-e89b-12d3-a456-426614174000" ] } }, { "name": "version_id", "in": "query", "description": "Filter by agent version ID. Repeat the parameter to filter by several.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "call_type", "in": "query", "description": "Filter by call type. `callback` and `voicemail` match calls of any direction that were callbacks or reached voicemail.", "schema": { "type": "string", "enum": [ "inbound", "outbound", "webcall", "callback", "voicemail" ], "example": "outbound" } }, { "name": "from_number", "in": "query", "description": "Filter by caller number.", "schema": { "type": "string", "example": "+919876540001" } }, { "name": "to_number", "in": "query", "description": "Filter by the number called.", "schema": { "type": "string", "example": "+919876543210" } }, { "name": "call_id", "in": "query", "description": "Return only this call (UUID).", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Field to sort by.", "schema": { "type": "string", "enum": [ "call_time", "created_at", "called_on_time", "call_duration", "credits_used", "retry_count" ], "default": "call_time" } }, { "name": "sort_order", "in": "query", "description": "Sort direction.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successful Response: Call history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "to_number": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "description": "`registered`: created, not dialled yet (queued, scheduled, outside calling hours or held by a call limit). `ongoing`: dialling, ringing or in conversation. `retry`: an attempt did not connect and another is scheduled. `completed`: connected and ended, including voicemail detected. `failed`: no conversation and nothing left to try, such as busy or unanswered on the last attempt, a DND number, or the campaign window ending first. `error`: a system-side failure, such as the dial or the pre-call API failing. `cancelled`: stopped on purpose, by Terminate calls, a passed deadline or a call limit. `forwarded`: an inbound call sent to the agent's transfer number by its inbound rate limit.", "enum": [ "registered", "ongoing", "retry", "error", "completed", "failed", "cancelled", "forwarded" ] }, "sub_status": { "type": "string", "description": "The detail behind `call_status`. Examples: `FREQUENCY_DEFERRED` (held by a call limit), `FREQUENCY_CAPPED` (cancelled by a call limit), `DEADLINE_PASSED` (cancelled at `call_deadline` or `call_validity_hours`), `USER_TERMINATED` (Terminate calls), `DND_SKIPPED`, `RETRY_LIMIT_REACHED`. For a failed or error call, webhooks and exports can carry the carrier's own reason instead.", "enum": [ "IN_DB", "QUEUED", "ACCEPTED", "RATE_LIMITED", "RETRY_LIMIT_REACHED", "RETRY_SCHEDULED", "FAILED", "USER_DID_NOT_JOIN", "USER_LEFT", "USER_BECAME_IDLE", "CAMPAIGN_TIME_EXCEEDED", "MAX_CALL_DURATION", "NOT_ABLE_TO_CALL", "USER_TERMINATED", "DND_SKIPPED", "VOICEMAIL_DETECTED", "VOICEMAIL_DETECTED_VIA_LLM", "PRE_CALL_API_FAILED", "RECONCILED_TO_ERROR_FROM_REGISTERED", "RECONCILED_TO_ERROR_FROM_RETRY", "RECONCILED_TO_ERROR_FROM_ONGOING", "RECONCILED_TO_COMPLETED_FROM_ONGOING", "FREQUENCY_DEFERRED", "FREQUENCY_CAPPED", "FREQUENCY_CHECK_FAILED", "DEADLINE_PASSED", "PHONOS_TIMEOUT" ] }, "transcript": { "type": "string", "description": "The transcript as a JSON-encoded string; parse it to get one object per turn." }, "audio_recording": { "type": "string", "format": "uri", "description": "URL of the call recording. The link may expire; fetch a fresh one from Get Call Details." }, "created_at": { "type": "string", "format": "date-time" }, "agent": { "type": "object", "properties": { "id": { "type": "string" }, "agent_name": { "type": "string" } } }, "call_duration": { "type": "number" }, "call_attempt_time": { "type": "string", "format": "date-time" }, "call_cost": { "type": "number" }, "call_type": { "type": "string" }, "inbound_from": { "type": "string", "nullable": true } } } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "count": { "type": "integer" }, "total": { "type": "integer" } } }, "examples": { "regular_response": { "summary": "Regular call history (download=false)", "value": { "calls": [ { "id": "00000000-0000-4000-8000-00000000010a", "to_number": "+919876543210", "name": "Priya", "status": "completed", "sub_status": "ACCEPTED", "transcript": "[{\"bot\": \"Hi Priya, this is Asha from Acme Lending. Is this a good time to talk about your EMI due on 5 October?\"}, {\"user\": \"Yes, go ahead.\"}]", "audio_recording": "https://example.com/recordings/call-123.mp3", "created_at": "2025-11-24T11:37:43.678043+00:00", "agent": { "id": "00000000-0000-4000-8000-000000000108", "agent_name": "Payment reminder", "agent_version_id": "00000000-0000-4000-8000-0000000000d1", "orchestration_mode": "single_node", "version": { "version_id": "00000000-0000-4000-8000-0000000000d1", "version_slug": "v1" } }, "call_duration": 7.98, "call_attempt_time": "2025-11-24T11:37:48.549486+00:00", "call_cost": 0.2, "call_type": "outbound", "inbound_from": null, "credits_processed": true, "from_numbers": [ "+919876500000" ], "voicemail_detected": false } ], "limit": 10, "offset": 0, "count": 1, "total": 1 } } } } } }, "400": { "description": "Bad Request - For example, `limit` over 200 or an ID that is not a UUID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Limit cannot be greater than 200" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "429": { "description": "Too Many Requests - More than 10 list requests in 60 seconds from one workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error - Something went wrong on our end.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/calling/history/download": { "post": { "tags": [ "calling" ], "summary": "Download Call History", "x-mint": { "metadata": { "og:title": "Download Call History | Ringg AI" } }, "description": "Queues a CSV export of call history and emails a download link to the requester. The link is valid for 7 days and downloads a ZIP with one CSV. Use `include_analysis=true` to add the post-call analysis columns.", "operationId": "downloadCallHistory", "x-code-samples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url 'https://prod-api.ringg.ai/ca/api/v0/calling/history/download?start_date=2025-09-25T00:00:00%2B05:30&end_date=2025-09-25T23:59:59%2B05:30&agent_id=00000000-0000-4000-8000-0000000000a1&status=completed&include_analysis=true&call_type=outbound&bulk_list_id=123e4567-e89b-12d3-a456-426614174000&voicemail=false&from_number=%2B1234567890&to_number=%2B0987654321&call_id=550e8400-e29b-41d4-a716-446655440000' \\\n --header 'X-API-KEY: '" } ], "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "start_date", "in": "query", "description": "Filter calls starting from this date (ISO 8601 format with timezone)", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2025-09-25T00:00:00+05:30" } }, { "name": "end_date", "in": "query", "description": "Filter calls up to this date (ISO 8601 format with timezone)", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2025-09-25T23:59:59+05:30" } }, { "name": "agent_id", "in": "query", "description": "Filter by agent ID(s) - can be repeated for multiple agents.", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "00000000-0000-4000-8000-0000000000a1" ] } }, { "name": "status", "in": "query", "description": "Filter by call status.", "required": false, "schema": { "type": "string", "enum": [ "registered", "ongoing", "retry", "error", "completed", "failed", "cancelled", "forwarded" ], "example": "completed" } }, { "name": "include_analysis", "in": "query", "description": "Include call analysis data (platform_analysis and client_analysis) in the export.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } }, { "name": "call_type", "in": "query", "description": "Filter by call type.", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound", "webcall" ], "example": "outbound" } }, { "name": "bulk_list_id", "in": "query", "description": "Filter by bulk list ID.", "required": false, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "voicemail", "in": "query", "description": "Filter by voicemail status.", "required": false, "schema": { "type": "boolean", "example": false } }, { "name": "from_number", "in": "query", "description": "Filter by caller phone number.", "required": false, "schema": { "type": "string", "example": "+1234567890" } }, { "name": "to_number", "in": "query", "description": "Filter by callee phone number.", "required": false, "schema": { "type": "string", "example": "+14155550123" } }, { "name": "call_id", "in": "query", "description": "Filter by specific call ID.", "required": false, "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "The export was queued. The download link arrives by email.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation that the export was queued.", "example": "Call history export has been queued. You will receive an email shortly." } }, "example": { "message": "Call history export has been queued. You will receive an email shortly." } } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid date format" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "409": { "description": "Conflict - The same export is already running.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "429": { "description": "Too Many Requests - Too many exports are running; try again later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred" } } } } } } } } }, "/calling/call-details": { "get": { "tags": [ "calling" ], "summary": "Get Call Details", "x-mint": { "metadata": { "og:title": "Get Call Details | Ringg AI" } }, "description": "Retrieves one call by its ID. Set `send_analysis=true` to include post-call analysis and `call_metrics=true` to include eval results.", "operationId": "getCallDetails", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "id", "in": "query", "description": "(Required) The unique identifier (UUID) of the call.", "required": true, "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } }, { "name": "send_analysis", "in": "query", "description": "(Optional) Include `platform_analysis` and `client_analysis`. Each key is left out of the response until its analysis is ready.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } }, { "name": "call_metrics", "in": "query", "description": "(Optional) Include eval results for the call in `data.metrics`.", "required": false, "schema": { "type": "boolean", "default": false, "example": true } } ], "responses": { "200": { "description": "Call details retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the call", "example": "550e8400-e29b-41d4-a716-446655440000" }, "call_direction": { "type": "string", "description": "The direction of the call", "enum": [ "inbound", "outbound", "webcall" ], "example": "outbound" }, "call_status": { "type": "string", "description": "`registered`: created, not dialled yet (queued, scheduled, outside calling hours or held by a call limit). `ongoing`: dialling, ringing or in conversation. `retry`: an attempt did not connect and another is scheduled. `completed`: connected and ended, including voicemail detected. `failed`: no conversation and nothing left to try, such as busy or unanswered on the last attempt, a DND number, or the campaign window ending first. `error`: a system-side failure, such as the dial or the pre-call API failing. `cancelled`: stopped on purpose, by Terminate calls, a passed deadline or a call limit. `forwarded`: an inbound call sent to the agent's transfer number by its inbound rate limit.", "enum": [ "registered", "ongoing", "retry", "error", "completed", "failed", "cancelled", "forwarded" ], "example": "completed" }, "call_sub_status": { "type": "string", "description": "The detail behind `call_status`. Examples: `FREQUENCY_DEFERRED` (held by a call limit), `FREQUENCY_CAPPED` (cancelled by a call limit), `DEADLINE_PASSED` (cancelled at `call_deadline` or `call_validity_hours`), `USER_TERMINATED` (Terminate calls), `DND_SKIPPED`, `RETRY_LIMIT_REACHED`. For a failed or error call, webhooks and exports can carry the carrier's own reason instead.", "enum": [ "IN_DB", "QUEUED", "ACCEPTED", "RATE_LIMITED", "RETRY_LIMIT_REACHED", "RETRY_SCHEDULED", "FAILED", "USER_DID_NOT_JOIN", "USER_LEFT", "USER_BECAME_IDLE", "CAMPAIGN_TIME_EXCEEDED", "MAX_CALL_DURATION", "NOT_ABLE_TO_CALL", "USER_TERMINATED", "DND_SKIPPED", "VOICEMAIL_DETECTED", "VOICEMAIL_DETECTED_VIA_LLM", "PRE_CALL_API_FAILED", "RECONCILED_TO_ERROR_FROM_REGISTERED", "RECONCILED_TO_ERROR_FROM_RETRY", "RECONCILED_TO_ERROR_FROM_ONGOING", "RECONCILED_TO_COMPLETED_FROM_ONGOING", "FREQUENCY_DEFERRED", "FREQUENCY_CAPPED", "FREQUENCY_CHECK_FAILED", "DEADLINE_PASSED", "PHONOS_TIMEOUT" ], "example": "ACCEPTED" }, "from_number": { "type": "string", "description": "The phone number the call was made from", "example": "+1234567890" }, "to_number": { "type": "string", "description": "The phone number the call was made to", "example": "+14155550123" }, "callee_name": { "type": "string", "description": "The name of the person called", "example": "John Doe" }, "agent_id": { "type": "string", "description": "The ID of the agent that handled the call", "example": "agent-123-456" }, "initiation_time": { "type": "string", "format": "date-time", "description": "When the call was initiated", "example": "2024-01-15T14:30:00Z" }, "recording_url": { "type": "string", "description": "URL of the call recording. The link may expire; call this endpoint again for a fresh link, and download the file if you need to keep it.", "example": "https://example.com/recordings/call-123.mp3" }, "transcription_url": { "type": "string", "nullable": true, "description": "The transcript as a JSON-encoded string, not an array: parse it to get one object per turn, keyed `bot` or `user`. `null` when there is no transcript, and `\"[]\"` for a call that never connected.", "example": "[{\"bot\": \"Hi Priya, this is Asha from Acme Lending. Is this a good time to talk about your EMI?\"}, {\"user\": \"Yes, go ahead.\"}]" }, "platform_analysis": { "type": "object", "description": "Ringg's post-call analysis, with `send_analysis=true`: `summary`, `key_points`, `action_items`, `classification` (one of the agent's labels), `sentiment` (`positive`, `neutral` or `negative`), `sentiment_reason`, `callback_requested`, `callback_requested_time`, `callback_requested_via_human_agent`, `call_disconnect_reason` (`agent_hangup` or `user_hangup`) and `timezone`, plus token counters. A call where the callee never spoke gets only `summary`, `classification`, `key_points`, `action_items` and `call_disconnect_reason`.", "example": { "summary": "Priya confirmed she will pay the EMI on 5 October.", "key_points": [ "EMI due on 5 October", "Customer will pay on time" ], "action_items": [], "classification": "promise_to_pay", "sentiment": "positive", "sentiment_reason": "The customer was cooperative.", "callback_requested": false, "callback_requested_time": null, "callback_requested_via_human_agent": false, "call_disconnect_reason": "agent_hangup", "timezone": "Asia/Kolkata" } }, "client_analysis": { "type": "object", "description": "Your Advanced Analysis results, with `send_analysis=true`.", "example": { "emi_payment_date": "2026-10-05", "payment_intent": "will_pay" } }, "metrics": { "type": "array", "description": "Eval results for the call, with `call_metrics=true`.", "items": { "type": "object", "properties": { "metric_id": { "type": "string" }, "metric_run_id": { "type": "string" }, "metric_name": { "type": "string", "example": "instruction_following" }, "output_type": { "type": "string" }, "score": { "type": "number" }, "explanation": { "type": "string" }, "raw_data": { "type": "object", "nullable": true }, "violations": { "type": "array", "nullable": true, "items": {} }, "created_at": { "type": "string", "format": "date-time" } } } } } } } }, "examples": { "basic_response": { "summary": "Basic call details (send_analysis=false)", "value": { "status": "success", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "call_direction": "outbound", "call_status": "completed", "call_sub_status": "ACCEPTED", "from_number": "+1234567890", "to_number": "+14155550123", "callee_name": "John Doe", "agent_id": "agent-123-456", "initiation_time": "2024-01-15T14:30:00Z", "recording_url": "https://example.com/recordings/call-123.mp3", "transcription_url": "[{\"bot\": \"Hi Priya, this is Asha from Acme Lending. Is this a good time to talk about your EMI?\"}, {\"user\": \"Yes, go ahead.\"}]" } } }, "with_analysis": { "summary": "Call details with analysis (send_analysis=true)", "value": { "status": "success", "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "call_direction": "outbound", "call_status": "completed", "call_sub_status": "ACCEPTED", "from_number": "+1234567890", "to_number": "+14155550123", "callee_name": "John Doe", "agent_id": "agent-123-456", "initiation_time": "2024-01-15T14:30:00Z", "recording_url": "https://example.com/recordings/call-123.mp3", "transcription_url": "[{\"bot\": \"Hi Priya, this is Asha from Acme Lending. Is this a good time to talk about your EMI?\"}, {\"user\": \"Yes, go ahead.\"}]", "platform_analysis": { "summary": "Priya confirmed she will pay the EMI on 5 October.", "key_points": [ "EMI due on 5 October", "Customer will pay on time" ], "action_items": [], "classification": "promise_to_pay", "sentiment": "positive", "sentiment_reason": "The customer was cooperative.", "callback_requested": false, "callback_requested_time": null, "callback_requested_via_human_agent": false, "call_disconnect_reason": "agent_hangup", "timezone": "Asia/Kolkata" }, "client_analysis": { "emi_payment_date": "2026-10-05", "payment_intent": "will_pay" } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "404": { "description": "Not Found - The call does not exist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Call not found" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/campaign/all": { "get": { "tags": [ "campaign" ], "summary": "Get All Campaigns", "x-mint": { "metadata": { "og:title": "Get All Campaigns | Ringg AI" } }, "description": "Retrieves the campaigns in the workspace, newest first, with paging. Lists that are not campaigns, such as contact lists, are also returned, with `campaign_status` `null`. A campaign in `insufficient_balance` that the balance now covers is moved back to `draft` when it is listed.", "operationId": "getAllCampaigns", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "limit", "in": "query", "description": "Maximum number of campaigns to return (default: 10).", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "offset", "in": "query", "description": "Number of campaigns to skip for pagination (default: 0).", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of campaigns retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign unique identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Campaign name", "example": "Q4 Sales Campaign" }, "campaign_status": { "type": "string", "nullable": true, "description": "`verifying`: the uploaded list is being checked. `draft`: checked, calls not started. `insufficient_balance`: the balance does not cover the list. `no_valid_contacts`: every row was invalid. `preparing`: launched, calls are being created. `scheduled`: waiting for the start time. `ongoing`: calls are being placed. `completed`: finished. `terminated`: stopped with Terminate calls. `failed`: the list or the launch failed. `processing`: a workflow campaign being prepared. `null`: a list that is not a campaign.", "enum": [ "verifying", "draft", "insufficient_balance", "no_valid_contacts", "preparing", "processing", "scheduled", "ongoing", "completed", "terminated", "failed" ], "example": "completed" }, "created_at": { "type": "string", "format": "date-time", "description": "Campaign creation timestamp", "example": "2024-01-15T14:30:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Campaign last update timestamp", "example": "2024-01-15T16:45:00Z" }, "campaign_start_time": { "type": "string", "format": "date-time", "description": "Scheduled start time for the campaign", "example": "2024-01-16T09:00:00Z" }, "campaign_end_time": { "type": "string", "format": "date-time", "description": "Scheduled end time for the campaign", "example": "2024-01-16T17:00:00Z" }, "agent_id": { "type": "string", "description": "Agent the campaign calls with", "example": "00000000-0000-4000-8000-0000000000a1" }, "total_calls": { "type": "integer", "description": "Number of valid contacts loaded from the list, not calls placed. `0` until the list has been checked.", "example": 150 }, "invalidated_rows_count": { "type": "integer", "description": "Rows dropped as invalid", "example": 2 }, "additional_balance_required": { "type": "string", "description": "Only on `insufficient_balance` rows: the extra balance needed, as a decimal string.", "example": "1250.00" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of campaigns available", "example": 25 }, "limit": { "type": "integer", "description": "Number of campaigns requested per page", "example": 10 }, "offset": { "type": "integer", "description": "Number of campaigns skipped", "example": 0 } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/campaign/start": { "post": { "tags": [ "campaign" ], "summary": "Start Campaign", "x-mint": { "metadata": { "og:title": "Start Campaign | Ringg AI" } }, "description": "Initiates a new campaign with the specified configuration.", "operationId": "startCampaign", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "list_id", "from_numbers" ], "properties": { "agent_id": { "type": "string", "description": "(Required) ID of the agent that will handle the calls.", "example": "00000000-0000-4000-8000-0000000000a1" }, "list_id": { "type": "string", "description": "(Required) ID of the uploaded campaign contact list.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "from_numbers": { "type": "array", "description": "(Required) Caller numbers, as workspace number IDs from List workspace numbers (recommended) or as numbers written exactly as listed there. Each retry dials the next number in the list. A number not in the workspace returns 400.", "items": { "type": "string" }, "example": [ "+1234567890", "+14155550123" ] } }, "example": { "agent_id": "00000000-0000-4000-8000-0000000000a1", "list_id": "123e4567-e89b-12d3-a456-426614174000", "from_numbers": [ "+1234567890" ] } } } } }, "responses": { "200": { "description": "Campaign started successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Success message indicating campaign registration", "example": "campaign registered successfully!" }, "has_ongoing_calls": { "type": "boolean", "description": "Whether the workspace has other ongoing calls", "example": false } }, "example": { "status": "campaign registered successfully!", "has_ongoing_calls": false } } } } }, "400": { "description": "Bad Request - Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid agent_id." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "402": { "description": "Payment Required - The balance (or available credit limit) does not cover the campaign.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "your current balance is insufficient to complete this action" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/campaign/v2/start": { "post": { "tags": [ "campaign" ], "summary": "Start Campaign (Number Pool)", "x-mint": { "metadata": { "og:title": "Start Campaign (Number Pool) | Ringg AI" } }, "description": "Initiates a new campaign using a number pool for outbound calls. Ringg picks caller numbers from the pool, rotating numbers and skipping ones flagged as spam.", "operationId": "startCampaignV2", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "list_id", "number_pool_id" ], "properties": { "agent_id": { "type": "string", "description": "(Required) ID of the agent that will handle the calls.", "example": "00000000-0000-4000-8000-0000000000a1" }, "list_id": { "type": "string", "description": "(Required) ID of the uploaded campaign contact list.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "number_pool_id": { "type": "string", "description": "(Required) ID of the managed number pool to use for outbound calls.", "example": "00000000-0000-4000-8000-0000000000b1" }, "email_completion_user_ids": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "User IDs to notify by email when the campaign completes." } }, "example": { "agent_id": "00000000-0000-4000-8000-0000000000a1", "list_id": "123e4567-e89b-12d3-a456-426614174000", "number_pool_id": "00000000-0000-4000-8000-0000000000b1" } } } } }, "responses": { "200": { "description": "Campaign started successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Success message indicating campaign registration.", "example": "campaign registered successfully!" }, "has_ongoing_calls": { "type": "boolean", "description": "Whether the workspace has other ongoing calls.", "example": false } }, "example": { "status": "campaign registered successfully!", "has_ongoing_calls": false } } } } }, "400": { "description": "Bad Request - Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Number pool not found." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "402": { "description": "Payment Required - The balance (or available credit limit) does not cover the campaign.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "your current balance is insufficient to complete this action" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/campaign/save": { "post": { "tags": [ "campaign" ], "summary": "Upload Campaign Contact List", "x-mint": { "metadata": { "og:title": "Upload Campaign Contact List | Ringg AI" } }, "description": "Uploads a contact list for a campaign. Accepts a CSV file and campaign configuration as form data.", "operationId": "uploadCampaignContactList", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "variables_map", "agent_id", "call_config", "country_code", "campaign_start_time", "campaign_end_time", "campaign_name", "file" ], "properties": { "variables_map": { "type": "string", "description": "(Required) JSON string mapping variable names to columns", "example": { "callee_name": "Name", "company_name": "Company" } }, "agent_id": { "type": "string", "description": "(Required) Unique identifier for the agent", "example": "00000000-0000-4000-8000-0000000000a1" }, "call_config": { "type": "string", "description": "(Required) JSON string of call configuration", "example": { "idle_timeout_warning": 10, "max_call_length": 300 } }, "country_code": { "type": "string", "description": "(Required) Phone number country code (e.g., +91 for India, +1 for US)", "example": "+91" }, "campaign_start_time": { "type": "string", "description": "(Required) Start time for the campaign (DD/MM/YYYY, HH:MM format)", "example": "18/10/2025, 09:00" }, "campaign_end_time": { "type": "string", "description": "(Required) End time for the campaign (DD/MM/YYYY, HH:MM format)", "example": "18/10/2025, 21:05" }, "campaign_name": { "type": "string", "description": "(Required) Name of the campaign.", "example": "Q1 Sales Campaign" }, "file": { "type": "string", "format": "binary", "description": "(Required) CSV file containing the contact list.", "example": "contacts.csv" }, "remove_invalid_rows": { "type": "boolean", "description": "(Optional) When true, invalid rows are left out. When false, any invalid row fails the whole upload with 400 and the uploader is emailed the errors.", "default": false, "example": false }, "transliterate_callee_name": { "type": "boolean", "description": "(Optional) Transliterate `callee_name` into the agent's language. Same as adding `callee_name` to `transliterate_fields`. A row whose name cannot be transliterated is dropped as invalid.", "default": false, "example": false }, "transliterate_fields": { "type": "string", "description": "(Optional) JSON string array of the agent's own variable names (not CSV headers) whose values are transliterated into the agent's language, for example [\"callee_name\"]. Each must be mapped in `variables_map`; `mobile_number` is refused with 400. The original value stays available as `original_`. Combined with `transliterate_callee_name` when both are sent.", "example": "[\"callee_name\"]" } } } } } }, "responses": { "200": { "description": "Contact list uploaded and campaign saved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Contacts imported successfully!" }, "list_id": { "type": "string", "description": "ID of the created campaign list", "example": "123e4567-e89b-12d3-a456-426614174000" }, "custom_args_values": { "type": "array", "description": "Array of custom variables for each contact", "items": { "type": "object" }, "example": [ { "callee_name": "John Doe", "company_name": "XYZ Corp", "mobile_number": "+1234567890" } ] }, "total_rows": { "type": "integer", "description": "Total number of rows in uploaded CSV", "example": 100 }, "successful_rows": { "type": "integer", "description": "Number of successfully processed rows", "example": 98 }, "failed_rows": { "type": "integer", "description": "Number of rows that failed validation", "example": 2 } } } } } }, "400": { "description": "Bad Request - Invalid input or file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid file format." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "402": { "description": "Payment Required - The list has more rows than the workspace may upload: 100 by default, 5,000 once Company details are saved. Contact Ringg for a higher limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "You can only upload up to 100 contacts." } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/analytics/platform-analytics": { "get": { "tags": [ "analytics" ], "summary": "Get Platform Analytics", "x-mint": { "metadata": { "og:title": "Get Platform Analytics | Ringg AI" } }, "description": "Retrieves workspace-level call metrics and a summary of key numbers.", "operationId": "getPlatformAnalytics", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "start_date", "in": "query", "description": "Start date for analytics filter (YYYY-MM-DD format)", "required": false, "schema": { "type": "string", "example": "2025-09-25" } }, { "name": "end_date", "in": "query", "description": "End date for analytics filter (YYYY-MM-DD format)", "required": false, "schema": { "type": "string", "example": "2025-09-25" } }, { "name": "agent_id", "in": "query", "description": "Filter by specific agent ID", "required": false, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "bulk_list_id", "in": "query", "description": "Filter by specific bulk list/campaign ID", "required": false, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "voicemail", "in": "query", "description": "Filter by voicemail status", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Platform analytics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "performance_metrics": { "type": "object", "description": "Performance metrics by different categories" }, "metrics_summary": { "type": "object", "description": "Summary of key metrics" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/analytics/drill-down-analytics": { "get": { "tags": [ "analytics" ], "summary": "Get Drill-Down Analytics", "x-mint": { "metadata": { "og:title": "Get Drill-Down Analytics | Ringg AI" } }, "description": "Retrieves detailed analytics for a specific bulk list/campaign with drill-down capabilities.", "operationId": "getDrillDownAnalytics", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "bulk_list_id", "in": "query", "description": "(Required) Bulk list/campaign ID to get drill-down analytics for", "required": true, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "start_date", "in": "query", "description": "Start date for analytics filter (YYYY-MM-DD format)", "required": false, "schema": { "type": "string", "example": "2025-09-25" } }, { "name": "end_date", "in": "query", "description": "End date for analytics filter (YYYY-MM-DD format)", "required": false, "schema": { "type": "string", "example": "2025-09-25" } }, { "name": "agent_id", "in": "query", "description": "Filter by specific agent ID", "required": false, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "voicemail", "in": "query", "description": "Filter by voicemail status", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Drill-down analytics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "performance_metrics": { "type": "object", "description": "Detailed performance metrics for the bulk list" }, "cached": { "type": "boolean", "description": "Whether the response was served from cache" } } } } } }, "400": { "description": "Bad Request - Missing required bulk_list_id parameter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/analytics/number-analytics": { "get": { "tags": [ "analytics" ], "summary": "Get Number Analytics", "x-mint": { "metadata": { "og:title": "Get Number Analytics | Ringg AI" } }, "description": "Retrieves analytics broken down by phone numbers.", "operationId": "getNumberAnalytics", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "start_date", "in": "query", "description": "Start date for analytics filter (YYYY-MM-DD format)", "required": false, "schema": { "type": "string", "example": "2025-09-25" } }, { "name": "end_date", "in": "query", "description": "End date for analytics filter (YYYY-MM-DD format)", "required": false, "schema": { "type": "string", "example": "2025-09-25" } }, { "name": "agent_id", "in": "query", "description": "Filter by specific agent ID", "required": false, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "bulk_list_id", "in": "query", "description": "Filter by specific bulk list/campaign ID", "required": false, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "voicemail", "in": "query", "description": "Filter by voicemail status", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Number analytics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "number_analytics": { "type": "array", "description": "Analytics data grouped by phone numbers" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/analytics/duration-distribution": { "get": { "tags": [ "analytics" ], "summary": "Get Duration Distribution", "x-mint": { "metadata": { "og:title": "Get Duration Distribution | Ringg AI" } }, "description": "Retrieves call duration distribution analytics.", "operationId": "getDurationDistribution", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "start_date", "in": "query", "description": "Start date for analytics filter (YYYY-MM-DD format)", "required": false, "schema": { "type": "string", "example": "2025-09-25" } }, { "name": "end_date", "in": "query", "description": "End date for analytics filter (YYYY-MM-DD format)", "required": false, "schema": { "type": "string", "example": "2025-09-25" } }, { "name": "agent_id", "in": "query", "description": "Filter by specific agent ID", "required": false, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "bulk_list_id", "in": "query", "description": "Filter by specific bulk list/campaign ID", "required": false, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "voicemail", "in": "query", "description": "Filter by voicemail status", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Duration distribution retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "duration_distribution": { "type": "object", "description": "Call duration distribution data" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/analytics/classification-analytics": { "get": { "tags": [ "analytics" ], "summary": "Get Classification Analytics", "x-mint": { "metadata": { "og:title": "Get Classification Analytics | Ringg AI" } }, "description": "Retrieves call classification analytics data.", "operationId": "getClassificationAnalytics", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "start_date", "in": "query", "description": "Start date for analytics filter (YYYY-MM-DD format)", "required": false, "schema": { "type": "string", "example": "2025-09-25" } }, { "name": "end_date", "in": "query", "description": "End date for analytics filter (YYYY-MM-DD format)", "required": false, "schema": { "type": "string", "example": "2025-09-25" } }, { "name": "agent_id", "in": "query", "description": "Filter by specific agent ID", "required": false, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "bulk_list_id", "in": "query", "description": "Filter by specific bulk list/campaign ID", "required": false, "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } }, { "name": "voicemail", "in": "query", "description": "Filter by voicemail status", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "Classification analytics retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "classification_analytics": { "type": "object", "description": "Call classification analytics data" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "500": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "An unexpected error occurred. Please try again later." } } } } } } } } }, "/campaign/terminate": { "patch": { "tags": [ "termination" ], "summary": "Terminate Calls", "x-mint": { "metadata": { "og:title": "Terminate Calls | Ringg AI" } }, "description": "Cancels queued (`registered`) and `retry` calls, by agent ID, call IDs, campaign ID, campaign plus mobile numbers, or mobile numbers. A call already in progress is not hung up: it ends normally and is not retried. Only calls created in the last 7 days are cancelled; agent, call ID and campaign modes apply to outbound calls.", "operationId": "terminateCalls", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "ID of the agent whose calls should be terminated", "example": "00000000-0000-4000-8000-000000000110" }, "call_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of call IDs to terminate", "example": [ "00000000-0000-4000-8000-000000000116", "00000000-0000-4000-8000-00000000010d" ] }, "campaign_id": { "type": "string", "description": "ID of the campaign whose calls should be terminated", "example": "00000000-0000-4000-8000-000000000103" }, "mobile_numbers": { "type": "array", "items": { "type": "string" }, "description": "Array of mobile numbers to terminate calls for (max 100)", "example": [ "+919876543210", "+919876543211" ] } } } } } }, "responses": { "200": { "description": "Request accepted. Agent, call ID and campaign modes return 200 even when no call matched.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Calls terminated successfully!" } } } } } }, "400": { "description": "Bad Request - In the mobile-number modes, a number has no call or no call that can be terminated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Mobile numbers not found in campaign: +919876543299" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "422": { "description": "Validation Error - No field sent, more than one mode at once, or more than 100 mobile numbers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/external/kb": { "post": { "tags": [ "knowledgebase" ], "summary": "Create Knowledge Base", "x-mint": { "metadata": { "title": "Create Knowledge Base | Ringg AI", "og:title": "Create Knowledge Base | Ringg AI" } }, "description": "Creates a new non-deterministic knowledge base. Rate limit: 10 requests per hour per workspace. File size limit: 2 MB per file, 5 MB total. Maximum 10 files and 20 URLs per request. Files are read by extension: PDF, DOCX, TXT, CSV (one entry per row) and JSON; any other extension is read as plain text. Knowledge bases created with the API are not listed on the dashboard's Knowledge Base page, but can be attached to agents.", "operationId": "createKnowledgeBase", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "kb_name" ], "properties": { "kb_name": { "type": "string", "description": "(Required) Name of the knowledge base", "example": "Product Documentation" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "(Optional) Files to upload (max 10 files, 2 MB each, 5 MB total). PDF, DOCX, TXT, CSV and JSON are parsed; other files are read as plain text." }, "urls": { "type": "string", "description": "(Optional) JSON string array of URLs to index (max 20 URLs)", "example": "[\"https://example.com/docs\", \"https://example.com/faq\"]" }, "faqs": { "type": "string", "description": "(Optional) JSON string array of FAQ objects", "example": "[{\"question\": \"What is your return policy?\", \"answer\": \"30-day money back guarantee\"}]" } } } } } }, "responses": { "200": { "description": "Knowledge base created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Knowledge Base creation initiated" }, "kb_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "processing_status": { "type": "string", "example": "pending" }, "files_queued": { "type": "integer", "example": 3 } } } } } }, "400": { "description": "Bad Request - Invalid parameters or file size exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "429": { "description": "Rate limit exceeded - Maximum 10 requests per hour." } } }, "patch": { "tags": [ "knowledgebase" ], "summary": "Edit Knowledge Base", "x-mint": { "metadata": { "title": "Edit Knowledge Base | Ringg AI", "og:title": "Edit Knowledge Base | Ringg AI" } }, "description": "Edits an existing knowledge base by adding or removing files, URLs, and FAQs. Rate limit: 20 requests per hour per workspace. File size limit: 2 MB per file, 5 MB total.", "operationId": "editKnowledgeBase", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "kb_id" ], "properties": { "kb_id": { "type": "string", "description": "(Required) ID of the knowledge base to edit", "example": "550e8400-e29b-41d4-a716-446655440000" }, "files_to_remove": { "type": "string", "description": "(Optional) JSON string array of file IDs to remove", "example": "[\"7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d\", \"8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e\"]" }, "urls_to_remove": { "type": "string", "description": "(Optional) JSON string array of URLs to remove", "example": "[\"https://example.com/old-page\"]" }, "faqs_to_remove": { "type": "string", "description": "(Optional) JSON string array of FAQ IDs to remove", "example": "[\"9c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f\", \"0d1e2f3a-4b5c-6d7e-8f9a-0b1c2d3e4f5a\"]" }, "new_files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "(Optional) Array of new files to upload" }, "new_urls": { "type": "string", "description": "(Optional) JSON string array of new URLs to add", "example": "[\"https://example.com/new-docs\"]" }, "new_faqs": { "type": "string", "description": "(Optional) JSON string array of new FAQ objects", "example": "[{\"question\": \"Do you ship internationally?\", \"answer\": \"Yes, worldwide shipping available\"}]" }, "new_files_metadata": { "type": "string", "description": "(Optional) JSON string object with metadata for new files", "example": "{}" } } } } } }, "responses": { "200": { "description": "Knowledge base updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Knowledge Base edit initiated" }, "kb_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "items_removed": { "type": "integer", "example": 2 }, "new_files_queued": { "type": "integer", "example": 1 }, "new_files": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "example": "document.pdf" }, "file_id": { "type": "string", "example": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b" }, "processing_status": { "type": "string", "example": "pending" } } } } } } } } }, "400": { "description": "Bad Request - Invalid parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "429": { "description": "Rate limit exceeded - Maximum 20 requests per hour." } } } }, "/external/kb/{kb_id}": { "get": { "tags": [ "knowledgebase" ], "summary": "Get Knowledge Base by ID", "x-mint": { "metadata": { "title": "Get Knowledge Base | Ringg AI", "og:title": "Get Knowledge Base | Ringg AI" } }, "description": "Retrieves a specific knowledge base by its ID. Rate limit: 60 requests per hour per workspace.", "operationId": "getKnowledgeBaseById", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "kb_id", "in": "path", "description": "(Required) ID of the knowledge base", "required": true, "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Knowledge base details retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "kb_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "kb_name": { "type": "string", "example": "Product Documentation" }, "status": { "type": "string", "description": "Processing status of the knowledge base", "example": "completed" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-12-16T13:03:29.947147+00:00" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-12-16T14:15:32.123456+00:00" }, "files": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string" }, "file_type": { "type": "string" }, "file_size": { "type": "number" }, "filename": { "type": "string" }, "file_path": { "type": "string" } } } }, "urls": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string" }, "file_type": { "type": "string" }, "file_size": { "type": "number" }, "url": { "type": "string" }, "file_path": { "type": "string" } } } }, "faqs": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string" }, "file_type": { "type": "string" }, "file_size": { "type": "number" }, "content": { "type": "object" } } } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "429": { "description": "Rate limit exceeded - Maximum 60 requests per hour." } } }, "delete": { "tags": [ "knowledgebase" ], "summary": "Delete Knowledge Base", "x-mint": { "metadata": { "title": "Delete Knowledge Base | Ringg AI", "og:title": "Delete Knowledge Base | Ringg AI" } }, "description": "Deletes a knowledge base by its ID. Rate limit: 10 requests per minute per workspace.", "operationId": "deleteKnowledgeBase", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "kb_id", "in": "path", "description": "(Required) ID of the knowledge base to delete", "required": true, "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Knowledge base deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Knowledge Base deleted successfully" }, "kb_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "429": { "description": "Rate limit exceeded - Maximum 10 requests per minute." } } } }, "/external/kb/all": { "get": { "tags": [ "knowledgebase" ], "summary": "Get All Knowledge Bases", "x-mint": { "metadata": { "title": "Get All Knowledge Bases | Ringg AI", "og:title": "Get All Knowledge Bases | Ringg AI" } }, "description": "Retrieves all knowledge bases for the current workspace. Rate limit: 60 requests per hour per workspace.", "operationId": "getAllKnowledgeBases", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "responses": { "200": { "description": "List of all knowledge bases retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "kb_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "kb_name": { "type": "string", "example": "Product Documentation" }, "type": { "type": "string", "example": "non_deterministic" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-12-16T13:03:29.947147+00:00" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "429": { "description": "Rate limit exceeded - Maximum 60 requests per hour." } } } }, "/public/agent": { "post": { "tags": [ "agent" ], "summary": "Create Agent", "x-mint": { "metadata": { "title": "Create Agent | Ringg AI", "og:title": "Create Agent | Ringg AI" } }, "description": "Creates a new AI agent with the specified configuration. The agent will be created with a single prompt-based flow.", "operationId": "createAgent", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_name", "introduction_and_objective", "response_guidelines", "task", "primary_language", "voice_id", "intro_message" ], "properties": { "agent_name": { "type": "string", "maxLength": 100, "description": "(Required) Name of the agent", "example": "My Sales Agent" }, "introduction_and_objective": { "type": "string", "maxLength": 2000, "description": "(Required) Introduction and objective of the agent", "example": "You are a customer support agent for Acme Corp." }, "response_guidelines": { "type": "string", "maxLength": 3000, "description": "(Required) Guidelines for how the agent should respond", "example": "Be polite, helpful, and concise. Always confirm understanding." }, "task": { "type": "string", "maxLength": 1500, "description": "(Required) The task the agent should perform", "example": "Help customers with their orders and answer product questions." }, "faq": { "type": "string", "maxLength": 5000, "description": "(Optional) FAQ content for the agent", "example": "Q: What are your hours? A: We are open 9am-6pm IST." }, "sample_conversations": { "type": "string", "maxLength": 5000, "description": "(Optional) Example conversations for the agent. Use \\n for newlines between turns.", "example": "User: Hi\nAgent: Hello! How can I help you today?" }, "primary_language": { "type": "string", "enum": [ "en-US", "en-GB", "en-AU", "en-IN", "hi-IN", "ta-IN", "te-IN", "bn-IN", "mr-IN", "kn-IN", "ms-MY", "zh-CN", "od-IN", "pa-IN", "my-MM" ], "description": "(Required) Primary language locale for the agent", "example": "en-IN" }, "secondary_language": { "type": "string", "enum": [ "en-US", "en-GB", "en-AU", "en-IN", "hi-IN", "ta-IN", "te-IN", "bn-IN", "mr-IN", "kn-IN", "ms-MY", "zh-CN", "od-IN", "pa-IN", "my-MM" ], "description": "(Optional) Secondary language locale for the agent", "example": "hi-IN" }, "voice_id": { "type": "string", "format": "uuid", "description": "(Required) Voice ID (UUID). Get available voices from the List Voices endpoint.", "example": "00000000-0000-4000-8000-00000000010e" }, "intro_message": { "type": "string", "maxLength": 500, "description": "(Required) Introduction message the agent will speak when the call starts", "example": "Hello, this is Sarah from Acme Corp. How can I assist you today?" }, "agent_type": { "type": "string", "enum": [ "inbound", "outbound", "outbound_inbound" ], "default": "outbound", "description": "(Required) Type of agent. Defaults to outbound.", "example": "outbound" }, "custom_variables": { "type": "array", "items": { "type": "string" }, "description": "(Optional) Custom variables for the agent. For outbound agents, callee_name and mobile_number are always included automatically.", "example": [ "callee_name", "mobile_number", "company", "lead_source" ] }, "call_config": { "type": "object", "description": "(Optional) Call behaviour for the agent. Every field is optional — omit the block, or any key in it, to accept the default. These are the same keys the settings are stored under, so what you send here is what the agent runs with.", "properties": { "call_time": { "type": "object", "description": "Daily window the agent may place calls in. Outside it an outbound call is not dialled immediately, and retries are pushed to the next opening. Applies to the agent's own calls; a campaign or an individual call can override it.", "properties": { "call_start_time": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Earliest local time the agent may dial, 'HH:MM' 24-hour (default: 09:00).", "default": "09:00", "example": "10:00" }, "call_end_time": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Latest local time the agent may dial, 'HH:MM' 24-hour. The window may cross midnight (e.g. 22:00-06:00) (default: 21:00).", "default": "21:00", "example": "18:30" }, "timezone": { "type": "string", "description": "IANA timezone the window is expressed in. **Any IANA zone is supported**, not just India - e.g. America/New_York, Europe/London, Asia/Dubai, Asia/Riyadh, Australia/Sydney, UTC. Always use the full Region/City form: 'IST'/'PST' are rejected outright, while 'EST'/'MST'/'GMT' are accepted but are fixed-offset zones that never observe daylight saving (an agent on 'EST' runs an hour behind New York for most of the year) (default: Asia/Kolkata).", "default": "Asia/Kolkata", "example": "America/New_York" } }, "example": { "call_start_time": "10:00", "call_end_time": "18:30", "timezone": "America/New_York" } }, "max_call_length": { "type": "integer", "minimum": 10, "maximum": 3600, "description": "Hard cap on call duration in seconds (default: 240).", "default": 240, "example": 600 }, "idle_timeout_warning": { "type": "integer", "minimum": 0, "maximum": 600, "description": "Seconds of caller silence before the agent checks in (“Are you still there?”). Must be less than idle_timeout_end; use 0 to disable the check-in (default: 5).", "default": 5, "example": 8 }, "idle_timeout_end": { "type": "integer", "minimum": 1, "maximum": 600, "description": "Seconds of caller silence before the call is dropped. Must be greater than idle_timeout_warning (default: 10).", "default": 10, "example": 20 }, "noise_filter_config": { "type": "object", "description": "Background-noise cancellation applied to the caller's audio.", "properties": { "filter_noise": { "type": "boolean", "description": "Turn noise cancellation on (default: false).", "default": false, "example": true }, "noise_suppression_level": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Suppression strength, 0-100 (default: 80).", "default": 80, "example": 95 } }, "example": { "filter_noise": true, "noise_suppression_level": 95 } }, "voicemail": { "type": "object", "description": "Voicemail / answering-machine handling.", "properties": { "detect": { "type": "boolean", "description": "Detect that the call reached a voicemail (default: true).", "default": true, "example": true }, "action": { "type": "string", "enum": [ "end", "summarise", "static_message" ], "description": "What the agent does once it detects a voicemail: hang up, leave a generated summary, or speak static_message (default: end).", "default": "end", "example": "end" }, "retry": { "type": "boolean", "description": "Re-queue the call for a later attempt after hitting voicemail (default: true).", "default": true, "example": true }, "static_message": { "type": "string", "nullable": true, "description": "Spoken verbatim when action is static_message. Ignored otherwise.", "example": "Sorry we missed you, please call us back." } }, "example": { "detect": true, "action": "end", "retry": true } }, "background_audio_config": { "type": "object", "description": "Ambient audio mixed under the agent's speech. Omit the whole object to keep background audio off.", "properties": { "audio_id": { "type": "string", "enum": [ "office_ambience" ], "description": "(Required within this object) Track to play. office_ambience is the only track available.", "example": "office_ambience" }, "volume": { "type": "number", "minimum": 0, "maximum": 1, "description": "Playback level as a fraction between 0.0 and 1.0 — not a percentage (default: 0.5).", "default": 0.5, "example": 0.35 }, "mixing": { "type": "boolean", "description": "Mix the track under the agent's speech (default: true).", "default": true, "example": true }, "loop": { "type": "boolean", "description": "Repeat the track for the whole call (default: true).", "default": true, "example": true } }, "example": { "audio_id": "office_ambience", "volume": 0.35 } }, "mute_during_intro": { "type": "boolean", "description": "When true the caller cannot interrupt the intro message — the agent finishes speaking it before it starts listening. Set false to make the first message interruptible (default: true).", "default": true, "example": false } }, "example": { "call_time": { "call_start_time": "10:00", "call_end_time": "18:30", "timezone": "America/New_York" }, "max_call_length": 600, "idle_timeout_warning": 8, "idle_timeout_end": 20, "noise_filter_config": { "filter_noise": true, "noise_suppression_level": 95 }, "voicemail": { "detect": true, "action": "end", "retry": true }, "background_audio_config": { "audio_id": "office_ambience", "volume": 0.35 }, "mute_during_intro": false } } } } } } }, "responses": { "200": { "description": "Agent created successfully. Returns the agent id and the version_id of the version that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique ID of the created agent", "example": "00000000-0000-4000-8000-000000000104" }, "version": { "type": "string", "description": "The version slug of the agent", "example": "v1" }, "version_id": { "type": "string", "description": "ID of the version created for this agent. Pass this to the version-scoped APIs.", "example": "00000000-0000-4000-8000-000000000105" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-12-16T13:03:29.947147+00:00" } } }, "message": { "type": "string", "example": "Agent created successfully" } } } } } }, "400": { "description": "Bad Request - Invalid parameters or voice does not support the selected language.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Voice does not support language 'en-US'" }, "code": { "type": "string", "enum": [ "AGENT_NOT_FOUND", "VERSION_NOT_FOUND", "NO_ACTIVE_VERSION", "INVALID_VOICE", "VOICE_LANGUAGE_MISMATCH", "INVALID_CUSTOM_VARIABLES", "INTERNAL_ERROR" ], "example": "VOICE_LANGUAGE_MISMATCH" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "422": { "description": "Validation Error - A field is missing, too long, or not one of the allowed values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/public/agent/{agent_id}": { "patch": { "tags": [ "agent" ], "summary": "Update Agent", "x-mint": { "metadata": { "title": "Update Agent | Ringg AI", "og:title": "Update Agent | Ringg AI" } }, "description": "Updates an existing agent with new configuration. Only provide the fields you want to update.", "operationId": "updateAgent", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "agent_id", "in": "path", "description": "(Required) The unique ID of the agent to update", "required": true, "schema": { "type": "string", "format": "uuid", "example": "00000000-0000-4000-8000-000000000104" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_name": { "type": "string", "maxLength": 100, "description": "(Optional) Name of the agent", "example": "My Updated Agent" }, "introduction_and_objective": { "type": "string", "maxLength": 2000, "description": "(Optional) Introduction and objective of the agent", "example": "You are a customer support agent for Acme Corp." }, "response_guidelines": { "type": "string", "maxLength": 3000, "description": "(Optional) Guidelines for how the agent should respond", "example": "Be polite, helpful, and concise. Always confirm understanding." }, "task": { "type": "string", "maxLength": 1500, "description": "(Optional) The task the agent should perform", "example": "Help customers with their orders and answer product questions." }, "faq": { "type": "string", "maxLength": 5000, "description": "(Optional) FAQ content for the agent", "example": "Q: What are your hours? A: We are open 9am-6pm IST." }, "sample_conversations": { "type": "string", "maxLength": 5000, "description": "(Optional) Example conversations for the agent. Use \\n for newlines between turns.", "example": "User: Hi\nAgent: Hello! How can I help you today?" }, "primary_language": { "type": "string", "enum": [ "en-US", "en-GB", "en-AU", "en-IN", "hi-IN", "ta-IN", "te-IN", "bn-IN", "mr-IN", "kn-IN", "ms-MY", "zh-CN", "od-IN", "pa-IN", "my-MM" ], "description": "(Optional) Primary language locale for the agent", "example": "en-IN" }, "secondary_language": { "type": "string", "enum": [ "en-US", "en-GB", "en-AU", "en-IN", "hi-IN", "ta-IN", "te-IN", "bn-IN", "mr-IN", "kn-IN", "ms-MY", "zh-CN", "od-IN", "pa-IN", "my-MM" ], "description": "(Optional) Secondary language locale for the agent", "example": "hi-IN" }, "voice_id": { "type": "string", "format": "uuid", "description": "(Optional) Voice ID (UUID). Get available voices from the List Voices endpoint.", "example": "00000000-0000-4000-8000-00000000010e" }, "intro_message": { "type": "string", "maxLength": 500, "description": "(Optional) Introduction message the agent will speak when the call starts", "example": "Hello, this is Sarah from Acme Corp. How can I assist you today?" }, "agent_type": { "type": "string", "enum": [ "inbound", "outbound", "outbound_inbound" ], "description": "(Optional) Type of agent", "example": "outbound" }, "custom_variables": { "type": "array", "items": { "type": "string" }, "description": "(Optional) Custom variables for the agent. For outbound agents, callee_name and mobile_number cannot be removed.", "example": [ "callee_name", "mobile_number", "company", "lead_source" ] } } } } } }, "responses": { "200": { "description": "Agent updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique ID of the updated agent", "example": "00000000-0000-4000-8000-000000000104" }, "version": { "type": "string", "description": "The version slug of the agent", "example": "v1" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-12-16T14:15:32.123456+00:00" } } }, "message": { "type": "string", "example": "Agent updated successfully" } } } } } }, "400": { "description": "Bad Request - Invalid parameters or voice does not support the selected language.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Voice does not support language 'en-US'" }, "code": { "type": "string", "enum": [ "AGENT_NOT_FOUND", "VERSION_NOT_FOUND", "NO_ACTIVE_VERSION", "INVALID_VOICE", "VOICE_LANGUAGE_MISMATCH", "INVALID_CUSTOM_VARIABLES", "INTERNAL_ERROR" ], "example": "VOICE_LANGUAGE_MISMATCH" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "404": { "description": "Agent not found or does not belong to your workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "422": { "description": "Validation Error - A field is missing, too long, or not one of the allowed values.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/campaign/upload-csv": { "post": { "tags": [ "campaign" ], "summary": "Upload Campaign CSV (Beta)", "x-mint": { "metadata": { "og:title": "Upload Campaign CSV Beta | Ringg AI" } }, "description": "Beta endpoint. Uploads a campaign list and checks it in the background, creating a draft bulk list. Works for lists of any size up to the workspace's row limit.", "operationId": "uploadCampaignCsvBeta", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "variables_map", "agent_id", "country_code", "campaign_name", "file" ], "properties": { "variables_map": { "type": "string", "description": "(Required) JSON string mapping agent variable names to CSV columns.", "example": "{\"mobile_number\":\"Mobile Number\",\"callee_name\":\"Name\"}" }, "agent_id": { "type": "string", "description": "(Required) Agent ID used to validate campaign variables.", "example": "00000000-0000-4000-8000-0000000000a1" }, "country_code": { "type": "string", "description": "(Required) Phone number country code, for example +91 or +1.", "example": "+91" }, "campaign_name": { "type": "string", "description": "(Required) Name of the campaign draft.", "example": "Renewal reminders - large upload" }, "file": { "type": "string", "format": "binary", "description": "(Required) CSV file containing campaign contacts." }, "remove_invalid_rows": { "type": "boolean", "description": "(Optional) Invalid rows never fail this upload: valid rows load and invalid rows are left out. When false, the uploader is emailed the invalid rows; true skips that email.", "default": false, "example": true }, "transliterate_callee_name": { "type": "boolean", "description": "(Optional) Transliterate `callee_name` into the agent's language. Same as adding `callee_name` to `transliterate_fields`. A row whose name cannot be transliterated is dropped as invalid.", "default": false, "example": false }, "transliterate_fields": { "type": "string", "description": "(Optional) JSON string array of the agent's own variable names (not CSV headers) whose values are transliterated into the agent's language, for example [\"callee_name\"]. Each must be mapped in `variables_map`; `mobile_number` is refused with 400. The original value stays available as `original_`. Combined with `transliterate_callee_name` when both are sent.", "example": "[\"callee_name\"]" } } } } } }, "responses": { "200": { "description": "CSV accepted. The list is checked in the background; poll Get Campaign Upload Status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "CSV uploaded successfully. Processing in background." }, "bulk_list_id": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "status": { "type": "string", "example": "verifying" }, "total_rows": { "type": "integer", "description": "Rows in the file, not counting fully blank rows.", "example": 5000 }, "campaign_name": { "type": "string", "example": "Renewal reminders - large upload" } }, "example": { "message": "CSV uploaded successfully. Processing in background.", "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000", "status": "verifying", "total_rows": 5000, "campaign_name": "Renewal reminders - large upload" } } } } }, "400": { "description": "Bad Request - Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid CSV file or variable mapping." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "402": { "description": "Payment Required - The list has more rows than the workspace may upload: 100 by default, 5,000 once Company details are saved. Contact Ringg for a higher limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "You can only upload up to 100 contacts." } } } } } } } } }, "/campaign/upload-status/{bulk_list_id}": { "get": { "tags": [ "campaign" ], "summary": "Get Campaign Upload Status (Beta)", "x-mint": { "metadata": { "og:title": "Get Campaign Upload Status Beta | Ringg AI" } }, "description": "Beta endpoint for checking asynchronous CSV validation status before starting a large campaign.", "operationId": "getCampaignUploadStatusBeta", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "bulk_list_id", "in": "path", "required": true, "description": "Bulk list ID returned by /campaign/upload-csv.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Upload status returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bulk_list_id": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "status": { "type": "string", "description": "`verifying`: still being checked, keep polling. `draft`: valid and ready to start with /campaign/make-call-async. `no_valid_contacts`: every row was invalid. `insufficient_balance`: add balance, then call /campaign/check-balance/{bulk_list_id}. `failed`: processing failed; upload again. After launch the campaign's own status is returned: `preparing`, `in_db`, `scheduled`, `ongoing`, `completed` or `terminated`.", "enum": [ "verifying", "draft", "no_valid_contacts", "insufficient_balance", "failed", "preparing", "in_db", "scheduled", "ongoing", "completed", "terminated" ], "example": "draft" }, "campaign_name": { "type": "string", "example": "Renewal reminders - large upload" }, "total_callees": { "type": "integer", "description": "Valid contacts loaded", "example": 4988 }, "invalidated_rows_count": { "type": "integer", "description": "Rows dropped as invalid", "example": 12 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "404": { "description": "Not Found - No campaign with this ID in the workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Campaign not found or you don't have access to it." } } } } } } } } }, "/campaign/make-call-async": { "post": { "tags": [ "campaign" ], "summary": "Start Large Campaign Calls (Beta)", "x-mint": { "metadata": { "og:title": "Start Large Campaign Calls Beta | Ringg AI" } }, "description": "Beta endpoint for starting calls from a draft bulk list created by /campaign/upload-csv.", "operationId": "makeCampaignCallAsyncBeta", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bulk_list_id", "agent_id", "country_code", "call_config" ], "properties": { "bulk_list_id": { "type": "string", "description": "Draft bulk list ID returned by /campaign/upload-csv.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "agent_id": { "type": "string", "description": "Agent ID used during upload.", "example": "00000000-0000-4000-8000-0000000000a1" }, "country_code": { "type": "string", "description": "Phone number country code.", "example": "+91" }, "campaign_start_time": { "type": "string", "description": "Campaign start time, `DD/MM/YYYY, HH:MM`, in `call_config.call_time.timezone`. Required unless `call_slots` is sent; send it with `campaign_end_time`.", "example": "18/10/2026, 09:00" }, "campaign_end_time": { "type": "string", "description": "Campaign end time, `DD/MM/YYYY, HH:MM`. Required unless `call_slots` is sent; send it with `campaign_start_time`.", "example": "18/10/2026, 18:00" }, "from_numbers": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Caller numbers, as workspace number IDs from List workspace numbers (recommended) or as numbers written exactly as listed there. Send exactly one of `from_numbers` or `number_pool_id`. A number that is not in the workspace makes the campaign `failed` after launch." }, "number_pool_id": { "type": "string", "nullable": true, "description": "Number pool ID. Ringg picks caller numbers from the pool, rotating numbers and skipping ones flagged as spam. Send exactly one of `from_numbers` or `number_pool_id`.", "example": "00000000-0000-4000-8000-0000000000b1" }, "call_config": { "type": "object", "properties": { "call_retry_config": { "type": "object", "properties": { "retry_count": { "type": "integer", "default": 0, "example": 1 }, "retry_busy": { "type": "integer", "default": 30, "example": 30 }, "retry_not_picked": { "type": "integer", "default": 30, "example": 30 }, "retry_failed": { "type": "integer", "default": 30, "example": 30 } }, "description": "Retries for unanswered, busy and failed calls. Without it the campaign makes no retries." }, "call_time": { "type": "object", "properties": { "call_start_time": { "type": "string", "default": "09:00", "example": "09:00" }, "call_end_time": { "type": "string", "default": "21:00", "example": "18:00" }, "timezone": { "type": "string", "default": "Asia/Kolkata", "example": "Asia/Kolkata" }, "scheduled_at": { "type": "string", "nullable": true, "description": "ISO 8601 datetime for scheduled call (e.g. '2026-10-18T09:00:00'). Uses the timezone above.", "example": null } } } } }, "concurrency_percentage": { "type": "integer", "minimum": 0, "maximum": 100, "default": 0, "example": 25, "description": "This campaign's share, in percent, of the workspace's concurrent calls while several campaigns are ongoing. Campaigns at `0` share what is left equally." }, "email_completion_user_ids": { "type": "array", "items": { "type": "string" }, "nullable": true }, "call_slots": { "description": "(Optional) Exact windows the campaign may dial in, in `call_config.call_time.timezone`. `absolute` lists dated intervals (`DD/MM/YYYY, HH:MM`); `weekly` repeats day-of-week windows (`HH:MM`). Each slot is 1 minute to 24 hours, not in the past, and inside the daily `call_time` window; the last must end at least 5 minutes from now. Without `campaign_start_time`/`campaign_end_time`, the campaign runs from the first slot's start to the last slot's end.", "oneOf": [ { "type": "object", "required": [ "mode", "intervals" ], "properties": { "mode": { "type": "string", "enum": [ "absolute" ] }, "intervals": { "type": "array", "maxItems": 500, "items": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "string", "example": "18/10/2026, 10:00" }, "end": { "type": "string", "example": "18/10/2026, 13:00" } } } } } }, { "type": "object", "required": [ "mode", "until", "windows" ], "properties": { "mode": { "type": "string", "enum": [ "weekly" ] }, "until": { "type": "string", "description": "`DD/MM/YYYY, HH:MM`. Windows repeat from `campaign_start_time` (or now) until this time, at most 90 days.", "example": "31/10/2026, 18:00" }, "windows": { "type": "array", "maxItems": 21, "items": { "type": "object", "required": [ "days", "start", "end" ], "properties": { "days": { "type": "array", "items": { "type": "string", "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ] }, "example": [ "mon", "wed", "fri" ] }, "start": { "type": "string", "example": "10:00" }, "end": { "type": "string", "example": "13:00" } } } } } } ] } }, "description": "Send exactly one of `from_numbers` or `number_pool_id`; both or neither returns 422. `campaign_start_time` and `campaign_end_time` are required unless `call_slots` is sent, and must be sent together." }, "examples": { "number_pool": { "summary": "Caller numbers from a number pool", "value": { "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000", "agent_id": "00000000-0000-4000-8000-0000000000a1", "country_code": "+91", "campaign_start_time": "18/10/2026, 09:00", "campaign_end_time": "18/10/2026, 18:00", "number_pool_id": "00000000-0000-4000-8000-0000000000b1", "call_config": { "call_time": { "call_start_time": "09:00", "call_end_time": "18:00", "timezone": "Asia/Kolkata" }, "call_retry_config": { "retry_count": 1, "retry_busy": 30, "retry_not_picked": 30, "retry_failed": 30 } } } }, "from_numbers": { "summary": "Caller numbers you list", "value": { "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000", "agent_id": "00000000-0000-4000-8000-0000000000a1", "country_code": "+91", "campaign_start_time": "18/10/2026, 09:00", "campaign_end_time": "18/10/2026, 18:00", "from_numbers": [ "00000000-0000-4000-8000-0000000000c1" ], "call_config": { "call_time": { "call_start_time": "09:00", "call_end_time": "18:00", "timezone": "Asia/Kolkata" }, "call_retry_config": { "retry_count": 1, "retry_busy": 30, "retry_not_picked": 30, "retry_failed": 30 } } } } } } } }, "responses": { "200": { "description": "Large campaign call creation accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "bulk_list_id": { "type": "string" }, "status": { "type": "string" } }, "example": { "message": "Campaign calls scheduled", "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000", "status": "scheduled" } } } } }, "400": { "description": "Bad Request - Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Bulk list is not ready to start." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "402": { "description": "Payment Required - The balance (or available credit limit) does not cover the campaign. The campaign is set to `insufficient_balance`; add balance, call Check Campaign Balance, then send this request again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Insufficient balance to start this campaign. Please top up and use /check-balance to re-verify." } } } } } }, "422": { "description": "Validation Error - Both or neither of `from_numbers` and `number_pool_id`, only one of `campaign_start_time` and `campaign_end_time`, invalid `call_slots`, or a field with the wrong type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Provide exactly one of from_numbers / number_pool_id, not both" } } } } } } } } }, "/campaign/check-balance/{bulk_list_id}": { "post": { "tags": [ "campaign" ], "summary": "Check Campaign Balance (Beta)", "x-mint": { "metadata": { "og:title": "Check Campaign Balance Beta | Ringg AI" } }, "description": "Beta endpoint for re-checking the balance of a campaign in `insufficient_balance` after a top-up. When the balance now covers it, the campaign returns to `draft`; then send /campaign/make-call-async again.", "operationId": "checkCampaignBalanceBeta", "parameters": [ { "name": "X-API-KEY", "in": "header", "description": "(Required) Your Ringg AI API key.", "required": true, "schema": { "type": "string", "example": "rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, { "name": "bulk_list_id", "in": "path", "required": true, "description": "Bulk list ID to re-check.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Balance checked. `status` is `draft` when the campaign can start, or still `insufficient_balance`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "insufficient_balance" ] }, "message": { "type": "string" }, "bulk_list_id": { "type": "string", "description": "When `status` is `draft`." }, "total_callees": { "type": "integer", "description": "When `status` is `draft`: valid contacts in the campaign." }, "required_credits": { "type": "number", "description": "When `status` is `insufficient_balance`: estimated cost of the campaign." }, "additional_balance_required": { "type": "number", "description": "When `status` is `insufficient_balance`: how much more balance is needed." } } }, "examples": { "ready": { "summary": "Balance now covers the campaign", "value": { "status": "draft", "message": "Balance is sufficient. You can now start the campaign via /make-call-async.", "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000", "total_callees": 4988 } }, "still_short": { "summary": "Balance still too low", "value": { "status": "insufficient_balance", "message": "Insufficient balance to start this campaign.", "required_credits": 2500.0, "additional_balance_required": 1250.0 } } } } } }, "400": { "description": "Bad Request - The campaign is not in `insufficient_balance`, has no contacts, or has no agent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid credentials" } } } } } }, "404": { "description": "Bulk list not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } } } }