{"openapi":"3.1.0","info":{"title":"CloudTalk (BYOK) API","version":"0.1.0","description":"CloudTalk (BYOK) lets an AI assistant read your own CloudTalk data through the CloudTalk API with a key you supply (API Access Key ID). Read-only: 7 tools (list_groups, list_campaigns, list_numbers, list_contact_tags, list_contact_attributes, get_group_statistics, list_call_history). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-cloudtalk.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-cloudtalk/docs"},"termsOfService":"https://connectorbay.com/byok-cloudtalk/terms"},"servers":[{"url":"https://byok-cloudtalk.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-cloudtalk/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/list_groups":{"post":{"operationId":"list_groups","summary":"List the agent groups (queues) of the account with their ids and internal names. Paged. Use for \"Which agent groups exis","description":"List the agent groups (queues) of the account with their ids and internal names. Paged. Use for \"Which agent groups exist in CloudTalk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_groupsArguments","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 dialer campaigns of the account (status, schedule, recording, linked group and agent). Pass id for one campaign","description":"List the dialer campaigns of the account (status, schedule, recording, linked group and agent). Pass id for one campaign. Paged. Use for \"Which CloudTalk campaigns are active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Return only the campaign with this id.","title":"Id"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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/list_numbers":{"post":{"operationId":"list_numbers","summary":"List the phone numbers of the account with country code, internal name and what each is routed to (group, agent, confere","description":"List the phone numbers of the account with country code, internal name and what each is routed to (group, agent, conference room or fax). Paged. Use for \"Which phone numbers do we have in CloudTalk and are any unused\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only numbers with this country calling code, for example 1 or 421.","title":"Country Code"},"connected_to":{"anyOf":[{"enum":[0,1,2,3],"type":"integer"},{"type":"null"}],"default":null,"description":"Route type: 0 group, 1 agent, 2 conference room, 3 fax.","title":"Connected To"},"is_free":{"anyOf":[{"enum":[0,1],"type":"integer"},{"type":"null"}],"default":null,"description":"1 for numbers with no routing configured, 0 for numbers in use.","title":"Is Free"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_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_contact_tags":{"post":{"operationId":"list_contact_tags","summary":"List the contact tags defined in the account. Pass id for one tag. Paged. Use for \"Which contact tags are defined in Clo","description":"List the contact tags defined in the account. Pass id for one tag. Paged. Use for \"Which contact tags are defined in CloudTalk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Return only the tag with this id.","title":"Id"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_contact_tagsArguments","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_contact_attributes":{"post":{"operationId":"list_contact_attributes","summary":"List the custom attributes that can be set on a contact. Use for \"What contact attributes can I use in CloudTalk\".","description":"List the custom attributes that can be set on a contact. Use for \"What contact attributes can I use in CloudTalk\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_contact_attributesArguments","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_group_statistics":{"post":{"operationId":"get_group_statistics","summary":"Show today's live statistics of every group: agents, answered and unanswered calls, abandon rate, average call duration ","description":"Show today's live statistics of every group: agents, answered and unanswered calls, abandon rate, average call duration and waiting times. Use for \"How is each CloudTalk group doing today: abandon rate and waiting times\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_group_statisticsArguments","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_call_history":{"post":{"operationId":"list_call_history","summary":"List calls (newest first) with type, status, timings, internal and external numbers and recording flag. Filter by date r","description":"List calls (newest first) with type, status, timings, internal and external numbers and recording flag. Filter by date range, type, status, agent or call id. Paged. Use for \"Which CloudTalk calls were missed yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only calls after this time, format 2026-10-01 00:00:00.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only calls before this time, format 2026-10-02 00:00:00.","title":"Date To"},"type":{"anyOf":[{"enum":["incoming","outgoing","internal"],"type":"string"},{"type":"null"}],"default":null,"description":"Call direction: incoming, outgoing or internal.","title":"Type"},"status":{"anyOf":[{"enum":["missed","answered"],"type":"string"},{"type":"null"}],"default":null,"description":"missed or answered.","title":"Status"},"user_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only calls of the agent with this id.","title":"User Id"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return per page (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_call_historyArguments","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}}}}