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.

Disambiguazione con le API di Askme Chat

Queste sono le API ufficiali di Askme AI (/api/v2, autenticazione con API key). Askme Chat espone anche un gruppo di endpoint /api/ai/..., documentato nella sua sezione API: si tratta di un livello interno legacy, non del canale consigliato per nuove integrazioni con le funzionalità di intelligenza artificiale.

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
• Endpoint: Agenti, Chat e Conversazioni — agenti, chat, conversazioni, server MCP, template prompt
• Endpoint: Knowledge Base — knowledge base, documenti, FAQ, scraping, sorgenti database, ricerca
• Endpoint: Analisi e Classificazione — analisi contenuti/PDF/CV/dati, OCR, cataloghi Similarity
• Endpoint: Utenti, Tenant e Quote — utenti, ruoli, API key, feature flag, quote, audit
• Endpoint: Monitoraggio e Costi — utilizzo, costi, allarmi, dashboard
• Esempi — flussi end-to-end (chat con agente, ingest knowledge base, analisi PDF)
• Migrazione dalle API v1 — compatibilità e transizione per integrazioni provenienti da Askme AI v1

Compatibilità con Askme AI v1

Per la transizione graduale dei tenant da Askme AI v1, è attivo uno shim di compatibilità sul prefisso legacy /api/*:

• Un sottoinsieme di endpoint v1 viene rimappato automaticamente verso le rotte v2 equivalenti. Le richieste instradate dallo shim sono marcate internamente con source_app=legacy-v1, per mantenere distinta l'attribuzione dei consumi rispetto alle integrazioni già portate su /api/v2.
• Gli endpoint v1 privi di un equivalente v2 rispondono 410 Gone con un corpo che indica il percorso di migrazione consigliato.

Per la tabella di corrispondenza endpoint v1 → v2 e la checklist di migrazione, vedere Migrazione dalle API v1.

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, contattare il referente tecnico della propria istanza Askme AI.