Quickstart API

Questa guida ti permette di andare dalla creazione di una knowledge base alla prima chat con un agente in pochi minuti, usando le API REST di Askme AI.

Prerequisiti

• API key: una chiave nel formato amai_<key>, generata dalla console del tenant in Amministrazione → API Keys (vedi Autenticazione e il manuale)
• URL base: l'host della console Askme AI del tuo tenant con suffisso /api/v2, ad esempio https://ai.askme.it/api/v2

Header obbligatori

Ogni richiesta deve trasportare X-Api-Key: amai_<key> e X-Source-App (per integrazioni esterne dirette il valore è api_direct). Dettagli in Autenticazione.

Puoi seguire questa guida in due modi: usando Postman se preferisci un'interfaccia grafica, oppure direttamente da terminale con cURL. Il flusso è lo stesso — scegli quello che ti è più comodo.

---

Postman

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

⬇ Scarica la Collection Postman

Step 1: Importa la collection

1. Apri Postman e clicca su Import (in alto a sinistra)
2. Trascina il file .json scaricato oppure clicca Upload Files
3. Conferma l'importazione — troverai la collection Askme AI — API nella barra laterale, con le cartelle per servizio (Agenti e Chat, Knowledge Base, Analisi, Amministrazione, Monitoraggio)

Step 2: Configura le variabili

1. Clicca sulla collection e vai nella tab Variables
2. Imposta i valori nelle colonne Current value:

Variabile	Valore
baseUrl	l'URL base del tuo tenant, es. https://ai.askme.it/api/v2
apiKey	la tua chiave amai_<key>
sourceApp	api_direct (già impostato di default)

3. Clicca Save

L'header X-Api-Key è configurato a livello di collection e viene applicato automaticamente a tutte le richieste.

Step 3: Crea la knowledge base

Nella cartella Knowledge Base, apri Crea knowledge base e clicca Send. L'id della KB creata viene salvato automaticamente nella variabile kb_id.

Step 4: Aggiungi un documento

Apri Aggiungi documento da testo e clicca Send: il documento viene creato nella KB appena generata (usa kb_id). Per caricare un file al posto del testo, usa Carica documento (file) e seleziona il file nella tab Body.

Step 5: Crea l'agente

Nella cartella Agenti e Chat, apri Crea agente e clicca Send. L'id dell'agente viene salvato nella variabile agent_id.

Step 6: Chatta con l'agente

Apri Invia messaggio (chat con agente). Nella tab Body, imposta agent_id al valore reale (es. {{agent_id}}) e clicca Send. Il conversation_id della risposta viene salvato automaticamente.

Streaming

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

Step 7: Leggi le conversazioni

Apri Messaggi della conversazione e clicca Send per leggere lo storico del conversation_id corrente. In alternativa, Conversazione per ID esterno recupera la conversazione tramite l'external_id fornito al passo precedente.

cURL

# Variabili d'ambiente — non committarle in chiaro
export ASKMEAI_HOST="https://ai.askme.it"
export ASKMEAI_API_KEY="amai_xxxxxxxxxxxxxxxx"
export ASKMEAI_SOURCE_APP="api_direct"

Step 1: Crea la knowledge base

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", "en"]
  }'

La risposta (201) contiene l'id della KB. Annotalo (es. 24).

Step 2: Aggiungi 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."
  }'

Per caricare un file al posto del testo, usa l'endpoint multipart POST /knowledge-bases/24/documents/upload con -F "[email protected]".

Step 3: Crea 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.",
    "temperature": 0.4
  }'

La risposta (201) contiene l'id dell'agente (es. 87).

Step 4: Chatta 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 "X-External-Id: ordine-7728" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 87,
    "message": "Quali sono i tempi medi di consegna in Italia?",
    "stream": false
  }'

La risposta contiene conversation_id, content e le rag_sources. Per lo streaming (SSE) imposta "stream": true.

Step 5: Leggi le conversazioni

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

In alternativa, recupera la conversazione tramite l'ID esterno passato in X-External-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"

---

Prossimi passi

Cosa fare	Dove leggere
Capire header, formato chiave e permessi	Autenticazione
Vedere tutti gli endpoint di agenti e chat	Endpoint: Agenti, Chat e Conversazioni
Gestire knowledge base, documenti e FAQ	Endpoint: Knowledge Base
Lanciare analisi PDF/CV e classificazione	Endpoint: Analisi e Classificazione
Vedere esempi completi in Python, JavaScript e cURL	Esempi