API reference · Reference

Versioning and changes

GreenHired API version 1 only grows. What can change, what never will, how a breaking change would be announced, and a dated list of changes to the API.

2 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. The promise
  2. Public names
  3. What is in version 1
  4. Changes
  5. Frequently asked questions

#The promise

Version 1 is additive only. Inside /v1 we may add endpoints, add fields to an answer, add a value to an enum that says so, and add optional parameters. We never remove or rename a field, change its type or meaning, or make an optional parameter required.

So read the fields you need and ignore the rest. A breaking change would be /v2, announced in advance, with /v1 running alongside it. Every public answer carries X-API-Version: 1.

#Public names

Field names are public names. They do not follow GreenHired's own table or column names, so changes inside GreenHired do not reach you. Times are ISO 8601 in UTC, and the salary figures are as the employer wrote them.

#What is in version 1

AreaCalls
Public jobs APIGET /v1/ping, GET /v1/jobs, GET /v1/jobs/{slug}, GET /v1/categories, GET /v1/insights/salaries, GET /v1/openapi.json
Account API, job seekersGET /me, GET and PATCH /profile, GET /applications, GET /saved, PUT and DELETE /saved/{slug}
Account API, employersGET /company, GET /jobs, GET /jobs/{slug}, POST /jobs, PATCH /jobs/{slug}, POST /jobs/{slug}/publish, POST /jobs/{slug}/close, DELETE /jobs/{slug}
MCP serverTools for jobs, categories and your own account

#Changes

DateChange
21 November 2026Account API: personal API keys for job seekers and employers; the employer jobs API (create, change, publish, close, remove); company rules for who may connect and whether keys may change jobs; these developer docs.

#Frequently asked questions

How will I hear about a breaking change?
A breaking change would be a new version path, /v2, announced before it ships, with /v1 running alongside it. Until then nothing in /v1 is removed or renamed.
Does the account API follow the same promise?
Yes. Its path is also v1, and it only grows: new calls and fields can appear, and nothing is removed or renamed.
Where do I report a bug in the docs?
Use the feedback buttons at the bottom of any page, or write to support@greenhired.com.