{"openapi":"3.1.0","info":{"title":"Recruitee (BYOK) API","version":"0.1.0","description":"Recruitee (BYOK) lets an AI assistant read your own Recruitee data through the Recruitee API with a key you supply (Recruitee personal API token). Read-only: 10 tools (list_offers, search_candidates, list_departments, list_locations, list_candidate_tags, list_sources, list_talent_pools, list_pipeline_templates, list_requisitions, list_disqualify_reasons). The BYOK key travels with each request,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-recruitee.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-recruitee/docs"},"termsOfService":"https://connectorbay.com/byok-recruitee/terms"},"servers":[{"url":"https://byok-recruitee.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-recruitee/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_offers":{"post":{"operationId":"list_offers","summary":"List Recruitee job offers with title, status (draft, published, closed, archived), kind, department, location, work mode","description":"List Recruitee job offers with title, status (draft, published, closed, archived), kind, department, location, work model flags, recruiter and hiring manager ids and URL. Use for \"Which job offers does Recruitee have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Your Recruitee company id (number) or company subdomain, for example '12345' or 'acme'.","maxLength":60,"title":"Company Id","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many offers to return (1 to 1000).","title":"Limit"}},"required":["company_id"],"title":"list_offersArguments","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/search_candidates":{"post":{"operationId":"search_candidates","summary":"List Recruitee candidates (newest first by default) with name, emails, phones, tags, source and dates. Contains personal","description":"List Recruitee candidates (newest first by default) with name, emails, phones, tags, source and dates. Contains personal data. Up to 10000 per call; the API default is 60. Use for \"Who are the newest Recruitee candidates\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Your Recruitee company id (number) or company subdomain, for example '12345' or 'acme'.","maxLength":60,"title":"Company Id","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many candidates to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"sort_by":{"anyOf":[{"enum":["created_at_desc","created_at_asc","candidate_name_asc","candidate_name_desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order: created_at_desc, created_at_asc, candidate_name_asc or candidate_name_desc.","title":"Sort By"}},"required":["company_id"],"title":"search_candidatesArguments","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_departments":{"post":{"operationId":"list_departments","summary":"List the Recruitee departments with id, name and the number of offers in each. Use for \"What departments does Recruitee ","description":"List the Recruitee departments with id, name and the number of offers in each. Use for \"What departments does Recruitee have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Your Recruitee company id (number) or company subdomain, for example '12345' or 'acme'.","maxLength":60,"title":"Company Id","type":"string"}},"required":["company_id"],"title":"list_departmentsArguments","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 the Recruitee locations with name, city, state, country code and archive time. Can search by text and filter by act","description":"List the Recruitee locations with name, city, state, country code and archive time. Can search by text and filter by active or archived. Use for \"Which locations are set up in Recruitee\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Your Recruitee company id (number) or company subdomain, for example '12345' or 'acme'.","maxLength":60,"title":"Company Id","type":"string"},"query":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text to search for in location names.","title":"Query"},"scope":{"anyOf":[{"enum":["active","archived","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Which locations: active, archived or all (default all).","title":"Scope"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many locations to return (1 to 1000).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["company_id"],"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_candidate_tags":{"post":{"operationId":"list_candidate_tags","summary":"List the candidate tags used in Recruitee with how many candidates carry each. Use for \"Which candidate tags are used in","description":"List the candidate tags used in Recruitee with how many candidates carry each. Use for \"Which candidate tags are used in Recruitee\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Your Recruitee company id (number) or company subdomain, for example '12345' or 'acme'.","maxLength":60,"title":"Company Id","type":"string"},"query":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text to search for in tag names.","title":"Query"},"sort_by":{"anyOf":[{"enum":["name","taggings_count"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field: name or taggings_count.","title":"Sort By"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc (default) or desc.","title":"Sort Order"}},"required":["company_id"],"title":"list_candidate_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 candidate sources defined in Recruitee with how many candidates came from each. Use for \"Where do Recruitee can","description":"List the candidate sources defined in Recruitee with how many candidates came from each. Use for \"Where do Recruitee candidates come from\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Your Recruitee company id (number) or company subdomain, for example '12345' or 'acme'.","maxLength":60,"title":"Company Id","type":"string"}},"required":["company_id"],"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_talent_pools":{"post":{"operationId":"list_talent_pools","summary":"List Recruitee talent pools with title, status, candidate count and dates. Use for \"What talent pools exist in Recruitee","description":"List Recruitee talent pools with title, status, candidate count and dates. Use for \"What talent pools exist in Recruitee\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Your Recruitee company id (number) or company subdomain, for example '12345' or 'acme'.","maxLength":60,"title":"Company Id","type":"string"},"scope":{"anyOf":[{"enum":["archived","not_archived"],"type":"string"},{"type":"null"}],"default":null,"description":"Which pools: archived or not_archived (leave out for all).","title":"Scope"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many talent pools to return.","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many talent pools to skip, for paging.","title":"Offset"}},"required":["company_id"],"title":"list_talent_poolsArguments","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_pipeline_templates":{"post":{"operationId":"list_pipeline_templates","summary":"List the Recruitee hiring pipeline templates with title, category and whether each is the default. Use for \"What pipelin","description":"List the Recruitee hiring pipeline templates with title, category and whether each is the default. Use for \"What pipeline templates does Recruitee have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Your Recruitee company id (number) or company subdomain, for example '12345' or 'acme'.","maxLength":60,"title":"Company Id","type":"string"},"title":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only templates with this title.","title":"Title"}},"required":["company_id"],"title":"list_pipeline_templatesArguments","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_requisitions":{"post":{"operationId":"list_requisitions","summary":"List Recruitee requisitions (hiring requests) with title, status, department, openings, hires and dates. Needs the requi","description":"List Recruitee requisitions (hiring requests) with title, status, department, openings, hires and dates. Needs the requisitions feature. Use for \"Which requisitions are active in Recruitee\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Your Recruitee company id (number) or company subdomain, for example '12345' or 'acme'.","maxLength":60,"title":"Company Id","type":"string"},"scope":{"anyOf":[{"enum":["active","requested_by_me","need_my_approval","archived"],"type":"string"},{"type":"null"}],"default":null,"description":"Which requisitions: active (default), requested_by_me, need_my_approval or archived.","title":"Scope"},"q":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Search text for title, guid or location.","title":"Q"}},"required":["company_id"],"title":"list_requisitionsArguments","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_disqualify_reasons":{"post":{"operationId":"list_disqualify_reasons","summary":"List the Recruitee reasons used to disqualify candidates, in display order. Use for \"What disqualification reasons are c","description":"List the Recruitee reasons used to disqualify candidates, in display order. Use for \"What disqualification reasons are configured in Recruitee\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Your Recruitee company id (number) or company subdomain, for example '12345' or 'acme'.","maxLength":60,"title":"Company Id","type":"string"}},"required":["company_id"],"title":"list_disqualify_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}}}}