{"openapi":"3.1.0","info":{"title":"Teamtailor (BYOK) API","version":"0.1.0","description":"Teamtailor (BYOK) lets an AI assistant read your own Teamtailor data through the Teamtailor API with a key you supply (Teamtailor API key (Admin scope for candidates and applications)). Read-only: 12 tools (get_company, list_jobs, get_job, list_candidates, get_candidate, list_job_applications, list_stages, list_departments, list_locations, list_users, list_requisitions, list_job_offers). The BYOK...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-teamtailor.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-teamtailor/docs"},"termsOfService":"https://connectorbay.com/byok-teamtailor/terms"},"servers":[{"url":"https://byok-teamtailor.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-teamtailor/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_company":{"post":{"operationId":"get_company","summary":"Show the company the key belongs to: name, website and locale. Use for \"Which Teamtailor company is this key connected t","description":"Show the company the key belongs to: name, website and locale. Use for \"Which Teamtailor company is this key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_companyArguments","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_jobs":{"post":{"operationId":"list_jobs","summary":"List jobs with title, status, remote status, dates and tags; filter by status (default published), department, location ","description":"List jobs with title, status, remote status, dates and tags; filter by status (default published), department, location or role. Needs a key whose scope allows the status asked for. Use for \"Which jobs are published at the moment\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["published","unlisted","archived","draft","scheduled","all"],"type":"string"},{"type":"null"}],"default":"published","description":"Job status: published, unlisted, archived, draft, scheduled or all.","title":"Status"},"department":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs of this department id.","title":"Department"},"locations":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs at this location id.","title":"Locations"},"role":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs of this role id.","title":"Role"},"include":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated related resources to embed in the answer, for example 'department,locations'.","title":"Include"},"page_size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 30).","title":"Page Size"},"page_after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from links.next of the previous answer to get the next page.","title":"Page After"}},"title":"list_jobsArguments","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_job":{"post":{"operationId":"get_job","summary":"Get one job by id with title, status, pitch, dates, tags and requirements. Use for \"Show the details of job 123\".","description":"Get one job by id with title, status, pitch, dates, tags and requirements. Use for \"Show the details of job 123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"description":"Teamtailor job id.","maxLength":200,"title":"Job Id","type":"string"},"include":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated related resources to embed in the answer, for example 'department,locations'.","title":"Include"}},"required":["job_id"],"title":"get_jobArguments","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_candidates":{"post":{"operationId":"list_candidates","summary":"List candidates with name, email, phone, city, tags and creation date; filter by email, department, city, country or cre","description":"List candidates with name, email, phone, city, tags and creation date; filter by email, department, city, country or created and updated dates. Needs an Admin scope key. Use for \"Who applied or was added as a candidate this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the candidate with this email address.","title":"Email"},"department":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only candidates of this department id.","title":"Department"},"city":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only candidates in this city.","title":"City"},"country":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only candidates in this country.","title":"Country"},"created_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only candidates created after this date (YYYY-MM-DD).","title":"Created From"},"created_to":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only candidates created before this date (YYYY-MM-DD).","title":"Created To"},"sort":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"-created-at","description":"Sort attribute; prefix with - for descending, for example '-created-at'.","title":"Sort"},"include":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated related resources to embed in the answer, for example 'job-applications'.","title":"Include"},"page_size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 30).","title":"Page Size"},"page_after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from links.next of the previous answer to get the next page.","title":"Page After"}},"title":"list_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/get_candidate":{"post":{"operationId":"get_candidate","summary":"Get one candidate by id with contact details, location, source flags, tags and links. Needs an Admin scope key. Use for ","description":"Get one candidate by id with contact details, location, source flags, tags and links. Needs an Admin scope key. Use for \"Show candidate 42\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"candidate_id":{"description":"Teamtailor candidate id.","maxLength":200,"title":"Candidate Id","type":"string"},"include":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated related resources to embed in the answer, for example 'job-applications'.","title":"Include"}},"required":["candidate_id"],"title":"get_candidateArguments","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_job_applications":{"post":{"operationId":"list_job_applications","summary":"List job applications with dates, rejection time, stage change time and source; filter by stage type or dates. Use inclu","description":"List job applications with dates, rejection time, stage change time and source; filter by stage type or dates. Use include=candidate,job,stage to embed them. Needs an Admin scope key. Use for \"Which job applications moved stage this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"stage_type":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Current stage type: Inbox, In process or Hired.","title":"Stage Type"},"created_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only applications created after this date (YYYY-MM-DD).","title":"Created From"},"changed_stage_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only applications that changed stage after this date (YYYY-MM-DD).","title":"Changed Stage From"},"sort":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"-changed-stage-at","description":"Sort, for example '-changed-stage-at' for the latest stage change first.","title":"Sort"},"include":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated related resources to embed in the answer, for example 'candidate,job,stage'.","title":"Include"},"page_size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 30).","title":"Page Size"},"page_after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from links.next of the previous answer to get the next page.","title":"Page After"}},"title":"list_job_applicationsArguments","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_stages":{"post":{"operationId":"list_stages","summary":"List hiring pipeline stages with name, order and counts of active and rejected applications; filter by job id. Use for \"","description":"List hiring pipeline stages with name, order and counts of active and rejected applications; filter by job id. Use for \"What stages does job 123 have and how many candidates are in each\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only stages of this job id.","title":"Job"},"sort":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"id","description":"Sort attribute, for example 'row-order' within one job.","title":"Sort"},"page_size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 30).","title":"Page Size"},"page_after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from links.next of the previous answer to get the next page.","title":"Page After"}},"title":"list_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_departments":{"post":{"operationId":"list_departments","summary":"List departments with name; use include=manager,division to embed managers and divisions. Use for \"What departments exis","description":"List departments with name; use include=manager,division to embed managers and divisions. Use for \"What departments exist\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated related resources to embed in the answer, for example 'manager,division'.","title":"Include"},"page_size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 30).","title":"Page Size"},"page_after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from links.next of the previous answer to get the next page.","title":"Page After"}},"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 company locations with name, address, city, country, email, phone and headquarters flag. Use for \"Where are our off","description":"List company locations with name, address, city, country, email, phone and headquarters flag. Use for \"Where are our offices\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 30).","title":"Page Size"},"page_after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from links.next of the previous answer to get the next page.","title":"Page After"}},"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_users":{"post":{"operationId":"list_users","summary":"List Teamtailor users with name, title, role, email, phone and visibility; filter by email or department id. Use for \"Wh","description":"List Teamtailor users with name, title, role, email, phone and visibility; filter by email or department id. Use for \"Who are the recruiters in our Teamtailor account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the user with this email address.","title":"Email"},"department":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only users of this department id.","title":"Department"},"include":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated related resources to embed in the answer, for example 'department,location'.","title":"Include"},"page_size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 30).","title":"Page Size"},"page_after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from links.next of the previous answer to get the next page.","title":"Page After"}},"title":"list_usersArguments","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 job requisitions with job title, status, salary range, openings and hired count. Use for \"Which requisitions are op","description":"List job requisitions with job title, status, salary range, openings and hired count. Use for \"Which requisitions are open and how many hires are left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated related resources to embed in the answer, for example 'department,location'.","title":"Include"},"page_size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 30).","title":"Page Size"},"page_after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from links.next of the previous answer to get the next page.","title":"Page After"}},"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_job_offers":{"post":{"operationId":"list_job_offers","summary":"List job offers with status, sent and answered times and response. Use for \"Which job offers are still waiting for an an","description":"List job offers with status, sent and answered times and response. Use for \"Which job offers are still waiting for an answer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated related resources to embed in the answer, for example 'job-application,user'.","title":"Include"},"page_size":{"anyOf":[{"maximum":30,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 30).","title":"Page Size"},"page_after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from links.next of the previous answer to get the next page.","title":"Page After"}},"title":"list_job_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}}}}