# Make your first request

> Call the GreenHired API in five minutes: check your key, list jobs in a category and read your own account with a personal key. Code in curl, JS and Python.

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

## Before you start

You need a key. For the public jobs API that is a `ghk_` key, which the GreenHired team issues on request (see [Authentication](https://greenhired.com/developers/api/v1/authentication/)). For your own account it is a `ghpk_` personal key, which you make yourself in about a minute (see [Personal keys](https://greenhired.com/developers/api/v1/personal-keys/)).

The examples read the key from an environment variable, so it never ends up in your code or your shell history:

```bash
export GREENHIRED_API_KEY="ghk_paste_your_key_here"
```

## Check that your key works

`GET /v1/ping` accepts any valid key, counts as one request, and tells you whose key it is, which permissions it has, its limits and what you have used.

**`GET https://api.greenhired.com/v1/ping`**: Check your key. Needs any valid key.

*curl*

```bash
curl -s https://api.greenhired.com/v1/ping \
  -H "Authorization: Bearer $GREENHIRED_API_KEY"
```

*JavaScript*

```javascript
const res = await fetch('https://api.greenhired.com/v1/ping', {
  headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_API_KEY },
});
console.log(await res.json());
```

*Python*

```python
import os, requests

res = requests.get(
    "https://api.greenhired.com/v1/ping",
    headers={"Authorization": "Bearer " + os.environ["GREENHIRED_API_KEY"]},
    timeout=15,
)
print(res.json())
```

A good answer looks like this (the numbers are an example):

```json
{
  "ok": true,
  "key": { "name": "My app", "scopes": ["jobs:read", "categories:read"] },
  "limits": { "requests_per_minute": 60, "requests_per_day": 5000 },
  "usage": {
    "minute": { "used": 1, "remaining": 59, "resets_in_seconds": 42 },
    "today": { "used": 1, "remaining": 4999 }
  }
}
```

If you get a `401`, the key is missing, wrong or revoked. If you get a `503 api_disabled`, the API is switched off at the moment.

## List jobs

This asks for the five newest remote jobs in the renewable energy category. Filters are optional and can be combined.

**`GET https://api.greenhired.com/v1/jobs`** (permission `jobs:read`): List jobs, newest first.

*curl*

```bash
curl -s "https://api.greenhired.com/v1/jobs?category=renewable-energy&work_mode=remote&limit=5" \
  -H "Authorization: Bearer $GREENHIRED_API_KEY"
```

*JavaScript*

```javascript
const url = 'https://api.greenhired.com/v1/jobs?category=renewable-energy&work_mode=remote&limit=5';
const res = await fetch(url, { headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_API_KEY } });
const { data, page } = await res.json();
for (const job of data) console.log(job.title, '-', job.url);
console.log('more pages:', page.has_more);
```

*Python*

```python
import os, requests

res = requests.get(
    "https://api.greenhired.com/v1/jobs",
    params={"category": "renewable-energy", "work_mode": "remote", "limit": 5},
    headers={"Authorization": "Bearer " + os.environ["GREENHIRED_API_KEY"]},
    timeout=15,
)
res.raise_for_status()
body = res.json()
for job in body["data"]:
    print(job["title"], "-", job["url"])
print("more pages:", body["page"]["has_more"])
```

Each job has a `url` on greenhired.com. When you show a job anywhere, link to that `url` next to it. See [Attribution](https://greenhired.com/developers/api/v1/attribution/). To get the next page, send `page.next_cursor` back as `cursor` with the same filters: see [Pagination](https://greenhired.com/developers/api/v1/pagination/).

## Read your own account

A personal key works against the account API. This call says who the key belongs to and what it may do:

**`GET https://api.greenhired.com/v1/assistant/me`**: Who am I. Needs any valid personal key.

*curl*

```bash
curl -s https://api.greenhired.com/v1/assistant/me \
  -H "Authorization: Bearer $GREENHIRED_PERSONAL_KEY"
```

*JavaScript*

```javascript
const res = await fetch('https://api.greenhired.com/v1/assistant/me', {
  headers: { Authorization: 'Bearer ' + process.env.GREENHIRED_PERSONAL_KEY },
});
console.log(await res.json());
```

*Python*

```python
import os, requests

res = requests.get(
    "https://api.greenhired.com/v1/assistant/me",
    headers={"Authorization": "Bearer " + os.environ["GREENHIRED_PERSONAL_KEY"]},
    timeout=15,
)
print(res.json())
```

**A job seeker's answer**

```json
{ "type": "job_seeker", "name": "Mia", "key": "my job tracker", "scopes": ["profile:read", "saved:read"] }
```

> **Info:** On the account API, send a JSON body with `Content-Type: application/json`. Calls that have no body (publish, close, delete) need no header.

## Where to go next

- Job seekers: [Job seeker API](https://greenhired.com/developers/api/v1/seekers/)
- Employers: [Employer API](https://greenhired.com/developers/api/v1/employers/) and [Manage jobs](https://greenhired.com/developers/api/v1/employer-jobs/)
- Apps and partners: [List jobs](https://greenhired.com/developers/api/v1/jobs/), [Categories](https://greenhired.com/developers/api/v1/categories/) and [Salary statistics](https://greenhired.com/developers/api/v1/salaries/)
- AI assistants: [MCP server](https://greenhired.com/developers/mcp/)

## Frequently asked questions

**Why do I get 401 on a request that worked yesterday?**

The key was revoked, it expired (personal keys last 90 days unless you chose otherwise), or it is a personal key and the account password changed. A password change ends every personal key. Make a new one.

**How many requests do I get?**

Public API keys default to 60 a minute and 5,000 a day, and your key may differ: `GET /v1/ping` shows yours. Personal keys have their own limits. See [Rate limits](https://greenhired.com/developers/api/v1/limits/).

**Does ping count against my limit?**

Yes. It counts as one request. It is still the quickest way to see your key's name, permissions, limits and what you have used.

**Which language should I use?**

Any. It is plain HTTPS and JSON. The examples use curl, JavaScript (Node 18 or later) and Python with the `requests` package.

## Related pages

- https://greenhired.com/developers/api/v1/authentication/
- https://greenhired.com/developers/api/v1/jobs/
- https://greenhired.com/developers/api/v1/personal-keys/
