{"openapi":"3.1.0","info":{"title":"Ringg AI (BYOK) API","version":"0.1.0","description":"Ringg AI (BYOK) lets an AI assistant read your own Ringg AI data through the Ringg AI API with a key you supply (Ringg AI workspace API key). Read-only: 12 tools (get_workspace, list_agents, get_agent, list_voices, list_knowledge_bases, list_workspace_numbers, list_campaigns, get_call_volume, get_connectivity, get_agent_performance, get_latency_trend, get_concurrency_trend). The BYOK key travels...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-ringg-ai.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-ringg-ai/docs"},"termsOfService":"https://connectorbay.com/byok-ringg-ai/terms"},"servers":[{"url":"https://byok-ringg-ai.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-ringg-ai/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_workspace":{"post":{"operationId":"get_workspace","summary":"Show the workspace that owns the API key: name, creation time, available credits and locked credits. Use for \"How many R","description":"Show the workspace that owns the API key: name, creation time, available credits and locked credits. Use for \"How many Ringg AI credits does my workspace have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_workspaceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_agents":{"post":{"operationId":"list_agents","summary":"List the voice and WhatsApp agents with id, display name, type (inbound, outbound or WhatsApp), orchestration mode, temp","description":"List the voice and WhatsApp agents with id, display name, type (inbound, outbound or WhatsApp), orchestration mode, template and versions. Prompts are not returned. Use for \"Which voice agents do I have on Ringg AI\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only agents whose name matches this text.","title":"Search"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many agents to return; omit for all.","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many agents to skip.","title":"Offset"}},"title":"list_agentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_agent":{"post":{"operationId":"get_agent","summary":"Get one agent's name, type, orchestration mode, telephony, template, A/B status, active version and classification label","description":"Get one agent's name, type, orchestration mode, telephony, template, A/B status, active version and classification labels. Use for \"What are the settings of my Ringg AI agent\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"agent_id":{"description":"Agent id (from list_agents).","maxLength":80,"title":"Agent Id","type":"string"}},"required":["agent_id"],"title":"get_agentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_voices":{"post":{"operationId":"list_voices","summary":"List the voices an agent can use with id, name, supported languages, gender and preview links. Use for \"Which Hindi voic","description":"List the voices an agent can use with id, name, supported languages, gender and preview links. Use for \"Which Hindi voices can I give my Ringg AI agent\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"language":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only voices for these language codes (comma-separated), for example hi-IN,en-US.","title":"Language"}},"title":"list_voicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_knowledge_bases":{"post":{"operationId":"list_knowledge_bases","summary":"List the knowledge bases with id, name, type and creation time. Use for \"Which knowledge bases are set up on Ringg AI\".","description":"List the knowledge bases with id, name, type and creation time. Use for \"Which knowledge bases are set up on Ringg AI\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_knowledge_basesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_workspace_numbers":{"post":{"operationId":"list_workspace_numbers","summary":"List the phone numbers in the workspace with call count, assigned agent, inbound flag, provider, owner, spam flag and ta","description":"List the phone numbers in the workspace with call count, assigned agent, inbound flag, provider, owner, spam flag and tags. Use for \"Which phone numbers does my Ringg AI workspace have and which agent answers each\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"telephony_account_id":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only numbers of this connected telephony account id, or ringg for Ringg-provided numbers.","title":"Telephony Account Id"},"inbound_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"true for numbers that can receive calls, false for the rest.","title":"Inbound Enabled"}},"title":"list_workspace_numbersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_campaigns":{"post":{"operationId":"list_campaigns","summary":"List the calling campaigns with name, status, schedule, agent, total calls and invalid rows. Use for \"What is the status","description":"List the calling campaigns with name, status, schedule, agent, total calls and invalid rows. Use for \"What is the status of my Ringg AI calling campaigns\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Campaigns to return.","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Campaigns to skip.","title":"Offset"}},"title":"list_campaignsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_call_volume":{"post":{"operationId":"get_call_volume","summary":"Get call volume for a period against the previous period: total, connected, failed, voicemail, connection rate, average ","description":"Get call volume for a period against the previous period: total, connected, failed, voicemail, connection rate, average handle time and total minutes. Use for \"How many calls did my Ringg AI agents connect last week compared with the week before\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the reporting window, YYYY-MM-DD or ISO-8601; omit both dates for all time.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End of the reporting window (inclusive), YYYY-MM-DD or ISO-8601.","title":"End Date"},"agent_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only calls of these agent ids (comma-separated).","title":"Agent Id"},"channel":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only these call channels (comma-separated): inbound, outbound, webcall.","title":"Channel"},"tz":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"IANA time zone used to bucket time series, for example Asia/Kolkata.","title":"Tz"}},"title":"get_call_volumeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_connectivity":{"post":{"operationId":"get_connectivity","summary":"Get how many calls connected and the connectivity percentage, with a breakdown by retry attempt. Use for \"What share of ","description":"Get how many calls connected and the connectivity percentage, with a breakdown by retry attempt. Use for \"What share of my Ringg AI calls connect\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the reporting window, YYYY-MM-DD or ISO-8601; omit both dates for all time.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End of the reporting window (inclusive), YYYY-MM-DD or ISO-8601.","title":"End Date"},"agent_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only calls of these agent ids (comma-separated).","title":"Agent Id"},"channel":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only these call channels (comma-separated): inbound, outbound, webcall.","title":"Channel"}},"title":"get_connectivityArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_agent_performance":{"post":{"operationId":"get_agent_performance","summary":"Get goal rate, average latency, total cost and cost per outcome, with a per-version comparison and per-agent call counts","description":"Get goal rate, average latency, total cost and cost per outcome, with a per-version comparison and per-agent call counts, minutes and cost. Use for \"How are my Ringg AI agents performing on goal rate and cost\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the reporting window, YYYY-MM-DD or ISO-8601; omit both dates for all time.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End of the reporting window (inclusive), YYYY-MM-DD or ISO-8601.","title":"End Date"},"agent_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only calls of these agent ids (comma-separated).","title":"Agent Id"},"channel":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only these call channels (comma-separated): inbound, outbound, webcall.","title":"Channel"}},"title":"get_agent_performanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_latency_trend":{"post":{"operationId":"get_latency_trend","summary":"Get median and 95th-percentile agent response latency per time bucket. Use for \"Has my Ringg AI agent response latency g","description":"Get median and 95th-percentile agent response latency per time bucket. Use for \"Has my Ringg AI agent response latency gotten worse this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the reporting window, YYYY-MM-DD or ISO-8601; omit both dates for all time.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End of the reporting window (inclusive), YYYY-MM-DD or ISO-8601.","title":"End Date"},"agent_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only calls of these agent ids (comma-separated).","title":"Agent Id"},"channel":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only these call channels (comma-separated): inbound, outbound, webcall.","title":"Channel"},"tz":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"IANA time zone used to bucket time series, for example Asia/Kolkata.","title":"Tz"}},"title":"get_latency_trendArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_concurrency_trend":{"post":{"operationId":"get_concurrency_trend","summary":"Get paid concurrency against received concurrency per time bucket. Use for \"Am I using all the concurrent calls I pay fo","description":"Get paid concurrency against received concurrency per time bucket. Use for \"Am I using all the concurrent calls I pay for on Ringg AI\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the reporting window, YYYY-MM-DD or ISO-8601; omit both dates for all time.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"End of the reporting window (inclusive), YYYY-MM-DD or ISO-8601.","title":"End Date"},"tz":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"IANA time zone used to bucket time series, for example Asia/Kolkata.","title":"Tz"}},"title":"get_concurrency_trendArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}