Passa al contenuto principale

Panoramica API REST

Le API REST di Askme AI consentono ad applicazioni esterne di orchestrare agenti conversazionali, conversare con gli agenti usando le basi di conoscenza, gestire basi di conoscenza e documenti, avviare analisi di documenti e testi (contenuti, PDF, CV, OCR, verifica documentale, anonimizzazione, classificazione) e tradurre testi, sempre all'interno della propria organizzazione.

Disambiguazione con le API di Askme Chat

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

URL base​

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

ai.askme.it rappresenta l'host della console Askme AI della propria organizzazione: negli esempi di questa documentazione va sostituito con l'indirizzo effettivo. Tutti gli endpoint sono prefissati con /api/v2/....

Autenticazione​

Le integrazioni si autenticano con una chiave API trasmessa nell'intestazione X-Api-Key.

X-Api-Key: amai_<chiave>

Le chiavi si generano dalla console in Impostazioni › Chiavi API (si veda il manuale) e hanno sempre il prefisso amai_. Ogni chiave può eseguire soltanto le operazioni coperte dai suoi scope. I dettagli sono descritti in Autenticazione.

Intestazioni​

IntestazioneObbligatoriaDescrizione
X-Api-KeySìChiave API amai_<chiave>
Content-TypeSui corpi JSONapplication/json sulle richieste POST, PUT e PATCH con corpo JSON; multipart/form-data sui caricamenti di file
X-Source-AppNoApplicazione a cui attribuire consumi e conversazioni. Se manca, o se il valore non è tra quelli riconosciuti, vale l'applicazione di origine impostata sulla chiave. Per un'integrazione diretta il valore consigliato è api_direct
X-External-IdNoIdentificativo opaco del sistema chiamante (numero di ticket, di ordine, ...), riportato nei record di consumo per la correlazione. Massimo 255 caratteri

L'intestazione X-External-Id serve soltanto all'attribuzione dei consumi: per ritrovare una conversazione tramite un identificativo esterno si usa il campo external_conversation_id nel corpo di POST /chat (si veda Endpoint: Agenti, Chat e Conversazioni).

Codici di stato HTTP​

CodiceDescrizione
200Richiesta eseguita
201Risorsa creata
202Richiesta accettata: l'elaborazione prosegue in background (analisi, reindicizzazione, test dei webhook)
204Richiesta eseguita, nessun contenuto nella risposta
400Richiesta non valida
401Chiave assente, non valida, revocata o scaduta
403Operazione non consentita. Il corpo indica il motivo: {"detail": {"code": "PERMISSION_DENIED", "permission": "<codice>"}} quando gli scope della chiave non coprono l'operazione, {"detail": {"code": "FEATURE_FLAG_DISABLED", "flag": "<codice>"}} quando la funzionalità non è attiva per l'organizzazione
404Risorsa inesistente, di un'altra organizzazione o non visibile alla chiave
409Conflitto con lo stato della risorsa (per esempio una base di conoscenza ancora usata da agenti, una reindicizzazione già in corso, una chiave revocata)
413Contenuto troppo grande: file oltre il limite consentito oppure messaggio che supera la finestra di contesto del modello
422Validazione del corpo o dei parametri non superata
429Limite di frequenza della chiave superato (con intestazione Retry-After) oppure quota del piano esaurita
500Errore interno
502Errore di un fornitore o di un servizio a monte
503Servizio temporaneamente non disponibile

Il testo dei messaggi di errore può variare tra i servizi: un'integrazione deve basarsi sul codice HTTP e, dove presente, sul campo code del corpo.

Paginazione​

Gli endpoint che restituiscono elenchi usano la paginazione offset/limit:

  • offset: indice del primo elemento (predefinito 0);
  • limit: numero di elementi (tipicamente predefinito 50; il massimo dipende dall'endpoint ed è indicato nella reference).
{
  "items": [],
  "total": 142,
  "offset": 0,
  "limit": 50
}

Limiti di frequenza e quote​

Ogni chiave può avere limiti dedicati, impostati alla creazione e modificabili in seguito:

  • rate_limit_rpm: richieste al minuto;
  • rate_limit_rpd: richieste al giorno.

I limiti sono conteggiati per singola chiave. Al superamento il servizio risponde 429 Too Many Requests con l'intestazione Retry-After, che indica i secondi di attesa.

Per l'organizzazione valgono inoltre le quote del piano (per esempio conversazioni al mese, crediti AI, documenti per base di conoscenza). Quando una quota è esaurita la risposta è 429 con un detail descrittivo e senza Retry-After. L'utilizzo corrente delle quote si legge con GET /quotas/usage (si veda Endpoint: Utenti, Organizzazione e Quote).

Streaming (SSE)​

POST /chat può restituire la risposta in streaming tramite Server-Sent Events: è sufficiente impostare "stream": true nel corpo. La risposta ha Content-Type: text/event-stream e contiene una sequenza di eventi data: {...}, ciascuno con un campo type. Il testo della risposta arriva negli eventi di tipo content; lo stream termina con l'evento done. L'elenco completo degli eventi, con i campi e i codici di errore, è in Endpoint: Agenti, Chat e Conversazioni.

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 "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "message": "Quali sono i tempi di consegna?",
    "external_conversation_id": "ticket-9281",
    "stream": false
  }'

Sezioni​

Monitoraggio e costi

I dati di consumo, costi e avvisi si consultano dalla console, nella sezione Monitoraggio: gli endpoint di monitoraggio non accettano chiavi API. Per controllare da un'integrazione quanto resta delle quote del piano si usa GET /quotas/usage.

Compatibilità con Askme AI v1​

Per la transizione delle integrazioni costruite su Askme AI v1 è attivo uno strato di compatibilità sul prefisso /api/*:

  • un sottoinsieme di endpoint v1 viene servito dalle rotte v2 equivalenti; le richieste instradate in questo modo sono attribuite all'origine legacy-v1, così che i loro consumi restino distinti da quelli delle integrazioni già portate su /api/v2;
  • gli endpoint v1 senza un equivalente v2 rispondono 410 Gone con un corpo che indica il percorso di migrazione consigliato.

La tabella di corrispondenza e la procedura di migrazione sono in Migrazione dalle API v1.

Errori comuni​

CodiceCausa tipicaCosa fare
401Intestazione X-Api-Key assente, chiave copiata in modo incompleto, revocata o scadutaVerificare l'intestazione e il valore completo della chiave; se necessario ruotarla o generarne una nuova
403 con PERMISSION_DENIEDGli scope della chiave non coprono l'operazione indicata in permissionAggiungere lo scope alla chiave in Impostazioni › Chiavi API
403 con FEATURE_FLAG_DISABLEDLa funzionalità indicata in flag non è attiva per l'organizzazioneRivolgersi al team Askme per l'attivazione
429 con Retry-AfterLimite di frequenza della chiave superatoAttendere i secondi indicati e ripetere la richiesta
429 senza Retry-AfterQuota del piano esauritaAttendere il rinnovo del periodo della quota oppure rivolgersi al team Askme

Supporto​

Per richieste su API e integrazioni è possibile rivolgersi al referente tecnico della propria istanza di Askme AI.