Prezentarea API-ului
Adresa de bază, autentificarea, formatul cererilor și al răspunsurilor, limitele și regulile comune tuturor rutelor.
Adresa de bază
https://app.ilustromania.com/nucleuRutele produsului au prefixul de versiune /v1. Excepțiile (5) sunt descoperirea OAuth (/.well-known/…) și verificarea de sănătate (/sanatate). Exemplu: GET https://app.ilustromania.com/nucleu/v1/agentie/creatori.
Autentificarea
| Cine apelează | Cum se autentifică |
|---|---|
| Aplicația web (browserul) | cookie-ul de sesiune __Host-sesiune, pus la intrarea în cont |
| Un script sau un server al firmei | o cheie API: Authorization: Bearer ilk_…, cu rol și expirare; deocamdată doar pe rutele de citire deschise cheilor |
| Un script care are nevoie de alte rute | cookie-ul de sesiune, trimis explicit în antetul Cookie |
| Un asistent AI prin MCP | Authorization: Bearer mcp_…, obținut prin OAuth |
| Executorii de pe server | jeton de serviciu, cu rolul executor |
curl https://app.ilustromania.com/nucleu/v1/agentie/creatori \
-H "Cookie: __Host-sesiune=$JETON_SESIUNE"Jetonul de sesiune dă aceleași drepturi ca și contul tău. Nu îl pune în cod, în commituri sau în mesaje; ține-l într-o variabilă de mediu.
Firma activă
Cererea lucrează pe firma activă a sesiunii. Când ai mai multe firme deschise în taburi diferite, aplicația trimite firma tabului în antetul x-firma-tab. Firma se verifică pe server: nu poți alege o firmă la care nu ai acces.
Formatul
- Cererile și răspunsurile sunt JSON (
Content-Type: application/json), în UTF-8. - Corpul cererilor de scriere este validat cu o schemă. Un câmp lipsă sau de alt tip înseamnă
400. - Datele calendaristice sunt
AAAA-LL-ZZ; momentele sunt ISO 8601 în UTC (2026-11-11T10:24:05Z).
Răspunsurile de eroare
Orice eroare are un corp cu câmpul eroare, iar uneori și motiv sau alte detalii:
{ "eroare": "interzis" }Cu antetul Accept: application/problem+json, aceeași eroare vine în formatul standard RFC 9457, cu un cod stabil. Lista completă a codurilor și formatul nou sunt în Erori.
Numărul cererii
Fiecare răspuns are antetul x-request-id. Poți trimite tu unul (8–64 de caractere: litere, cifre, - sau _) și platforma îl păstrează; altfel pune unul nou. Când raportezi o eroare, trimite acest număr.
Scrierile repetate
Câteva rute care creează documente acceptă antetul Idempotency-Key: o scriere trimisă din nou cu aceeași cheie nu se aplică de două ori. Detaliile sunt în Cereri repetate fără dubluri.
Accesul fiecărei rute
Fiecare rută din referință are o etichetă de acces:
| Etichetă | Înseamnă |
|---|---|
public | fără autentificare |
sesiune | orice cont intrat; modulul verifică apoi drepturile fine |
rol:admin | doar administratorul firmei active |
rol:executor | doar jetoanele de serviciu ale agenților |
intern | dovadă verificată de modul (canal semnat), nu de sesiune |
Limitele
Scrierile au o limită comună de 300 pe minut pe sesiune și 1200 pe minut pe IP; citirile, 1200 pe sesiune și 6000 pe IP. Fiecare scriere primește antetele RateLimit și RateLimit-Policy, cu câte cereri mai ai; peste prag, răspunsul este 429 cu Retry-After. Detaliile sunt în Limite.
Specificația OpenAPI
GET /v1/openapi.json întoarce specificația OpenAPI a rutelor descrise cu scheme. Ruta cere rolul admin. Din aceeași specificație vin, în referința de aici, tabelele de parametri, de corp și de răspuns și exemplele de corp și de răspuns, pe cele 107 de rute care au schemă; celelalte au descrierea și un exemplu de cerere.
Versiunile
Versiunea curentă este v1 și este singura. Adăugirile intră în v1; o schimbare care rupe ceva apare doar în v2, cu cel puțin 6 luni în care merg amândouă. Regula întreagă este în Versiuni API; schimbările se anunță în Noutăți.