# Give your agent job data it can cite

- Canonical page: https://jobopportunitiesapi.org/for/ai-agents
- Description: Job and company data for AI agents, with per-field provenance so a model can tell what an employer stated from what we derived. Worked examples with tool definitions for Claude and GPT, plus a remote MCP server at api.jobopportunitiesapi.org/mcp.
- This is the Markdown version of the page above, generated from the page itself. Links to other pages on this site point to their Markdown versions (addresses ending in .md) where one exists, so you can keep navigating in Markdown; every other link is an absolute address.

For AI agents

Building a job-search agent, a sourcing assistant, or retrieval over labour-market data? Every row carries `field_sources`, which marks each field `published` (the employer said it) or `inferred` (we derived it). Your agent can then tell the two apart instead of presenting guesses as facts. Closed roles stay in the ledger with a closure date, so an agent can say “this role closed on 12 September” instead of sending someone to a dead link.

Start with [the MCP server](https://jobopportunitiesapi.org/docs/ai/mcp.md), a remote endpoint your agent can point at directly from Claude, Cursor, Windsurf, VS Code or Cline with the same key, metering and plan limits as the REST API, or use [llms.txt](https://jobopportunitiesapi.org/llms.txt) or the [worked examples](https://github.com/lucagiftzek/joa-examples), which include tool definitions for Claude and GPT, or the OpenAPI spec and plain HTTP. 1,000 records a month are free, no card.

[Get a free key →](https://jobopportunitiesapi.org/login?ref=for-ai) [Read llms.txt](https://jobopportunitiesapi.org/llms.txt)

Explore is free forever, no card: 1,000 records a month against every endpoint. Outgrow that and Starter is €29 / month for 10,000 records, or Growth is €80 / month for 60,000 records with the incremental delta feed, both self-serve, no call required. [See the full ladder →](https://jobopportunitiesapi.org/pricing.md)

## Check our numbers right now: no key, no account

```
GET https://api.jobopportunitiesapi.org/public/facets
```

Loading live counts…

**One job row, as a key returns it.** A real row captured on 2026-08-03, shown as an example, not a live call. The counts above are what you can check without one.

```
{
  "data": [
    {
      "id": "8f2c…", "slug": "backend-engineer-8f2c1a4b",
      "title": "Backend Engineer", "company": "Nordbridge Labs",
      "company_slug": "nordbridge-labs",
      "category": "Engineering", "category_confidence": 0.82,
      "country": "DE", "city": "Berlin",
      "remote": "hybrid", "remote_inferred": false,
      "employment_type": "Full-time", "seniority": "Senior",
      "posted_at": "2026-07-12T09:00:00Z",
      "last_verified_at": "2026-08-03T04:00:00Z",
      "status": "live", "closed_at": null, "closed_reason": null,
      "source": "greenhouse",
      "source_type": "ats", "provider_type": "employer_ats",
      "has_description": true,
      "description": "We're looking for a backend engineer to join our platform team, "
        + "building the services that route millions of jobs a day. You'll work mostly in "
        + "Go, own a service end to end, and be on a small rotation for on-call. Remote "
        + "within the EU, or hybrid from our Berlin office two days a week.",
      "field_sources": {
        "remote": "published", "employment_type": "published",
        "category": "inferred", "seniority": "inferred",
        "salary": "absent", "location": "published",
        "posted_at": "published", "description": "published",
        "source_type": "inferred"
      }
    }
  ],
  "next_cursor": null,
  "has_more": true
}
```

Keyless requests return the ledger’s shape: counts, coverage and freshness. Job and company rows need a key. A free Primary key takes about a minute, needs no card, and gives you 1,000 records a month that never expire.

[Get a free key →](https://jobopportunitiesapi.org/login?ref=api)

1. Enter your email.
2. Click the link we send.
3. Press “Create a free Primary key”. No card, and nothing to cancel.

## What an agent gets that HTML does not

- **Provenance per field.** `field_sources` marks every field `published`, `inferred` or `absent`: an agent that has to decide how much to trust a field can read the answer instead of guessing it.
- **Closures, not dead links.** A role that comes off its source is kept with `closed_at` and `closed_reason`, so an agent can report what happened instead of following a link to nothing.
- **Cursors, not scraping.** Rows arrive as JSON with a real pagination cursor and an incremental delta feed on paid plans: nothing here survives being parsed out of rendered HTML, which is the alternative.
- **Worked tool definitions.** The [example programs](https://github.com/lucagiftzek/joa-examples) include a tool definition for Claude and for GPT, an embedding-chunking example that keeps its provenance, and a SQLite mirror off the delta feed. Python, standard library only, run against this API before every release. The [integrations reference](https://jobopportunitiesapi.org/docs/ai/recipes-build.md) covers what is packaged today and what is not, including the [MCP server](https://jobopportunitiesapi.org/docs/ai/mcp.md).
- **An integration brief written for you, not about you.** `GET /public/ai-prompt` returns a live, keyless, machine-generated brief covering the shape of the data, the gates and how to page it. Paste it straight into a system prompt. Try it: [api.jobopportunitiesapi.org/public/ai-prompt](https://api.jobopportunitiesapi.org/public/ai-prompt).
- `GET /public/help` is the API describing itself in one JSON document: every endpoint and every parameter, the query grammar exactly as the parser implements it, the limits and quotas, the error codes and one worked example per endpoint. Versioned and cacheable, keyless. Try it: [api.jobopportunitiesapi.org/public/help](https://api.jobopportunitiesapi.org/public/help).

## Query grammar for title, q, company_name_contains and description_contains

- **Quoted words are a phrase.** `"change manager"` is the two words adjacent and in order (`'change manager'` works too). A one-word quote is an exact word, and so is a bare word: there is no automatic prefix since 10 November 2026.
- **A space, AND or & is AND.** `"change" "lead"` is both words in the field, in any order, at any distance. It is broader than `"change lead"`.
- **OR (or |) binds loosest.** AND groups form first, then `OR` joins whole groups: `a b OR c d` parses as `(a b) OR (c d)`. So `title="change" "lead" OR "change" "manager" OR "training" "lead" OR "training" "manager"` is the four word-pair alternatives it looks like: 88 rows in GB. Until 25 October 2026 `OR` bound tighter (that line read as `a AND (b OR c) AND d` and returned 1 row), so a workaround written against the old rule needs rewriting.
- **Parentheses group.** They decide what an `OR` binds to: `("change" "lead") OR ("change" "manager")` is two alternatives and the same 88 rows, while around plain words with no `OR` inside they change nothing. A value the grammar cannot honour is refused with HTTP 422 `query_syntax` naming the character and the fix: an unmatched parenthesis, an empty group, an operator with no term on one side. A boolean expression over 32 terms or 8 levels of parentheses is `query_too_complex`. Nothing is dropped silently.
- **Prefix, exclusion, followed by.** `engineer*` or `engineer:*` prefix-matches; `-term`, `!term` or `NOT term` excludes (NOT binds tightest; the `-` and `!` must touch the term); `machine <-> learning` is followed-by. The Fantastic.jobs notation, for example `(react | vue) & (node | golang) & !aws`, works as written.
- **The limit.** `include_description=true` caps `limit` at 50, above which the answer is HTTP 422 `limit_too_large`. More rows come from `has_more` and `next_cursor`, never from a bigger limit. Full worked example: [the query grammar](https://jobopportunitiesapi.org/docs/ai/api-filtering.md#query-grammar).

There is a remote MCP server today, at `api.jobopportunitiesapi.org/mcp` (Streamable HTTP): eight tools, two keyless. [Set it up for your client →](https://jobopportunitiesapi.org/docs/ai/mcp.md) For anything it doesn’t cover, integrate through the [OpenAPI spec](https://api.jobopportunitiesapi.org/v1/openapi.yaml) or plain HTTP. Honest limit still true: submission to the ChatGPT plugin directory isn’t made yet. [Tell us](https://jobopportunitiesapi.org/contact?topic=mcp) if that is what you need.

---

More machine readable files for this site: https://jobopportunitiesapi.org/llms.txt
