{"openapi":"3.1.0","info":{"title":"USAJOBS (BYOK) API","version":"0.1.0","description":"USAJOBS (BYOK) lets an AI assistant read your own USAJOBS data through the USAJOBS API with a key you supply (USAJOBS API key). Read-only: 6 tools (search_jobs, list_agencies, list_job_series, list_hiring_paths, list_pay_plans, list_security_clearances). 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...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-usajobs.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-usajobs/docs"},"termsOfService":"https://connectorbay.com/byok-usajobs/terms"},"servers":[{"url":"https://byok-usajobs.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-usajobs/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/search_jobs":{"post":{"operationId":"search_jobs","summary":"Search current federal job announcements by keyword, title, place, agency, salary, grade, remote status, hiring path or ","description":"Search current federal job announcements by keyword, title, place, agency, salary, grade, remote status, hiring path or posting age; returns titles, agencies, locations, pay ranges and apply links. Fields=Min keeps answers short. Use for \"Which remote federal data scientist jobs were posted in the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"keyword":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words matched anywhere in the announcement, synonyms included.","title":"Keyword"},"position_title":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words contained in the job title.","title":"Position Title"},"location_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"City and state, or several separated by semicolons, for example 'Denver, Colorado'.","title":"Location Name"},"radius":{"anyOf":[{"maximum":1000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Search radius around the location (used with location_name).","title":"Radius"},"organization":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Agency sub-element code (from list_agencies), several separated by semicolons.","title":"Organization"},"job_category_code":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Occupational series code (from list_job_series), several separated by semicolons.","title":"Job Category Code"},"remote":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for remote jobs only, false to leave them out; omit to include both.","title":"Remote"},"date_posted":{"anyOf":[{"maximum":60,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only announcements posted within this many days (0 to 60).","title":"Date Posted"},"pay_grade_low":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Lowest pay grade, 01 to 15.","title":"Pay Grade Low"},"pay_grade_high":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Highest pay grade, 01 to 15.","title":"Pay Grade High"},"salary_min":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Minimum salary amount.","title":"Salary Min"},"salary_max":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Maximum salary amount.","title":"Salary Max"},"hiring_path":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Who may apply, for example public, vet, student, disability, graduates; several separated by semicolons.","title":"Hiring Path"},"schedule_type":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Schedule code: 1 full-time, 2 part-time, 3 shift, 4 intermittent, 5 job sharing, 6 multiple; several separated by semicolons.","title":"Schedule Type"},"sort_field":{"anyOf":[{"enum":["opendate","closedate","organizationname","jobtitle","positiontitle","salarymin","location","department","title","agency","salary"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort field.","title":"Sort Field"},"sort_direction":{"anyOf":[{"enum":["Asc","Desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Asc or Desc.","title":"Sort Direction"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"results_per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Announcements per page (1 to 50).","title":"Results Per Page"},"fields":{"anyOf":[{"enum":["Min","Full"],"type":"string"},{"type":"null"}],"default":"Min","description":"Min for a short record or Full for the whole announcement.","title":"Fields"}},"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/list_agencies":{"post":{"operationId":"list_agencies","summary":"List agency sub-element codes and names, used for the organization filter of search_jobs. Each entry has Code, Value, La","description":"List agency sub-element codes and names, used for the organization filter of search_jobs. Each entry has Code, Value, LastModified and IsDisabled. This list needs no key on USAJOBS, but the call is sent with yours like the others. Use for \"What is the USAJOBS code for the Forest Service\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"last_modified":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only return entries modified on or after this date (for example 2026-01-01).","title":"Last Modified"}},"title":"list_agenciesArguments","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_series":{"post":{"operationId":"list_job_series","summary":"List occupational series codes and job category names, used for the job_category_code filter of search_jobs. Each entry ","description":"List occupational series codes and job category names, used for the job_category_code filter of search_jobs. Each entry has Code, Value, LastModified and IsDisabled. This list needs no key on USAJOBS, but the call is sent with yours like the others. Use for \"What is the occupational series code for IT management\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"last_modified":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only return entries modified on or after this date (for example 2026-01-01).","title":"Last Modified"}},"title":"list_job_seriesArguments","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_paths":{"post":{"operationId":"list_hiring_paths","summary":"List hiring path codes (who may apply), used for the hiring_path filter of search_jobs. Each entry has Code, Value, Last","description":"List hiring path codes (who may apply), used for the hiring_path filter of search_jobs. Each entry has Code, Value, LastModified and IsDisabled. This list needs no key on USAJOBS, but the call is sent with yours like the others. Use for \"Which hiring paths does USAJOBS define\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"last_modified":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only return entries modified on or after this date (for example 2026-01-01).","title":"Last Modified"}},"title":"list_hiring_pathsArguments","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_pay_plans":{"post":{"operationId":"list_pay_plans","summary":"List federal pay plan codes with descriptions. Each entry has Code, Value, LastModified and IsDisabled. This list needs ","description":"List federal pay plan codes with descriptions. Each entry has Code, Value, LastModified and IsDisabled. This list needs no key on USAJOBS, but the call is sent with yours like the others. Use for \"What pay plans exist on USAJOBS\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"last_modified":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only return entries modified on or after this date (for example 2026-01-01).","title":"Last Modified"}},"title":"list_pay_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_security_clearances":{"post":{"operationId":"list_security_clearances","summary":"List security clearance codes and names. Each entry has Code, Value, LastModified and IsDisabled. This list needs no key","description":"List security clearance codes and names. Each entry has Code, Value, LastModified and IsDisabled. This list needs no key on USAJOBS, but the call is sent with yours like the others. Use for \"Which security clearance levels does USAJOBS use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"last_modified":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only return entries modified on or after this date (for example 2026-01-01).","title":"Last Modified"}},"title":"list_security_clearancesArguments","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}}}}