# Documentazione API

Cognitor Assistant espone un'API REST basata su FastAPI per l'integrazione con altri sistemi.

Endpoint

GET /health

Health check dell'applicazione.

Response:

{
  "status": "ok"
}

POST /auth/token

Autenticazione utente, restituisce JWT token.

Request Body (form-urlencoded):

• username: Username dell'utente
• password: Password dell'utente

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Esempio:

curl -X POST http://localhost:8000/auth/token \
  -d "username=admin&password=admin123"

POST /chatbot/message

Invia un messaggio al chatbot (richiede autenticazione).

Headers:

• Authorization: Bearer token JWT

Request Body:

{
  "message": "Ciao!",
  "session_id": "optional-session-id"
}

Response:

{
  "response": "Ciao! Come posso aiutarti?",
  "session_id": "uuid-della-sessione"
}

Esempio:

curl -X POST http://localhost:8000/chatbot/message \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"message": "Ciao!"}'

POST /auth/refresh e GET /auth/me

/auth/refresh rinnova il token JWT; /auth/me restituisce l'utente autenticato.

GET /chatbot/intents

Elenca gli intent disponibili (richiede autenticazione).

POST /chatbot/message/stream e POST /chatbot/cancel

Variante in streaming (SSE) con cancellazione a metà turno. È spenta di default: si attiva avviando il server con COGNITOR_STREAMING_ENABLED=true.

Campi aggiuntivi della risposta di /chatbot/message

Oltre a response e session_id: intent, confidence, entities, options e waiting_for_slot (true quando il bot attende il valore di uno slot).

Autenticazione

L'API utilizza JWT (JSON Web Tokens) per l'autenticazione. Per accedere agli endpoint protetti:

1. Ottenere un token tramite /auth/token
2. Includere il token nell'header Authorization: Bearer

Errori

Gli endpoint possono restituire i seguenti codici di errore:

• 401 Unauthorized: Token mancante o invalido
• 404 Not Found: Risorsa non trovata
• 500 Internal Server Error: Errore interno del server

CORS

L'API configura CORS per permettere richieste da qualsiasi origine (allow_origins=["*"]).