{"openapi":"3.1.0","info":{"title":"Bolna (BYOK) API","version":"0.1.0","description":"Bolna (BYOK) lets an AI assistant read your own Bolna data through the Bolna API with a key you supply (Bolna API key). Read-only: 12 tools (get_account, list_agents, list_agent_executions, list_batches, get_batch, list_knowledgebases, get_knowledgebase, list_dispositions, list_workflows, list_sip_trunks, list_tts_providers, list_voices). The BYOK key travels with each request, is used for that...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-bolna.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-bolna/docs"},"termsOfService":"https://connectorbay.com/byok-bolna/terms"},"servers":[{"url":"https://byok-bolna.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-bolna/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_account":{"post":{"operationId":"get_account","summary":"Get the account behind the key: name, wallet balance and the concurrent call limit with current usage (email is not show","description":"Get the account behind the key: name, wallet balance and the concurrent call limit with current usage (email is not shown). Use for \"How much Bolna wallet balance do I have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_accountArguments","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 all voice AI agents with name, type, status and created and updated time (task and prompt configuration is not show","description":"List all voice AI agents with name, type, status and created and updated time (task and prompt configuration is not shown). Use for \"Which voice agents do I have in Bolna\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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/list_agent_executions":{"post":{"operationId":"list_agent_executions","summary":"List call executions of one agent within a time window with status, duration, cost split, hangup reason and call type; p","description":"List call executions of one agent within a time window with status, duration, cost split, hangup reason and call type; phone numbers, transcripts and recordings are not shown. Use for \"Which Bolna calls of my agent failed last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"agent_id":{"description":"Id of the Bolna voice agent, from list_agents.","maxLength":200,"title":"Agent Id","type":"string"},"from_time":{"description":"Start of the window as ISO 8601 date-time, for example 2026-10-01T00:00:00.000Z.","maxLength":200,"title":"From Time","type":"string"},"to_time":{"description":"End of the window as ISO 8601 date-time.","maxLength":200,"title":"To Time","type":"string"},"page_number":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page Number"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Items per page (1 to 50).","title":"Page Size"},"status":{"anyOf":[{"enum":["scheduled","queued","rescheduled","ringing","initiated","in-progress","call-disconnected","completed","balance-low","busy","no-answer","canceled","failed","stopped","error"],"type":"string"},{"type":"null"}],"default":null,"description":"Only executions with this status.","title":"Status"},"call_type":{"anyOf":[{"enum":["inbound","outbound"],"type":"string"},{"type":"null"}],"default":null,"description":"Only inbound or outbound calls.","title":"Call Type"},"batch_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only executions of this batch id.","title":"Batch Id"}},"required":["agent_id","from_time","to_time"],"title":"list_agent_executionsArguments","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_batches":{"post":{"operationId":"list_batches","summary":"List the call batches of an agent with status, schedule, file name and valid and total contact counts plus per-status ex","description":"List the call batches of an agent with status, schedule, file name and valid and total contact counts plus per-status execution counts. Use for \"How are my Bolna batch campaigns doing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"agent_id":{"description":"Id of the Bolna voice agent, from list_agents.","maxLength":200,"title":"Agent Id","type":"string"}},"required":["agent_id"],"title":"list_batchesArguments","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_batch":{"post":{"operationId":"get_batch","summary":"Get one batch: status, schedule, file name, contact counts and per-status execution counts. Use for \"How far along is Bo","description":"Get one batch: status, schedule, file name, contact counts and per-status execution counts. Use for \"How far along is Bolna batch a1b2c3d4\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"batch_id":{"description":"Id of the batch, from list_batches.","maxLength":200,"title":"Batch Id","type":"string"}},"required":["batch_id"],"title":"get_batchArguments","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_knowledgebases":{"post":{"operationId":"list_knowledgebases","summary":"List the knowledge bases (ingested PDFs and URLs) with status, chunk size and language. Use for \"Which knowledge bases d","description":"List the knowledge bases (ingested PDFs and URLs) with status, chunk size and language. Use for \"Which knowledge bases do my Bolna agents use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_knowledgebasesArguments","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_knowledgebase":{"post":{"operationId":"get_knowledgebase","summary":"Get one knowledge base: file name, status, chunking settings and language. Use for \"Is Bolna knowledge base kb_1 process","description":"Get one knowledge base: file name, status, chunking settings and language. Use for \"Is Bolna knowledge base kb_1 processed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"rag_id":{"description":"Id of the knowledge base, from list_knowledgebases.","maxLength":200,"title":"Rag Id","type":"string"}},"required":["rag_id"],"title":"get_knowledgebaseArguments","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_dispositions":{"post":{"operationId":"list_dispositions","summary":"List call dispositions (post-call questions that classify outcomes) with category, model and whether they are subjective","description":"List call dispositions (post-call questions that classify outcomes) with category, model and whether they are subjective or objective; optionally for one agent. Use for \"Which dispositions classify my Bolna calls\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"agent_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only dispositions linked to this agent id.","title":"Agent Id"}},"title":"list_dispositionsArguments","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_workflows":{"post":{"operationId":"list_workflows","summary":"List voice workflows, newest first, with status and latest published version; filter by name. Use for \"Which workflows d","description":"List voice workflows, newest first, with status and latest published version; filter by name. Use for \"Which workflows do I have in Bolna\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive text to find in workflow names.","title":"Name"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many workflows to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many workflows to skip.","title":"Offset"}},"title":"list_workflowsArguments","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_sip_trunks":{"post":{"operationId":"list_sip_trunks","summary":"List SIP trunks with status, direction, channels, transport, health and active calls (credentials, gateways and numbers ","description":"List SIP trunks with status, direction, channels, transport, health and active calls (credentials, gateways and numbers are not shown). Use for \"Are my Bolna SIP trunks healthy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_sip_trunksArguments","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_tts_providers":{"post":{"operationId":"list_tts_providers","summary":"List the supported text-to-speech providers and their models for a language, with quality tier, pricing and capabilities","description":"List the supported text-to-speech providers and their models for a language, with quality tier, pricing and capabilities; the ids feed list_voices. Use for \"Which TTS providers does Bolna support for Hindi\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"language":{"description":"Language code to filter by, for example en, hi or ta.","maxLength":200,"title":"Language","type":"string"}},"required":["language"],"title":"list_tts_providersArguments","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 voices for a TTS provider and model (from list_tts_providers) with name, gender, accent, age range and use cases. U","description":"List voices for a TTS provider and model (from list_tts_providers) with name, gender, accent, age range and use cases. Use for \"Which Bolna voices are available for ElevenLabs in English\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"provider_id":{"description":"Provider id from list_tts_providers.","maxLength":200,"title":"Provider Id","type":"string"},"model_id":{"description":"Model id from list_tts_providers (the 'id' field of the model).","maxLength":200,"title":"Model Id","type":"string"},"language":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"BCP-47 language code to filter voices.","title":"Language"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Voices per page (1 to 100).","title":"Page Size"}},"required":["provider_id","model_id"],"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}}}}