API REST

L’API REST è la stessa che usa l’interfaccia: non esiste alcuna route privata. I suoi URL riportano i nomi fisici — quelli che leggi anche in SQL.

/api/v1/<tenant>/data/<base>/<table>
/api/v1/t4z56fq/data/b_t4z56fq_ventes/opportunites

Un token

Nell’interfaccia, menu ⋯ del database → API e agenti → Token API e MCP…: chi ha il livello Gestione sul database, o sul suo progetto, vi crea un token di integrazione limitato a questo database — tutti i suoi ambienti, oppure uno solo —, in sola lettura per impostazione predefinita, dopo aver confermato la propria password — un account senza password, che accede tramite un fornitore di identità, non può ancora farlo. Viene mostrato una sola volta; mettilo in una variabile d’ambiente.

Un token legge; crea e modifica se è stato creato in scrittura, ed elimina se è stato creato per questo — permessi «Lettura, scrittura ed eliminazione», salvo una riga che una relazione a cascata porterebbe via insieme ad altre. Non ha mai più permessi della persona che l’ha creato.

export BASEDB_TOKEN=bdb_…
curl "http://localhost:3000/api/v1/t4z56fq/data/b_t4z56fq_ventes/opportunites?limit=20" \
  -H "Authorization: Bearer $BASEDB_TOKEN"

Scegliere l’ambiente

Un database che ha più ambienti — produzione, collaudo… — resta un solo database per un token creato per tutto il database. Il percorso nomina il database con il nome della sua produzione, e l’intestazione X-Basedb-Environment sceglie l’ambiente:

curl "http://localhost:3000/api/v1/t4z56fq/data/b_t4z56fq_ventes/opportunites" \
  -H "Authorization: Bearer $BASEDB_TOKEN" \
  -H "X-Basedb-Environment: recette"

• Senza l’intestazione, vale l’ambiente che il percorso nomina: b_t4z56fq_ventes è la produzione, b_t4z56fq_ventes_recette il collaudo — le due scritture restano valide.
• ?environment=recette fa lo stesso per un client che non imposta intestazioni.
• Un ambiente si indica con il suo badge, senza tenere conto di maiuscole e accenti, oppure con production. Un ambiente che il database non ha risponde 404, come ogni risorsa assente.
• GET /api/v1/<tenant>/meta/bases elenca ogni ambiente con il suo blocco environment (label, production); con l’intestazione, elenca solo quello.

Un token limitato a un solo ambiente, alla creazione, non ne apre nessun altro: l’intestazione non cambia nulla. I suoi permessi sono sempre incrociati, ambiente per ambiente, con quelli della persona che l’ha creato.

Leggere

Parametro	Ruolo
filter	un’espressione leggibile: statut eq "gagne" and montant gte 10000
sort	-montant,nom
fields	le colonne da restituire
limit, after	paginazione tramite cursore cifrato: meta.next_cursor di una pagina, passato come after, restituisce quella successiva (meta.has_next_page)
links=display	le relazioni con il loro valore visualizzato
count=exact	il totale, con un tetto di 100.000
variables=raw	i testi lunghi così come sono scritti, {{colonne}} compreso, anziché con i valori della riga

Gli operatori: eq, ne, eq_ci, contains, starts_with, ends_with, in, is_null, gt, gte, lt, lte, between, combinati con and, or, not e parentesi. Un filtro attraversa una relazione: clients_id.ville eq "Lyon".

Scrivere

curl -X POST "http://localhost:3000/api/v1/t4z56fq/data/b_t4z56fq_ventes/opportunites" \
  -H "Authorization: Bearer $BASEDB_TOKEN" -H "content-type: application/json" \
  -d '{"values": {"nom": "Audit RGPD", "statut": "nouveau", "montant": 12000}}'

PATCH …/<table>/<_id> modifica una riga con lo stesso corpo {"values": {…}}. Gli errori hanno una forma unica: { "code": "…", "details": {…}, "request_id": "…" }, con un codice stabile per ogni causa.

Ogni scrittura restituisce l’intestazione x-basedb-transaction: passarla a POST /api/v1/<tenant>/history/undo ({"transaction": "…"}) la annulla, come Ctrl+Z nell’interfaccia — con un rifiuto se la riga è stata modificata nel frattempo.

Oltre le righe

Con lo stesso token:

Route	Ruolo
GET …/data/<base>/<table>/aggregate	riepiloghi su tutte le righe di un filtro: aggregates=montant:sum,nom:filled, group=statut
GET …/data/<base>/<table>/<_id>/comments, POST	leggere e scrivere i commenti di una riga
POST /api/v1/<tenant>/automations/<id>/run	avviare un’automazione attivata da un pulsante, su una riga ({"record": "…"})
GET /api/v1/<tenant>/meta/bases/<base>/dashboards	le dashboard di un database
GET /api/v1/<tenant>/meta/users	i membri dello spazio di lavoro, per un campo Persona
GET /api/v1/<tenant>/meta/templates	i modelli di database della galleria
GET /api/v1/<tenant>/events?base=<base>&table=<table>	seguire una tabella in tempo reale: dei segnali, riletti poi dalle route qui sopra (vedi Webhook)

Le viste condivise si leggono senza account: GET /api/v1/views/<jeton> e …/rows in JSON, …/calendar.ics in iCalendar.

Costruire — creare un’automazione, una dashboard, un’integrazione — resta riservato a una sessione dell’interfaccia: un token legge e scrive righe, non modifica il database.

Colori e icone

Una tabella e ogni opzione di un campo di selezione hanno un colore (color, #rrggbb) e un’icona (icon, il nome di un’icona Lucide che l’interfaccia disegna: truck, circle-check, flame…). GET …/meta/bases/<base> li restituisce per il database, le sue tabelle e le opzioni dei suoi campi.

Per sceglierli, con il token di accesso di una persona che può modificare la struttura (POST /auth/session/access) — un token di integrazione non modifica il database:

Route	Corpo
POST …/admin/bases/<base>/tables	{"label": "Tickets", "color": "#dc2626", "icon": "flame", "fields": […]}
PATCH …/admin/bases/<base>/tables/<table>	{"color": "#2563eb", "icon": "inbox"} — le tre chiavi color, icon, image viaggiano insieme: nominarne una sostituisce tutte e tre
POST …/admin/bases/<base>/tables/<table>/fields	{"label": "Priorité", "kind": "select", "options": [{"value": "haute", "color": "#dc2626", "icon": "flame"}, …]}
PUT …/admin/bases/<base>/tables/<table>/fields/<champ>/options	l’intero elenco delle opzioni, nell’ordine, ciascuna con il suo colore e la sua icona

Un agente passa dal server MCP, dove propone queste modifiche. Un campo non ha un’icona da scegliere: l’interfaccia disegna quella del suo tipo.

Creare un database da un modello

Un’applicazione che si installa crea il suo database in una sola chiamata: il server applica il modello — tabelle, campi, relazioni, righe di esempio, viste, dashboard, automazioni — e, se un passaggio fallisce, non lascia alcun database dietro di sé.

curl -X POST "http://localhost:3000/api/v1/t4z56fq/admin/bases" \
  -H "Authorization: Bearer $ACCES" -H "content-type: application/json" \
  -d '{"template": "crm", "label": "Ventes", "rows": false}'

template è la chiave di un modello della galleria, oppure un modello intero nel formato dei modelli. Con l’intestazione Accept: application/x-ndjson, la risposta arriva riga per riga: una riga {"step": …} per passaggio, poi il database creato. Questa chiamata richiede il token di accesso di una persona che può creare un database (POST /auth/session/access, dopo l’accesso): un token di integrazione apre solo un database esistente.

Verificare un token

I token di basedb non si verificano fuori da basedb. Un’applicazione che ne riceve uno — uno strumento aperto da basedb con il token della persona, per esempio — chiede quanto vale (introspezione, RFC 7662), con il proprio token di integrazione:

curl -X POST "http://localhost:3000/auth/introspect" \
  -H "Authorization: Bearer $BASEDB_TOKEN" \
  --data-urlencode "token=$JETON_RECU"

{ "active": true, "token_type": "access_token",
  "sub": "0195a…", "email": "claire@example.com", "name": "Claire Martin",
  "tenant": "t4z56fq", "groups": ["Commerciaux"], "exp": 1790000000 }

Ogni token che non vale — sconosciuto, scaduto, revocato, sessione chiusa, altro spazio di lavoro — risponde {"active": false}, senza dire perché. La risposta è letta in diretta: una disconnessione si vede immediatamente. Per un token di integrazione, la risposta indica anche il database che apre (base, la sua produzione), se ne apre tutti gli ambienti (environments: all) oppure uno solo (one), il suo accesso (read, write o delete) e le sue superfici.

La documentazione generata

Ogni database ha la sua pagina Documentazione API e MCP: per ogni tabella, i suoi endpoint, le sue colonne, esempi in cURL e in JavaScript. È filtrata in base ai tuoi permessi — due lettori ne ottengono due versioni —, scritta nella lingua del tuo schermo, ed esiste anche in OpenAPI 3.1 (/api/v1/<tenant>/meta/bases/<base>/openapi.json), che dichiara il token Bearer e l’intestazione X-Basedb-Environment. I nomi, i percorsi e i codici di errore restano gli stessi in tutte le lingue.