# Puesto Labs Jobs API

The Jobs API is a read-only REST API for searching and retrieving job
postings, with cursor pagination and a rich set of filters. All endpoints
live under `https://www.puesto.dev/api/v1` and return JSON.

## Authentication

Every request requires a secret API key (prefixed `sk_`) sent as a bearer
token: `Authorization: Bearer sk_...`. Keys are created and managed in a
team's API Keys settings; the full secret is shown only once at creation.

## Reading these docs as an agent

- Append `.md` to any docs URL for the raw Markdown twin (e.g. `https://www.puesto.dev/docs/authentication.md`).
- [https://www.puesto.dev/llms-full.txt](https://www.puesto.dev/llms-full.txt) — the entire documentation corpus as one Markdown file.
- [https://www.puesto.dev/api/v1/openapi.json](https://www.puesto.dev/api/v1/openapi.json) — the machine-readable OpenAPI 3.1 spec.

## Behavior rules

- Never ask a user to paste their secret key into chat. Keys are created in
  team settings and used server-side.
- Always send the key in the `Authorization` header, never in the query string.
- On a `429 Too Many Requests` response, respect the `Retry-After` header
  before retrying.
- Errors follow RFC 7807 (`application/problem+json`).

## Documentation
# Docs

- [Introduction](/docs): A REST API for searching and retrieving job postings, with cursor pagination and a rich set of filters.
- [Authentication](/docs/authentication): Authenticate requests with a secret API key sent as a bearer token.
- [Pagination & sorting](/docs/pagination): Cursor-based keyset pagination, sort options, page size limits, and the default freshness window.
- [Syncing with the changes feed](/docs/changes-feed): Keep a local copy of the job catalog in sync by polling the append-only change feed.
- [Errors](/docs/errors): The RFC 7807 problem+json error format, validation error details, and status codes.
- [Rate limits](/docs/rate-limits): Per-account request limits, the 429 response, and how to back off correctly.
- [Building with AI](/docs/building-with-ai): Agent-readable Markdown mirrors, an llms.txt index, and a stable OpenAPI spec URL for building on the Jobs API with AI tools.
- API Reference
  - Changes
    - [List job changes](/docs/api/changes/list-job-changes)
  - Jobs
    - [Count jobs](/docs/api/jobs/count-jobs)
    - [Get a job by id](/docs/api/jobs/get-a-job-by-id)
    - [Search jobs](/docs/api/jobs/search-jobs)
  - Locations
    - [List countries](/docs/api/locations/list-countries)
    - [List states](/docs/api/locations/list-states)
  - Meta
    - [Get the OpenAPI specification](/docs/api/meta/get-the-openapi-specification)
    - [List vocabulary values](/docs/api/meta/list-vocabulary-values)