# 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.

- Source: https://greenhired.com/developers/api/v1/openapi/
- Section: GreenHired developers · API · Reference
- Last updated: 2026-11-21

## 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 https://api.greenhired.com/v1/openapi.json`**: The OpenAPI 3.1 description of the public jobs API. No key.

*curl*

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

*Python*

```python
import requests

spec = requests.get("https://api.greenhired.com/v1/openapi.json", timeout=15).json()
print(sorted(spec["paths"]))
# ['/categories', '/insights/salaries', '/jobs', '/jobs/{slug}', '/openapi.json', '/ping']
```

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](https://greenhired.com/developers/api/v1/seekers/), [Employer API](https://greenhired.com/developers/api/v1/employers/) and [Manage jobs](https://greenhired.com/developers/api/v1/employer-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](https://greenhired.com/developers/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](https://greenhired.com/developers/api/v1/versioning/).

## Related pages

- https://greenhired.com/developers/api/v1/versioning/
- https://greenhired.com/developers/api/v1/jobs/
- https://greenhired.com/developers/mcp/tools/
