Source: https://www.puesto.dev/docs
Markdown source: https://www.puesto.dev/docs.md
Description: A REST API for searching and retrieving job postings, with cursor pagination and a rich set of filters.

# Introduction



The Jobs API is a read-only REST API for searching and retrieving job postings.
It exposes two resources — a paginated job search and a single job lookup — both
returning JSON.

## Base URL [#base-url]

All endpoints live under the `/api/v1` prefix:

```
https://www.puesto.dev/api/v1
```

## Authentication [#authentication]

Every request must include a secret API key (prefixed `sk_`) as a bearer token:

```
Authorization: Bearer sk_your_key_here
```

Create and manage keys from your [team's](/home) **API Keys** settings. See
[Authentication](/docs/authentication) for details.

## Quickstart [#quickstart]

Fetch the three most recent jobs in the United States:

```bash
curl "https://www.puesto.dev/api/v1/jobs?country=US&limit=3" \
  -H "Authorization: Bearer sk_your_key_here"
```

A successful response is a page of job summaries plus a `next_cursor` for
fetching the following page:

```json
{
  "data": [
    {
      "id": 12345,
      "title": "Senior Software Engineer",
      "country_code": "US",
      "workplace": "remote",
      "posted_at": "2024-05-01T12:00:00Z",
      "company": {
        "id": 67,
        "name": "Acme Inc.",
        "website_url": "https://acme.example",
        "logo_url": null
      }
    }
  ],
  "next_cursor": "eyJ2IjoicG9zdGVkX2F0Ii...",
  "limit": 3
}
```

## Next steps [#next-steps]

* [Authentication](/docs/authentication) — how to create and use API keys.
* [Pagination](/docs/pagination) — the cursor model, sorting, and the default
  freshness window.
* [Errors](/docs/errors) — the `application/problem+json` error format.
* [API Reference](/docs/api/jobs/search-jobs) — the full, auto-generated
  reference with an interactive playground.