API documentation

Base path /v1. JSON, UTF-8. The version is in the path; breaking changes will require /v2.

Authenticate with Authorization: Bearer acta_.... Keys are issued by hand — there is no signup. Below, $ACTA_KEY is your token.

Every act and segment response includes content_hash or hash, source.url, retrieved_at and a disclaimer object.

Errors

Status	When
400	Bad query — a malformed filter, or a from that is not RFC 3339
401	Missing or invalid API key
404	Unknown act, segment or watchlist
429	Rate limit or daily quota exceeded. The response carries Retry-After
503	An upstream Publications Office call is the only copy available

Routes

GET/healthpublic

Liveness plus library counts and the last poll. Rate-limited, unauthenticated.

curl -s '/v1/health'

GET/resolve?q=public

Resolve a messy citation to 0..n acts. Accepts an Acta ID, a CELEX (including consolidation and corrigendum forms), an ELI URL or path, a EUR-Lex or Cellar URL, or informal wording such as Regulation (EU) 2023/956. If exactly one act matches and the query named an article or annex, the default segment is returned too. An unresolved query is not an error.

q — the citation string (required)

curl -s --get --data-urlencode 'q=Regulation (EU) 2023/956' \
  '/v1/resolve'

GET/actsAPI key

List acts with filters and cursor pagination.

celex, resource_type, in_force, is_consolidation, authentic, watchlist
date_publication_from, date_publication_to (YYYY-MM-DD)
cursor — opaque, from the previous response
limit — max 100, default 25

curl -s -H "Authorization: Bearer $ACTA_KEY" \
  '/v1/acts?in_force=true&limit=1'

GET/acts/{id}API key

Act metadata plus a segment outline (id, kind, anchor, heading, hash). {id} accepts an Acta ID or a CELEX.

curl -s -H "Authorization: Bearer $ACTA_KEY" \
  '/v1/acts/32023R0956'

GET/acts/{id}/segmentsAPI key

Every segment of an act, in document order.

kind — article | paragraph | recital | annex | body

curl -s -H "Authorization: Bearer $ACTA_KEY" \
  '/v1/acts/32023R0956/segments'

GET/acts/{id}/segments/{anchor}API key

One segment with full text, its hash and the official source URL. This is the call a filing tool makes to show a cited article next to a rule.

curl -s -H "Authorization: Bearer $ACTA_KEY" \
  '/v1/acts/32023R0956/segments/art_2'

GET/acts/{id}/textAPI key

Concatenated English text of the whole act.

format — plain (default; the only format in the MVP)

curl -s -H "Authorization: Bearer $ACTA_KEY" \
  '/v1/acts/32023R0956/text?format=plain'

GET/acts/{id}/graphAPI key

One hop of the relationship graph: legal_basis, amends, amended_by, corrects, corrected_by, consolidates, latest_consolidation. IDs only, served from Acta with no upstream call.

curl -s -H "Authorization: Bearer $ACTA_KEY" \
  '/v1/acts/32023R0956/graph'

GET/search?q=public

BM25 search over segment text and English titles. resolve() runs first, so an exact citation is returned ahead of ranked hits and tagged match=exact. Filters are the same as /acts plus kind. Defaults to language=en.

q — the query (required)
in_force, resource_type, watchlist, authentic, is_consolidation, kind
date_publication_from, date_publication_to

curl -s --get --data-urlencode 'q="carbon border"' \
  --data-urlencode 'in_force=true' '/v1/search'

GET/changesAPI key

The change feed: new or updated works in scope, plus graph events touching a watchlist. Ordered oldest first; page with cursor.

from — RFC 3339 timestamp (required)
watchlist, severity (P0|P1|P2|P3), cursor, limit

curl -s -H "Authorization: Bearer $ACTA_KEY" \
  '/v1/changes?from=2026-01-01T00:00:00Z&watchlist=cbam-core&severity=P0'

GET/watchlistsAPI key

List watchlists with their resolved set size.

curl -s -H "Authorization: Bearer $ACTA_KEY" '/v1/watchlists'

GET/watchlists/{id}API key

A watchlist definition plus the CELEX set resolved from the Cellar graph at the last poll.

curl -s -H "Authorization: Bearer $ACTA_KEY" \
  '/v1/watchlists/cbam-core'

GET/statuspublic

Last successful and attempted poll, last poll error, last event, library counts and index size. The field is named `corpus`, as the spec requires.

curl -s '/v1/status'

POST/webhooksAPI key

Subscribe to events. Acta POSTs the event JSON to your URL with an X-Acta-Signature header containing sha256=<HMAC-SHA256(secret, raw body)>. Delivery is retried 3 times, then dropped and logged. The secret is returned once, at creation.

curl -s -X POST -H "Authorization: Bearer $ACTA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/acta","watchlist":"cbam-core","min_severity":"P0"}' \
  '/v1/webhooks'

Required wording

Acta is an unofficial mirror of texts published by the Publications Office of the European Union. Consolidations are reading aids and are not authentic. Acta is not legal advice and is not a substitute for EUR-Lex or the Official Journal. Hashes identify the bytes Acta stored, not an official instrument.

Full disclaimer