{"openapi":"3.1.0","info":{"title":"Ashby Hiring Process (BYOK) API","version":"0.1.0","description":"Ashby Hiring Process (BYOK) lets an AI assistant read your own Ashby Hiring Process data through the Ashby Hiring Process API with a key you supply (Ashby API key (hiringProcessMetadataRead and interviewsRead permissions)). Read-only: 12 tools (list_archive_reasons, list_close_reasons, list_custom_fields, list_candidate_tags, list_source_tracking_links, list_survey_form_definitions,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-ashby-hiring-process.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-ashby-hiring-process/docs"},"termsOfService":"https://connectorbay.com/byok-ashby-hiring-process/terms"},"servers":[{"url":"https://byok-ashby-hiring-process.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-ashby-hiring-process/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_archive_reasons":{"post":{"operationId":"list_archive_reasons","summary":"List the reasons used when archiving a candidate application: text, type (rejected by candidate, by organization, other)","description":"List the reasons used when archiving a candidate application: text, type (rejected by candidate, by organization, other) and archived flag. Needs the hiringProcessMetadataRead permission. Use for \"Which archive reasons are configured in Ashby\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also include archived archive reasons.","title":"Include Archived"}},"title":"list_archive_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_close_reasons":{"post":{"operationId":"list_close_reasons","summary":"List the reasons used when closing a job or opening: text and archived flag. Needs the hiringProcessMetadataRead permiss","description":"List the reasons used when closing a job or opening: text and archived flag. Needs the hiringProcessMetadataRead permission. Use for \"Which close reasons does Ashby have for jobs\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also include archived close reasons.","title":"Include Archived"}},"title":"list_close_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_custom_fields":{"post":{"operationId":"list_custom_fields","summary":"List custom field definitions (title, object type, field type, required flag, private flag, selectable values). Definiti","description":"List custom field definitions (title, object type, field type, required flag, private flag, selectable values). Definitions only, no values. Needs the hiringProcessMetadataRead permission. Use for \"What custom fields are defined in Ashby\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: leave out for the first page, or pass the nextCursor value from the previous answer.","title":"Cursor"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also include archived custom fields.","title":"Include Archived"}},"title":"list_custom_fieldsArguments","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 candidate tags with id, title and archived flag. Needs the hiringProcessMetadataRead permission. Use for \"What cand","description":"List candidate tags with id, title and archived flag. Needs the hiringProcessMetadataRead permission. Use for \"What candidate tags exist in Ashby\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: leave out for the first page, or pass the nextCursor value from the previous answer.","title":"Cursor"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also include archived candidate tags.","title":"Include Archived"}},"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_source_tracking_links":{"post":{"operationId":"list_source_tracking_links","summary":"List custom source tracking links (code, link, source id, enabled flag), optionally for one source. Needs the hiringProc","description":"List custom source tracking links (code, link, source id, enabled flag), optionally for one source. Needs the hiringProcessMetadataRead permission. Use for \"What source tracking links are set up in Ashby\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: leave out for the first page, or pass the nextCursor value from the previous answer.","title":"Cursor"},"source_id":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only tracking links of the source with this id.","title":"Source Id"},"include_disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also include disabled links.","title":"Include Disabled"}},"title":"list_source_tracking_linksArguments","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_survey_form_definitions":{"post":{"operationId":"list_survey_form_definitions","summary":"List survey form definitions (title, survey type such as EEOC, Diversity or CandidateExperience, archived flag and the f","description":"List survey form definitions (title, survey type such as EEOC, Diversity or CandidateExperience, archived flag and the form structure). Definitions only, no submissions. Needs the hiringProcessMetadataRead permission. Use for \"What survey forms are defined in Ashby\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: leave out for the first page, or pass the nextCursor value from the previous answer.","title":"Cursor"}},"title":"list_survey_form_definitionsArguments","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_feedback_form_definitions":{"post":{"operationId":"list_feedback_form_definitions","summary":"List interview feedback form definitions (title, default flag, archived flag and the form structure). Definitions only, ","description":"List interview feedback form definitions (title, default flag, archived flag and the form structure). Definitions only, no submitted feedback. Needs the hiringProcessMetadataRead permission. Use for \"What interview feedback forms exist in Ashby\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: leave out for the first page, or pass the nextCursor value from the previous answer.","title":"Cursor"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also include archived feedback forms.","title":"Include Archived"}},"title":"list_feedback_form_definitionsArguments","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_interview_plans":{"post":{"operationId":"list_interview_plans","summary":"List published interview plans with title, archived flag and dates. Needs the hiringProcessMetadataRead permission. Use ","description":"List published interview plans with title, archived flag and dates. Needs the hiringProcessMetadataRead permission. Use for \"What interview plans does Ashby have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: leave out for the first page, or pass the nextCursor value from the previous answer.","title":"Cursor"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also include archived interview plans.","title":"Include Archived"}},"title":"list_interview_plansArguments","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_interview_stages":{"post":{"operationId":"list_interview_stages","summary":"List the stages of one interview plan in order: title, type and position. Needs the interviewsRead permission. Use for \"","description":"List the stages of one interview plan in order: title, type and position. Needs the interviewsRead permission. Use for \"What stages are in Ashby interview plan ip1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"interview_plan_id":{"description":"Interview plan id (from list_interview_plans).","maxLength":60,"title":"Interview Plan Id","type":"string"}},"required":["interview_plan_id"],"title":"list_interview_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_interview_stage_groups":{"post":{"operationId":"list_interview_stage_groups","summary":"List the interview stage groups of the organization in order: title, order and stage type. Needs the interviewsRead perm","description":"List the interview stage groups of the organization in order: title, order and stage type. Needs the interviewsRead permission. Use for \"What interview stage groups exist in Ashby\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_interview_stage_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_interviewer_pools":{"post":{"operationId":"list_interviewer_pools","summary":"List interviewer pools with title, archived flag and training path. Needs the hiringProcessMetadataRead permission. Use ","description":"List interviewer pools with title, archived flag and training path. Needs the hiringProcessMetadataRead permission. Use for \"What interviewer pools exist in Ashby\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: leave out for the first page, or pass the nextCursor value from the previous answer.","title":"Cursor"}},"title":"list_interviewer_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_communication_templates":{"post":{"operationId":"list_communication_templates","summary":"List enabled email communication templates: id, title, dates and intended types. Template bodies are not returned. Needs","description":"List enabled email communication templates: id, title, dates and intended types. Template bodies are not returned. Needs the hiringProcessMetadataRead permission. Use for \"What email templates exist in Ashby\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ownership_filter":{"anyOf":[{"enum":["org","personal","personalAndOrg"],"type":"string"},{"type":"null"}],"default":"org","description":"Which templates: org (organization), personal (the key owner's) or personalAndOrg.","title":"Ownership Filter"}},"title":"list_communication_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}}}}