API reference · Start here

GreenHired API overview

GreenHired has two REST APIs: a read-only jobs API for apps and partners, and an account API for job seekers and employers to use their own data and jobs.

3 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. Two APIs, one version
  2. Which one do you need?
  3. What is the same in both
  4. Frequently asked questions

#Two APIs, one version

GreenHired offers two REST APIs, both JSON over HTTPS and both at version 1. The public jobs API lets your app read green jobs, the 28 job categories and salary statistics. The account API lets a job seeker or an employer work with their own GreenHired account from their own scripts and systems.

ItemPublic jobs APIAccount API
Base URLhttps://api.greenhired.com/v1https://api.greenhired.com/v1/assistant
ForApps, researchers and partners that show or analyse green jobsOne job seeker or one employer, working with their own account
What it doesReads jobs, job detail, categories and salary statisticsSeekers read their profile, applications and saved jobs. Employers read their company and manage its jobs
CredentialAn API key that starts with ghk_A personal key that starts with ghpk_
How you get itOn request, from the GreenHired teamYou make it yourself on your account page
Writes dataNever. Every call is a GETOnly what you allow: your profile and saved jobs (seekers), your company's jobs (employers)

Both send the key as Authorization: Bearer <key>. Neither is meant to be called from a web page, because that would put your key in front of every visitor. New here? Start with the quickstart.

#Which one do you need?

You want toUseStart with
Show GreenHired jobs in your app or on your sitePublic jobs APIList jobs
Chart pay by category or countryPublic jobs APISalary statistics
Keep your own tracker in step with your applications and saved jobsAccount API, job seekerJob seeker API
Sync your careers site or ATS with the jobs on GreenHiredAccount API, employerManage jobs
Let an AI assistant search jobs or act for a personMCP serverMCP overview

#What is the same in both

  • One host. Every GreenHired API is at api.greenhired.com. Addresses under greenhired.com/api/ belong to the website's own pages: they are not an API we offer, support or document, and they can change at any time.
  • Every answer is JSON. Times are ISO 8601 in UTC.
  • A key is shown once, when it is made. We keep only a fingerprint, so a lost key cannot be recovered: make a new one.
  • Each key has a per-minute limit and a daily cap. See Rate limits.
  • Errors have a stable code you can program against. See Errors. The two APIs word the error body a little differently.
  • Version 1 only grows: new endpoints and fields can appear, nothing is removed or renamed. See Versioning.

#Frequently asked questions

Is there a free-text search?
Not in version 1. GET /v1/jobs filters by category, country, work mode, employment type, seniority, company, posting date and pay. A request with a q parameter is refused with a clear unknown_parameter error rather than ignored.
Can I call the API from a browser?
Do not. Keep the key on your server and send visitors your own pages or your own endpoint. Anything in browser code can be read by every visitor.
Does the public API ever change data?
No. It is read-only, and every endpoint is a GET. Changing data is only possible with the account API, with a personal key you made yourself.
Where is the machine-readable description?
The public API publishes an OpenAPI 3.1 file at https://api.greenhired.com/v1/openapi.json. It needs no key. See OpenAPI and tool lists.