Risorse · Chat API

Documentazione dell'API Chat

Riferimento enterprise per /chat/completions che include lo schema della richiesta, gli eventi in streaming, il comportamento in fase di esecuzione e la semantica degli errori.

Torna alla documentazione Vai agli endpoint

Endpoint

GET /api/v1/chat/health

POST /api/v1/chat/completions

Intestazioni richieste

Authorization: Bearer [token] o autenticazione tramite chiave APIContent-Type: application/jsonX-Scope-Type: personal | workspaceX-Workspace-ID: richiesto solo quando lo scope è workspace

Corpo della richiesta

json

{
  "message": "Summarize the last meeting in bullet points",
  "session_id": "sess_123",
  "stream": true,
  "attachments": [],
  "metadata": {
    "locale": "en",
    "channel": "web"
  }
}

Corpo della risposta

json

{
  "success": true,
  "session_id": "sess_123",
  "content": "• Discussed roadmap\n• Confirmed release scope\n• Assigned owners",
  "provider": "pulse",
  "usage": {
    "input_tokens": 324,
    "output_tokens": 118
  },
  "metadata": {
    "latency_ms": 612
  }
}

Eventi in streaming

response.started — avvio dell'esecuzione della chat
response.delta — token di testo incrementali
response.tool_call — evento di invocazione dello strumento (se presente)
response.usage — aggiornamento di utilizzo/token
response.completed — risposta finale assemblata

Comportamenti di runtime

Il controllo del backpressure respinge il sovraccarico con 503.
Il locking distribuito previene l'elaborazione duplicata in corso.
La cache di deduplicazione soddisfa richieste non in streaming ripetute.
La persistenza della sessione memorizza i turni dell'utente e dell'assistente.
La validazione verifica il corpo della richiesta, gli allegati e il contesto di accesso.

Modelli di errore

400

Payload della richiesta non valido o campi obbligatori mancanti.

401

Autenticazione mancante o non valida.

403

Restrizione di ambito/permessi.

409

Conflitto di lock: richiesta già in elaborazione.

422

Errore di validazione in intestazioni/corpo/contesto.

429

Limite di richieste superato.

503

Sovraccarico del sistema o indisponibilità a monte.

Esempi

bash

curl -X POST "/api/v1/chat/completions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Write a short product update",
    "session_id":"sess_123",
    "stream":false
  }'