Panoramica API REST

Le API REST di Askme AI consentono ad applicazioni esterne di orchestrare agenti conversazionali, eseguire chat con RAG, gestire knowledge base, lanciare analisi (PDF, CV, classificazione, OCR) e leggere metriche di monitoraggio del proprio tenant.

URL Base

https://ai.askme.it/api/v2

ai.askme.it è l'host della console Askme AI del tuo tenant. Tutti gli endpoint sono prefissati con /api/v2/....

Autenticazione

Unico canale: API key nell'header X-Api-Key.

X-Api-Key: amai_<la_tua_chiave>

Le chiavi si generano dalla console amministrativa del tenant (sezione Amministrazione → Chiavi API, vedi manuale). Hanno sempre prefisso amai_. Dettagli completi: Autenticazione.

Header obbligatori

Header	Descrizione
X-Api-Key	Chiave API amai_<key>
X-Source-App	Identifica il chiamante. Lista chiusa: askmechat, askmedesk, api_direct, askmeai, internal. Per integrazioni esterne il valore tipico è api_direct
Content-Type	application/json sui POST/PUT/PATCH

Header opzionale ma consigliato:

Header	Descrizione
X-External-Id	Identificatore opaco del sistema chiamante (ticket ID, ordine ID, ...). Propagato nei record di costo per la correlazione end-to-end. Max 255 caratteri

Codici di stato HTTP

Codice	Descrizione
200	OK
201	Risorsa creata
204	OK senza body
400	Richiesta malformata
401	API key assente o non valida
403	Permesso insufficiente per la chiave
404	Risorsa non trovata
409	Conflitto (es. risorsa già esistente)
422	Validazione del body fallita
429	Quota o rate limit superato
500	Errore interno
503	Servizio temporaneamente non disponibile

Paginazione

Gli endpoint che restituiscono liste usano paginazione offset/limit:

Query string:

• offset — indice del primo elemento (default 0)
• limit — numero di elementi (default tipicamente 50, max 200)

Response:

{
  "items": [ /* ... */ ],
  "total": 142,
  "offset": 0,
  "limit": 50
}

Rate limit

Ogni chiave può avere limiti dedicati impostati al momento della creazione:

• rate_limit_rpm — richieste al minuto
• rate_limit_rpd — richieste al giorno

Al superamento il servizio risponde 429 Too Many Requests con header Retry-After (secondi).

A livello tenant agiscono inoltre le quote di piano (es. conversazioni al mese, AI credit). Al superamento la risposta è 429 con detail esplicativo.

Streaming (SSE)

Gli endpoint di chat supportano lo streaming via Server-Sent Events. Per richiedere lo stream basta passare "stream": true nel body del POST /api/v2/chat. La risposta avrà Content-Type: text/event-stream e una sequenza di eventi data: {...} con i token man mano che vengono generati. Eventi tipici: rag_thinking, delta, confidence, handoff_decision, usage, done.

Esempio rapido

curl -X POST "https://ai.askme.it/api/v2/chat" \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -H "X-External-Id: ticket-9281" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "message": "Riassumi le ultime tre policy aziendali",
    "stream": false
  }'

Sezioni

• Autenticazione — generazione chiavi, header, esempi
• Endpoints — riferimento delle principali risorse
• Esempi — flussi end-to-end (chat con agente, ingest knowledge base, analisi PDF)

Errori comuni

Codice	Causa tipica	Cosa fare
401 X-Api-Key header required	Header non inviato	Aggiungi X-Api-Key
401 Invalid API key format	Prefisso amai_ mancante	Verifica di copiare la chiave intera
401 Invalid API key	Chiave revocata o scaduta	Genera/ruota la chiave
403 Forbidden	Permesso insufficiente	Aggiorna il ruolo associato alla chiave
429 Quota exceeded	Limite di piano superato	Attendi il rinnovo del periodo di quota o richiedi upgrade

Supporto

Per richieste su API e integrazioni: contatta il referente tecnico della tua istanza Askme AI.