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

All endpoints live under the /api/v1 prefix:

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

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 API Keys settings. See Authentication for details.

Quickstart

Fetch the three most recent jobs in the United States:

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:

{
  "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

• Authentication — how to create and use API keys.
• Pagination — the cursor model, sorting, and the default freshness window.
• Errors — the application/problem+json error format.
• API Reference — the full, auto-generated reference with an interactive playground.