Riferimento API — Panoramica

URL base, autenticazione JWT, rate limit per piano, formato errori, codici di stato e versioning.

URL Base

Tutte le richieste sono dirette a:

https://api.relaai.com/api/v1/

Le richieste interne tra microservizi utilizzano:

http://internal-api:8000/api/v1/

Autenticazione

L'API utilizza JSON Web Token (JWT) emessi al momento del login. Includi il token nell'header Authorization:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Campo JWT	Descrizione
`sub`	ID dell'utente
`tenant_id`	ID del tenant
`role`	Ruolo dell'utente
`permissions`	Lista dei permessi
`exp`	Scadenza (15 minuti per impostazione predefinita)

I token vengono aggiornati tramite POST /api/v1/auth/refresh con il refresh token.

Rate Limit per Piano

Piano	Richieste/min	Burst massimo
Free	30	10
Starter	120	30
Professional	600	100
Enterprise	3.000	500

Header di risposta inclusi in ogni richiesta:

X-RateLimit-Limit — Limite totale della finestra
X-RateLimit-Remaining — Richieste rimanenti
X-RateLimit-Reset — Timestamp di reset (Unix epoch)

Formato degli Errori

Tutti gli errori seguono un formato consistente:

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND",
  "request_id": "req_abc123"
}

Codici di Stato

Codice	Significato
`200`	Operazione riuscita
`201`	Risorsa creata
`204`	Eliminato, nessun contenuto
`400`	Richiesta non valida
`401`	Non autenticato
`403`	Nessun permesso o limite del piano
`404`	Risorsa non trovata
`409`	Conflitto (duplicato)
`422`	Errore di validazione
`429`	Rate limit superato
`500`	Errore interno del server

Paginazione

Gli endpoint di elenco supportano la paginazione con skip e limit:

GET /api/v1/agents?skip=0&limit=20

La risposta include metadati di paginazione nel corpo.

L'API live espone ~20 router sotto /api/v1/. Le pagine di questa sezione coprono i gruppi più usati (agents, assets, maintenance, data, admin). Questa tabella è la fonte unica di verità per l'elenco completo:

Prefisso	Scopo	Docs
`/api/v1/whatsapp/agents`	Agenti WhatsApp	whatsapp-agents/create
`/api/v1/whatsapp/numbers`	Numeri Evolution API	whatsapp-agents/numbers
`/api/v1/email`	Agenti email	email-agents/create
`/api/v1/email/accounts`	Account email Postmark	email-agents/accounts
`/api/v1/tools`	Tool di agenti	tools/overview
`/api/v1/prompts`	Gemini prompt optimizer	features/prompt-optimizer
`/api/v1/collections`	Collezioni di dati	data/collections
`/api/v1/extraction-templates`	Template di estrazione	data/extractions
`/api/v1/extractions`	Estrazione IA + CRUD record	data/extractions
`/api/v1/files`	Upload multipart a GCS	features/file-uploads
`/api/v1/machine`	Gateway eventi industriali	machine-agents/create
`/api/v1/dashboard`	KPI della dashboard operativa	features/operational-dashboard
`/api/v1/assets`	Asset industriali	assets-api
`/api/v1/predictive-config`	Config del motore predittivo	maintenance/predictive-config
`/api/v1/reports`	Report PDF/Excel on-demand	data/reports
`/api/v1/scheduled-reports`	Report programmati	data/scheduled-reports
`/api/v1/brandings`	Preset di branding	admin/brandings
`/api/v1/audit`	Audit trail immutabile	admin/audit
`/api/v1/csat`	Sondaggi CSAT	features/csat

Tutti gli endpoint sono REST JSON, autenticati con JWT e rate-limited secondo il piano del tenant. L'architettura del pipeline vive in architecture.

Versioning

La versione corrente e v1. Quando una nuova versione sara disponibile, gli header di deprecazione indicheranno il percorso di migrazione:

Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: </api/v2/resource>; rel="successor-version"

Endpoint Interni

Alcuni endpoint sono riservati alla comunicazione tra servizi:

Endpoint	Utilizzo
`POST /internal/events`	Ingestione interna di eventi
`POST /internal/notifications`	Coda delle notifiche
`GET /internal/health`	Health check del servizio

Questi endpoint richiedono un token di servizio interno e non sono esposti nell'API pubblica.