Quickstart API

Questa guida porta dalla creazione di una base di conoscenza alla prima conversazione con un agente che la consulta, usando le API REST di Askme AI.

Prerequisiti

• Chiave API: una chiave nel formato amai_<chiave>, generata dalla console in Impostazioni › Chiavi API (si vedano Autenticazione e il manuale). Per seguire tutti i passi la chiave deve coprire la gestione delle basi di conoscenza e degli agenti e l'avvio delle conversazioni; la scelta predefinita Tutte le funzioni (*) è sufficiente.
• URL base: l'indirizzo della console Askme AI della propria organizzazione seguito da /api/v2, per esempio https://ai.askme.it/api/v2.

Intestazioni

Ogni richiesta deve contenere X-Api-Key: amai_<chiave>. L'intestazione X-Source-App è facoltativa: per un'integrazione diretta si consiglia api_direct, così che i consumi siano attribuiti in modo riconoscibile. Dettagli in Autenticazione.

La guida si può seguire in due modi: con Postman, se si preferisce un'interfaccia grafica, oppure da terminale con cURL. Il flusso è lo stesso.

---

Postman

Il modo più rapido per esplorare le API senza scrivere codice.

⬇ Collection Postman di Askme AI (download)

Passo 1: importare la collection

1. In Postman selezionare Import (in alto a sinistra).
2. Trascinare il file .json scaricato oppure selezionare Upload Files.
3. Confermare l'importazione: nella barra laterale compare la collection Askme AI — API, con le cartelle Agenti e Chat, Knowledge Base, Analisi e Traduzione, Amministrazione.

Passo 2: configurare le variabili

1. Selezionare la collection e aprire la scheda Variables.
2. Impostare i valori nella colonna Current value:

Variabile	Valore
baseUrl	l'URL base della propria organizzazione, per esempio https://ai.askme.it/api/v2
apiKey	la chiave amai_<chiave>
sourceApp	api_direct (già impostato)

3. Selezionare Save.

L'intestazione X-Api-Key è configurata a livello di collection e viene applicata automaticamente a tutte le richieste.

Passo 3: creare la base di conoscenza

Nella cartella Knowledge Base aprire Crea knowledge base e selezionare Send. L'id della base creata viene salvato automaticamente nella variabile kb_id.

Passo 4: aggiungere ed elaborare un documento

Aprire Aggiungi documento da testo e selezionare Send: il documento viene creato nella base appena generata e il suo id viene salvato in document_id. Aprire poi Elabora documento e selezionare Send: l'elaborazione divide il testo in frammenti e li indicizza, e al termine lo stato del documento diventa indexed. Per caricare un file al posto del testo si usa Carica documento (file), selezionando il file nella scheda Body, seguito sempre da Elabora documento.

Passo 5: creare l'agente

Nella cartella Agenti e Chat aprire Crea agente e selezionare Send. La richiesta collega l'agente alla base di conoscenza tramite rag_config; l'id dell'agente viene salvato nella variabile agent_id.

Passo 6: conversare con l'agente

Aprire Invia messaggio (chat con agente) e selezionare Send. Il corpo usa {{agent_id}} e passa l'identificativo esterno {{external_id}} nel campo external_conversation_id; il conversation_id della risposta viene salvato automaticamente.

Streaming

Per ricevere la risposta in streaming (SSE) si imposta "stream": true nel corpo: l'endpoint resta POST /chat e risponde con Content-Type: text/event-stream.

Passo 7: leggere la conversazione

Aprire Messaggi della conversazione e selezionare Send per leggere i messaggi del conversation_id corrente. In alternativa, Conversazione per ID esterno recupera la conversazione tramite l'external_conversation_id inviato al passo precedente.

cURL

# Variabili d'ambiente: non vanno salvate in chiaro nei repository
export ASKMEAI_HOST="https://ai.askme.it"
export ASKMEAI_API_KEY="amai_xxxxxxxxxxxxxxxx"
export ASKMEAI_SOURCE_APP="api_direct"

Passo 1: creare la base di conoscenza

curl -X POST "$ASKMEAI_HOST/api/v2/knowledge-bases" \
  -H "X-Api-Key: $ASKMEAI_API_KEY" \
  -H "X-Source-App: $ASKMEAI_SOURCE_APP" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Manuali tecnici",
    "type": "manual",
    "languages": ["it"]
  }'

La risposta (201) contiene l'id della base di conoscenza, da annotare (negli esempi seguenti 24).

Passo 2: aggiungere ed elaborare un documento

curl -X POST "$ASKMEAI_HOST/api/v2/knowledge-bases/24/documents/text" \
  -H "X-Api-Key: $ASKMEAI_API_KEY" \
  -H "X-Source-App: $ASKMEAI_SOURCE_APP" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Politica spedizioni",
    "content": "Le spedizioni standard partono entro 24 ore lavorative e arrivano in 2-3 giorni lavorativi in tutta Italia."
  }'

La risposta (201) contiene l'id del documento (negli esempi 711) con stato pending. Il documento va poi elaborato, cioè diviso in frammenti e indicizzato:

curl -X POST "$ASKMEAI_HOST/api/v2/knowledge-bases/24/documents/711/process" \
  -H "X-Api-Key: $ASKMEAI_API_KEY" \
  -H "X-Source-App: $ASKMEAI_SOURCE_APP"

Al termine la risposta riporta lo stato indexed. Per caricare un file al posto del testo si usa POST /knowledge-bases/24/documents/upload con -F "[email protected]", seguito dalla stessa chiamata di elaborazione.

Passo 3: creare l'agente

curl -X POST "$ASKMEAI_HOST/api/v2/agents" \
  -H "X-Api-Key: $ASKMEAI_API_KEY" \
  -H "X-Source-App: $ASKMEAI_SOURCE_APP" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Assistente customer care",
    "model_provider": "openai",
    "model_name": "gpt-4o-mini",
    "system_prompt": "Sei un assistente cortese di supporto clienti. Rispondi usando le informazioni della base di conoscenza.",
    "temperature": 0.3,
    "rag_config": {
      "enabled": true,
      "knowledge_base_ids": [24]
    }
  }'

La risposta (201) contiene l'id dell'agente (negli esempi 87). Il campo rag_config collega l'agente alla base di conoscenza: senza questo campo l'agente risponde senza consultare i documenti. Il modello indicato deve essere tra quelli abilitati per l'organizzazione.

Passo 4: conversare con l'agente

curl -X POST "$ASKMEAI_HOST/api/v2/chat" \
  -H "X-Api-Key: $ASKMEAI_API_KEY" \
  -H "X-Source-App: $ASKMEAI_SOURCE_APP" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 87,
    "message": "Quali sono i tempi di consegna in Italia?",
    "external_conversation_id": "ordine-7728",
    "stream": false
  }'

La risposta contiene conversation_id, il testo della risposta nel campo content e le fonti usate in rag_sources. Una nuova richiesta con lo stesso external_conversation_id prosegue la stessa conversazione. Per lo streaming (SSE) si imposta "stream": true.

Passo 5: leggere la conversazione

curl "$ASKMEAI_HOST/api/v2/conversations/4421/messages" \
  -H "X-Api-Key: $ASKMEAI_API_KEY" \
  -H "X-Source-App: $ASKMEAI_SOURCE_APP"

In alternativa si recupera la conversazione tramite l'identificativo esterno inviato in external_conversation_id:

curl "$ASKMEAI_HOST/api/v2/conversations/by-external-id/ordine-7728" \
  -H "X-Api-Key: $ASKMEAI_API_KEY" \
  -H "X-Source-App: $ASKMEAI_SOURCE_APP"

---

Passi successivi

Obiettivo	Dove leggere
Intestazioni, formato della chiave e scope	Autenticazione
Tutti gli endpoint di agenti e chat	Endpoint: Agenti, Chat e Conversazioni
Basi di conoscenza, documenti e FAQ	Endpoint: Knowledge Base
Analisi di PDF e CV, anonimizzazione e classificazione	Endpoint: Analisi e Classificazione
Esempi completi in Python, JavaScript e cURL	Esempi