{"openapi":"3.1.0","info":{"title":"Kommo (BYOK) API","version":"0.1.0","description":"Kommo (BYOK) lets an AI assistant read your own Kommo data through the Kommo API with a key you supply (Kommo long-lived token). Read-only: 8 tools (get_account, list_leads, list_pipelines, list_loss_reasons, list_tasks, list_tags, list_sources, list_salesbots). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-kommo.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-kommo/docs"},"termsOfService":"https://connectorbay.com/byok-kommo/terms"},"servers":[{"url":"https://byok-kommo.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-kommo/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":"Show the Kommo account: id, name, subdomain, country, currency, whether unsorted leads and loss reasons are enabled, and","description":"Show the Kommo account: id, name, subdomain, country, currency, whether unsorted leads and loss reasons are enabled, and the API version. Use for \"Which Kommo account is this token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Kommo account subdomain, the part before .kommo.com (for example 'acme' for acme.kommo.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"}},"required":["subdomain"],"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_leads":{"post":{"operationId":"list_leads","summary":"List leads with name, price, pipeline and stage ids, responsible user, loss reason, timestamps, custom field values, tag","description":"List leads with name, price, pipeline and stage ids, responsible user, loss reason, timestamps, custom field values, tags and linked companies. Use for \"Which Kommo leads were created this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Kommo account subdomain, the part before .kommo.com (for example 'acme' for acme.kommo.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (the API allows up to 250; this tool defaults to 50).","title":"Limit"},"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against the lead's filled fields.","title":"Query"},"pipeline_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only leads in this pipeline id.","title":"Pipeline Id"},"responsible_user_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only leads of this responsible user id.","title":"Responsible User Id"},"created_from":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only leads created at or after this Unix timestamp.","title":"Created From"},"created_to":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only leads created at or before this Unix timestamp.","title":"Created To"},"updated_from":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only leads updated at or after this Unix timestamp.","title":"Updated From"},"updated_to":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only leads updated at or before this Unix timestamp.","title":"Updated To"}},"required":["subdomain"],"title":"list_leadsArguments","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_pipelines":{"post":{"operationId":"list_pipelines","summary":"List the lead pipelines with name, order, main/archive flags and their stages (id, name, color, type). Use for \"What sta","description":"List the lead pipelines with name, order, main/archive flags and their stages (id, name, color, type). Use for \"What stages does our Kommo sales pipeline have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Kommo account subdomain, the part before .kommo.com (for example 'acme' for acme.kommo.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"}},"required":["subdomain"],"title":"list_pipelinesArguments","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_loss_reasons":{"post":{"operationId":"list_loss_reasons","summary":"List the reasons a lead can be marked lost, with id, name and dates. Use for \"Which loss reasons are set up in Kommo\".","description":"List the reasons a lead can be marked lost, with id, name and dates. Use for \"Which loss reasons are set up in Kommo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Kommo account subdomain, the part before .kommo.com (for example 'acme' for acme.kommo.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"}},"required":["subdomain"],"title":"list_loss_reasonsArguments","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_tasks":{"post":{"operationId":"list_tasks","summary":"List tasks with text, type, linked entity, responsible user, completion state and due time (Unix seconds). Use for \"Whic","description":"List tasks with text, type, linked entity, responsible user, completion state and due time (Unix seconds). Use for \"Which Kommo tasks are still open\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Kommo account subdomain, the part before .kommo.com (for example 'acme' for acme.kommo.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (the API allows up to 250; this tool defaults to 50).","title":"Limit"},"is_completed":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"1 for completed tasks, 0 for open ones.","title":"Is Completed"},"responsible_user_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only tasks of this responsible user id.","title":"Responsible User Id"},"entity_type":{"anyOf":[{"enum":["leads","contacts","companies"],"type":"string"},{"type":"null"}],"default":null,"description":"Only tasks linked to this kind of entity; use together with entity_id.","title":"Entity Type"},"entity_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only tasks linked to this entity id; needs entity_type.","title":"Entity Id"}},"required":["subdomain"],"title":"list_tasksArguments","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_tags":{"post":{"operationId":"list_tags","summary":"List the tags used on leads, contacts or companies with id and name. Use for \"Which tags do we use on Kommo leads\".","description":"List the tags used on leads, contacts or companies with id and name. Use for \"Which tags do we use on Kommo leads\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Kommo account subdomain, the part before .kommo.com (for example 'acme' for acme.kommo.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"entity_type":{"description":"Which kind of entity the tags belong to.","enum":["leads","contacts","companies"],"title":"Entity Type","type":"string"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (the API allows up to 250; this tool defaults to 50).","title":"Limit"},"query":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Full-text search on the tag name.","title":"Query"}},"required":["subdomain","entity_type"],"title":"list_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_sources":{"post":{"operationId":"list_sources","summary":"List the integration sources for incoming leads with name, external id, pipeline and origin code. Use for \"Which lead so","description":"List the integration sources for incoming leads with name, external id, pipeline and origin code. Use for \"Which lead sources are configured in Kommo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Kommo account subdomain, the part before .kommo.com (for example 'acme' for acme.kommo.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"}},"required":["subdomain"],"title":"list_sourcesArguments","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_salesbots":{"post":{"operationId":"list_salesbots","summary":"List the Salesbots with id, name, functionality type (for example regular or greeting) and whether they are active. Use ","description":"List the Salesbots with id, name, functionality type (for example regular or greeting) and whether they are active. Use for \"Which Salesbots are active in Kommo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"subdomain":{"description":"Your Kommo account subdomain, the part before .kommo.com (for example 'acme' for acme.kommo.com).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Subdomain","type":"string"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Items per page (the API allows up to 250; this tool defaults to 50).","title":"Limit"},"type_functionality":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only Salesbots of this functionality type, for example regular or greeting.","title":"Type Functionality"}},"required":["subdomain"],"title":"list_salesbotsArguments","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}}}}