On this page
Documentation·API v1

Documentation

A complete, plainspoken reference. Every endpoint lists its exact request shape, response shape, and the error codes it can return.


LexAPI is a thin, opinionated REST layer over the European Union's public legal corpus — EUR-Lex, the Court of Justice (CJEU) docket, and the Official Journal. We mirror the source records, normalize them to a stable JSON schema, expose the citation graph as a first-class index, and serve everything from EU-region infrastructure with a single API key. The base URL is https://lex-api.com and every endpoint lives under /api/v1/.

Quickstart

Three calls is enough to know whether LexAPI fits your project.

terminal — quickstart
# Set your API key (create one at https://lex-api.com/dashboard)
$ export LEX_KEY="lex_..."

# 1. fetch a regulation
$ curl -X POST "https://lex-api.com/api/v1/documentContent" \
   -H "x-api-key: $LEX_KEY" \
   -H "Content-Type: application/json" \
   -d '{"celexNumber":"32016R0679"}'

# 2. full-text search
$ curl -X POST "https://lex-api.com/api/v1/search" \
   -H "x-api-key: $LEX_KEY" \
   -H "Content-Type: application/json" \
   -d '{"query":"GDPR data protection"}'

# 3. get a document by URL
$ curl -X POST "https://lex-api.com/api/v1/documents/url" \
   -H "x-api-key: $LEX_KEY" \
   -H "Content-Type: application/json" \
   -d '{"url":"https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32016R0679"}'

Authentication

Every request takes an API key via the x-api-key header. Keys are issued from your dashboard, prefixed lex_, and can be rotated or revoked at any time. Public keys are not supported — your token does not belong in client-side code.

HeaderRequiredNotes
x-api-keyyesYour API key from the dashboard
Content-Typeyes (POST/PUT)application/json
AcceptnoDefaults to application/json
X-LexAPI-ClientnoNames the framework or integration making the call — see below

A body sent without Content-Type: application/json is not read as JSON: curl -d '{…}' on its own sends a form post, and the request fails with a 400 saying a required field is missing.

X-LexAPI-Client (optional)

If you publish a framework, a wrapper or a tool that calls LexAPI, send this header to name it. It never affects authentication, credits or limits.

request header
X-LexAPI-Client: <name>/<version>[; mode=hosted|stdio][; tool=<tool>][; app=<name>[/<version>]]
X-LexAPI-Client: acme-legal-agent/1.4.2
  • <name>: 1–48 characters — a–z, 0–9, ., _, -, starting with a letter or digit; upper case is read as lower case. Names starting with lexapi- are for the official clients.
  • <version>: required; 1–24 characters — letters, digits, ., +, _, -, starting with a letter or digit.
  • The whole value: at most 256 printable ASCII characters, no comma, sent once.
  • mode, tool, app: reserved for the LexAPI MCP server (tool: the MCP tool, up to 64 characters of a–z, 0–9, _, starting with a letter; app: the MCP client’s name). They are not recorded for other clients.

A value that breaks a rule for the name, the version or the whole value is ignored, and so is the header when it is sent twice; an unknown or malformed parameter is dropped and the rest is kept. Either way the request is served as usual. A valid value is logged with the request, as described in the privacy notice.

Plans & limits

LexAPI is billed on a monthly credit pool. Each request draws credits by operation (see What each call costs below); when the pool is empty, metered calls return 402 until your monthly reset or a top-up. Limits are enforced server-side and reflected in every response under subscription, usage, and credits. usage is { current, limit, remaining, resetsAt, unit }; unit is credits on credit-pool plans and calls on legacy daily-call plans.

TierPriceCredits / monthRate / minMax pagesBatch sizeWebhooks
FREE€0150 (500 in the first cycle)15110
STARTER€15/mo30,00060552
PROFESSIONAL€39/mo150,000120202010
BUSINESS€99/mo500,0003001005050
SCALE€349/mo2,000,00060010050100
ENTERPRISEcustomcustomcustom10050100

Annual billing is ~20% off (Starter €12/mo, Professional €31/mo, Business €79/mo, Scale €279/mo, billed yearly). Credits reset monthly and do not roll over. Need more mid-cycle? Buy a top-up pack — +10,000 for €10, +50,000 for €40, or +200,000 for €120. Top-up credits are spent after your monthly allowance, do not expire at the monthly reset, and stay on your account while your paid plan is active; when the plan ends, remaining top-up credits are forfeited. Top-ups are sold on paid plans only (on a FREE or legacy plan the dashboard’s top-up checkout answers 403), and only while the subscription is active: otherwise, also while a payment is past due, it answers 409 with code: "SUBSCRIPTION_NOT_ACTIVE". Paid plans can opt in to automatic top-ups in the dashboard (off by default). Once it is active for your account, your saved card is charged for the pack you chose when the pool runs low or a request is refused with CREDITS_EXHAUSTED, at most three times per monthly credit cycle. The dashboard shows the exact terms and asks you to confirm them before anything is charged.

What each call costs

CreditsOperations
0/info — always free
1Resolve, cites / cited-by, version history reads; per row exported, at least 1 per export (reserved before the export streams, unwritten rows refunded — see Bulk export). Also the settled price of any document read served from LexAPI's own corpus (see the 5-credit row)
3 / pageKeyword search and recent documents. A repeat of a keyword search answered in the last 60 minutes may come from cache (X-Search-Cache: hit; same price). Charged upfront for the pages you request (maxPages, tier-capped); pages never fetched are refunded
5Document fetch / metadata / by-URL (and per item in a batch), and citation extraction. Settles at 4 when X-Source is cellar (or cellar-oj on document content / by-URL) and at 1 when it is corpus; citation extraction settles at 1 when alreadyExtracted
1/legislation/as-of. With provision, when the version’s text is not in our corpus it is fetched and the call costs 4 (5 when fetched live from EUR-Lex) whatever the answer; 1 if the fetch fails
5Semantic search (case law & legislation)
15Semantic case-law search with hyde: true (LLM query rewriting; auto-refunded to 5 if rewriting falls back)
20Citation network / graph (network, path, related, stats)
5Transposition (/citations/transposition/:celexNumber, every plan) — read from our database, nothing is fetched live. A 5xx is refunded in full

Failed requests refund automatically.

  • Requests rejected before any upstream work — validation errors (400), plan/tier gates (403) — refund in full.
  • A 404 refunds down to 1 credit, except the boundary_unknown 404 of /documents/:celex/at/:date, which is refunded in full.
  • Every 5xx LexAPI sends (TIMEOUT, UPSTREAM_ERROR, INTERNAL) refunds in full, and each failed item of a batch settles the same way on its own.
  • Not refunded: a 5xx that did not come from LexAPI (it has no X-LexAPI-Version header), and a dropped connection.

On an error response the credits figures may show the charge before an automatic refund: errors refunded after the response is sent (a charged 400, a 404, a 5xx) show the admitted charge, and a later response shows the refunded balance. Errors a handler refunds before answering (for example a /search 502 with no page fetched) show the settled values; errors raised before any charge carry no charge.

Rate limits and caps.

  • Requests over a per-minute rate limit return 429 RATE_LIMITED with a retryAfter (seconds, also the Retry-After header).
  • On legacy daily-call plans a used-up quota is a 429 QUOTA_EXHAUSTED with resetsAt and no Retry-After, so the official SDKs and the MCP server don't retry it.
  • When your monthly credit pool is exhausted, metered calls return 402 with a credits breakdown and resetsAt.
  • Asking for more maxPages or a larger batch than your tier allows is silently capped with an X-Warning header; you still get a 200, and you're only charged for the capped amount actually processed.

Existing customers: accounts created before the credit-pricing launch keep their original daily-call plan — those responses report usage against a daily limit with subscription.pricingMode: "daily" and no credits object. GET /api/v1/info does not count against the daily limit and is answered when the limit is used up. Nothing about your plan changes.

Errors & retries

HTTP status codes follow the conventional grammar. The body is always JSON and carries a stable code to branch on, in one of two shapes:

Typed envelope
error is an object; the code is error.code.
Legacy shape
error is a human-readable string; the code is a top-level code. Routes still on this shape: every 429, the semantic endpoints, search and citation validation, 5xx, and the 403 PAYMENT_PAST_DUE. The 502 UPSTREAM_ERROR and 504 TIMEOUT of /search, /parse and /documents/recent are in the typed envelope.

API-key 401s, the 403 of an inactive subscription or of an account with no subscription record (No subscription found), the /export tier gate and webhook management errors have no code yet (except a webhook’s WEBHOOK_URL_NOT_ALLOWED, which is in the typed envelope, as are /export’s other errors). Branch on typeof body.error, then on the status.

429 Too Many Requestsapplication/json
{
  "success": false,
  "code": "RATE_LIMITED",
  "error": "Rate limit exceeded",
  "message": "You can make up to 120 requests per minute on your current plan",
  "retryAfter": 45
}
402 Payment Required — credit pool exhaustedapplication/json
{
  "success": false,
  "error": {
    "code": "CREDITS_EXHAUSTED",
    "message": "Credit pool exhausted",
    "details": {
      "operation": "semantic_case_law", "weight": 5,
      "available": 2, "included": 30000, "topup": 0,
      "used": 29998, "resetsAt": "2026-07-01T00:00:00.000Z"
    }
  }
}
403 Forbidden — payment past dueapplication/json
{
  "success": false,
  "code": "PAYMENT_PAST_DUE",
  "error": "Payment past due",
  "message": "Your subscription payment failed, so API requests are refused. Pay the open invoice or update your card at https://lex-api.com/dashboard#billing; access returns when the payment succeeds.",
  "accessEndedAt": "2026-11-25T09:14:03.000Z",
  "billingUrl": "https://lex-api.com/dashboard#billing"
}

When a subscription payment fails, API access continues for up to 7 days; the e-mail and the dashboard show the exact time. After that, API requests are refused with 403 and the code PAYMENT_PAST_DUE until the payment succeeds: pay the open invoice in the dashboard (billingUrl). If payment keeps failing, the subscription may be cancelled, also before the 7 days are over; the account is then on the FREE plan. During the 7 days the monthly credits are not renewed and top-ups are not sold; both return when the payment succeeds. accessEndedAt is when access ended; it is absent when that time is not known. For client authors: for a past-due account this 403 with code: "PAYMENT_PAST_DUE" replaces the earlier body { "error": "Subscription inactive" }; SDK releases from 0.2.0 up to (not including) 0.5.0 raise their generic API error for it.

Unknown endpoint. A path or method the API does not have (with a valid API key; without one the answer is 401) answers 404 NOT_FOUND with error.details.reason set to unknown_endpoint (since API 2.27.0). No other 404 carries that value, so it tells “this API has no such endpoint” from “no such document” without reading the message.

404 Not Found — unknown endpointapplication/json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Unknown API endpoint: GET /api/v1/serach. See https://lex-api.com/docs for the endpoint reference.",
    "details": { "reason": "unknown_endpoint" }
  }
}

A JSON body without its content type

When a 400 or 422 answers a request whose body looks like JSON (an object or an array) but was not sent as application/json — a form post, text/plain, or no Content-Type — the message ends with one more sentence: The request body looks like JSON but was not sent as JSON: add the header Content-Type: application/json. Status and code are the ones the route sends anyway, and on credit plans the charge is refunded in full, as for any such rejection. In the legacy shape the sentence is appended to message (or is the message, when the body had none); the error string and code are unchanged. It is added for bodies of up to 100 kB sent with a Content-Length, not for chunked ones.

400 Bad Request — JSON sent as a form postapplication/json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Please provide a CELEX number (e.g., 52020DC0790). The request body looks like JSON but was not sent as JSON: add the header Content-Type: application/json."
  }
}
StatusMeaning
400Bad request — invalid parameters or missing required fields
401Missing or invalid API key (or key has been deactivated). Legacy shape without code: { "error": "API key required", "message": … }, { "error": "Invalid API key" } or { "error": "API key has been deactivated" }. A JWT-shaped Authorization: Bearer value without x-api-key is read as an OAuth token of the hosted MCP server (those tokens work only there); when it does not authenticate: { "error": "Invalid access token", "message": … } with WWW-Authenticate: Bearer realm="lexapi", error="invalid_token"
402Monthly credit pool exhausted — buy a top-up or wait for the reset. Carries a credits/details breakdown with resetsAt
403No active subscription, a FREE plan on a paid-only endpoint, or a failed subscription payment that was not completed in time (PAYMENT_PAST_DUE, above): pay the open invoice in the dashboard; not retryable until then
404Document or resource not found, or no such endpoint (error.details.reason is unknown_endpoint). On document reads and /documents/metadata: EUR-Lex itself answered that the document does not exist. A document published only moments ago can answer NOT_FOUND until up to 10 minutes after EUR-Lex has it: try again in 10 minutes. When LexAPI could not find out, the answer is a 502, 504 or 500 — never a 404
410A deprecated endpoint or parameter past its removal date — GONE, see Deprecations
429Per-minute rate limit exceeded (RATE_LIMITED) — retry after Retry-After. On legacy daily plans also the daily or monthly-semantic quota (QUOTA_EXHAUSTED) — no Retry-After; resetsAt says when it resets (omitted on a semantic quota whose billing period has already ended — stop on code)
502UPSTREAM_ERROR — EUR-Lex returned no usable page (LexAPI could not determine the answer; it does not mean the document, or its text, is missing), or semantic search failed upstream; on /search and /documents/recent, EUR-Lex returned a server error and no fallback had results. Retry; refunded in full. On document reads, /documents/metadata and /citations/extract it carries Retry-After (seconds) when the wait is known; a retry before that is likely to get the same 502
504TIMEOUT — the upstream timed out, or a document route reached its 90-second request deadline. Retry-safe; refunded in full
5xxServer error — retry with exponential backoff. Every 5xx LexAPI sends is refunded in full

Versioning & changelog

Every endpoint lives under /api/v1/. Within it, the API contract carries a semantic version: info.version in the OpenAPI spec, also returned as version by GET /api/v1/info. The path number is the transport major and the semver is the contract inside it: 3.x is served under /api/v1, and a MAJOR version keeps the path.

BumpMeansExamples
MINOR (2.1.0 → 2.2.0)Something was addedA new endpoint, optional parameter, response field, enum value or header
PATCH (2.1.0 → 2.1.1)The spec was corrected or clarified; behaviour did not changeA wrong pattern or description fixed to match what the API does
MAJORBehaviour changed in a way an existing integration may notice. Same /api/v1 path; every change is listed in that version’s changelog entry.A changed status or error code; stricter validation of input that used to be accepted; a changed default; a field that becomes nullable

One exception: input that never had a valid meaning (for example a date that does not exist, which was read as another day) can be refused in a MINOR release; it is listed under Changed in the changelog. A request that failed with a 5xx and is now answered, or refused with a 4xx, is a fix: it can ship in any release and is listed under Fixed in the changelog.

Write clients that ignore response fields and enum values they don’t know — those arrive in MINOR versions. Every response, errors and /health included (CORS preflights excepted), carries two headers:

response headers
X-LexAPI-Version: 3.1.0
X-LexAPI-Release: 3.1.0+633eb67

X-LexAPI-Version is the contract version the server implements. X-LexAPI-Release identifies the deployed build — the contract version plus the commit it was built from — and changes with every deploy, including fixes that leave the contract alone. Quote it when you report a problem; it identifies a build and does not order releases.

User-visible changes — new endpoints and fields, pricing, and behavior fixes — are tracked in the changelog (also as raw Markdown), grouped by month; an entry that changes the contract names the version it introduced (API 2.1.0). The full error catalog, rate-limit headers, and webhook signature guide live in the Markdown reference.

Deprecations

Additive changes ship at any time. A change in behaviour that an existing integration may notice (a changed status or error code, stricter validation, a changed default) ships in a MAJOR version, under the same /api/v1 path and without a notice period; the changelog entry for that version lists every such change. The first number of X-LexAPI-Version is the MAJOR version that answered. Nothing under /api/v1 (endpoint, parameter or response field) is removed or renamed without first being deprecated, and a deprecated surface keeps working for at least 180 days after its removal date is published.

The 180 days are enforced in code: a removal date is refused unless it is at least 180 days after the day it is published, and CI refuses a publication date in the past.

We email the accounts that used it in the previous 90 days when it is deprecated, and again when a removal date is set. Each deprecation is also marked deprecated: true in the OpenAPI spec (with x-deprecated-at, and x-sunset once a removal date is set), listed below, announced in the changelog under a Deprecated: heading, and signalled on the responses that use it:

response headers
Deprecation: @1793059200
Sunset: Thu, 29 Apr 2027 00:00:00 GMT
Link: <https://lex-api.com/docs#deprecations>; rel="deprecation"; type="text/html"
Link: <https://lex-api.com/api/v1/search>; rel="successor-version"
X-LexAPI-Deprecations: parse-endpoint
Deprecation (RFC 9745)
The date the surface was deprecated, as @ + Unix seconds.
Sunset (RFC 8594)
The removal date. Appears only once one is set.
rel="successor-version"
Points at a replacement endpoint, when there is one.
X-LexAPI-Deprecations
Names the entries.

Which responses carry them:

  • Endpoint deprecations: every request to the endpoint (HEAD counts as GET).
  • Parameter deprecations: every request that sends the parameter.
  • Field deprecations: every JSON response that contains the field — anywhere in it, including inside arrays (results[].score). On an NDJSON stream such as /export a field deprecation’s headers are on every response of the route, because the stream starts before its lines are known; after the removal date the field is dropped from each line.

All of them are exposed to browser clients (CORS).

After the removal date a request to a removed endpoint, or one that sends a removed parameter, gets 410 Gone with error code GONE naming the replacement (error.details.deprecation). A removed response field is no longer included.

DeprecatedUse insteadDeprecated onRemoval date
POST /api/v1/parse — the original name of search, kept as an alias (same handler, body, response and price)POST /api/v1/search2026-10-27Not set
GET /api/v1/documents/recent with more than one documentType — only the first value was ever applied, the rest dropped without noticeOne documentType per request (or POST /api/v1/search, which accepts a list)2026-10-28Not set
GET /api/v1/documents/recent with more than one subdomain — only the first value was ever appliedOne subdomain per request (or POST /api/v1/search)2026-10-28Not set

Python SDK

The official Python client — hand-written, dependency-light (httpx only), with sync and async clients, retries that honor Retry-After, typed exceptions for every error code, and credit visibility on every response. PyPI · GitHub

From 0.4.0, both SDKs — this one and the TypeScript SDK — have a method for every endpoint in this reference except the deprecated /parse.

terminal
pip install lexapi-client

The distribution is lexapi-client; the import is lexapi:

python
from lexapi import LexAPI, CreditsExhaustedError

client = LexAPI()  # reads LEXAPI_API_KEY from the environment

doc = client.get_document("32016R0679").document
print(doc.title)

resp = client.semantic_search("credit scoring article 22", hyde=True)
print(resp.hyde, [hit.case_name for hit in resp.results[:3]])

snapshot = client.get_document_at_date("32016R0679", "2026-04-01")
print(snapshot.document.version)

An AsyncLexAPI mirrors every method as a coroutine. Bulk export streams as an iterator; batch, citations, webhooks, and point-in-time history are all first-class.

TypeScript SDK

The official TypeScript client — zero runtime dependencies, strict types hand-curated from the OpenAPI spec, ESM + CJS, and the same retry/error/credits contract as the Python SDK. Server-side only: API keys are secrets and must not ship in browser code. npm · GitHub

terminal
npm install @lexapi/client
typescript
import { LexAPI, CreditsExhaustedError } from "@lexapi/client";

const client = new LexAPI(); // reads LEXAPI_API_KEY

const doc = await client.getDocument({ celexNumber: "32016R0679" });

const results = await client.semanticSearch({
  query: "credit scoring article 22",
  hyde: true,
});

const stream = await client.export({ documentType: "regulation" });
for await (const row of stream) {
  index(row); // streaming NDJSON export (Business tier)
}

Errors are typed classes you can branch on — RateLimitedError carries retryAfter, CreditsExhaustedError carries resetsAt — and truncation/partial signals surface as response fields, never silently.

MCP server (Claude, Cursor)

@lexapi/mcp exposes the API as 37 tools over the Model Context Protocol, so Claude, Cursor, VS Code or any other MCP client can research EU law natively, with real citations. Run the npm package locally (stdio) or connect to the hosted server (Streamable HTTP); both serve the same tools. npm · source · MCP Registry: io.github.Lex-API/lexapi-mcp

GroupTools
Workflowslex_check_citation, lex_act_history, lex_research
Searchlex_search, lex_recent_documents
Documentslex_get_document, lex_get_documents_batch, lex_get_metadata, lex_get_document_by_url, lex_resolve, lex_legislation_as_of, lex_document_versions, lex_get_document_version, lex_export
Citationslex_cites, lex_cited_by, lex_citation_network, lex_citation_path, lex_related, lex_citation_stats, lex_extract_citations, lex_transposition
Semantic searchlex_semantic_legislation, lex_semantic_case_law
Webhookslex_list_webhooks, lex_get_webhook, lex_create_webhook, lex_update_webhook, lex_delete_webhook, lex_test_webhook
Accountlex_info

Workflow tools combine several calls and cost their sum; anything they could not get is named.

ToolWhat it doesCredits
lex_check_citationLook a citation up (CELEX, EUR-Lex URL, ELI or ECLI): whether the document exists, its title and link, whether an article is in its text, and whether the act is in force today1 to resolve a URL, ELI or ECLI, plus one read (1 corpus · 4 Publications Office · 5 live); an article that is not matched can cost a second read; at most 11
lex_act_historyThe acts that amend, correct or repeal an EU act, from the citation graph, with the act’s in-force status today. An empty list is not proof that nothing changed1 per page of relations plus the act’s metadata (1 · 4 · 5): 2–6; each document date read adds the same, up to 10 dates
lex_researchOne query run as semantic searches over EU legislation and EU case law, returned as one list; sources reports each search as ok, failed or not run5 per search: 10 by default, at most 80
lex_legislation_as_ofThe version of an EU act listed for a date (the newest consolidated version on or before it, else the act as published) and, optionally, one article, annex or recitals of it; the text only when asOfResolved is true1; 4 via the Publications Office or 5 live when a provision’s text is fetched

The other six tools are listed in the package README.

Each tool calls the REST endpoint it wraps and is billed exactly like it, from the same monthly credit pool; every tool description states its cost so the model can see it.

Plan gates apply as they do over REST: lex_export needs BUSINESS or above, webhooks need a paid plan, and semantic search works on every credit plan, FREE included. A new FREE account’s 500 starting credits are enough to evaluate the search, document, citation and semantic tools; after the first 30-day cycle the FREE pool is 150 credits a month.

Stdio (npm package, Node.js 20+). Claude Code:

terminal
claude mcp add lexapi --env LEXAPI_API_KEY=lex_your_key -- npx -y @lexapi/mcp

Claude Desktop (claude_desktop_config.json); Cursor (~/.cursor/mcp.json) and other stdio clients take the same command / args / env:

json
{
  "mcpServers": {
    "lexapi": {
      "command": "npx",
      "args": ["-y", "@lexapi/mcp"],
      "env": { "LEXAPI_API_KEY": "lex_your_key" }
    }
  }
}

Hosted (no local install). The endpoint is POST https://mcp.lex-api.com/v1 (Streamable HTTP). Authenticate with your API key as Authorization: Bearer lex_your_key or x-api-key: lex_your_key. A request without a key or OAuth token gets a 401 with WWW-Authenticate: Bearer realm="lexapi", resource_metadata="https://mcp.lex-api.com/.well-known/oauth-protected-resource/v1", scope="lex" — that challenge is how MCP clients find the OAuth sign-in — and GET /v1 answers 405.

Browser requests are accepted only when their Origin is allowlisted (others get a 403); non-browser clients send no Origin and are unaffected. Claude Code:

terminal
claude mcp add --transport http lexapi https://mcp.lex-api.com/v1 --header "Authorization: Bearer lex_your_key"

Read-only mode. Set LEXAPI_MCP_READ_ONLY=true on the npm package to hide (and refuse) the five tools that are not read-only: lex_extract_citations, which writes to the shared citation graph and costs credits, and the four webhook writes (lex_create_webhook, lex_update_webhook, lex_delete_webhook, lex_test_webhook). 32 tools remain. The hosted server runs with read-only mode off and serves all 37.

Connect with your LexAPI account (OAuth)

The hosted MCP server at https://mcp.lex-api.com/v1 also supports “log in with LexAPI”: instead of pasting an API key, you add the server’s URL to your MCP client, sign in to LexAPI in your browser, and approve the connection. Every plan can connect, the Free plan included.

claude.ai / Claude Desktop: LexAPI is listed in Claude’s Connectors Directory: Customize → Connectors, find LexAPI (or open claude.ai/directory/lexapi) → Connect. Or add it yourself: Add custom connector → URL https://mcp.lex-api.com/v1 → Connect. Either way a LexAPI page opens; sign in (with your two-factor code if you use one) and approve. On Team and Enterprise plans an organization Owner adds the connector first; members then connect with their own LexAPI account.

Claude Code:

terminal
claude mcp add --transport http lexapi https://mcp.lex-api.com/v1

Then run /mcp in Claude Code, pick lexapi and choose Authenticate; your browser opens the same LexAPI sign-in and approval page.

What you approve. The consent page shows the app’s name and how far LexAPI can vouch for it: Verified only for apps on LexAPI’s own short list whose approval goes back to the vendor’s own sign-in address (today: Claude, returning to claude.ai / claude.com); Hosted at a website when the app publishes its identity at a web address (a client ID metadata document — the name is whatever that site publishes, nothing more is checked); or “self-registered, not verified” when it registered itself. An unverified app that calls itself after a well-known product (Claude, ChatGPT, Cursor, …) gets a prominent warning. The page also shows the address your browser returns to afterwards. Approving lets the app use everything the LexAPI MCP server offers on your behalf — every source your plan covers, including searching and reading EU legislation and case law, following the citation graph and semantic search — and create, change and delete your webhooks. It never sees your password or your API keys and cannot change your plan or billing. Apps that return to your own computer — a localhost address (Claude Code, VS Code) or an app link such as cursor://… — get an extra warning naming that address or link scheme, because any program on your machine could start such a request: only approve if you started the connection yourself.

What it costs. Each connection calls the API with its own internal key, so its calls are billed to your plan exactly like calls with your own API keys (same credit weights, same per-key rate limit, same plan gates), and it shows up as its own line with its own usage. Connections don’t count toward your plan’s API-key limit; you can have up to 10 connected apps.

Remembered approvals. If you tick Remember my decision, a verified app (such as Claude) or an app that publishes its identity at a web address, reconnecting from the same web address, shows a short page with one Continue button instead of the full request — still one click, so a connection someone else started can’t go through without you. Self-registered apps, and any request the page has a warning for (a name that claims a well-known product, an inactive plan), always show the full page. Apps returning to your own computer (localhost or an app link) always ask. To be asked again, use Ask again under Dashboard → Connected apps.

Disconnecting. Dashboard → Connected apps lists every connection with its last use and its requests and credits for the last 30 days. Disconnect stops it immediately: its key is switched off and every token it holds stops working. Reconnecting means approving again. We email you whenever a new app is connected (with a link to disconnect it), and resetting your password disconnects every app — reconnect the ones you use from the app afterwards. After a reset, a browser still signed in from before it can’t approve new connections; sign in again with the new password first. Your API keys are not affected by either. Webhooks an app created for you belong to your account and keep running after you disconnect it — delete them under Dashboard → Webhooks if you no longer want them. We may also email you about unusual sign-in activity on a connected app. Nothing is disconnected automatically; if you don’t recognise the activity, disconnect the app under Dashboard → Connected apps.

Security details for integrators. LexAPI is a standard OAuth 2.1 authorization server: metadata at https://lex-api.com/.well-known/oauth-authorization-server (RFC 8414), authorization code flow with PKCE (S256 only), resource indicators (RFC 8707, resource https://mcp.lex-api.com/v1), Client ID Metadata Documents and dynamic client registration (RFC 7591; public clients only — no client secrets are issued; redirect URIs are https, http on a loopback address, or the app’s own reverse-domain scheme such as com.example.app:/callback), short-lived ES256 JWT access tokens (15 minutes, keys at /.well-known/jwks.json), rotating refresh tokens, revocation at /oauth/revoke (RFC 7009). Use each refresh token once and store the new one returned with it. If a refresh request fails before you receive the response, retry it once straight away with the same token; if that is refused, start the authorization again. Re-using an older token ends the connection. One scope, lex, which covers reading (lex:read) and webhook management (lex:webhooks); a token without the scope a route needs gets 403 TIER_FORBIDDEN with WWW-Authenticate: Bearer … error="insufficient_scope". Connections hold lex; API keys have no scopes. These tokens work with the hosted MCP server only — to call the REST API from your own code, use an API key.

Corpus coverage

LexAPI maintains its own mirror of the EU legal corpus in the EU, with a permanent version history. Most reads (/documentContent, /documents/metadata) are served from the corpus. A document not yet held is fetched from the EU’s official sources and added to the corpus.

What's indexed

DimensionCoverage
DomainEU_LAW (all subdomains: legislation, case law, treaties, opinions, communications, …)
Date range2010 → present, with ongoing hourly delta
LanguageEnglish is warm-indexed. The other 23 official EU languages are fetched on demand via the language parameter and cached per (CELEX, language) on first request.
Document count~21,000 documents and growing
Citation graphEdges typed reference, amendment, repeal, corrigendum, implementation, legal-basis, proposal; the current count is stats.totalCitations from GET /citations/stats
Refresh latencyNew EUR-Lex publications appear in the corpus within ~1 hour

What's stored per document

  • Parsed metadata: title, document type, author, dates, ECLI/ELI, keywords, EUROVOC descriptors
  • Parsed content: full text, structured articles (e.g. GDPR's 99 articles are individually addressable), tables, annexes, section headings
  • Raw HTML (metadata page + rendered page) for both the current version and every historical version
  • Citation edges to/from other documents in the corpus

Versioning

When a document's parsed legal text changes, we keep the previous version as a snapshot and bump version. Metadata-only changes and changes to EUR-Lex page chrome (menus, banners) refresh in place without a new version. X-Corpus-Version and X-Corpus-FetchedAt response headers tell you which version you got.

How to tell whether your response came from the corpus

response headers
X-Source: corpus    # served from our own corpus
X-Source: cellar    # fetched from the EU Publications Office (Cellar)
X-Source: cellar-oj # text taken from the Official Journal issue that carries it
X-Source: live      # fetched live from EUR-Lex
X-Corpus-Version: 2
X-Corpus-FetchedAt: 2026-05-12T07:57:48.313Z

Price by source: corpus 1 credit, cellar / cellar-oj 4, live 5. Document reads may also carry an X-Cache header; treat it as informational.

Force a fresh fetch

Pass bypassCorpus: true in the request body or as a query parameter to skip the corpus and any cached copy. It is charged 5 and settles by X-Source like any cold read (4 cellar, 5 live), never from the corpus:

bypass corpus
$ curl -X POST "https://lex-api.com/api/v1/documentContent" \
   -H "x-api-key: $LEX_KEY" \
   -H "Content-Type: application/json" \
   -d '{"celexNumber":"32016R0679","bypassCorpus":true}'

What's not in the corpus today

  • Documents predating 2010 (still accessible — they'll be live-fetched and added to the corpus on first request)
  • Non-EU national law and non-English language renderings (same fallback applies)
  • EUR-Lex search results without parseable CELEX identifiers (rare metadata-only listings)

Need historic coverage (pre-2010), other domains, or other languages indexed proactively? Contact support.

CELEX numbers

Each EUR-Lex document has a CELEX identifier — a 10–12 character string that encodes its legal type, year, and sequence. The GDPR is 32016R0679; Schrems II is 62018CJ0311. CELEX numbers are case-insensitive on input — the API canonicalizes them to upper case in responses. How a CELEX number is built, and what each part of a EUR-Lex link means (TXT, ALL, qid…): EUR-Lex URLs and the web service, explained.

Languages

All twenty-four official EU languages are available. Pass language=en (default) for English; language=de for German, and so on. Supported codes: en, fr, de, es, it, pl, nl, pt, ro, bg, cs, da, el, et, fi, ga, hr, hu, lt, lv, mt, sk, sl, sv.

On /documentContent and /documentContent/batch, language localizes the entire parsed document — both content.articles (title + content) and content.fullText — and falls back to English (with an X-Language-Fallback header) when a document is not published in that language on EUR-Lex.

Article and annex structure. content.articles[].id is the article id (art_17, art_6a for an inserted article) and number is the heading as published. Acts (sector 3, incl. corrigenda) and consolidated versions (sector 0) are split into articles and annexes. Older documents without per-article markup are split at their headings: plain-text headings only in English, French, German, Dutch, Spanish, Portuguese and Italian, and never at number-first or dotted headings (Finnish "1 artikla", Hungarian "1. cikk", Croatian "Članak 1.").

Everything else — judgments, Commission documents and proposals, OJ C notices, and the unsplit cases above — has articles: [] and the text in paragraphs[]. On a split document the text outside articles and annexes (title, preamble, signatures, footnotes…) is in paragraphs[].

Citation graph

The citation index is a first-class object. Every document tracks both directions: who it cites (cites) and who cites it (cited-by). Walk either direction with the /citations endpoints — or grab the full network in one call. Every edge carries a citationType: reference, amendment, repeal, corrigendum, implementation, legal-basis, proposal, or transposition: a member-state measure’s link to the EU act it was notified for or records that it transposes (see /citations/transposition).

Worked example: EU law citation graph API.

Provenance, resolution and node identity. Every edge detail — citations[] on cited-by / cites, edgeDetails[] on network neighbours — says where the relation comes from (provenance) and how its target was identified (resolution):

  • provenance: notice (the EUR-Lex notice page of the citing document), cellar (recorded in the Publications Office’s Cellar repository), notice+cellar (both), or cellar-nim (a measure a member state notified to the Commission for an EU act — a notification, not a finding that the measure transposes the act, or transposes it completely).
  • resolution is null on every edge read from EUR-Lex or Cellar.
  • Every node — citedBy[] / cites[] groups, network neighbours, path[] nodes, related[] entries — carries id (the CELEX number for an EU document, the same as celexNumber, which is unchanged), jurisdiction (EU) and documentKind: act for CELEX sector 3, decision for sector 6, null for every other sector.
  • Filters. On cited-by, cites, network, path and related, citationType takes one value or a comma-separated list (amendment,repeal), and provenance a comma-separated list. An unknown value is a 400 INVALID_PARAMS naming the parameter and its allowed values (legacy shape on cited-by / cites / network, typed on path / related), refunded in full.

Where edges come from, and how complete they are.

  • Structural relations (amendment, corrigendum, repeal) for legislation (CELEX sectors 1–4) come from the Publications Office's Cellar repository, including acts older than our 2010+ corpus window.
  • Freshness. Reading cited-by or network for an act whose relations are more than 7 days old refreshes them first, waiting at most about 2.5 seconds; if that is not enough you get the stored edges with relationSync.status: "pending", and a later read sees the refresh.
  • Corrigenda (32008R1272R(01), …R(02), …) are typed corrigendum and each is its own citing document; its title is often not in English. A …R(nn) document that EUR-Lex lists under "Modified by" is typed amendment.
  • One edge per pair. When one act both amends and corrects another, the edge carries the stronger type (repeal over amendment over corrigendum). Watch webhooks deliver each relation separately.
  • Every other type (reference, implementation, legal-basis, proposal) comes from the EUR-Lex notice pages of the documents we have extracted (plus Cellar’s case-law citations), not the whole of EUR-Lex. implementation includes the delegated and implementing acts EUR-Lex lists as "Completed by". proposal edges run both ways: from a Commission proposal to the act it would amend, and from an act to the proposal it was adopted from. Neither counts as an amendment.
  • repeal means the whole act. A partial repeal, or a replacement of part of an act (an annex, an article), is typed amendment.
  • /citations/path, /citations/related, /citations/stats and /citations/transposition read the stored data and don't trigger a refresh.
  • Completeness. Structural edges are as current as the last refresh (relationSync says when; with pending, cooldown, error or skipped, a recent amendment may be missing until a later read), and the other types grow as more documents are extracted. A short or empty list is not proof that nothing cites the act.

Provenance

Every document says where it came from. provenance has the same eight keys on every document; a value LexAPI does not know for the document is null — never estimated.

provenanceapplication/json
"provenance": {
  "publisher": "Publications Office of the European Union",
  "sourceUrl": "https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32016R0679",
  "sourceIdentifier": "32016R0679",
  "retrievedAt": "2026-11-01T08:00:00.000Z",
  "contentHash": "9f2b7c0e…",
  "versionIdentifier": "32016R0679",
  "language": "en",
  "licence": "EUR-Lex legal notice"
}
publisher
Who publishes the document LexAPI read. EU documents: the Publications Office of the European Union (EUR-Lex).
sourceUrl
The document’s page at its publisher — never a LexAPI address. EU documents: the EUR-Lex page of the CELEX number in the language of the text — the HTML text, or the notice when the response carries no text or EUR-Lex has no page of its own for the text (parliamentary questions). null when LexAPI holds no stable page address for the document, or does not know the language. The page shows what the publisher serves today, which can be a later version than the one LexAPI holds — also for a version snapshot.
sourceIdentifier
The publisher’s identifier. EU documents: the CELEX number. null where none is held.
retrievedAt
When LexAPI fetched from the publisher what the response returns. On a read that had to fetch the document, that is the time of the fetch — the time of your request, or earlier when the page came from LexAPI’s short-lived page cache. null on /search/semantic and /legislation/semantic hits — read the document for it. Also null on a document held without text and on /documents/metadata answered from LexAPI’s corpus.
contentHash
A SHA-256 fingerprint of the text LexAPI holds — the contentHash of the version history. Compare values; it cannot be recomputed from the response. A different value means the text LexAPI holds changed: a change at the source, or a LexAPI re-parse (then version can stay the same). It covers the whole text whatever include or articleId selected. null when there is no text, on /documents/metadata, and on /search/semantic and /legislation/semantic hits — read the document for it.
versionIdentifier
Which version of the text this is, in the publisher’s terms. EU documents: the CELEX number of the text served — the act as published in the Official Journal (32016R0679) or one consolidated version (02016R0679-20160504; a consolidated text is documentation without legal force). LexAPI’s own snapshot number is version.
language
Language of the text. On a search hit: the hit’s language, else the language searched.
licence
The source’s reuse terms. EU documents: EUR-Lex legal notice — the notice that sets the reuse conditions for what EUR-Lex publishes (see also Terms §7).

Which parts are source text. fieldProvenance lists, per class, the fields of the object that carries it:

fieldProvenanceapplication/json
"fieldProvenance": {
  "official_source_text": ["title", "content.fullText", "content.articles[].content", "content.annexes[].content"],
  "machine_extracted_structure": ["documentType", "dateOfDocument", "eli", "inForce", "content.articles", "content.annexes"]
}
ClassWhat it is
official_source_textThe publisher’s wording as extracted by LexAPI: labels and separators may be added, and tables, images and footnotes simplified. The full text and the body of each article, recital, paragraph and annex. A snippet listed here is an excerpt — the whitespace-collapsed start of the matched text. It does not mean legally authentic: a consolidated text is the publisher’s wording and still has no legal force.
machine_extracted_structureParsed or computed by rule from the source’s records: metadata, identifiers, the in-force fields (inForce, notInForceReason, endOfValidity, entryIntoForce) and the split into articles. Article headings, section titles and table cells are classed here. Text read by OCR is listed here too, and so is text whose origin the response cannot establish.
machine_generated_translationMachine-translated text. LexAPI serves none today, so the class never appears.
machine_generated_interpretationProduced by a model: summary, score, a snippet cut from a summary, extracted outcome fields, the HyDE hypotheticalDocument. Not source text.
editorial_enrichmentWritten by LexAPI: notes such as consolidatedNote, and attribution statements.

Paths are relative to the object: . for a nested key, [] for “each element”. A path covers everything under it, and a longer path overrides a shorter one — content.articles is LexAPI’s split into articles, content.articles[].content inside it is the publisher’s text. Only classes with a field in the response appear, and only fields that hold a value, so with include or articleId the list shrinks. Fields not listed are not classified.

WhereprovenancefieldProvenance
/documentContent, /documentContent/batch items, /documents/urlon documenton document
/documents/metadataon metadata: sourceUrl is the notice, contentHash is null, retrievedAt is when the metadata was read from the publisher (null from the corpus)on metadata
/documents/:celex/versions/:version, /at/:dateon document — the snapshot’s own hash and time; sourceUrl is the document’s page today, which can show a later texton document
/documents/:celex/versions— each entry already has contentHash and fetchedAt—
/search/semantic, /legislation/semanticon each hit, retrievedAt and contentHash nullon each hit; on the /search/semantic response itself only with hypotheticalDocument, which it marks as machine_generated_interpretation

No extra credits. This object is not the provenance of a citation edge, which says how an edge was derived.

Webhooks & deltas

Two kinds of subscription, combinable on one webhook:

  • new documents matching search criteria (documents.new);
  • a watch list of acts whose amendments, corrigenda, repeals and new consolidated versions are pushed to you (watchlist.changes).

Matching is keyed on when a document appeared on EUR-Lex, not its document date, so late-published acts and consolidated versions are caught. Each match — a (document, reason, watched act) — is delivered once, so a document that amends two watched acts arrives once for each.

Deliveries are signed (X-Webhook-Signature, HMAC-SHA-256 of the body), retry with exponential backoff for 24 hours, and are listed via GET /webhooks/:id/deliveries. Webhook deliveries cost no credits.

Worked example: EU law change monitoring.


GET /api/v1/info

Returns the service catalog, your current subscription tier, your usage for the day, and the list of allowed values for filter parameters. Useful as a health check and for building dynamic UIs.

responseapplication/json
{
  "service": "LexAPI",
  "version": "3.1.0",
  "endpoints": { /* every endpoint with params */ },
  "subscription": {
    "tier": "PROFESSIONAL",
    "maxPages": 20,
    "maxBatchSize": 20,
    "maxWebhooks": 10,
    "maxSemanticResults": 50,
    "maxSemanticLegislationResults": 50,
    "pricingMode": "credits",
    "dailyLimit": null,
    "monthlyCredits": 150000,
    "rateLimit": "120 requests/minute"
  },
  "usage": { /* back-compat mirror of the pool */ },
  "credits": {
    "included": 150000,
    "topup": 0,
    "current": 1240,
    "limit": 150000,
    "remaining": 148760,
    "resetsAt": "2026-07-01T00:00:00.000Z"
  },
  "searchFilters": { /* allowed values for textScope, domain, documentType, author, procedure */ },
  "supportedLanguages": ["en", "fr", "de", /* … */]
}

endpoints lists the endpoints open to your account, each with its method, path and parameters (the deprecated /parse is left out). subscription holds your plan’s limits: maxPages (search), maxBatchSize (batch), maxWebhooks, and the most results one semantic search returns — maxSemanticResults for case law and maxSemanticLegislationResults for legislation (the plan’s cap, and at most 50 per call). A semantic limit above them is clamped to them. Both are 0 on an account without semantic search (the FREE tier of the legacy daily-call plans).

Search EUR-Lex with user-friendly parameters (no URL building required).

Request body

request
{
  "query": "GDPR data protection",
  "textScope": "title-text",
  "dateFrom": "2020-01-01",
  "dateTo": "2024-12-31",
  "year": [2023, 2024],
  "documentType": ["judgment", "opinion"],
  "author": ["court-of-justice"],
  "procedure": "ordinary",
  "domain": "EU_LAW",
  "subdomain": "LEGISLATION",
  "language": "en",
  "maxPages": 2
}

Parameters

FieldTypeDescription
querystringSearch text. Optional if another filter is present — at least one of query, year, month, dateFrom/dateTo, documentType, author, procedure, domain, subdomain is required (400 otherwise). * (or only wildcard/quote characters) means no text constraint — a filter-only search
textScopestringtitle, text, title-text (default), or any
dateFrom · dateToYYYY-MM-DDDate range filter
year · monthint / listSpecific year(s) or month(s)
documentTypestring / listjudgment, directive, regulation, decision, communication, …
authorstring / listcommission, council, parliament, court-of-justice, general-court, …
procedurestring / listordinary, codecision, consent, consultation, …
domainstringEUR-Lex collection: EU_LAW, NATIONAL_LAW, ALL. NATIONAL_LAW is EUR-Lex’s own national-law collection (national measures transposing EU directives, and national case law as EUR-Lex indexes it)
subdomainstring / listLEGISLATION, CONSLEG, TREATIES, EU_CASE_LAW, … A list is matched as any of when X-Search-Source: soap; an answer without an X-Search-Source header applies only the first — send one per request if that matters
languagestringTwo-letter language code (default: en)
maxPagesintResult pages to fetch (default: 1, capped by tier)
freshbooltrue bypasses the result cache and re-fetches from EUR-Lex (default: false)

X-Search-Source says how complete an answer is. soap and cellar answers have an exact document-date range (cellar answers a filter-only date window — no text, dateFrom and dateTo, no documentType/author/procedure — and costs one page). An answer with no header has its date range applied after fetching (see Post-filters). corpus (with partial: true and source: "corpus"): the list may be incomplete and text matches titles only; retry later for the complete list. If nothing can answer, you get a 504 TIMEOUT or 502 UPSTREAM_ERROR, refunded in full, never an empty result.

Result cache. A search identical to one answered in the last 60 minutes (same filters, same maxPages, any key order) is served from cache. Cached and live answers cost the same.

The X-Search-Cache header is hit, miss or bypass, and fetchedAt says when the results were fetched from EUR-Lex. Partial results are never cached. fresh: true forces a re-fetch.

Post-filters. general-court / civil-service-tribunal authors and date ranges on answers without an X-Search-Source header are applied after fetching. When one dropped rows the response carries postFilteredBy and the headers X-PostFiltered-By and X-PostFiltered-Kept — each filter’s rows as <filter>:<kept>/<before>, joined by ; in the order they ran: author:3/10;date:2/3.

Response

responseapplication/json
{
  "searchParameters": { /* echoed back */ },
  "totalResults": 1234,
  "totalPages": 124,
  "pagesFetched": 2,
  "resultCount": 20,
  "results": [
    {
      "celexNumber": "32016R0679",
      "title": "Regulation (EU) 2016/679...",
      "documentType": "Regulation",
      "author": "European Parliament, Council",
      "dateOfDocument": "27/04/2016",
      "url": "https://eur-lex.europa.eu/..."
    }
  ],
  "subscription": { "tier": "PROFESSIONAL", "maxPages": 20 },
  "usage": { "current": 235, "limit": 150000, "remaining": 149765, "resetsAt": "2026-07-01T00:00:00.000Z", "unit": "credits" },
  "fetchedAt": "2025-05-12T10:30:00.000Z"
}

POST /api/v1/documentContent

Get full document content and metadata by CELEX number.

Request body

request
{
  "celexNumber": "32016R0679"
}

Response

responseapplication/json
{
  "success": true,
  "document": {
    "celex": "32016R0679",
    "title": "Regulation (EU) 2016/679...",
    "documentType": "Regulation",
    "author": "European Parliament, Council",
    "dateOfDocument": "27/04/2016",
    "keywords": ["data protection", "privacy"],
    "content": { /* fullText, sections, articles, tables */ },
    "textAvailability": { "available": true },
    "urls": {
      "metadata": "https://eur-lex.europa.eu/.../ALL/?uri=CELEX:32016R0679",
      "html":     "https://eur-lex.europa.eu/.../TXT/HTML/?uri=CELEX:32016R0679",
      "pdf":      "https://eur-lex.europa.eu/.../TXT/PDF/?uri=CELEX:32016R0679",
      "xml":      "https://eur-lex.europa.eu/.../TXT/XML/?uri=CELEX:32016R0679"
    },
    "fetchedAt": "2025-05-12T10:30:00.000Z",
    "provenance": { /* publisher, sourceUrl, … — see Provenance */ },
    "fieldProvenance": { /* which fields are source text */ }
  },
  "subscription": { "tier": "PROFESSIONAL" },
  "usage": { "current": 236, "limit": 150000, "remaining": 149764, "resetsAt": "2026-07-01T00:00:00.000Z", "unit": "credits" }
}

Note: the field name is document.celex, not document.celexNumber — keep that in mind when destructuring.

fetchedAt is when LexAPI fetched this text from the source.

Payload selection. include / fields (array or comma-separated) trims the document to metadata (with documentTypeCode), fullText, articles, recitals, paragraphs, sections, tables, annexes; identity fields (celex, language, urls, version, fetchedAt, textAvailability, the in-force label, provenance, …) are always kept. articleId returns one article. bypassCorpus: true skips the corpus.

Deadline. A read gets 90 seconds; when that runs out you get a 504 TIMEOUT, refunded in full. A retry a little later may be a 1-credit corpus read. The batch, /documents/url and /documents/metadata have the same deadline.

Text availability

Every document response carries a textAvailability block. Usually it is just { available: true }. When EUR-Lex publishes the document’s notice but not its text, you get:

  • 200 with full metadata and content: null;
  • an X-Text-Available: false header;
  • a charge of 1 credit rather than 5 — the same price as /documents/metadata, which is all you received.
text unavailableapplication/json
{
  "content": null,
  "textAvailability": {
    "available": false,
    "reason": "not_in_language",
    "retryable": true,
    "availableLanguages": ["es", "it", "lv"]
  }
}
reasonWhat it meansWhat to do
not_in_languageThe document has text, but not in the language you asked for.Retry with one of availableLanguages.
not_published_yetThe notice exists ahead of the text.Retry later.
no_machine_readable_renditionEUR-Lex publishes no per-document text for it at all.Don't retry.
too_largeThe text exists upstream but the document could not be processed (source: "parse-worker"). availableLanguages is null.Don't retry. For a base act, latestConsolidated may point at its consolidated version — a separate document with its own availability.
unknownWe could not establish why.Retry later.

A semantic case-law hit (POST /api/v1/search/semantic with include: ["text"]) carries a textAvailability too, with its own reasons: not_in_corpus and unknown. A document response never carries not_in_corpus.

availableLanguages is null when unknown and [] when there are none. Parliamentary questions are a special case: their text is published inside an Official Journal issue rather than as a per-document rendition, and we extract it for you (X-Source: cellar-oj). Questions from before 2012 have no text anywhere upstream.

Pointer to the consolidated version. When the unavailable document is a legislation base act (CELEX sector 3, e.g. REACH 32006R1907, including acts with an OJ sequence qualifier such as 32019D0003(01)), the block may also carry:

latestConsolidated
The newest consolidated version (CONSLEG, sector 0) dated on or before today: the act with its amendments integrated, usually what you were after. Pass its celex back to /documentContent (a normal, separately charged read).
upcomingConsolidated
Appears when the next consolidation is already published ahead of its date.
source
"cellar" is the Publications Office's full list; "corpus" means this is the newest one we hold, which may not be the newest that exists.

Consolidated versions are a documentation tool without legal value of their own — the authentic text is the one in the Official Journal.

Best-effort and free; its absence does not prove there is no consolidated version. /documents/metadata carries the same fields only when a recent document read already looked them up.

The pointer does not guarantee text. A consolidated version is a separate document, charged like any other read, and it can itself answer available: false (e.g. too_large or not_in_language); we leave the pointer out when we already know that.

Language. Each pointer appears only if its version exists in the language you asked for (a version whose languages the Publications Office did not report also counts as a match) — some consolidated versions exist in only a few languages (02024R0370-20240423 is published in Estonian alone).

  • When the newest one lacks your language, latestConsolidated is left out — we never point at an older, superseded consolidation — and newestConsolidated names the newest version with its availableLanguages: information, not a pointer to follow in your language.
  • upcomingConsolidated is likewise the next version or nothing.
  • newestConsolidated only appears with source: "cellar"; a corpus answer does not know the languages, so its pick is not language-filtered.
newest version not in your languageapplication/json
"newestConsolidated": { "celex": "02024R0370-20240423", "date": "2024-04-23", "source": "cellar", "availableLanguages": ["et"] }
consolidated pointerapplication/json
"textAvailability": {
  "available": false,
  "reason": "too_large",
  "latestConsolidated": { "celex": "02006R1907-20260622", "date": "2026-06-22", "source": "cellar" }
}

Most General Court decisions have no English text and never will — the authentic text is the language of the case, usually alongside French.

If your pipeline can consume other languages, pass acceptLanguages (an ordered list of ISO codes, or "any") and the authentic text is served directly in one call, labeled via languageRequested / languageFallback and the X-Language-Fallback header — the same semantics as the automatic English fallback. Works on /documentContent and the batch endpoint.

Titles follow the same rule. When EUR-Lex has no title in the requested language, the response carries titleLanguage — the ISO code of the language the title is in (en, or for a document published in neither, the language whose official title is shown). No titleLanguage means the title is in the language you asked for. Present on document, batch and metadata responses.

In-force label

Legislation, treaties and international agreements carry inForce when the Publications Office’s records establish it: whether the act is in force today (UTC).

inForce
true or false. Absent when the status is unknown — never guessed. Many acts carry no label.
notInForceReason
Only with inForce: false: no_longer_in_force (past its end of validity: repealed or expired) or not_yet_in_force.
endOfValidity
The act’s last day in force. Only when the Publications Office records exactly one end date for the act; with several, the field is left out and inForce is still given.
entryIntoForce
With not_yet_in_force, when the entry into force is recorded.
a repealed actapplication/json
{ "celex": "31995L0046", "inForce": false, "notInForceReason": "no_longer_in_force", "endOfValidity": "2018-05-24" }
  • Consolidated texts (0…-YYYYMMDD) are labelled by the act they consolidate, and corrigenda (…R(nn)) by the act they correct: 32016R0679R(02) carries the label of 32016R0679. On those documents the fields describe that act.
  • Not covered: amendments (an amended act is still inForce: true; see latestConsolidated) and dates of application.
  • No label on case law, preparatory acts and other documents that have no in-force status.
  • Entry into force: for legislation (CELEX sector 3), a recorded entry into force earlier than the date of the act is ignored; the next recorded one counts, and when there is none the entry into force is unknown.
  • Unknown includes a failed or rate-limited lookup, acts the Publications Office records no end of validity for (an open end counts; many acts and many treaty articles have none), and acts whose dates and in-force flag contradict each other.
  • The status is at most 24 hours old.
  • Free. The same fields are on batch items, /documents/url, /documents/metadata and /legislation/semantic hits.

POST /api/v1/documentContent/batch

Fetch multiple documents in one request. The batch size is capped by tier (FREE 1 / STARTER 5 / PROFESSIONAL 20 / BUSINESS, SCALE and ENTERPRISE 50). CELEX numbers past the cap are not processed and not charged, and the response says so: trimmed: true, trimmedTo, trimmedReason and an X-Warning header.

Items whose text EUR-Lex does not publish stay in documents[] with their metadata and a textAvailability block, not in errors[]. The response carries a textUnavailable count and an X-Batch-Text-Unavailable header.

Item outcomeCreditsCounted in
Served from the LexAPI corpus1X-Batch-Corpus-Hits
Answered by the Publications Office (Cellar)4X-Batch-Cellar-Served
Recovered from an Official Journal issue4X-Batch-OJ-Recovered
Fetched live from EUR-Lex5X-Batch-Live-Fetches
… but EUR-Lex has no text for it1X-Batch-Live-Fetches (and X-Batch-Text-Unavailable)
Failed with NOT_FOUND1X-Batch-Failed
Failed otherwise (TIMEOUT, UPSTREAM_ERROR, INTERNAL)0X-Batch-Failed
A national-law id, not an EU document (UNSUPPORTED_JURISDICTION)0X-Batch-Failed

Corpus-Hits + Cellar-Served + OJ-Recovered + Live-Fetches + Failed = processed. Each errors[] entry is { celex, celexNumber, code, error, message } — code is what a single /documentContent call failing the same way returns (or UNSUPPORTED_JURISDICTION for a national-law id). The batch has the same 90-second deadline; items still being fetched then, or not yet started, come back as TIMEOUT errors.

Request body

request
{
  "celexNumbers": [
    "32016R0679",
    "62018CJ0311",
    "52020DC0790"
  ]
}

Response

responseapplication/json
{
  "success": true,
  "requested": 3,
  "processed": 3,
  "successful": 3,
  "failed": 0,
  "documents": [ /* document objects, same shape as /documentContent */ ],
  "errors": [],
  "subscription": { "tier": "PROFESSIONAL", "maxBatchSize": 20 },
  "usage": { /* … */ }
}

GET /api/v1/documents/recent

Get recently published EUR-Lex documents. All parameters are query-string.

Unfiltered requests (X-Source: cellar) cost 3 credits regardless of limit. Requests filtering on documentType, author, domain or subdomain (X-Source: live) are priced per page.

Query parameters

FieldTypeDescription
daysintLook-back window in days (default: 7). A value that gives no valid date (no number in it, or too large) is a 400 INVALID_PARAMS, refunded
documentTypestringFilter by type — one value. implementing, proposal and guideline match only their first EUR-Lex form here; use /search for those. An unknown documentType (for example corrigendum) is accepted (charged as usual), filters nothing and is named in ignoredDocumentTypes
authorstringFilter by author. general-court and civil-service-tribunal are not filtered here (no EUR-Lex author filter exists for them): you get all case law of the window — use /search
domainstringEUR-Lex collection: EU_LAW, NATIONAL_LAW, ALL. NATIONAL_LAW is EUR-Lex’s own national-law collection (national measures transposing EU directives, and national case law as EUR-Lex indexes it)
subdomainstringFilter by subdomain — one value
languagestringDefault en
limitintMax results (default: 50). A value that does not start with a number, or a negative one, is a 400 INVALID_PARAMS, refunded
example
$ curl "https://lex-api.com/api/v1/documents/recent?days=14&documentType=judgment&limit=25" \
   -H "x-api-key: $LEX_KEY"

One value per filter. A repeated documentType or subdomain applies only the first valid value, with an X-Warning header; that multi-value form is deprecated (see Deprecations).

An unknown documentType (for example corrigendum) is not refused (charged as usual): it filters nothing, and the response says so in ignoredDocumentTypes (the value as sent) and the X-Ignored-DocumentTypes header (since API 2.30.0; printable ASCII, other characters as ?, at most 64 characters), as on /search. There is no corrigendum type; a type filter can return corrigenda of that type: documentType=regulation returns rows labelled Regulation, Corrigendum, whose documentTypeCode is regulation_corrigendum. A corrigendum’s label can also be Corrigendum, Regulation (corrigendum_regulation) or Corrigendum (corrigendum); the same pairs occur for directives and decisions. documentTypeCode is not a closed list: a label without a listed code comes back as its slug, so treat an unknown value as a new type. These codes are not documentType filter values.

Language filter. Rows are filtered by the languages each one lists; rows that list none, or fewer than 4 (fresh documents still being translated), are kept. When the filter dropped or leniently kept anything, the response carries languageFilter: { requested, kept, beforeFilter, partialMetadataKept } and the X-Language-Filter, X-Language-Kept (<kept>/<before>) and X-Language-Partial-Kept headers, and totalResults is the post-filter count.

POST /api/v1/documents/url

Extract and fetch a document directly from any EUR-Lex URL. We parse the CELEX out of the URL and resolve to the canonical document. Which parts of a EUR-Lex link matter: anatomy of a legal-content URL.

Request body

request
{
  "url": "https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32016R0679"
}

Response

responseapplication/json
{
  "success": true,
  "sourceUrl": "https://eur-lex.europa.eu/...",
  "extractedCelex": "32016R0679",
  "document": { /* same shape as /documentContent */ },
  "subscription": { /* … */ },
  "usage": { /* … */ }
}

Returns 400 if the URL is not from eur-lex.europa.eu or no CELEX can be extracted. Reads the English rendition; takes include / fields, articleId and bypassCorpus like /documentContent and has the same 90-second deadline.

POST /api/v1/documents/metadata

Get only document metadata — title, date, author, type, keywords — without fetching the full content. Much faster when you only need to identify a document. X-Source is corpus (1 credit), cellar (4) or live (5); bypassCorpus: true skips the corpus. Same 90-second deadline as /documentContent.

Request body

request
{
  "celexNumber": "32016R0679"
}

Response

responseapplication/json
{
  "success": true,
  "metadata": {
    "celexNumber": "32016R0679",
    "title": "Regulation (EU) 2016/679...",
    "documentType": "Regulation",
    "author": "European Parliament, Council",
    "dateOfDocument": "27/04/2016",
    "ecli": null,
    "keywords": ["data protection"],
    "urls": { /* metadata, html, pdf, xml */ }
  },
  "subscription": { /* … */ },
  "usage": { /* … */ }
}

POST /api/v1/resolve

Resolve any legal identifier — a bare CELEX, a pasted EUR-Lex URL (URL-encoded colons supported), an ELI URI, or an ECLI — to the canonical CELEX plus the four document access URLs. Costs 1 credit.

Worked example: CELEX, ELI & ECLI resolver.

Request body

request
{
  "identifier": "ECLI:EU:C:2020:559"
}

Response

responseapplication/json
{
  "success": true,
  "identifier": "ECLI:EU:C:2020:559",
  "identifierType": "ecli",
  "resolvedVia": "ecli-corpus",
  "verified": true,
  "celex": "62018CJ0311",
  "urls": { /* metadata, html, pdf, xml */ },
  "subscription": { /* … */ },
  "usage": { /* … */ }
}

identifierType is what the input parsed as (celex · url · eli · ecli). resolvedVia is how the CELEX was found: celex/url resolve purely from the identifier; ecli-corpus means a corpus lookup answered. ELIs resolve via eli-corpus (our copy of the act carries exactly this ELI) or eli-cellar (the Publications Office’s Cellar register), because a CELEX can’t always be derived from an ELI: eli/dec/2019/166/oj is 32019D0003(01), not 32019D0166. Corrigendum and consolidated-version ELIs resolve to their own CELEX (32016R0679R(02), 02016R0679-20160504), and an ELI written with the parent type (eli/reg/2019/947/oj for eli/reg_impl/2019/947/oj) to the same act. A bare CELEX naming a distinct work (qualified, corrigendum or dated consolidated id) is kept as given; only _SUM/_RES-style tags are dropped. Every CELEX /resolve returns resolves to itself.

verified is true when the corpus or Cellar confirmed the mapping. It is false for CELEX and URL inputs, which are read off the identifier without a lookup, and for resolvedVia: "eli". That one is an ELI resolved from its pattern while Cellar was unreachable, and it may name a CELEX that doesn’t exist. An identifier that can’t be resolved returns a typed 404 (the ECLI lookup can only resolve documents already in the corpus, so that 404 is not proof the decision does not exist; a corpus lookup that fails is a 500, refunded). An ELI that couldn’t be checked and has no pattern to fall back on returns 502 UPSTREAM_ERROR (refunded).

POST /api/v1/legislation/as-of

Given an EU act and a date, returns the version listed for that date: the newest consolidated version dated on or before it, or the act as published in the Official Journal when none is. With provision, it also returns that article, annex or recital of the version. Cost: 1 credit; 4 or 5 when the text has to be fetched (below). Since API 2.26.0.

Worked example: EU law on a date.

request
curl -X POST "https://lex-api.com/api/v1/legislation/as-of" \
  -H "x-api-key: $LEX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document":"32016R0679","asOf":"2019-06-01","provision":"art_17"}'

Request body

FieldNotes
documentRequired. CELEX number of an EU act, without a CELEX: prefix. A consolidated id (02016R0679-20160504) is read as its act; the version is always chosen by asOf. For an ELI or a URL, call /resolve first
asOfRequired. YYYY-MM-DD, from 1952-01-01 to today (UTC)
provisionOptional. A whole article (art_17, 17, Article 17, 6a), an annex by its numeral or letter as printed (anx_III, anx_A), or recitals (rct_26, rct_26-28, at most 50). Numbers match exactly: 6 is not 6a. Paragraphs and points are not addressable. Omit it to get the version only
languageOptional, default en

Response

responseapplication/json
{
  "success": true,
  "document": "32016R0679",
  "language": "en",
  "asOf": "2019-06-01",
  "asOfResolved": true,
  "asOfVersion": {
    "celex": "02016R0679-20160504",
    "kind": "consolidated",
    "date": "2016-05-04",
    "checkedAt": "2026-11-18T04:43:00.000Z"
  },
  "act": {
    "celex": "32016R0679",
    "dateOfDocument": "2016-04-27",
    "entryIntoForce": "2016-05-24",
    "inForceToday": true
  },
  "provision": {
    "id": "art_17",
    "number": "Article 17",
    "title": "Right to erasure (‘right to be forgotten’)",
    "text": "1. The data subject shall have the right to obtain from the controller the erasure of personal data …"
  },
  "consolidated": true,
  "consolidatedAsOf": "2016-05-04",
  "baseCelex": "32016R0679",
  "consolidatedNote": "The act as amended, consolidated as of 2016-05-04; not the authentic text. Only the act as published in the Official Journal is authentic (32016R0679).",
  "provenance": { /* see Provenance */ },
  "credits": { /* … */ }
}
  • asOfVersion.kind is consolidated or as_published (the act as published in the Official Journal: no consolidated version is dated on or before the date).
  • asOfVersion.date is the date the consolidated version carries. It can be earlier than the act’s entry into force.
  • validUntil is the day before the next version listed, in any language, as listed when the list was read, and never later than the act’s end of validity. It may be absent. checkedAt is when the version list was read, when known (absent when the list came from a cache); it dates the list, not the text.
  • act holds what the Publications Office records about the act; a field is absent when not known. act.inForceToday is about today. It says nothing about asOf.
  • An annex is addressable where its heading reads as the annex word and its numeral or letter (ANNEX III, III. MELLÉKLET, ANNEX A); other heading forms answer version_not_parsed.

What it does not say. It does not say whether an individual provision applied on that date: an act can be in force while some of its provisions apply later. Consolidated versions are documentation without legal force; only the act as published in the Official Journal (baseCelex) is authentic. LexAPI mirrors the official consolidated versions and does not reconstruct texts.

Amendments and corrigenda. An amendment that applies retroactively counts from the date of the amending act, as for asOf in semantic search. When no consolidated version is listed for the date, the answer is the act as published in the Official Journal, without later corrigenda.

Unresolved. When the version or the text cannot be established, the answer is still a 200, with asOfResolved: false, an asOfReason and no provision. Use a text only when asOfResolved is true.

asOfReasonWhen
not_yet_adopted · not_yet_in_force · no_longer_in_forceThe date is outside the act’s dates
in_force_dates_unknownThe act’s dates do not establish it, or could not be read
act_type_not_supportedThe act is not a regulation, directive, decision or other act of the institutions (CELEX sector 3) — for example a treaty or an international agreement. Only this endpoint returns it
version_list_unavailable · version_lookup_capThe list of versions, or of the acts amending the act, could not be read, or a lookup limit was reached. Retry
not_in_languageThe version for the date has no text in language
amendment_not_consolidatedAn act amending this act may have applied by the date, and no listed version is known to include it
article_not_in_versionWith provision: the version has no such article, annex or recital. asOfVersion is present
provision_ambiguous · version_not_parsedWith provision: more than one part of the text answers to that id, or the text is not split into identifiable parts of that kind. Only this endpoint returns them
text_unavailableWith provision: the version has no text at the source
fetch_failed · fetch_timeout · fetch_pending · fetch_capacity · fetch_budget_exhausted · request_deadlineWith provision: the text could not be fetched now. Retry
insufficient_credits · credit_check_failedWith provision: the fetch was not paid for, so it was not made

Errors. 400 for a document that is not the CELEX number of an EU act (case law, a corrigendum), a missing or invalid asOf, a provision that is not a whole article, annex or recital, or an unsupported language — refunded in full. 404 when LexAPI holds no such act and the Publications Office answered that it has none (1 credit).

Cost. 1 credit for the version alone, for a provision read from our corpus, and for any answer that needed no fetch. When the text has to be fetched, the call costs 4 (5 when it is fetched live from EUR-Lex) whatever the answer — also when the answer is then article_not_in_version, provision_ambiguous, version_not_parsed or not_in_language — and 1 if the fetch fails or finds no text. Up to 5 credits are reserved while the text is fetched: a pool holding fewer than 5 gets insufficient_credits, even when the answer would have cost 4. Legacy (pre-credits) plans count one call.

GET /api/v1/documents/:celex/versions

List a document’s point-in-time version history, newest first. Every content change LexAPI detects (by content hash, between fetches) is kept as an immutable snapshot.

These are observation snapshots — the document as LexAPI fetched it — not legal in-force reconstructions; history begins when a document first enters the corpus. For the version of an EU act for a date, use POST /api/v1/legislation/as-of. When we improve the parser, the current version can be re-parsed in place (same version, new contentHash); older snapshots keep their parse.

observedFrom: when the version began; null when LexAPI has no record of it. fetchedAt is when that version’s text arrived at LexAPI; for a version without observedFrom (possible for snapshots stored before API 2.28.0) it is the last fetch of its text, which is not when the version began. /versions/:version carries both too.

Query params: language (2-letter ISO, default en). Cost: 1 credit.

Response

responseapplication/json
{
  "success": true,
  "celex": "32016R0679",
  "language": "en",
  "currentVersion": 3,
  "trackedSince": "2026-01-10T08:00:00.000Z",
  "semantics": "Versions are LexAPI observation snapshots…",
  "versions": [
    {
      "version": 3,
      "isCurrent": true,
      "contentHash": "…",
      "fetchedAt": "2026-06-01T09:00:00.000Z",
      "observedFrom": "2026-06-01T09:00:00.000Z",
      "title": "Regulation (EU) 2016/679…",
      "documentTypeCode": "regulation"
    },
    {
      "version": 2,
      "isCurrent": false,
      "contentHash": "…",
      "fetchedAt": "2026-03-15T08:00:00.000Z",
      "observedFrom": "2026-03-15T08:00:00.000Z",
      "title": "Regulation (EU) 2016/679…",
      "documentTypeCode": "regulation"
    },
    {
      "version": 1,
      "isCurrent": false,
      "contentHash": "…",
      "fetchedAt": "2026-01-10T08:00:00.000Z",
      "observedFrom": "2026-01-10T08:00:00.000Z",
      "title": "Regulation (EU) 2016/679…",
      "documentTypeCode": "regulation"
    } /* listings carry no content */
  ]
}

GET /api/v1/documents/:celex/versions/:version

Fetch one immutable snapshot, including its parsedContent as it stood in that version. The current version is served from the live corpus row; the X-Corpus-Version response header mirrors the returned version. A missing version returns a typed 404 naming the current one. Cost: 1 credit.

request
curl "https://lex-api.com/api/v1/documents/32016R0679/versions/2" \
  -H "x-api-key: $LEX_KEY"

GET /api/v1/documents/:celex/at/:date

What LexAPI held on that day: from its own fetch history, the snapshot that was current at the end of that day (UTC), with content (YYYY-MM-DD). A version that arrived during the day is the answer for that day; a version that both began and was replaced within one UTC day is reachable only through /versions/:version. Cost: 1 credit.

It is not the law in force on that date. For the version of an EU act for a date, use POST /api/v1/legislation/as-of.

request
curl "https://lex-api.com/api/v1/documents/32016R0679/at/2026-04-01" \
  -H "x-api-key: $LEX_KEY"
responseapplication/json
{
  "success": true,
  "celex": "32016R0679",
  "language": "en",
  "kind": "observation_snapshot",
  "asOf": "2026-04-01",
  "semantics": "Versions are LexAPI observation snapshots…",
  "inForceLookup": { "method": "POST", "path": "/api/v1/legislation/as-of" },
  "document": {
    "version": 2,
    "isCurrent": false,
    "fetchedAt": "2026-03-15T08:00:00.000Z",
    "observedFrom": "2026-03-15T08:00:00.000Z",
    "observedUntil": "2026-06-01T09:00:00.000Z", /* … contentHash, title, parsedContent, provenance … */
  }
}
FieldMeaning
kindAlways observation_snapshot: a snapshot from LexAPI’s fetch history
asOfThe date you asked about, in LexAPI’s fetch history. Not a date of the law: unlike asOf in /legislation/as-of and in semantic search
document.observedFromWhen the version began; null when LexAPI has no record of it
document.observedUntilWhen the next version’s text arrived; null for the current version
document.fetchedAtWhen this version’s text arrived at LexAPI (the same time as observedFrom)
inForceLookupWhere the version of the act for a date is answered. Present for an EU act that endpoint resolves (CELEX sector 3, e.g. regulations, directives, decisions, or a consolidated version of one). Absent for case law, treaties, corrigenda
dateInFuturetrue when the date is after today (UTC); absent otherwise

Dates. A date that is not a calendar day (2026-02-31) is a 400 INVALID_PARAMS. A future date returns the current version with dateInFuture: true and an X-Warning header. language must be one of the 24 EU languages; any other code is a 400.

404. NOT_FOUND with error.details.reason:

reasonMeaning
before_trackingThe date is before the document entered the corpus. details.trackedSince says when that was; details.inForceLookup is present as above
boundary_unknownLexAPI has no record of when a version stored before API 2.28.0 began, so it cannot say which snapshot it held on this date and does not guess. details.candidates lists the versions it could be (version, fetchedAt, observedFrom; for these versions fetchedAt can be the last fetch and later than your date; at most 10, candidatesTruncated: true beyond; can be empty). Read them with /versions/:version. Refunded

A document that is not in the corpus is a 404 without details. A 404 costs 1 credit, except boundary_unknown, which is refunded. A 400 is refunded.

Both SDKs expose them: get_document_at_date (Python) / getDocumentAtDate (TypeScript).


POST /api/v1/citations/extract

Crawl a document for outbound citations and persist them to the graph. Idempotent — if citations have already been extracted for the CELEX, the response carries alreadyExtracted: true.

Request body

request
{
  "celexNumber": "32016R0679"
}

Response

responseapplication/json
{
  "success": true,
  "message": "Citations extracted successfully",
  "document": {
    "celexNumber": "32016R0679",
    "title": "Regulation (EU) 2016/679..."
  },
  "citationCount": 45,
  "citations": [
    { "targetCelex": "31995L0046", "citationType": "reference" }
  ]
}

If the EUR-Lex notice page could not be read, the answer is a 502 UPSTREAM_ERROR (refunded), not a citation count. Retry after Retry-After.

GET /api/v1/citations/cited-by/:celexNumber

Documents that cite the target. Grouped by source document.

Query parameters

FieldTypeDescription
limitintPage size, in edge rows (default: 100)
offsetintSkip N edge rows (default: 0)
citationTypestringOne type, or a comma-separated list: reference, amendment, repeal, corrigendum, implementation, legal-basis, proposal, transposition
provenancestringComma-separated: notice, cellar, notice+cellar (see Citation graph)
languagestringLanguage of the titles filled in from the corpus (default en; see titleSource). Does not filter edges
responseapplication/json
{
  "success": true,
  "targetDocument": "32016R0679",
  "totalCitations": 456,
  "totalEdges": 458,
  "countsSource": "stats",
  "uniqueDocuments": 123,
  "limit": 100,
  "offset": 0,
  "citedBy": [
    {
      "id": "52020DC0790",
      "jurisdiction": "EU",
      "documentKind": null,
      "celexNumber": "52020DC0790",
      "title": "Communication...",
      "titleSource": "edge",
      "hasResume": false,
      "hasSummary": false,
      "citationCount": 3,
      "citations": [
        { "citationType": "reference", "contextSnippet": "...as set out in Regulation 2016/679...", "extractedAt": "2025-04-01T...", "provenance": "notice", "resolution": null }
      ]
    }
  ],
  "relationSync": { "source": "cellar", "status": "fresh", "syncedAt": "2026-10-07T09:12:00.000Z" }
}

relationSync reports how fresh the act's inbound amendment / corrigendum / repeal edges are. Its status is one of:

  • fresh: refreshed within the last 7 days (24 hours when the last refresh looked incomplete).
  • refreshed: refreshed during this request.
  • pending: the refresh took longer than ~2.5 s; it finishes in the background, and this response shows the stored edges.
  • cooldown or error: the refresh failed recently; the stored edges are served.
  • skipped: no refresh ran; reason is not-applicable (not a legislation CELEX), disabled, busy or budget (the stored edges are served and a later read refreshes).

syncedAt is the last completed refresh when known; null when the act has never been refreshed, and always for disabled / not-applicable.

The refresh costs no extra credits.

Paging. limit and offset count edge rows, newest extractedAt first, in a stable order. Page until offset + limit >= totalEdges.

totalCitations counts distinct citing→cited document pairs, so it can be smaller than totalEdges — don’t page on it. countsSource is stats or counted (always counted with an edge filter such as citationType or provenance); both are exact. Rows are grouped by citing document within a page, so a document can appear on two consecutive pages, and uniqueDocuments counts the citing documents in the returned page only. The same applies to /cites below.

Per group, hasResume / hasSummary say legacy _RES / _SUM rows of that document were folded in, and titleSource says where the title came from: edge, corpus (in your language), corpus-fallback-lang, citation-source / citation-target, or unknown (title is null). Network neighbours, path nodes and related entries carry it too.

GET /api/v1/citations/cites/:celexNumber

Documents the target cites. Same query parameters (limit, offset, citationType, provenance, language), paging (totalEdges) and shape as /cited-by, but keyed on the source document. Response uses sourceDocument and cites instead of targetDocument and citedBy.

responseapplication/json
{
  "success": true,
  "sourceDocument": "32016R0679",
  "totalCitations": 789,
  "totalEdges": 789,
  "countsSource": "stats",
  "uniqueDocuments": 234,
  "limit": 100,
  "offset": 0,
  "cites": [ /* grouped by targetCelex */ ]
}

GET /api/v1/citations/network/:celexNumber

Both directions of the graph in one call — outbound and inbound, with citation type counts. Query params: limit (max edges per direction; default 100, max 500), offset (paging cursor over edge rows, both directions), citationType (filter both directions: one type or a comma-separated list), provenance (comma-separated, as on /cited-by), language (title language).

responseapplication/json
{
  "success": true,
  "document": "32016R0679",
  "network": {
    "celexNumber": "32016R0679",
    "citesCount": 35,
    "citedByCount": 100,
    "cites": [
      { "id": "31995L0046", "jurisdiction": "EU", "documentKind": "act", "celexNumber": "31995L0046", "title": "Directive 95/46/EC...", "count": 2, "types": ["reference"],
        "edgeDetails": [{ "citationType": "reference", "provenance": "notice", "resolution": null }] }
    ],
    "citedBy": [ /* same shape */ ]
  },
  "paging": { "limit": 100, "offset": 0, "citesTotal": 35, "citedByTotal": 456, "citesEdgeTotal": 35, "citedByEdgeTotal": 458, "countsSource": "stats" },
  "relationSync": { "source": "cellar", "status": "fresh", "syncedAt": "2026-10-07T09:12:00.000Z" }
}

relationSync works as it does on /cited-by; the refresh does not count against the 30 s budget.

edgeDetails lists the distinct citationType / provenance / resolution combinations of the page’s edges to that neighbour; types stays the plain list of types.

citesCount / citedByCount are page-scoped — they count the deduplicated neighbours in the returned page, so a dense document shows citedByCount: 100 at the default limit even when far more documents cite it. The unbounded totals are always in paging.citesTotal / paging.citedByTotal (distinct document pairs); offset pages over edge rows, counted by paging.citesEdgeTotal / paging.citedByEdgeTotal.

On a server-side timeout (30 s) the endpoint returns 200 with partial: true, partialReason: "TIMEOUT", an empty network and null paging totals — and refunds the 20 credits in full.

GET /api/v1/citations/path/:from/:to

Shortest citation path between two documents — BFS over the outbound citation graph. Query params maxDepth (an integer from 1, default 3 — also for an empty value, and 3.0 counts as 3; above 8 is clamped to 8, and 0, negatives or non-integers are a 400 INVALID_PARAMS) and language (title language), plus citationType and provenance (comma-separated: walk only those edges); the search visits at most 5,000 nodes. Costs 20 credits.

responseapplication/json
{
  "success": true,
  "from": "32016R0679",
  "to": "31995L0046",
  "found": true,
  "pathLength": 1,
  "maxDepth": 3,
  "path": [
    { "id": "32016R0679", "jurisdiction": "EU", "documentKind": "act", "celexNumber": "32016R0679", "title": "Regulation (EU) 2016/679…", "titleSource": "corpus" },
    { "id": "31995L0046", "jurisdiction": "EU", "documentKind": "act", "celexNumber": "31995L0046", "title": "Directive 95/46/EC…", "titleSource": "corpus" }
  ]
}

No path within the budget is not an error: you get a 200 with found: false, pathLength: null, the maxDepth used and a message.

Bibliographic-coupling neighbours — documents that share the most outbound citation targets with the seed. Query params limit (default 10, max 50), language, and citationType / provenance (comma-separated: couple only on those edges). Costs 20 credits.

responseapplication/json
{
  "success": true,
  "celexNumber": "32016R0679",
  "method": "bibliographic-coupling",
  "seedCitationCount": 35,
  "count": 2,
  "related": [
    { "id": "32016L0680", "jurisdiction": "EU", "documentKind": "act", "celexNumber": "32016L0680", "title": "Directive (EU) 2016/680…", "sharedCount": 9, "sharedTargets": ["31995L0046", "…"], "titleSource": "corpus" }
  ]
}

A seed with no outbound citations returns a graceful empty list with a message — extract its citations first if you expect coupling.

GET /api/v1/citations/stats

Global statistics on the citation graph — top cited documents, top citers, totals. Recomputed at most every 5 minutes; a cached answer carries X-Cache: hit and X-Cache-Age (seconds), and the body’s cachedAt / cacheTtlSeconds.

responseapplication/json
{
  "success": true,
  "stats": {
    "totalCitations": 456789,
    "uniqueSourceDocuments": 12345,
    "uniqueTargetDocuments": 23456,
    "mostCited": [
      { "celexNumber": "32016R0679", "title": "GDPR...", "citedByCount": 5678 }
    ],
    "mostCiting": [
      { "celexNumber": "52020DC0790", "title": "Communication...", "citesCount": 123 }
    ]
  }
}

GET /api/v1/citations/transposition/:celexNumber

The measures the member states notified to the Commission for an EU act — a directive, regulation or framework decision (CELEX sector 3, e.g. 32016L0680) — grouped by country, as the Publications Office publishes them, for all 27 member states and the United Kingdom. A notification is not a finding that the measure transposes the act, or transposes it completely — every answer carries that note. Costs 5 credits, on every plan.

Worked example: Transposition measures API.

Query parameters

FieldTypeDescription
jurisdictionsstringCountries to list, comma-separated ISO-2 codes (es,cz; EL for Greece, UK for the United Kingdom). Default: all 28. eu is accepted and ignored; an unknown code is a 400 INVALID_PARAMS. source.cellar.measures always counts every country
languagestringLanguage of the act’s title (default en)
responseapplication/json
{
  "success": true,
  "document": { "id": "32016L0680", "celexNumber": "32016L0680", "jurisdiction": "EU", "documentKind": "act", "title": "Directive (EU) 2016/680 …" },
  "source": {
    "cellar": { "syncedAt": "2026-12-01T03:10:00.000Z", "measures": 333, "attribution": "Source: Publications Office of the European Union, …" },
    "lanes": null
  },
  "note": "Measures are those the member state notified to the Commission for this act. A notification is not a finding that the measure transposes the act, or transposes it completely.",
  "jurisdictions": [
    {
      "jurisdiction": "ES", "live": false,
      "counts": { "measures": 1, "resolved": null },
      "measures": [
        {
          "id": null, "resolved": null, "resolution": null, "resolutionBasis": null,
          "provenance": "cellar-nim", "citationType": "transposition",
          "title": "Ley Orgánica 7/2021, de 26 de mayo, de protección de datos personales tratados para fines de prevención …",
          "typeAct": "Ley Orgánica", "officialJournal": { "name": "Boletín Oficial del Estado", "number": "126/2021", "date": "2021-05-27" },
          "reference": "BOE-A-2021-8806", "eli": null, "link": "https://www.boe.es/boe/dias/2021/05/27/pdfs/BOE-A-2021-8806.pdf",
          "cellar": { "id": "…", "celex": "72016L0680ESP_202101234", "commissionReference": null, "dateDocument": "2021-05-27", "dateNotification": "2021-06-02", "entryIntoForce": "2021-06-16" }
        }
      ]
    }
  ],
  "truncated": false
}

id, resolved, resolution, resolutionBasis, counts.resolved and source.lanes are always null, and live is always false.

Every measure has the same keys in every country; a field the record lacks is null, never omitted. cellar.celex is the record’s sector-7 CELEX for this act (null when it has none); cellar.commissionReference is always null. citationType is transposition for a directive or framework decision, implementation otherwise. jurisdictions lists the countries with at least one measure, in code order; counts.measures counts all of a country’s measures for the act. At most 2,000 measures per call (truncated: true — narrow with jurisdictions). Measures no longer listed by the Publications Office are left out. Keep source.cellar.attribution with anything you republish.

Errors (legacy shape): 400 INVALID_PARAMS for an unknown jurisdictions code (refunded); 404 NOT_FOUND with "Not an EU act: <CELEX>" when :celexNumber is not CELEX sector 3 (settles at 1 credit, like a 404); 500 INTERNAL (refunded).


AI-powered semantic search over EU case law using embeddings. Find relevant rulings by meaning, not just keywords. Case-law results are deduplicated by CELEX; each result carries a compact snippet by default. include: ["text"] returns the full text of each matched document that LexAPI holds (tens–hundreds of KB per hit); other hits keep their snippet. Every hit carries textAvailability. Costs 5 credits — or 15 with hyde: true.

Request body

request
{
  "query": "data protection breach notification obligations",
  "min_score": 0.7,
  "limit": 20,
  "filters": { "date_from": "2020-01-01", "date_to": "2024-12-31" },
  "hyde": false
}

Parameters

FieldTypeDescription
querystring (required)Natural-language query, 3–1000 characters (Unicode code points) after trimming; outside them is a 400 INVALID_PARAMS
min_scorenumber 0–1Minimum relevance score (optional)
limitintMax results; capped by tier (FREE 10 / STARTER 20 / PROFESSIONAL 50 / BUSINESS and above 100)
filtersobjectOptional: date_from / date_to (decision date; a narrow window can return fewer than limit; YYYY-MM-DD, a midnight ISO datetime such as 2024-01-01T00:00:00.000Z, or a midnight-UTC Unix timestamp; anything else is a 400), court, case_number / ecli (exact lookup instead of a similarity search; matches carry score: 1), language (the top-level one wins). Other keys are ignored
includearray["text"] returns the full text of each matched document that LexAPI holds (tens–hundreds of KB per hit); other hits keep their snippet. Every hit carries textAvailability. Default: a ~600-character snippet instead.
languagestringContent language (default en). The semantic index currently covers en, fr, de, es, it, sl, el, nl, pt, pl; an unsupported code returns 400.
hydebooleanHyDE query rewriting (default false): an LLM drafts the passage a relevant judgment would contain, and both are searched — better recall on short or keyword-style queries. 15 credits instead of 5, ~1–3 s extra latency. If rewriting fails, the search runs without it, the response reports "hyde": false, and the 10-credit premium is refunded. When it runs, the response includes the generated hypotheticalDocument for relevance debugging.

Response — case-law result shape

Each entry is a structured case record. Note: score is at the top level of each result, not nested under metadata. The metadata sub-object carries the CELEX and document type (and, when available, the paragraph number). Fields that could not be populated are omitted, not sent as null — never assume a key’s presence.

responseapplication/json
{
  "success": true,
  "searchType": "semantic-case-law",
  "query": "data protection breach notification",
  "resultCount": 2,
  "results": [
    {
      "case_id": "ECLI_EU_C_2024_785_en_c0007",
      "score": 0.764,
      "jurisdiction": "EU",
      "language": "en",
      "case_name": "Land Hessen (Obligation d'agir de l'autorité de protection des données)",
      "court": "Court of Justice",
      "decision_date": "2024-09-26",
      "case_number": "C-768/21",
      "ecli": "ECLI:EU:C:2024:785",
      "parties": ["Land Hessen v TR"],
      "summary": "The Court examined whether, under the GDPR…",
      "snippet": "The Court examined whether, under the GDPR, the supervisory authority…",
      "metadata": {
        "celex_id": "62021CJ0768",
        "document_type": "judgment"
      }
    }
  ],
  "metadata": { /* processing_time_ms, model, … */ },
  "tookMs": 3120,
  "subscription": { "tier": "PROFESSIONAL", "maxResults": 50 }
}

semanticUsage appears on legacy daily-call plans only. On credit plans it is omitted — semantic search is metered from the monthly credit pool and reported in the credits envelope instead.

limit is optional and must be an integer of 1 or greater; it is clamped down to your plan's maxResults. A limit below 1 returns 400 Invalid limit.

Without an explicit min_score, a default relevance floor of ~0.7 applies, which can leave you with fewer results than limit. If that happens, pass min_score: 0.5 (or 0 to disable the floor) to widen recall.

Result fields

FieldNotes
case_idSnapshot-scoped id — can change when the index is rebuilt. For a persistent key use metadata.celex_id + metadata.document_type.
scoreFloat 0–1. Higher = more relevant.
jurisdiction · languageUsually EU / en.
case_name · case_number · ecliHuman-readable identifiers.
partiesThe litigants as an array of strings — often a single "A v B" element. Omitted when unknown.
court · decision_dateIssuing court and ISO-8601 date.
summaryLLM-generated digest of the ruling. Useful for previews.
summary_languageOnly when summary is not in the hit’s language: the summary’s ISO code.
snippet≤600-character preview (head of the summary, else of the matched text; empty when the hit has neither). Returned by default, in place of text. With include: ["text"], only on hits without text; a blank text counts as none.
textThe document’s full text — LexAPI’s copy, or the text the search index returned with the hit. Only with include: ["text"], and only on hits that have it (tens–hundreds of KB per hit). A blank text from the search index is passed through and counts as no text: that hit also carries a snippet.
textAvailabilityOnly with include: ["text"] (since API 2.30.0). { "available": true } when the hit carries text. Otherwise available: false with a reason, and the hit keeps its snippet, which is then the head of the machine-written summary, not court text. Reasons: not_in_corpus — LexAPI does not hold the text of this document in the hit’s language; /documentContent reads it (5 credits, settled at 4 when served from Cellar, 5 when fetched live, 1 from LexAPI’s corpus). unknown — LexAPI could not check its copy for this request; a retry may return the text. Same search cost either way. A document response’s textAvailability has other reasons (see the document reads above).
metadata.celex_idCELEX you can feed into /documentContent.
metadata.document_typejudgment, order, ag_opinion, … Together with celex_id, the identity key that survives index rebuilds.
metadata.paragraph_numberPosition of the match within the judgment — when available.
outcome · claimed_amount · legal_area · was_appealed · extraction_* · …Structured analytics, present only when available — omitted otherwise (never null).

A best-effort response (top hit below your min_score, or the adaptive floor engaged) carries a hint string explaining that the results are low-confidence; the key is absent otherwise. tookMs is the server-measured wall-clock time for the request.

Errors are in the legacy shape with a top-level code:

  • 400 INVALID_PARAMS — query length, min_score, limit, language, hyde, a date filter;
  • 403 TIER_FORBIDDEN — legacy pre-credits FREE keys, inactive subscriptions;
  • 429 QUOTA_EXHAUSTED — a legacy plan’s monthly semantic quota, with resetsAt and no Retry-After (no resetsAt either once the billing period has ended — key off the top-level code);
  • 502 UPSTREAM_ERROR, 504 TIMEOUT.

Results are deduplicated by CELEX server-side, so a tight limit may produce fewer hits than requested even on dense topics.

POST /api/v1/legislation/semantic

Embedding-based semantic search over EU legislation, matched at article level. Same request shape as /search/semantic (query, limit, min_score, filters, language, include) — but no HyDE: hyde is ignored on this endpoint, and filters is only read for language. Costs 5 credits.

limit is capped at 50 here (tier caps FREE 10 / STARTER 20 / PROFESSIONAL and above 50); the response's subscription.maxResults reports that cap.

responseapplication/json
{
  "success": true,
  "searchType": "semantic-legislation",
  "query": "right to be forgotten",
  "resultCount": 2,
  "results": [
    {
      "id": "86ef6918-c491-5568-b387-e4bdd7c17f81",
      "law_id": "32018R1725",
      "law_title": "Regulation (EU) 2018/1725 of the European Parliament and of the Council…",
      "article_ref": "art_19",
      "language": "en",
      "score": 0.728,
      "exact_match_law_id": false,
      "snippet": "1. The data subject shall have the right to obtain from the controller the erasure of…"
    }
  ],
  "metadata": { /* upstream pass-through — shape not guaranteed */ },
  "tookMs": 973
}
law_id
A CELEX — feed it into /documentContent, and use article_ref (art_19) as its articleId to fetch just the matched article.
language
The matched text’s language: the request’s language is a preference, so an act with no version in that language comes back in another one, labelled there.
id
The matched chunk’s id in the index — snapshot-scoped, so key on law_id + article_ref.
chapter / section
The headings the article sits in, when the index has them.
exact_match_law_id
Always false on this endpoint; ignore it.

The same ~0.7 default relevance floor and best-effort hint semantics as /search/semantic apply.

In force today: label and filter

Every hit carries the in-force label of its act — inForce, with notInForceReason, endOfValidity or entryIntoForce (the fields are described under /documentContent) — when the status is known. It is always about today, also on an asOf request, and it does not cover amendments: for the version listed for a date, use asOf.

Pass inForce: true to get only hits whose act is known to be in force today. Hits whose act is not in force, and hits whose status is unknown, are removed. Many acts carry no label, so the filter removes them. The page is refilled from the index (at most twice, never past 50 results), so it can still come back shorter than limit. inForce: false filters nothing. Same cost: 5 credits.

inForceFilter (removedNotInForce, removedUnknown) counts the removed hits you would otherwise have seen: those ranked above the last returned hit, or all of them when the page came back short. Unknown can be temporary (the status lookup failed or was rate-limited): when removedUnknown is above 0 the response carries a hint; retry later, or search without inForce. With asOf the filter is still about today: an act in force on the asOf date but repealed since is removed.

Consolidated texts

The index can hold the latest consolidated version of an act (the act with its amendments integrated, published by the Publications Office) alongside the act as published in the Official Journal. When both match the same article (articles match by number) you get one hit: the consolidated article, at the higher of the two scores, with the authentic act's own match under baseAct.

Every consolidated hit carries consolidated: true, consolidatedAsOf, baseCelex and consolidatedNote ("the act as amended, consolidated as of <date>; not the authentic text"). Only the Official Journal text is authentic: cite baseCelex.

Merging can leave a page shorter than limit. Without consolidated hits the response is unchanged.

asOf — the text in force on a date

Pass asOf (YYYY-MM-DD, 1952-01-01 to today, UTC). Each hit then answers with the version listed for that date. The act (for a consolidated text, the act it consolidates) must be in force then, per its date, entry into force and end of validity from the Publications Office. For a corrigendum hit the corrigendum’s own dates are checked, not the corrected act’s, so it can be asOfResolved: false next to inForce: true.

Before its first consolidation that is the act as published, otherwise the newest consolidated version dated on or before that date (versions dated after asOf never count). For an act not amended by that date, a consolidated version that only integrates corrigenda published in other languages does not count for a hit’s language. When an act amending the act may have applied after that version and on or before asOf, the hit is amendment_not_consolidated. This is checked for regulations, directives and decisions (not treaties). Corrigenda never trigger it. An amendment that applies retroactively counts from the date of the amending act, so a hit for an earlier date carries the text as consolidated before that amendment existed.

For today's version, pass today's date (UTC) as asOf and use only hits with asOfResolved: true. It does not say whether an individual provision applied on that date; see POST /api/v1/legislation/as-of. Without asOf you get the indexed texts as they are (the act as published, or its latest consolidated version where indexed): acts no longer in force are marked inForce: false when their status is known; since-amended provisions are not marked.

The text comes from our corpus. A version the corpus does not hold is fetched live — at most 3 versions per request, each waiting at most 8 s.

Version lookups are limited to 8 per request and 30 per account per minute.

Each hit carries asOfVersion ({ celex, date, kind }) and asOfResolved. When the text was swapped, id, law_id, law_title and section describe the version for that date, and matchedVersion: { id, law_id, consolidatedAsOf } names what the index matched. score stays the similarity of the indexed text.

A hit that cannot be answered keeps its indexed text with asOfResolved: false and an asOfReason:

  • In-force dates: not_yet_adopted, not_yet_in_force, no_longer_in_force, in_force_dates_unknown (no start or no end of validity recorded, placeholders, or contradicted by the Publications Office’s own in-force flag).
  • Text: not_in_language (the newest consolidated version on or before asOf has no text in that language, and it could not be established that the act is unamended and that version only integrates corrigenda published in other languages; older consolidations are never substituted), amendment_not_consolidated (an act amending this act may have applied on that date, and no consolidated version listed for the date is known to include it; the hit keeps its indexed text, which is not established as the text for that date; asking again later helps only for recent dates; since API 2.25.0), text_unavailable, article_not_in_version, part_not_resolvable, article_unknown.
  • Version lists: version_list_unavailable (the list of consolidated versions, or of the acts amending the act, could not be read), version_lookup_cap.
  • Fetches: fetch_budget_exhausted, fetch_pending, fetch_capacity, fetch_failed, fetch_timeout, request_deadline.
  • Credits: insufficient_credits, credit_check_failed.

asOfSummary.liveFetches counts fetches attempted, including failed ones.

Cost: 5 credits for the search. Each live fetch reserves 5 just before it starts and settles at what the document route charges for the same outcome: 4 from the Publications Office (Cellar), 5 live from EUR-Lex (also when it fell back to English, which leaves the hit unresolved), 1 when the version has no text, 0 when it failed or timed out.

A fetch your pool cannot cover is skipped, and that hit is insufficient_credits. Corpus reads are free. An invalid asOf is a 400, refunded in full.


GET /api/v1/export BUSINESS+

Stream the LexAPI corpus as NDJSON (newline-delimited JSON) — one document per line. Suitable for ETL into your own datastore, search indexes, retrieval (RAG) pipelines, or compliance archives. Rows are streamed as they are read, so memory stays bounded at any export size.

Cost: 1 credit per row written, at least 1 per export. Available on BUSINESS, SCALE and ENTERPRISE; 403 for lower tiers.

Licensing. Bulk export is licensed for building your own products and internal systems on the API.

Using exported content — including our parsed structure — to train, fine-tune or evaluate machine-learning models, or to create embeddings or derived datasets for those purposes, needs a separate written licence from us (Terms §6) — email [email protected]. Retrieval and search embeddings built to serve your own application are not covered by that restriction.

Query parameters

FieldTypeDescription
documentTypestring / listExact stored label, ignoring case; several values (comma-separated or repeated) are ORed. regulation matches Regulation, not Implementing regulation — use documentTypeCode for a family
documentTypeCodestring / listType family by the documentTypeCode each row carries: regulation covers Regulation, Implementing regulation, Delegated regulation and the Commission implementing/delegated labels (likewise directive, decision). Combined with documentType, both must match
authorstring / listWhole stored author value, ignoring case; values ORed. A joint act’s author is one value (European Parliament, Council of the European Union) — pass that whole string to select it; European Parliament alone does not match joint acts. Commas separate values unless the whole value is itself a stored author
languagestringDefault en. Give it once (a repeated language is a 400)
dateFrom · dateToYYYY-MM-DDDocument-date range, inclusive, compared as dates (rows without a document date are left out of a dated export). Any other format, including a timestamp, is a 400
fetchedSinceISO 8601Rows whose lastSeenAt is at or after this time: any write to the row, including metadata refreshes and re-checks that left the text unchanged. A date (2026-05-11, midnight UTC) or a date-time with a timezone (2026-05-11T00:00:00Z); anything else is a 400
changedSinceISO 8601Rows whose text changed (contentChangedAt, a new version) at or after this time. The cheapest incremental sync. Same format as fetchedSince
includeContentboolInclude parsed sections/articles/tables (default true)
includeHtmlboolInclude raw HTML blobs (large; default false)
includeStubsboolAlso stream metadata-only rows (documents whose text EUR-Lex does not publish, or not yet). Default false; skipped rows are counted as skippedStubs on the _done trailer.
limitintPositive integer; cap on rows returned (server max: 50,000). Omit it for the maximum. 0, negatives, decimals, 1e3 or an empty value are a 400. Also caps the credit reservation

How export is billed (credit plans)

  • Admission: 1 credit. Every export costs at least 1 credit: it pays for counting the matching rows. If your pool is empty, the request fails with 402 CREDITS_EXHAUSTED before anything is counted, and nothing is charged.
  • Reservation. After the count, the request reserves the rest of 1 credit for every row it can return: the matching rows, capped at limit and the 50,000 server maximum. X-Export-Credits-Reserved shows the total, and _meta.credits the pool after it.
  • Low balance. If your pool cannot cover the reservation, the request fails with 402 CREDITS_EXHAUSTED before anything streams, the same as a search whose pages your pool cannot cover. The 1 admission credit is kept, since the count ran. error.details.weight is the reservation and error.details.available your balance after it: retry with limit at or below available.
  • Rows added since the count. The count (cached for up to a minute) sizes the reservation but never caps the export: rows added since then are streamed too, each reserved as it comes. If your pool cannot pay for all of them, the export streams as many as it can still pay for, then ends with truncated: true and truncatedBy: "credits".
  • Settlement. You pay for the rows written, at least 1. When the stream ends, every reserved credit beyond that is refunded: rows skipped as metadata-only stubs (skippedStubs), rows that disappeared during the export, and rows not sent because you disconnected. If the export fails on our side, you pay only for the rows written. The settled charge is _done.credits.charged; response headers show only the reservation. The refund is applied even if our server stops mid-export.
  • On legacy daily plans an export counts as one call against your daily quota, including one you abort.

Response format

Content-Type: application/x-ndjson. The response stream is framed by an envelope: the first line is a { "_meta": … } object describing the filters and counts, the middle is one document per line, and the last line is { "_done": … } with what actually happened:

_done fieldNotes
writtenRows sent
truncatedtrue when matching rows remain that this export did not reach — because of limit, the server maximum or the credit pool. Skipped stubs do not count
truncatedBylimit, max_rows, credits (the pool could not pay for rows added since the count), recovered (the export was stopped on our side and its unused reservation refunded — run it again), or null
skippedStubsRows that matched but hold no document text. Not written, not charged
creditsCredit plans: the pool after settlement, plus reserved, charged (max(written, 1); less after a recovered export, whose recovery refunded the reservation as it stood) and refunded. refundPending: true means part of refunded is applied automatically within minutes rather than during the request

An export is complete only if it ends with the _done line. If the export fails after streaming has started, the stream ends without a _done line; no error line is written. Treat a missing trailer as an incomplete export and retry — the official SDKs raise an incomplete-export error. Rows already written are charged, the rest of the reservation is refunded.

response (NDJSON stream)
{"_meta": {"totalMatching":12450, "streaming":12450, "truncated":false, "credits":{"reserved":12450, "remaining":487550, /* … */}, /* … */}}
{"celex":"32016R0679","title":"Regulation (EU) 2016/679…","documentType":"Regulation","author":"…","parsedContent":{…},"version":1,"contentHash":"…","fetchedAt":"2026-05-12T…"}
{"celex":"32022R2065",/* … */}
/* … one line per document … */
{"_done": {"written":12447, "truncated":false, "truncatedBy":null, "skippedStubs":3, "credits":{"reserved":12450, "charged":12447, "refunded":3, "remaining":487553, /* … */}}}

Response headers

HeaderNotes
X-Export-TotalRows matching when counted (regardless of limit; cached for up to a minute). The count never limits what is streamed
X-Export-StreamingRows reserved up front. Rows added since the count are streamed too, each reserved as it comes; _done.written is the final count
X-Export-Truncated1 if limit or the server maximum is below the match count; 0 otherwise. _done.truncated is authoritative
X-Export-Credits-ReservedCredit plans: credits reserved (1 per row in X-Export-Streaming, at least 1). The settled charge is _done.credits.charged

A count that takes longer than 15 s returns 504 TIMEOUT; the 1-credit admission is kept (the count ran) and nothing else is charged. Narrow the filters, for example with a dateFrom/dateTo or changedSince window.

Examples

bash
# Incremental sync — everything whose text changed since yesterday
$ curl -L "https://lex-api.com/api/v1/export?changedSince=2026-05-11T00:00:00Z" \
   -H "x-api-key: $LEX_KEY" \
   -o yesterday.ndjson

# All EU regulations (incl. implementing and delegated) from 2020 onward, full content but no raw HTML
$ curl -L "https://lex-api.com/api/v1/export?documentTypeCode=regulation&dateFrom=2020-01-01" \
   -H "x-api-key: $LEX_KEY" \
   -o eu-regulations.ndjson

# Parse as a stream in Node — and refuse an export without its trailer
$ node -e "let done = false; const rl = require('readline').createInterface({input: process.stdin}); rl.on('line', l => { const r = JSON.parse(l); if (r._done) { done = true; return; } if (r._meta) return; console.log(r.celex, r.title.slice(0,60)); }); rl.on('close', () => { if (!done) { console.error('incomplete export'); process.exit(1); } });" < eu-regulations.ndjson

403 below BUSINESS (FREE, STARTER, PROFESSIONAL). X-Export-Truncated: 1 indicates the result set exceeded the limit. When more rows match than one export returns (truncated: true), split the selection into consecutive dateFrom/dateTo windows and export each. Rows without a document date are in no dated window. On credit plans an export is billed per row written (see above); on legacy daily plans one export call counts as one call against your daily quota.


POST /api/v1/webhooks

Create a webhook subscription. The secret in the response is returned only once — store it; you will need it to verify incoming payload signatures. A webhook needs searchCriteria, watchCelex, or both.

Webhook URL requirements

The url must be a public HTTPS endpoint:

  • https:// only, on port 443 (the default) or 8443;
  • no credentials in the URL (user:pass@) — verify the signature instead;
  • a public, fully-qualified hostname or IP address, resolving to public addresses only.

The URL is checked when you create or change it — a 400 WEBHOOK_URL_NOT_ALLOWED, with details.reason: invalid_url, scheme, userinfo, port, internal_hostname or not_public (the hostname does not resolve to public addresses). A delivery to a URL that no longer qualifies fails (recorded in the delivery history with errorMessage starting Webhook URL not allowed) and is retried like any failed attempt.

Redirects are not followed: a 3xx answer is a failed delivery, so point the webhook at the final URL.

Request body — new matching documents

request
{
  "name": "New data-protection regulations",
  "url": "https://myapp.example.com/lexapi-webhook",
  "searchCriteria": {
    "query": "\"data protection\"",
    "documentType": "regulation"
  },
  "secret": "optional-supplied-secret"
}

Request body — watch list

request
{
  "name": "Chemicals compliance watch",
  "url": "https://myapp.example.com/lexapi-webhook",
  "watchCelex": ["32006R1907", "32008R1272"]
}

searchCriteria filters

All optional; every filter given must match. searchCriteria: {} matches every new EU-law document (sectors 1–6), never consolidated texts. A subdomain replaces that default instead of adding to it: { "subdomain": "consolidated" } matches consolidated texts only; to get both, list every subdomain you want plus consolidated (sector 4, complementary legislation, has no subdomain value and comes only with no subdomain).

FilterMatches
queryEvery term (or "quoted phrase") must match whole words of the document title — case- and accent-insensitive; punctuation and hyphens separate words. Terms of 4+ characters match the start of a word (chemical → "chemicals"); terms of 3 characters or fewer, or all digits, must be a whole word (AI matches "AI Act", not "aid" or "Ukraine"; ETS not "sheets"). A trailing * matches word starts at any length (tax* → "taxation"); use it for acronym plurals (SME* matches "SMEs", SME does not). Any other * is ignored; CO2 matches "CO₂". low-emission or 2024/1689 match those words in a row; a quoted phrase matches its exact words in a row. Titles only, not full text. Operators are upper-case: AND is the default; OR, NOT, NEAR, -term are refused. Lower-case and/or/not are ordinary words; a lone - or / is ignored.
documentTypeSame values as /search. regulation, directive and decision match every sub-type of their family (implementing, delegated, international-agreement, framework, review, …); every other type matches exactly (opinion excludes Advocate General opinions).
authorSame values as /search (commission, council, parliament, court-of-justice, general-court, ecb, efsa, …); unknown authors are refused, and so are member-states and ema, alone or in a list (they never match).
subdomainSame values as /search (one or a list). Without one: EU law, sectors 1–6. Given, it replaces that default: only the listed subdomains match (consolidated alone = consolidated texts only).
dateFrom / dateTo / yearOptional bounds on the document date.

Anything else (procedure, textScope: "text", national law, unknown types or authors, boolean operators) is refused with 400 and a details list rather than silently ignored; textScope accepts title, title-text and any (all match titles).

Stored criteria that no longer validate are skipped, never widened, and reported in criteriaErrors — except a stored author list mixing member-states/ema with valid authors, which keeps matching on the valid ones (the ignored value is still listed). Derived notices (_SUM, _INF) are not delivered.

Limits per plan. Webhooks per account: Free 0 · Starter 2 · Professional 10 · Business 50 · Scale 100 · Enterprise 100. Acts per watch list: Starter 100 · Professional 500 · Business 1,000 · Scale 2,000 · Enterprise 5,000.

When deliveries happen. Webhooks are evaluated hourly; most documents reach you the morning they appear on EUR-Lex. A new webhook only fires for documents that appear after it was created; a re-enabled one catches up on the last 7 days and re-sends deliveries that ran out of retries in that window.

Response (201 Created)

responseapplication/json
{
  "success": true,
  "message": "Webhook created successfully",
  "webhook": {
    "id": "a1b2c3...",
    "name": "New GDPR-related judgments",
    "url": "https://myapp.example.com/lexapi-webhook",
    "secret": "7f9a...",            // returned ONCE
    "status": "ACTIVE",
    "searchCriteria": { /* … */ },
    "watchCelex": [],
    "createdAt": "2025-05-12T10:30:00.000Z"
  }
}

Delivery format

When a webhook fires, we POST to your URL with these headers. Three events: documents.new, watchlist.changes, and webhook.test. At most 100 documents per delivery — larger batches arrive as several deliveries, nothing is dropped.

headers
POST /your-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: LexAPI-Webhook/1.0
X-Webhook-ID: a1b2c3...
X-Webhook-Delivery: d1e2f3...
X-Webhook-Signature: <hmac-sha256(secret, body) hex>

watchlist.changes (captured live, 2026-10-05)

body
{
  "event": "watchlist.changes",
  "timestamp": "2026-10-05T11:35:50.493Z",
  "webhook": { "id": "a1b2...", "name": "Chemicals compliance watch" },
  "delivery": { "id": "d1e2...", "attempt": 1 },
  "data": {
    "count": 1,
    "changes": [{
      "watchedCelex": "32008R1272",
      "relation": "consolidated_version",
      "document": {
        "celex": "02008R1272-20270101",
        "title": "Regulation (EC) No 1272/2008 … on classification, labelling and packaging of substances and mixtures …",
        "documentType": "Consolidated text",
        "documentTypeCode": "consolidated_text",
        "resourceTypes": ["CONS_TEXT"],
        "dateOfDocumentISO": "2027-01-01",
        "consolidationDate": "2027-01-01",
        "addedAt": "2026-09-29T18:38:19.634Z",
        "availableLanguages": ["BG", "CS", /* … */],
        "url": "https://eur-lex.europa.eu/legal-content/EN/ALL/?uri=CELEX:02008R1272-20270101"
      }
    }]
  }
}
relation
One of amended_by, corrected_by, repealed_by, consolidated_version.
consolidationDate
A consolidated version’s date it applies from; can be in the future.
availableLanguages
The languages it can be fetched in — check it first: some consolidated versions exist in only a few languages (02024R0370-20240423 is Estonian only, ["ET"]).
addedAt
When the document appeared on EUR-Lex — the clock webhooks match on.

A documents.new delivery carries searchCriteria and data: { count, totalAvailable, documents: [...] } with each document in the same shape (plus celexNumber / form aliases for earlier receivers); at most 100 per delivery, count for this delivery and totalAvailable for every new match from the same check.

Rarely, a new document’s title, type, author and date are not yet available. It is then held back for up to about 46 hours after its addedAt; if they still don’t arrive it is delivered with those fields null. Criteria on query, documentType, author (except the courts matched by CELEX) or dates cannot match such a document.

Retries and failure

  • Any 2xx within 10 seconds counts as delivered (a 3xx is a failure: redirects are not followed).
  • Otherwise the delivery is retried with increasing delays: seven attempts in all, across about 24 hours.
  • Each attempt is signed fresh: timestamp is the time of that attempt, while delivery.id (also X-Webhook-Delivery) stays the same — dedupe on it. Deliveries can arrive out of order.
  • The owner is normally emailed when deliveries keep failing (watch the webhook’s status and consecutiveFailures); if all seven attempts fail the webhook is set to FAILED (the owner is emailed; its other queued deliveries wait too) until you re-enable it.

Re-enabling sends again its deliveries created in the last 7 days that had run out of retries (requeuedDeliveries in the response), resumes the other queued ones, and delivers new matches from the last 7 days; exhausted deliveries created earlier stay FAILED, readable under /deliveries for 30 days.

An outage on our side does not count against your webhook.

GET /api/v1/webhooks

List every webhook on the account.

responseapplication/json
{
  "success": true,
  "count": 3,
  "webhooks": [
    {
      "id": "a1b2c3...",
      "name": "New GDPR judgments",
      "url": "https://...",
      "status": "ACTIVE",
      "searchCriteria": { /* … */ },
      "criteriaErrors": [],
      "urlError": null,
      "watchCelex": ["32006R1907", "32008R1272"],
      "lastChecked": "2025-05-12T10:00:00.000Z",
      "lastTriggered": "2025-05-12T09:30:00.000Z",
      "consecutiveFailures": 0,
      "deliveryCount": 12,
      "createdAt": "2025-04-01T..."
    }
  ]
}

GET /api/v1/webhooks/:id

Single-webhook detail, including the last 20 delivery records.

responseapplication/json
{
  "success": true,
  "webhook": {
    "id": "a1b2...",
    "name": "...",
    "url": "...",
    "status": "ACTIVE",
    "searchCriteria": { /* … */ },
    "criteriaErrors": [],
    "urlError": null,
    "watchCelex": [],
    "lastChecked": "...",
    "lastTriggered": "...",
    "consecutiveFailures": 0,
    "retryPolicy": { "maxAttempts": 7, "windowHours": 24, "delaysMinutes": [1, 5, 30, 120, 360, 900] },
    "createdAt": "...",
    "updatedAt": "...",
    "recentDeliveries": [ /* last 20, same fields as /deliveries */ ]
  }
}

PUT /api/v1/webhooks/:id

Update any of name, url, searchCriteria, watchCelex, or status.

  • watchCelex replaces the whole list; searchCriteria: null removes the criteria (one of the two must remain).
  • Allowed status values: ACTIVE, PAUSED, FAILED. Setting it to ACTIVE also clears the failure counter.
  • A new url must meet the URL requirements (url: null or "" means no change), and so must the stored one when you set a FAILED or PAUSED webhook back to ACTIVE.

Two fields on every webhook read report problems with what is stored:

criteriaErrors
Lists what is wrong with stored searchCriteria; they are skipped, never widened, until you fix them here (an ignored member-states/ema beside valid authors is listed but does not stop the other authors matching).
urlError
null, or { reason, message } when the stored URL breaks a rule that needs no DNS lookup (for example an http:// URL) — its deliveries are refused until you change the URL.
request
{
  "name": "GDPR judgments (paused)",
  "status": "PAUSED"
}

DELETE /api/v1/webhooks/:id

Permanently delete a webhook and its delivery history.

responseapplication/json
{
  "success": true,
  "message": "Webhook deleted successfully"
}

POST /api/v1/webhooks/:id/test

Send a one-off webhook.test event to the webhook's URL and return the upstream response. Useful for verifying signature handling before going live. The same URL requirements apply (a refused URL is a 400 WEBHOOK_URL_NOT_ALLOWED and nothing is sent).

responseBody is the first 500 characters of your endpoint's reply when its content type is text, JSON or XML (text/*, application/json, +json, application/xml, +xml), else null; durationMs is the attempt's wall time.

responseapplication/json
{
  "success": true,
  "message": "Test webhook delivered successfully",
  "delivery": {
    "status": "SUCCESS",
    "responseStatus": 200,
    "responseBody": "{...}",
    "errorMessage": null,
    "durationMs": 184
  }
}

GET /api/v1/webhooks/:id/deliveries

Paginated delivery history.

Query parameters

FieldTypeDescription
limitintPage size (default: 50)
offsetintSkip N (default: 0)
responseapplication/json
{
  "success": true,
  "total": 156,
  "limit": 50,
  "offset": 0,
  "deliveries": [
    {
      "id": "d1e2...",
      "status": "SUCCESS",
      "payload": { /* the JSON body that was POSTed */ },
      "responseStatus": 200,
      "responseBody": "...",
      "errorMessage": null,
      "attemptCount": 1,
      "nextRetryAt": null,
      "deliveredAt": "2025-05-12T09:30:01.000Z",
      "createdAt": "2025-05-12T09:30:00.000Z"
    }
  ]
}

Node.js example

search.js
const res = await fetch('https://lex-api.com/api/v1/search', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.LEX_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'GDPR data protection',
    documentType: ['judgment', 'opinion'],
    year: [2023, 2024],
    maxPages: 2,
  }),
});
const data = await res.json();

Python example

search.py
import requests

res = requests.post(
  'https://lex-api.com/api/v1/search',
  json={
    'query': 'GDPR data protection',
    'documentType': ['judgment', 'opinion'],
    'maxPages': 2,
  },
  headers={'x-api-key': API_KEY},
)
data = res.json()

cURL example

bash
$ curl -X POST "https://lex-api.com/api/v1/search" \
   -H "x-api-key: $LEX_KEY" \
   -H "Content-Type: application/json" \
   -d '{"query":"GDPR","year":[2023,2024]}'

Verifying webhook signatures (Node)

verify.js
const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader),
  );
}

End of documentationNeed help? Contact support