API reference · Reference

OpenAPI file and tool lists

The public jobs API is described by an OpenAPI 3.1 file you can fetch without a key, and the MCP server publishes a JSON Schema for each tool.

1 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. The OpenAPI file
  2. The account API
  3. MCP tool schemas
  4. Frequently asked questions

#The OpenAPI file

The public jobs API is described by an OpenAPI 3.1 document. It needs no key, is public, and can be cached for an hour. A test in the API's own repository fails if the code and this file ever differ, so it is the source of truth for field names and parameters.

GET/v1/openapi.jsonapi.greenhired.comany valid key

The OpenAPI 3.1 description of the public jobs API. No key.

curl -s https://api.greenhired.com/v1/openapi.json -o greenhired-openapi.json

Load it in any tool that reads OpenAPI 3.1, such as an API client or a code generator. The key goes in the Authorization header as a bearer token (the file declares both bearerAuth and an X-API-Key header scheme).

#The account API

The account API (personal keys) has no OpenAPI file yet. The pages in this section are its reference: Job seeker API, Employer API and Manage jobs.

#MCP tool schemas

The MCP server returns every tool with a JSON Schema for its arguments from tools/list, built from the same contract as the endpoints. See MCP tools.

#Frequently asked questions

Can I generate a client library from it?
Yes, with any generator that supports OpenAPI 3.1. Check the result against the examples in these docs before you rely on it.
Does the file need a key?
No. GET /v1/openapi.json is public, so a build tool or a documentation viewer can fetch it. Every other endpoint needs a key.
Will the file change?
Version 1 only grows: new endpoints, fields and optional parameters can appear, and nothing is removed or renamed. See Versioning.