Capabilities

Chat

Génération augmentée par récupération conversationnelle sur le vault d'un tenant. Chaque réponse est ancrée dans des citations de documents que vous pouvez restituer dans votre UI.

chat.ask

POST/api/v2/chat

Posez une question sur le vault. Retourne une réponse ancrée et des citations structurées.

scope: chat:writescope: vault:readcost: 10

Corps de requête

json
{
  "query": "What's the overall fire rating strategy on the tower?",
  "project_ids": ["8f2e3c1a-..."],
  "document_ids": null,
  "conversation_id": null,
  "k": 15
}

field — 1 à 8000 caractères. Requis.
field — portée optionnelle. Omettez pour rechercher dans tout le vault accessible.
field — portée profonde optionnelle vers des documents spécifiques.
field — continuez un fil existant. Omettez pour en démarrer un nouveau.
field — 1 à 50, défaut 15. Contrôle combien de chunks le récupérateur fourni au LLM.

bash
curl -sS https://api.alloovium.com/api/v2/chat \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What fire rating is specified for the tower lobby?",
    "project_ids": ["8f2e3c1a-..."]
  }'

Réponse

json
{
  "answer": "The lobby walls require a 90-minute fire rating per AS 1530.4...",
  "citations": [
    {
      "document_id": "4a1c2b3d-...",
      "chunk_id": "7b3e1a-...",
      "page_number": 14,
      "content": "Level-3 lobby walls carry a 90-minute fire rating per AS 1530.4...",
      "score": 0.9142
    }
  ],
  "conversation_id": "2e5f09bb-...",
  "message_id": "9d8c7b6a-...",
  "usage": {
    "prompt_tokens": 3120,
    "completion_tokens": 284,
    "total_tokens": 3404
  }
}

Le field est créé au premier appel si vous n'en avez pas passé un. Stockez-le et renvoyez-le au prochain capability pour maintenir un dialogue multi-tours.

Les citations sont le contrat

Le answer est lisible par l'homme et peut être réordonné entre les appels. Le tableau Les citations sont le contrat est l'ancrage stable et parseable par machine — chaque élément identifie le chunk exact dans votre vault. Rendez les citations comme notes de bas de page ou badges de lien inline et vos utilisateurs feront davantage confiance au résultat.

chat.ask_stream

POST/api/v2/chat/stream

Variante en streaming de chat.ask. Retourne des server-sent events pendant que le modèle génère.

scope: chat:writescope: vault:readcost: 10streaming (SSE)

Pas encore disponible en v2

L'endpoint de streaming v2 est actuellement un stub — l'appeler retourne code. Si vous avez besoin de SSE aujourd'hui, utilisez l'endpoint de streaming chat v1 depuis l'application principale. Quand le streaming v2 arrivera, il reflétera le protocole d'événements v1 (delta, progress, citation, done).

Une fois activé, les clients devraient le consommer avec le streaming fetch plus un parser SSE manuel — eventsource ne peut pas envoyer un header auth. Le coût (10 tokens) est déduit au moment de la requête, pas par événement.

chat.list_conversations

GET/api/v2/conversations

Liste paginée des conversations chat de l'utilisateur de la clé API.

scope: chat:readcost: 1

Requête

bash
curl -sS "https://api.alloovium.com/api/v2/conversations?limit=25" \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY"

Réponse

json
{
  "data": [
    {
      "id": "2e5f09bb-...",
      "title": "Fire rating strategy",
      "created_at": "2026-04-08T10:12:00+00:00",
      "updated_at": "2026-04-08T10:14:22+00:00",
      "message_count": 4
    }
  ],
  "next_cursor": null,
  "has_more": false
}

chat.get_conversation

GET/api/v2/conversations/{conversation_id}

Récupérez une seule conversation avec son historique complet de messages.

scope: chat:readcost: 1

Réponse

json
{
  "id": "2e5f09bb-...",
  "title": "Fire rating strategy",
  "created_at": "2026-04-08T10:12:00+00:00",
  "updated_at": "2026-04-08T10:14:22+00:00",
  "messages": [
    {
      "id": "9d8c7b6a-...",
      "role": "user",
      "content": "What fire rating is specified for the tower lobby?",
      "created_at": "2026-04-08T10:12:00+00:00"
    },
    {
      "id": "abc123...",
      "role": "assistant",
      "content": "The lobby walls require a 90-minute fire rating...",
      "citations": [
        {
          "document_id": "4a1c2b3d-...",
          "page_number": 14,
          "content": "Level-3 lobby walls carry a 90-minute fire rating per AS 1530.4..."
        }
      ],
      "created_at": "2026-04-08T10:12:05+00:00"
    }
  ]
}

Isolement de tenant

Les conversations sont clés sur le principal. Demander un ID de conversation appartenant à un autre utilisateur, ou un autre tenant, retourne code.

Patterns

Q&R sans état

Pour les questions ponctuelles, omettez field. Chaque appel crée une nouvelle conversation. Vous pouvez toujours lire field depuis la réponse et auditer l'historique plus tard via capability.

Multi-tours avec mémoire

Stockez le field depuis la première réponse et renvoyez-le à chaque appel suivant. Le serveur réassemble l'historique — vous n'avez pas besoin d'écho des messages précédents.

Portée pour la précision

Les recherches étroites surpassent les recherches larges. Si vous connaissez le projet pertinent, passez field. Si vous connaissez les documents exacts, passez field. Le LLM obtient un contexte plus propre et les citations deviennent plus précises.

Voir aussi

vault.search — récupération sans génération, si vous voulez classer les chunks et les rendre vous-même.
Limites de débit — capability coûte 10 tokens par appel.