{"openapi":"3.1.0","info":{"title":"SmartRecruiters (BYOK) API","version":"0.1.0","description":"SmartRecruiters (BYOK) lets an AI assistant read your own SmartRecruiters data through the SmartRecruiters API with a key you supply (SmartRecruiters API key). Read-only: 11 tools (get_company, search_jobs, get_job, list_job_positions, get_job_status_history, list_departments, list_hiring_processes, list_job_properties, list_predefined_locations, list_career_sites, list_published_postings). The...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-smartrecruiters.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-smartrecruiters/docs"},"termsOfService":"https://connectorbay.com/byok-smartrecruiters/terms"},"servers":[{"url":"https://byok-smartrecruiters.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-smartrecruiters/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 your company profile in SmartRecruiters: identifier, name, headquarters location, website and industry. Use for \"Wh","description":"Show your company profile in SmartRecruiters: identifier, name, headquarters location, website and industry. Use for \"What company profile does my SmartRecruiters account have\".","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/search_jobs":{"post":{"operationId":"search_jobs","summary":"Search your jobs by title text, status, posting status, department, city or update time. Returns job id, title, referenc","description":"Search your jobs by title text, status, posting status, department, city or update time. Returns job id, title, reference number, department, location, status and dates, with a cursor for the next page. Use for \"Which of our jobs are currently sourcing candidates\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words to match in the job title, case insensitive, for example 'java developer'.","title":"Q"},"statuses":{"anyOf":[{"enum":["CREATED","SOURCING","FILLED","INTERVIEW","OFFER","CANCELLED","ON_HOLD"],"type":"string"},{"type":"null"}],"default":null,"description":"One job status to keep: CREATED, SOURCING, FILLED, INTERVIEW, OFFER, CANCELLED or ON_HOLD.","title":"Statuses"},"posting_status":{"anyOf":[{"enum":["PUBLIC","INTERNAL","NOT_PUBLISHED","PRIVATE"],"type":"string"},{"type":"null"}],"default":null,"description":"Where the job is published: PUBLIC, INTERNAL, NOT_PUBLISHED or PRIVATE.","title":"Posting Status"},"department":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Department label to filter by (case sensitive), for example 'Marketing'.","title":"Department"},"city":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"City to filter by (case sensitive), for example 'San Francisco'.","title":"City"},"updated_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only jobs updated after this ISO 8601 time, for example 2026-01-01T00:00:00.000Z.","title":"Updated After"},"sort":{"anyOf":[{"enum":["default","job_id"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: default (newest first, or best match with q) or job_id (required when using page_id).","title":"Sort"},"page_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from nextPageId of the previous page. Needs sort=job_id.","title":"Page Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many jobs to return (1 to 100).","title":"Limit"}},"title":"search_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: title, status, department, location, employment type, experience level, function, industry, compensation ra","description":"Get one job: title, status, department, location, employment type, experience level, function, industry, compensation range, target hiring date and job ad sections. Use for \"Show me the full details of one of our open jobs\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"description":"SmartRecruiters job id (a long identifier returned by search_jobs in the id field).","maxLength":200,"title":"Job Id","type":"string"}},"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_job_positions":{"post":{"operationId":"list_job_positions","summary":"List the positions (headcount slots) of a job with position id, type, open date, target start date and status. Names of ","description":"List the positions (headcount slots) of a job with position id, type, open date, target start date and status. Names of incumbents are not returned. Use for \"How many positions are open for this job and when should they start\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"description":"SmartRecruiters job id (a long identifier returned by search_jobs in the id field).","maxLength":200,"title":"Job Id","type":"string"}},"required":["job_id"],"title":"list_job_positionsArguments","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_status_history":{"post":{"operationId":"get_job_status_history","summary":"Show when a job moved between statuses (created, sourcing, interview, offer, filled ...), newest changes included. Use f","description":"Show when a job moved between statuses (created, sourcing, interview, offer, filled ...), newest changes included. Use for \"When did this job change status\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"description":"SmartRecruiters job id (a long identifier returned by search_jobs in the id field).","maxLength":200,"title":"Job Id","type":"string"}},"required":["job_id"],"title":"get_job_status_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}},"/v1/tools/list_departments":{"post":{"operationId":"list_departments","summary":"List the departments configured in your account with id, label, description and whether they are archived. Use for \"What","description":"List the departments configured in your account with id, label, description and whether they are archived. Use for \"What departments do we have in SmartRecruiters\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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_hiring_processes":{"post":{"operationId":"list_hiring_processes","summary":"List the hiring processes (pipelines) of your account with their name, active flag and the sub-statuses per stage. Use f","description":"List the hiring processes (pipelines) of your account with their name, active flag and the sub-statuses per stage. Use for \"What hiring processes and stages are set up\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_hiring_processesArguments","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_properties":{"post":{"operationId":"list_job_properties","summary":"List the job properties (custom job fields) of your account with key, label, category and whether each is active, visibl","description":"List the job properties (custom job fields) of your account with key, label, category and whether each is active, visible or required. Use for \"Which custom fields can I set on a job\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_job_propertiesArguments","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_predefined_locations":{"post":{"operationId":"list_predefined_locations","summary":"List the predefined locations of your account (title, city, region, country, address, coordinates), paginated. Use for \"","description":"List the predefined locations of your account (title, city, region, country, address, coordinates), paginated. Use for \"Which office locations can be used on jobs\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Locations per page (1 to 5000).","title":"Page Size"},"page_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from nextPageId of the previous page.","title":"Page Id"}},"title":"list_predefined_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_career_sites":{"post":{"operationId":"list_career_sites","summary":"List the career site configurations of your account with name, path, language, published flag and custom URL. Use for \"W","description":"List the career site configurations of your account with name, path, language, published flag and custom URL. Use for \"Which career sites do we publish\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Career sites per page (1 to 100).","title":"Page Size"},"page_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from nextPageId of the previous page.","title":"Page Id"}},"title":"list_career_sitesArguments","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_published_postings":{"post":{"operationId":"list_published_postings","summary":"List the active public job postings of a company (the public Posting API): name, location, department, employment type, ","description":"List the active public job postings of a company (the public Posting API): name, location, department, employment type, release date and language. Use for \"What jobs is a company publicly advertising on SmartRecruiters\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_identifier":{"description":"Company identifier shown by get_company in the identifier field, for example 'AcmeCorp'.","maxLength":200,"title":"Company Identifier","type":"string"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words to match in the posting title or location.","title":"Q"},"country":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Country code filter, for example us or de.","title":"Country"},"city":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"City filter.","title":"City"},"department":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Department id filter (the id, not the label).","title":"Department"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many postings to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many postings to skip.","title":"Offset"}},"required":["company_identifier"],"title":"list_published_postingsArguments","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}}}}