Intelligence

The Intelligence API provides Retrieval-Augmented Generation (RAG) capabilities — query your datasets with natural language and receive AI-generated answers grounded in your data. Supports both streaming (SSE) and non-streaming responses, plus persistent chat sessions. All endpoints live under the unprefixed /intelligence namespace.

Unprefixed paths

Use the unprefixed /intelligence/... paths. The legacy /v1/intelligence/... prefix is deprecated, and /api/v1/... is not routed (404).

---

RAG Query

POST /intelligence/query

Request Body

Name	Type	Required	Description
query	string	✅	Natural language question
dataset_id	UUID | "all" | null		Dataset to search. Use "all" to search across all datasets, or null for default behavior
top_k	integer		Number of chunks to retrieve (1–50, default 5)
conversation_history	array		Prior conversation turns for context
stream	boolean		Enable SSE streaming (default true)
include_sources	boolean		Include source citations (default true)

Conversation History Item:

Name	Type	Description
role	string	user or assistant
content	string	Message content

cURL (Streaming)

curl -X POST https://api.vectoramp.com/intelligence/query \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the key features of our product?",
    "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
    "top_k": 5,
    "stream": true,
    "conversation_history": [
      {"role": "user", "content": "Tell me about the product"},
      {"role": "assistant", "content": "Our product is a vector database..."}
    ]
  }'

cURL (Non-Streaming)

curl -X POST https://api.vectoramp.com/intelligence/query \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the key features?",
    "dataset_id": "all",
    "stream": false
  }'

Non-Streaming Response

{
  "answer": "The key features include real-time vector search, hybrid search combining dense and sparse vectors...",
  "sources": [
    {
      "name": "product-overview.pdf",
      "path": "gdrive://1abc2def3ghi",
      "url": null,
      "source_type": "gdrive",
      "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
      "dataset_document_id": "doc_01HZY...",
      "content_type": "application/pdf",
      "relevance": 0.95,
      "pages": [3, 4],
      "sheet_names": [],
      "chunk_count": 2,
      "preview": "Our platform supports real-time vector search...",
      "preview_ref": "prev_eyJhbGciOi...",
      "chunks": [
        {
          "chunk_id": "chunk-001",
          "score": 0.95,
          "text": "Our platform supports real-time vector search...",
          "chunk_index": null,
          "sheet_name": null,
          "row_start": null,
          "row_end": null,
          "column_names": null
        }
      ],
      "timestamp_start": null,
      "timestamp_end": null,
      "file_id": "1abc2def3ghi",
      "thumbnail_url": null
    }
  ],
  "chunks": [
    {
      "id": "chunk-001",
      "text": "Our platform supports real-time vector search...",
      "score": 0.95,
      "source": "product-overview.pdf",
      "source_url": null,
      "page": 3,
      "metadata": {
        "source": "gdrive://1abc2def3ghi",
        "content_type": "application/pdf"
      }
    }
  ],
  "message": null,
  "metadata": {}
}

Public metadata

Chunk metadata returned by /intelligence/query is sanitized. Internal storage fields such as document_storage_key, document_storage_bucket, and payload_ref are never returned.

Citations and previews

Inline numeric citations in answer use 1-based source ordering: [1] refers to sources[0], [2] to sources[1], and so on. preview_ref is an opaque signed reference for authenticated preview/download flows; do not treat it as a storage key or construct object URLs from it.

Streaming Response (SSE)

When stream: true, the response is sent as Server-Sent Events. Each event contains a JSON chunk:

data: {"chunk_type": "text", "content": "The key ", "metadata": {}}
data: {"chunk_type": "text", "content": "features include ", "metadata": {}}
data: {"chunk_type": "citation", "content": "", "metadata": {"source": "product-overview.pdf"}}
data: {"chunk_type": "done", "content": "", "metadata": {}}

Chunk Types:

Type	Description
text	Text content of the answer
image	Image reference
audio	Audio reference
video	Video reference
code	Code block content
citation	Source citation
error	Error message
metadata	Additional metadata
visualization	Data visualization
done	Stream complete

---

Persistent Sessions

Persistent Intelligence sessions let clients store workspace-scoped chat state and replay message history around /intelligence/query.

Create a session

POST /intelligence/sessions

Name	Type	Required	Description
title	string		Human-readable session title
workspace_id	string		Optional workspace identifier
dataset_id	UUID		Optional default dataset scope
metadata	object		Client metadata

curl -X POST https://api.vectoramp.com/intelligence/sessions \
  -H "X-API-Key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Q4 planning","dataset_id":"550e8400-e29b-41d4-a716-446655440000"}'

List sessions

GET /intelligence/sessions?limit=50

Returns:

{ "sessions": [{ "id": "sess_01HZ...", "title": "Q4 planning" }] }

Get a session

GET /intelligence/sessions/{id}

Returns an IntelligenceSession.

Delete a session

DELETE /intelligence/sessions/{id}

Permanently deletes the session and its messages. Returns 204 No Content.

curl -X DELETE https://api.vectoramp.com/intelligence/sessions/sess_01HZ... \
  -H "X-API-Key: vsk_<64hex>"

Append a message

POST /intelligence/sessions/{id}/messages

Name	Type	Required	Description
role	user | assistant | system | tool	✅	Message role
content	string	✅	Message content
metadata	object		Client metadata

{ "role": "user", "content": "Summarize the latest planning docs" }

List messages

GET /intelligence/sessions/{id}/messages?limit=100

Returns:

{ "messages": [{ "id": "msg_01HZ...", "role": "user", "content": "Summarize the latest planning docs" }] }