{"openapi":"3.1.0","info":{"title":"Kombo (BYOK) API","version":"0.1.0","description":"Kombo (BYOK) lets an AI assistant read your own Kombo data through the Kombo API with a key you supply (Kombo API key (Secrets page of the Kombo dashboard)). Read-only: 11 tools (check_api_key, get_integration, list_teams, list_groups, list_locations, list_absence_types, list_legal_entities, list_time_off_balances, list_application_stages, list_rejection_reasons, list_ats_tags). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-kombo.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-kombo/docs"},"termsOfService":"https://connectorbay.com/byok-kombo/terms"},"servers":[{"url":"https://byok-kombo.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-kombo/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/check_api_key":{"post":{"operationId":"check_api_key","summary":"Check that the Kombo API key works and show the environment and customer ids it belongs to. Use for \"Is my Kombo API key","description":"Check that the Kombo API key works and show the environment and customer ids it belongs to. Use for \"Is my Kombo API key valid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"check_api_keyArguments","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_integration":{"post":{"operationId":"get_integration","summary":"Get one linked integration by id: the connected tool, category, status, setup status, organization name, data expiry and","description":"Get one linked integration by id: the connected tool, category, status, setup status, organization name, data expiry and creation time. Use for \"Is my linked HR integration healthy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"integration_id":{"description":"Kombo integration id, for example bamboohr:HWUTwvyx2wLoSUHphiWVrp28.","maxLength":120,"title":"Integration Id","type":"string"}},"required":["integration_id"],"title":"get_integrationArguments","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_teams":{"post":{"operationId":"list_teams","summary":"List teams (departments, teams, cost centers) of the linked HR system with name, type and parent. Items are returned as ","description":"List teams (departments, teams, cost centers) of the linked HR system with name, type and parent. Items are returned as Kombo sends them (no personal or pay data on this record type). Use for \"What teams exist in our HR system\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records per page (1 to 250).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the 'next' value of the previous answer.","title":"Cursor"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records changed after this ISO 8601 time.","title":"Updated After"}},"title":"list_teamsArguments","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_groups":{"post":{"operationId":"list_groups","summary":"List groups of the linked HR system with name, type and parent, optionally filtered by type or name. Items are returned ","description":"List groups of the linked HR system with name, type and parent, optionally filtered by type or name. Items are returned as Kombo sends them (no personal or pay data on this record type). Use for \"What groups and departments exist in our HR system\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records per page (1 to 250).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the 'next' value of the previous answer.","title":"Cursor"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records changed after this ISO 8601 time.","title":"Updated After"},"types":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only groups of these types, comma separated (DEPARTMENT, TEAM, COST_CENTER).","title":"Types"},"name_contains":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only groups whose name contains this text.","title":"Name Contains"}},"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_locations":{"post":{"operationId":"list_locations","summary":"List company locations of the linked HR system with name, type and address. Items are returned as Kombo sends them (no p","description":"List company locations of the linked HR system with name, type and address. Items are returned as Kombo sends them (no personal or pay data on this record type). Use for \"Which offices are in our HR system\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records per page (1 to 250).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the 'next' value of the previous answer.","title":"Cursor"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records changed after this ISO 8601 time.","title":"Updated After"},"name_contains":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only locations whose name contains this text.","title":"Name Contains"}},"title":"list_locationsArguments","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_absence_types":{"post":{"operationId":"list_absence_types","summary":"List absence types (vacation, sick leave and similar) with name, unit and half-day support. Items are returned as Kombo ","description":"List absence types (vacation, sick leave and similar) with name, unit and half-day support. Items are returned as Kombo sends them (no personal or pay data on this record type). Use for \"Which absence types does our HR system offer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records per page (1 to 250).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the 'next' value of the previous answer.","title":"Cursor"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records changed after this ISO 8601 time.","title":"Updated After"}},"title":"list_absence_typesArguments","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_legal_entities":{"post":{"operationId":"list_legal_entities","summary":"List legal entities of the company in the linked HR system with name and address. Items are returned as Kombo sends them","description":"List legal entities of the company in the linked HR system with name and address. Items are returned as Kombo sends them (no personal or pay data on this record type). Use for \"Which legal entities does the company have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records per page (1 to 250).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the 'next' value of the previous answer.","title":"Cursor"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records changed after this ISO 8601 time.","title":"Updated After"},"name_contains":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only entities whose name contains this text.","title":"Name Contains"}},"title":"list_legal_entitiesArguments","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_time_off_balances":{"post":{"operationId":"list_time_off_balances","summary":"List time off balances per employee and absence type with remaining balance, used amount and units. Items are returned a","description":"List time off balances per employee and absence type with remaining balance, used amount and units. Items are returned as Kombo sends them (no personal or pay data on this record type). Use for \"How much time off do employees have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records per page (1 to 250).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the 'next' value of the previous answer.","title":"Cursor"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records changed after this ISO 8601 time.","title":"Updated After"},"employee_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only balances of this Kombo employee id.","title":"Employee Id"}},"title":"list_time_off_balancesArguments","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_application_stages":{"post":{"operationId":"list_application_stages","summary":"List the hiring pipeline stages of the linked recruiting system with name and status. Items are returned as Kombo sends ","description":"List the hiring pipeline stages of the linked recruiting system with name and status. Items are returned as Kombo sends them (no personal or pay data on this record type). Use for \"What stages are in our hiring pipeline\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records per page (1 to 250).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the 'next' value of the previous answer.","title":"Cursor"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records changed after this ISO 8601 time.","title":"Updated After"}},"title":"list_application_stagesArguments","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_rejection_reasons":{"post":{"operationId":"list_rejection_reasons","summary":"List the rejection reasons configured in the linked recruiting system. Items are returned as Kombo sends them (no person","description":"List the rejection reasons configured in the linked recruiting system. Items are returned as Kombo sends them (no personal or pay data on this record type). Use for \"Which rejection reasons can recruiters pick\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records per page (1 to 250).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the 'next' value of the previous answer.","title":"Cursor"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records changed after this ISO 8601 time.","title":"Updated After"}},"title":"list_rejection_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_ats_tags":{"post":{"operationId":"list_ats_tags","summary":"List candidate tags configured in the linked recruiting system (tag names only, no candidates). Items are returned as Ko","description":"List candidate tags configured in the linked recruiting system (tag names only, no candidates). Items are returned as Kombo sends them (no personal or pay data on this record type). Use for \"Which candidate tags exist in our ATS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records per page (1 to 250).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor: the 'next' value of the previous answer.","title":"Cursor"},"updated_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records changed after this ISO 8601 time.","title":"Updated After"}},"title":"list_ats_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}}}}