API & MCP

Lexistoria oferă abonaților acces programatic la legislația României: un server MCP (Model Context Protocol) pentru asistenți AI — inclus din planul Pro — și un API REST pentru aplicațiile tale — în planul Max. Ambele servesc aceleași răspunsuri, cu aceleași reguli de onestitate ca site-ul: textul consolidat la zi sau la orice dată din istoric, cu citări canonice și cu stările reale ale evidenței spuse explicit.

Principii

• Răspunsuri în formă de întrebare. Fiecare răspuns e legat de o citare concretă — un act, un articol, o dată — și e mărginit. Nu există endpoint-uri de export în masă.
• Onestitate temporală. La o dată din trecut, răspunsul poate fi legitim „nu exista încă”, „istoricul e în verificare” sau „actul era abrogat” — stări explicite în răspuns (vezi Stările oneste), niciodată textul de azi prezentat drept forma de atunci.
• Adresare identică cu site-ul. Slug-urile și parametrul la= sunt aceleași ca în URL-urile paginilor — un răspuns API și o pagină citează la fel.

Autentificare

Toate cererile poartă o cheie de API în antetul Authorization:

Authorization: Bearer lxk_...

Cheile se emit pentru conturile cu planul Pro sau Max, din pagina contului. O singură cheie servește ambele suprafețe: cheia este identitatea, iar planul contului decide, la fiecare cerere, ce suprafețe răspund — serverul MCP din planul Pro, API-ul REST din planul Max (o cheie Pro primește 403 pe /api/v1). Cheia se afișează o singură dată la emitere și moștenește planul contului la fiecare cerere: un abonament expirat răspunde imediat cu 403. Autentificarea se face exclusiv prin antet — sesiunea de browser nu deschide API-ul, iar API-ul nu poate fi apelat din JavaScript-ul altor site-uri.

Limite

Un apel de tool MCP contează ca o cerere. Erorile au forma { "error": "...", "message": "..." } cu status HTTP corect.

API REST — /api/v1

Baza: https://www.lexistoria.ro/api/v1 — în planul Max. Toate răspunsurile sunt JSON, UTF-8. Parametrul la=AAAA-LL-ZZ cere forma legii la acea dată, oriunde apare.

Exemple

Articolul 16 din Codul muncii, în forma de azi:

curl https://www.lexistoria.ro/api/v1/act/codul-muncii/articol/art-16 \
  -H "Authorization: Bearer lxk_..."

Același articol, în forma din 1 ianuarie 2012:

curl "https://www.lexistoria.ro/api/v1/act/codul-muncii/articol/art-16?la=2012-01-01" \
  -H "Authorization: Bearer lxk_..."

Răspunsul (scurtat):

{
  "act": { "slug": "codul-muncii", "name": "Codul muncii" },
  "articol": {
    "slug": "art-16",
    "article_number": "16",
    "la": "2012-01-01",
    "absent_at_date": false,
    "history_held": false,
    "text": "Contractul individual de muncă se încheie ...",
    "segments": [ { "type": "alineat", "label": "(1)", "text": "...", "children": [] } ],
    "version": {
      "change_type": "republicare",
      "effective_from": "2011-05-18",
      "effective_until": "2018-04-13",
      "citation": null
    }
  }
}

O citare rezolvată:

curl "https://www.lexistoria.ro/api/v1/citare?text=art.%2028%20og%202/2001" \
  -H "Authorization: Bearer lxk_..."

Stările oneste

Distincția de bază: 404 înseamnă că identitatea nu există deloc; 200 cu indicatori înseamnă că există, dar nu la data cerută — clientul trebuie să le deosebească.

Serverul MCP

Endpoint: https://www.lexistoria.ro/mcp — în planul Pro; transport streamable HTTP, fără sesiuni, cu aceeași cheie în același antet. Tool-urile corespund 1:1 endpoint-urilor REST și întorc aceleași forme JSON:

În Claude Code:

claude mcp add --transport http lexistoria https://www.lexistoria.ro/mcp \
  --header "Authorization: Bearer lxk_..."

În orice client MCP care suportă servere remote cu antete personalizate (configurație generică):

{
  "mcpServers": {
    "lexistoria": {
      "type": "http",
      "url": "https://www.lexistoria.ro/mcp",
      "headers": { "Authorization": "Bearer lxk_..." }
    }
  }
}

Descrierile tool-urilor învață asistentul gramatica citărilor și stările oneste, așa că un agent conectat va spune „articolul nu exista la această dată” în loc să inventeze — exact comportamentul site-ului.

Versionare și stabilitate

Formele răspunsurilor din /api/v1 sunt înghețate: câmpuri noi pot apărea (aditiv), câmpurile existente nu se schimbă și nu dispar. O schimbare incompatibilă ar deschide /v2, cu /v1 păstrat în paralel.

Erori

Server MCP în planul Pro · API REST în planul Max — planurile · texte cu caracter informativ, conform termenilor.