{"openapi":"3.1.0","info":{"title":"Homerun (BYOK) API","version":"0.1.0","description":"Homerun (BYOK) lets an AI assistant read your own Homerun data through the Homerun API with a key you supply (Homerun API key). Read-only: 6 tools (ping, list_vacancies, get_vacancy, list_vacancy_questions, list_tags, list_application_funnel). 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 api.homerun.co....\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-homerun.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-homerun/docs"},"termsOfService":"https://connectorbay.com/byok-homerun/terms"},"servers":[{"url":"https://byok-homerun.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-homerun/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/ping":{"post":{"operationId":"ping","summary":"Check that the Homerun API key is accepted. Returns pong true when the key works. Use for \"Is my Homerun API key valid\".","description":"Check that the Homerun API key is accepted. Returns pong true when the key works. Use for \"Is my Homerun API key valid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"pingArguments","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_vacancies":{"post":{"operationId":"list_vacancies","summary":"List your vacancies with title, status, type, remote flag, dates and links. Add include for location, department, stages","description":"List your vacancies with title, status, type, remote flag, dates and links. Add include for location, department, stages, salary range or candidate counts. Use for \"Which vacancies do we have open in Homerun\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["public","private","draft","closed"],"type":"string"},{"type":"null"}],"default":null,"description":"Vacancy status to keep: public, private, draft or closed.","title":"Status"},"include":{"anyOf":[{"enum":["location","department","stages","salaryIndication","total_candidate_count","page_content"],"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to add to each vacancy: location, department, stages, salaryIndication, total_candidate_count or page_content (the vacancy page text). One value.","title":"Include"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many results per page (1 to 100).","title":"Per Page"}},"title":"list_vacanciesArguments","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_vacancy":{"post":{"operationId":"get_vacancy","summary":"Get one vacancy by id with title, status, type, dates and links; use include to add location, department, stages, salary","description":"Get one vacancy by id with title, status, type, dates and links; use include to add location, department, stages, salary range or page content. Use for \"Show the details and salary range of one vacancy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vacancy_id":{"description":"Homerun vacancy id (starts with job_, as returned by list_vacancies in the id field).","maxLength":200,"title":"Vacancy Id","type":"string"},"include":{"anyOf":[{"enum":["location","department","stages","salaryIndication","total_candidate_count","page_content"],"type":"string"},{"type":"null"}],"default":null,"description":"Extra data to add to each vacancy: location, department, stages, salaryIndication, total_candidate_count or page_content (the vacancy page text). One value.","title":"Include"}},"required":["vacancy_id"],"title":"get_vacancyArguments","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_vacancy_questions":{"post":{"operationId":"list_vacancy_questions","summary":"List the application form questions of a vacancy in all languages: type, whether mandatory and sensitive, and the questi","description":"List the application form questions of a vacancy in all languages: type, whether mandatory and sensitive, and the question titles. Use for \"What questions does the application form of this vacancy ask\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vacancy_id":{"description":"Homerun vacancy id (starts with job_, as returned by list_vacancies in the id field).","maxLength":200,"title":"Vacancy Id","type":"string"}},"required":["vacancy_id"],"title":"list_vacancy_questionsArguments","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 that can be attached to applicants, with id and name. Use for \"Which applicant tags exist in Homerun\".","description":"List the tags that can be attached to applicants, with id and name. Use for \"Which applicant tags exist in Homerun\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many results per page (1 to 100).","title":"Per Page"}},"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_application_funnel":{"post":{"operationId":"list_application_funnel","summary":"List job applications as funnel rows only: id, vacancy id, current stage name, created, hired and first reply dates, and","description":"List job applications as funnel rows only: id, vacancy id, current stage name, created, hired and first reply dates, and flags for disqualified, sourced and consent. Applicant names, contact details, notes and ratings are not returned. Use for \"How many applications are in each stage for this vacancy, and which were hired\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vacancy_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only applications of this vacancy id (starts with job_).","title":"Vacancy Id"},"stage":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only applications in the stage with this name (stage names are per vacancy).","title":"Stage"},"disqualified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only disqualified applications, false for only active ones.","title":"Disqualified"},"hired_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only applications hired after this date (YYYY-MM-DD).","title":"Hired After"},"include":{"anyOf":[{"enum":["stage","vacancy","sources"],"type":"string"},{"type":"null"}],"default":"stage","description":"Add the current stage name to each row (stage), the vacancy (vacancy) or the application sources (sources). One value.","title":"Include"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":15,"description":"How many results per page (1 to 100).","title":"Per Page"}},"title":"list_application_funnelArguments","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}}}}