Alloovium

Capabilities

Chat

Conversational retrieval-augmented generation over a tenant's vault. Every answer is grounded in document citations you can render back into your UI.

chat.ask

POST/api/v2/chat

Ask a question over the vault. Returns a grounded answer and structured citations.

scope: chat:writescope: vault:readcost: 10

Request body

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 to 8000 characters. Required.
  • field — optional scope. Omit to search the entire accessible vault.
  • field — optional deep scope to specific documents.
  • field — continue an existing thread. Omit to start a new one.
  • field — 1 to 50, default 15. Controls how many chunks the retriever feeds the 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-..."]
  }'

Response

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
  }
}

The field is created on the first call if you didn't pass one. Store it and pass it back on the next capability to keep a multi-turn dialogue going.

Citations are the contract

The answer is human-readable and may reorder between calls. The Citations are the contract array is the stable, machine-parseable grounding — each item identifies the exact chunk in your vault. Render citations as footnotes or inline link badges and your users will trust the output more.

chat.ask_stream

POST/api/v2/chat/stream

Streaming variant of chat.ask. Returns server-sent events as the model generates.

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

Not available in v2 yet

The v2 streaming endpoint is currently a stub — calling it returns code. If you need SSE today, use the v1 chat streaming endpoint from the main app. When v2 streaming lands it will mirror the v1 event protocol (delta, progress, citation, done).

Once enabled, clients should consume it with fetch streaming plus a manual SSE parser — eventsource cannot send an auth header. The cost (10 tokens) is deducted at request time, not per event.

chat.list_conversations

GET/api/v2/conversations

Paginated list of the API key's user's chat conversations.

scope: chat:readcost: 1

Request

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

Response

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}

Fetch a single conversation with its full message history.

scope: chat:readcost: 1

Response

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"
    }
  ]
}

Tenant isolation

Conversations are keyed on the principal. Requesting a conversation ID owned by another user, or another tenant, returns code.

Patterns

Stateless Q&A

For one-shot questions, omit field. Each call creates a fresh conversation. You can still read the field from the response and audit the history later via capability.

Multi-turn with memory

Store the field from the first response and pass it back on each subsequent call. The server re-assembles the history — you don't need to echo prior messages.

Scoping for accuracy

Narrow searches outperform broad ones. If you know the relevant project, pass field. If you know the exact documents, pass field. The LLM gets cleaner context and the citations become sharper.

See also

  • vault.search — retrieval without generation, if you want to rank chunks and render them yourself.
  • Rate Limits — capability costs 10 tokens per call.