{"openapi":"3.1.0","info":{"title":"JOIN (BYOK) API","version":"0.1.0","description":"JOIN (BYOK) lets an AI assistant read your own JOIN data through the JOIN API with a key you supply (JOIN API token). Read-only: 10 tools (list_jobs, get_job, list_applications, get_application, list_application_scorecards, list_candidates, list_offices, list_categories, list_employment_types, list_seniority_levels). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-join.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-join/docs"},"termsOfService":"https://connectorbay.com/byok-join/terms"},"servers":[{"url":"https://byok-join.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-join/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_jobs":{"post":{"operationId":"list_jobs","summary":"List job ads with title, status, remote flag, office, salary range and dates. Active (ONLINE) jobs by default. Use for \"","description":"List job ads with title, status, remote flag, office, salary range and dates. Active (ONLINE) jobs by default. Use for \"Which jobs are currently online in JOIN\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"ONLINE","description":"Job status, or several separated by commas: ONLINE, OFFLINE, ARCHIVED. Defaults to ONLINE.","title":"Status"},"title_like":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Partial match on the job title.","title":"Title Like"},"country_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO 3166-1 country code of the job.","title":"Country Code"},"sort":{"anyOf":[{"enum":["createdAt","-createdAt","lastUpdatedAt","-lastUpdatedAt"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: createdAt, -createdAt, lastUpdatedAt or -lastUpdatedAt (default -createdAt).","title":"Sort"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 50).","title":"Page Size"}},"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 ad by id with description, office, salary, employment type, category, seniority and hiring team roles. Use f","description":"Get one job ad by id with description, office, salary, employment type, category, seniority and hiring team roles. Use for \"Show the details of JOIN job 123456\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"description":"Numeric JOIN job id from list_jobs.","title":"Job Id","type":"integer"}},"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_applications":{"post":{"operationId":"list_applications","summary":"List job applications with job, candidate name and country, hiring state, pipeline stage and dates (no contact details o","description":"List job applications with job, candidate name and country, hiring state, pipeline stage and dates (no contact details or answers). Use for \"How many applications are in the interview stage in JOIN\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only applications for this job id.","title":"Job Id"},"hiring_state":{"anyOf":[{"enum":["APPLIED","ACTIVE","REJECTED","HIRED","OFFER"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by state: APPLIED, ACTIVE, REJECTED, HIRED or OFFER.","title":"Hiring State"},"stage_type":{"anyOf":[{"enum":["APPLIED","APPLICATION_REVIEW","INTERVIEW","OFFER","HIRED"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by pipeline stage: APPLIED, APPLICATION_REVIEW, INTERVIEW, OFFER or HIRED.","title":"Stage Type"},"created_at_gte":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only applications created at or after this date or date-time.","title":"Created At Gte"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 50).","title":"Page Size"}},"title":"list_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/get_application":{"post":{"operationId":"get_application","summary":"Get one application by id: job, candidate name and country, hiring state, pipeline stage and consent status. Use for \"Sh","description":"Get one application by id: job, candidate name and country, hiring state, pipeline stage and consent status. Use for \"Show the status of JOIN application 7890\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"application_id":{"description":"Numeric application id from list_applications.","title":"Application Id","type":"integer"}},"required":["application_id"],"title":"get_applicationArguments","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_scorecards":{"post":{"operationId":"list_application_scorecards","summary":"List the interview scorecards for one application with overall recommendation and impression. Use for \"What scorecards w","description":"List the interview scorecards for one application with overall recommendation and impression. Use for \"What scorecards were submitted for JOIN application 7890\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"application_id":{"description":"Numeric application id from list_applications.","title":"Application Id","type":"integer"}},"required":["application_id"],"title":"list_application_scorecardsArguments","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, country, source, tags and the jobs they applied to (no email, phone or notes). Use for \"Find ","description":"List candidates with name, country, source, tags and the jobs they applied to (no email, phone or notes). Use for \"Find JOIN candidates named Smith\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Fuzzy search on email, first name and last name.","title":"Search"},"created_at_gte":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only candidates created at or after this ISO 8601 time.","title":"Created At Gte"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 50).","title":"Page Size"}},"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/list_offices":{"post":{"operationId":"list_offices","summary":"List the company offices with name, city, country and whether each is the default office. Use for \"Which offices are set","description":"List the company offices with name, city, country and whether each is the default office. Use for \"Which offices are set up in JOIN\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country_code":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter ISO 3166-1 country code.","title":"Country Code"},"city_name_like":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Partial match on the city name.","title":"City Name Like"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 50).","title":"Page Size"}},"title":"list_officesArguments","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_categories":{"post":{"operationId":"list_categories","summary":"List the job categories and their sub-categories that can be set on a job. Use for \"What job categories does JOIN offer\"","description":"List the job categories and their sub-categories that can be set on a job. Use for \"What job categories does JOIN offer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"language":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":"en","description":"Language code for the translated names, for example en or de.","title":"Language"}},"title":"list_categoriesArguments","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_employment_types":{"post":{"operationId":"list_employment_types","summary":"List the employment types (for example full-time) used on jobs, with their ids. Use for \"What employment types exist in ","description":"List the employment types (for example full-time) used on jobs, with their ids. Use for \"What employment types exist in JOIN\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"language":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":"en","description":"Language code for the translated names, for example en or de.","title":"Language"}},"title":"list_employment_typesArguments","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_seniority_levels":{"post":{"operationId":"list_seniority_levels","summary":"List the seniority levels used on jobs, with their ids. Use for \"What seniority levels are available in JOIN\".","description":"List the seniority levels used on jobs, with their ids. Use for \"What seniority levels are available in JOIN\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"language":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":"en","description":"Language code for the translated names, for example en or de.","title":"Language"}},"title":"list_seniority_levelsArguments","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}}}}