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.
# 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.
| Header | Required | Notes |
|---|---|---|
x-api-key | yes | Your API key from the dashboard |
Content-Type | yes (POST/PUT) | application/json |
Accept | no | Defaults to application/json |
X-LexAPI-Client | no | Names 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.
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 withlexapi-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 ofa–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.
| Tier | Price | Credits / month | Rate / min | Max pages | Batch size | Webhooks |
|---|---|---|---|---|---|---|
| FREE | €0 | 150 (500 in the first cycle) | 15 | 1 | 1 | 0 |
| STARTER | €15/mo | 30,000 | 60 | 5 | 5 | 2 |
| PROFESSIONAL | €39/mo | 150,000 | 120 | 20 | 20 | 10 |
| BUSINESS | €99/mo | 500,000 | 300 | 100 | 50 | 50 |
| SCALE | €349/mo | 2,000,000 | 600 | 100 | 50 | 100 |
| ENTERPRISE | custom | custom | custom | 100 | 50 | 100 |
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
| Credits | Operations |
|---|---|
| 0 | /info — always free |
| 1 | Resolve, 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 / page | Keyword 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 |
| 5 | Document 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 |
| 5 | Semantic search (case law & legislation) |
| 15 | Semantic case-law search with hyde: true (LLM query rewriting; auto-refunded to 5 if rewriting falls back) |
| 20 | Citation network / graph (network, path, related, stats) |
| 5 | Transposition (/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_unknown404 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-Versionheader), 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_LIMITEDwith aretryAfter(seconds, also theRetry-Afterheader). - On legacy daily-call plans a used-up quota is a 429
QUOTA_EXHAUSTEDwithresetsAtand noRetry-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
creditsbreakdown andresetsAt. - Asking for more
maxPagesor a larger batch than your tier allows is silently capped with anX-Warningheader; 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
erroris an object; the code iserror.code.- Legacy shape
erroris a human-readable string; the code is a top-levelcode. Routes still on this shape: every 429, the semantic endpoints, search and citation validation, 5xx, and the 403PAYMENT_PAST_DUE. The 502UPSTREAM_ERRORand 504TIMEOUTof/search,/parseand/documents/recentare 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.
{
"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
}{
"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"
}
}
}{
"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.
{
"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.
{
"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."
}
}| Status | Meaning |
|---|---|
| 400 | Bad request — invalid parameters or missing required fields |
| 401 | Missing 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" |
| 402 | Monthly credit pool exhausted — buy a top-up or wait for the reset. Carries a credits/details breakdown with resetsAt |
| 403 | No 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 |
| 404 | Document 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 |
| 410 | A deprecated endpoint or parameter past its removal date — GONE, see Deprecations |
| 429 | Per-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) |
| 502 | UPSTREAM_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 |
| 504 | TIMEOUT — the upstream timed out, or a document route reached its 90-second request deadline. Retry-safe; refunded in full |
| 5xx | Server 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.
| Bump | Means | Examples |
|---|---|---|
MINOR (2.1.0 → 2.2.0) | Something was added | A 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 change | A wrong pattern or description fixed to match what the API does |
| MAJOR | Behaviour 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:
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:
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 (
HEADcounts asGET). - 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/exporta 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.
| Deprecated | Use instead | Deprecated on | Removal date |
|---|---|---|---|
POST /api/v1/parse — the original name of search, kept as an alias (same handler, body, response and price) | POST /api/v1/search | 2026-10-27 | Not set |
GET /api/v1/documents/recent with more than one documentType — only the first value was ever applied, the rest dropped without notice | One documentType per request (or POST /api/v1/search, which accepts a list) | 2026-10-28 | Not set |
GET /api/v1/documents/recent with more than one subdomain — only the first value was ever applied | One subdomain per request (or POST /api/v1/search) | 2026-10-28 | Not 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.
pip install lexapi-client
The distribution is lexapi-client; the import is lexapi:
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
npm install @lexapi/client
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
| Group | Tools |
|---|---|
| Workflows | lex_check_citation, lex_act_history, lex_research |
| Search | lex_search, lex_recent_documents |
| Documents | lex_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 |
| Citations | lex_cites, lex_cited_by, lex_citation_network, lex_citation_path, lex_related, lex_citation_stats, lex_extract_citations, lex_transposition |
| Semantic search | lex_semantic_legislation, lex_semantic_case_law |
| Webhooks | lex_list_webhooks, lex_get_webhook, lex_create_webhook, lex_update_webhook, lex_delete_webhook, lex_test_webhook |
| Account | lex_info |
Workflow tools combine several calls and cost their sum; anything they could not get is named.
| Tool | What it does | Credits |
|---|---|---|
lex_check_citation | Look 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 today | 1 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_history | The 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 changed | 1 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_research | One 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 run | 5 per search: 10 by default, at most 80 |
lex_legislation_as_of | The 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 true | 1; 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:
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:
{
"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:
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:
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
| Dimension | Coverage |
|---|---|
| Domain | EU_LAW (all subdomains: legislation, case law, treaties, opinions, communications, …) |
| Date range | 2010 → present, with ongoing hourly delta |
| Language | English 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 graph | Edges typed reference, amendment, repeal, corrigendum, implementation, legal-basis, proposal; the current count is stats.totalCitations from GET /citations/stats |
| Refresh latency | New 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
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:
$ 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), orcellar-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).resolutionisnullon every edge read from EUR-Lex or Cellar.- Every node —
citedBy[]/cites[]groups, network neighbours,path[]nodes,related[]entries — carriesid(the CELEX number for an EU document, the same ascelexNumber, which is unchanged),jurisdiction(EU) anddocumentKind:actfor CELEX sector 3,decisionfor sector 6,nullfor every other sector. - Filters. On
cited-by,cites,network,pathandrelated,citationTypetakes one value or a comma-separated list (amendment,repeal), andprovenancea comma-separated list. An unknown value is a400 INVALID_PARAMSnaming the parameter and its allowed values (legacy shape oncited-by/cites/network, typed onpath/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-byornetworkfor 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 withrelationSync.status: "pending", and a later read sees the refresh. - Corrigenda (
32008R1272R(01),…R(02), …) are typedcorrigendumand 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 typedamendment. - One edge per pair. When one act both amends and corrects another, the edge carries the stronger type (
repealoveramendmentovercorrigendum). 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.implementationincludes the delegated and implementing acts EUR-Lex lists as "Completed by".proposaledges 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. repealmeans the whole act. A partial repeal, or a replacement of part of an act (an annex, an article), is typedamendment./citations/path,/citations/related,/citations/statsand/citations/transpositionread the stored data and don't trigger a refresh.- Completeness. Structural edges are as current as the last refresh (
relationSyncsays when; withpending,cooldown,errororskipped, 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.
"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).
nullwhen 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.
nullwhere 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.
nullon/search/semanticand/legislation/semantichits — read the document for it. Alsonullon a document held without text and on/documents/metadataanswered from LexAPI’s corpus. contentHash- A SHA-256 fingerprint of the text LexAPI holds — the
contentHashof 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 (thenversioncan stay the same). It covers the whole text whateverincludeorarticleIdselected.nullwhen there is no text, on/documents/metadata, and on/search/semanticand/legislation/semantichits — 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 isversion. language- Language of the text. On a search hit: the hit’s
language, else the language searched.
Which parts are source text. fieldProvenance lists, per class, the fields of the object that carries it:
"fieldProvenance": { "official_source_text": ["title", "content.fullText", "content.articles[].content", "content.annexes[].content"], "machine_extracted_structure": ["documentType", "dateOfDocument", "eli", "inForce", "content.articles", "content.annexes"] }
| Class | What it is |
|---|---|
official_source_text | The 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_structure | Parsed 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_translation | Machine-translated text. LexAPI serves none today, so the class never appears. |
machine_generated_interpretation | Produced by a model: summary, score, a snippet cut from a summary, extracted outcome fields, the HyDE hypotheticalDocument. Not source text. |
editorial_enrichment | Written 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.
| Where | provenance | fieldProvenance |
|---|---|---|
/documentContent, /documentContent/batch items, /documents/url | on document | on document |
/documents/metadata | on 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/:date | on document — the snapshot’s own hash and time; sourceUrl is the document’s page today, which can show a later text | on document |
/documents/:celex/versions | — each entry already has contentHash and fetchedAt | — |
/search/semantic, /legislation/semantic | on each hit, retrievedAt and contentHash null | on 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.
{
"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).
POST /api/v1/search
Search EUR-Lex with user-friendly parameters (no URL building required).
Request body
{
"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
| Field | Type | Description |
|---|---|---|
query | string | Search 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 |
textScope | string | title, text, title-text (default), or any |
dateFrom · dateTo | YYYY-MM-DD | Date range filter |
year · month | int / list | Specific year(s) or month(s) |
documentType | string / list | judgment, directive, regulation, decision, communication, … |
author | string / list | commission, council, parliament, court-of-justice, general-court, … |
procedure | string / list | ordinary, codecision, consent, consultation, … |
domain | string | EUR-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) |
subdomain | string / list | LEGISLATION, 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 |
language | string | Two-letter language code (default: en) |
maxPages | int | Result pages to fetch (default: 1, capped by tier) |
fresh | bool | true 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
{
"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
{
"celexNumber": "32016R0679"
}Response
{
"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:
200with full metadata andcontent: null;- an
X-Text-Available: falseheader; - a charge of 1 credit rather than 5 — the same price as
/documents/metadata, which is all you received.
{
"content": null,
"textAvailability": {
"available": false,
"reason": "not_in_language",
"retryable": true,
"availableLanguages": ["es", "it", "lv"]
}
}| reason | What it means | What to do |
|---|---|---|
not_in_language | The document has text, but not in the language you asked for. | Retry with one of availableLanguages. |
not_published_yet | The notice exists ahead of the text. | Retry later. |
no_machine_readable_rendition | EUR-Lex publishes no per-document text for it at all. | Don't retry. |
too_large | The 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. |
unknown | We 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
celexback 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,
latestConsolidatedis left out — we never point at an older, superseded consolidation — andnewestConsolidatednames the newest version with itsavailableLanguages: information, not a pointer to follow in your language. upcomingConsolidatedis likewise the next version or nothing.newestConsolidatedonly appears withsource: "cellar"; a corpus answer does not know the languages, so its pick is not language-filtered.
"newestConsolidated": { "celex": "02024R0370-20240423", "date": "2024-04-23", "source": "cellar", "availableLanguages": ["et"] }
"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).
inForcetrueorfalse. 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) ornot_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
inForceis still given. entryIntoForce- With
not_yet_in_force, when the entry into force is recorded.
{ "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 of32016R0679. On those documents the fields describe that act. - Not covered: amendments (an amended act is still
inForce: true; seelatestConsolidated) 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/metadataand/legislation/semantichits.
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 outcome | Credits | Counted in |
|---|---|---|
| Served from the LexAPI corpus | 1 | X-Batch-Corpus-Hits |
| Answered by the Publications Office (Cellar) | 4 | X-Batch-Cellar-Served |
| Recovered from an Official Journal issue | 4 | X-Batch-OJ-Recovered |
| Fetched live from EUR-Lex | 5 | X-Batch-Live-Fetches |
| … but EUR-Lex has no text for it | 1 | X-Batch-Live-Fetches (and X-Batch-Text-Unavailable) |
Failed with NOT_FOUND | 1 | X-Batch-Failed |
Failed otherwise (TIMEOUT, UPSTREAM_ERROR, INTERNAL) | 0 | X-Batch-Failed |
A national-law id, not an EU document (UNSUPPORTED_JURISDICTION) | 0 | X-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
{
"celexNumbers": [
"32016R0679",
"62018CJ0311",
"52020DC0790"
]
}Response
{
"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
| Field | Type | Description |
|---|---|---|
days | int | Look-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 |
documentType | string | Filter 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 |
author | string | Filter 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 |
domain | string | EUR-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) |
subdomain | string | Filter by subdomain — one value |
language | string | Default en |
limit | int | Max results (default: 50). A value that does not start with a number, or a negative one, is a 400 INVALID_PARAMS, refunded |
$ 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
{
"url": "https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32016R0679"
}Response
{
"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
{
"celexNumber": "32016R0679"
}Response
{
"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
{
"identifier": "ECLI:EU:C:2020:559"
}Response
{
"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.
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
| Field | Notes |
|---|---|
document | Required. 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 |
asOf | Required. YYYY-MM-DD, from 1952-01-01 to today (UTC) |
provision | Optional. 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 |
language | Optional, default en |
Response
{
"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.kindisconsolidatedoras_published(the act as published in the Official Journal: no consolidated version is dated on or before the date).asOfVersion.dateis the date the consolidated version carries. It can be earlier than the act’s entry into force.validUntilis 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.checkedAtis when the version list was read, when known (absent when the list came from a cache); it dates the list, not the text.actholds what the Publications Office records about the act; a field is absent when not known.act.inForceTodayis about today. It says nothing aboutasOf.- 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 answerversion_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.
asOfReason | When |
|---|---|
not_yet_adopted · not_yet_in_force · no_longer_in_force | The date is outside the act’s dates |
in_force_dates_unknown | The act’s dates do not establish it, or could not be read |
act_type_not_supported | The 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_cap | The list of versions, or of the acts amending the act, could not be read, or a lookup limit was reached. Retry |
not_in_language | The version for the date has no text in language |
amendment_not_consolidated | An act amending this act may have applied by the date, and no listed version is known to include it |
article_not_in_version | With provision: the version has no such article, annex or recital. asOfVersion is present |
provision_ambiguous · version_not_parsed | With 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_unavailable | With provision: the version has no text at the source |
fetch_failed · fetch_timeout · fetch_pending · fetch_capacity · fetch_budget_exhausted · request_deadline | With provision: the text could not be fetched now. Retry |
insufficient_credits · credit_check_failed | With 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
{
"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.
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.
curl "https://lex-api.com/api/v1/documents/32016R0679/at/2026-04-01" \ -H "x-api-key: $LEX_KEY"
{
"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 … */
}
}| Field | Meaning |
|---|---|
kind | Always observation_snapshot: a snapshot from LexAPI’s fetch history |
asOf | The 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.observedFrom | When the version began; null when LexAPI has no record of it |
document.observedUntil | When the next version’s text arrived; null for the current version |
document.fetchedAt | When this version’s text arrived at LexAPI (the same time as observedFrom) |
inForceLookup | Where 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 |
dateInFuture | true 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:
reason | Meaning |
|---|---|
before_tracking | The date is before the document entered the corpus. details.trackedSince says when that was; details.inForceLookup is present as above |
boundary_unknown | LexAPI 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
{
"celexNumber": "32016R0679"
}Response
{
"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
| Field | Type | Description |
|---|---|---|
limit | int | Page size, in edge rows (default: 100) |
offset | int | Skip N edge rows (default: 0) |
citationType | string | One type, or a comma-separated list: reference, amendment, repeal, corrigendum, implementation, legal-basis, proposal, transposition |
provenance | string | Comma-separated: notice, cellar, notice+cellar (see Citation graph) |
language | string | Language of the titles filled in from the corpus (default en; see titleSource). Does not filter edges |
{
"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.cooldownorerror: the refresh failed recently; the stored edges are served.skipped: no refresh ran;reasonisnot-applicable(not a legislation CELEX),disabled,busyorbudget(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.
{
"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).
{
"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.
{
"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.
GET /api/v1/citations/related/:celexNumber
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.
{
"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.
{
"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
| Field | Type | Description |
|---|---|---|
jurisdictions | string | Countries 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 |
language | string | Language of the act’s title (default en) |
{
"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).
POST /api/v1/search/semantic All credit plans
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
{
"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
| Field | Type | Description |
|---|---|---|
query | string (required) | Natural-language query, 3–1000 characters (Unicode code points) after trimming; outside them is a 400 INVALID_PARAMS |
min_score | number 0–1 | Minimum relevance score (optional) |
limit | int | Max results; capped by tier (FREE 10 / STARTER 20 / PROFESSIONAL 50 / BUSINESS and above 100) |
filters | object | Optional: 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 |
include | array | ["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. |
language | string | Content language (default en). The semantic index currently covers en, fr, de, es, it, sl, el, nl, pt, pl; an unsupported code returns 400. |
hyde | boolean | HyDE 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.
{
"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
| Field | Notes |
|---|---|
case_id | Snapshot-scoped id — can change when the index is rebuilt. For a persistent key use metadata.celex_id + metadata.document_type. |
score | Float 0–1. Higher = more relevant. |
jurisdiction · language | Usually EU / en. |
case_name · case_number · ecli | Human-readable identifiers. |
parties | The litigants as an array of strings — often a single "A v B" element. Omitted when unknown. |
court · decision_date | Issuing court and ISO-8601 date. |
summary | LLM-generated digest of the ruling. Useful for previews. |
summary_language | Only 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. |
text | The 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. |
textAvailability | Only 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_id | CELEX you can feed into /documentContent. |
metadata.document_type | judgment, order, ag_opinion, … Together with celex_id, the identity key that survives index rebuilds. |
metadata.paragraph_number | Position 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, withresetsAtand noRetry-After(noresetsAteither once the billing period has ended — key off the top-levelcode); - 502
UPSTREAM_ERROR, 504TIMEOUT.
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.
{
"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 usearticle_ref(art_19) as itsarticleIdto fetch just the matched article. language- The matched text’s language: the request’s
languageis 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
falseon 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 beforeasOfhas 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
| Field | Type | Description |
|---|---|---|
documentType | string / list | Exact stored label, ignoring case; several values (comma-separated or repeated) are ORed. regulation matches Regulation, not Implementing regulation — use documentTypeCode for a family |
documentTypeCode | string / list | Type 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 |
author | string / list | Whole 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 |
language | string | Default en. Give it once (a repeated language is a 400) |
dateFrom · dateTo | YYYY-MM-DD | Document-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 |
fetchedSince | ISO 8601 | Rows 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 |
changedSince | ISO 8601 | Rows whose text changed (contentChangedAt, a new version) at or after this time. The cheapest incremental sync. Same format as fetchedSince |
includeContent | bool | Include parsed sections/articles/tables (default true) |
includeHtml | bool | Include raw HTML blobs (large; default false) |
includeStubs | bool | Also 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. |
limit | int | Positive 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_EXHAUSTEDbefore 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
limitand the 50,000 server maximum.X-Export-Credits-Reservedshows the total, and_meta.creditsthe pool after it. - Low balance. If your pool cannot cover the reservation, the request fails with 402
CREDITS_EXHAUSTEDbefore 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.weightis the reservation anderror.details.availableyour balance after it: retry withlimitat or belowavailable. - 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: trueandtruncatedBy: "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 field | Notes |
|---|---|
written | Rows sent |
truncated | true 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 |
truncatedBy | limit, 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 |
skippedStubs | Rows that matched but hold no document text. Not written, not charged |
credits | Credit 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.
{"_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
| Header | Notes |
|---|---|
X-Export-Total | Rows matching when counted (regardless of limit; cached for up to a minute). The count never limits what is streamed |
X-Export-Streaming | Rows reserved up front. Rows added since the count are streamed too, each reserved as it comes; _done.written is the final count |
X-Export-Truncated | 1 if limit or the server maximum is below the match count; 0 otherwise. _done.truncated is authoritative |
X-Export-Credits-Reserved | Credit 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
# 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
{
"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
{
"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).
| Filter | Matches |
|---|---|
query | Every 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. |
documentType | Same 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). |
author | Same 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). |
subdomain | Same 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 / year | Optional 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)
{
"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.
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)
{
"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-20240423is 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
2xxwithin 10 seconds counts as delivered (a3xxis 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:
timestampis the time of that attempt, whiledelivery.id(alsoX-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
statusandconsecutiveFailures); if all seven attempts fail the webhook is set toFAILED(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.
{
"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.
{
"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.
watchCelexreplaces the whole list;searchCriteria: nullremoves the criteria (one of the two must remain).- Allowed
statusvalues:ACTIVE,PAUSED,FAILED. Setting it toACTIVEalso clears the failure counter. - A new
urlmust meet the URL requirements (url: nullor""means no change), and so must the stored one when you set aFAILEDorPAUSEDwebhook back toACTIVE.
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 ignoredmember-states/emabeside valid authors is listed but does not stop the other authors matching). urlErrornull, or{ reason, message }when the stored URL breaks a rule that needs no DNS lookup (for example anhttp://URL) — its deliveries are refused until you change the URL.
{
"name": "GDPR judgments (paused)",
"status": "PAUSED"
}DELETE /api/v1/webhooks/:id
Permanently delete a webhook and its delivery history.
{
"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.
{
"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
| Field | Type | Description |
|---|---|---|
limit | int | Page size (default: 50) |
offset | int | Skip N (default: 0) |
{
"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
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
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
$ 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)
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), ); }