Intelligence

The Intelligence API answers natural-language questions from your own data. Ask a question and Intelligence works out how to answer it: which datasets to search, what metadata filters apply, whether it needs to read whole documents, and whether the answer requires computation over structured data. Streaming responses report each step as it happens.

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).

dataset_id is retired

Scope a question with dataset_ids (a list). Sending dataset_id returns 400 — it is not ignored, because silently widening a scoped question to every dataset produces a plausible answer built from the wrong evidence.

The old dataset_id: "all" sentinel is replaced by omitting dataset_ids.

- { "query": "...", "dataset_id": "550e8400-..." }
+ { "query": "...", "dataset_ids": ["550e8400-..."] }

- { "query": "...", "dataset_id": "all" }
+ { "query": "..." }

dataset_id remains correct elsewhere — on /datasets/{id}/... routes, and as a session's default dataset scope.

Intelligence Query

POST /intelligence/query

Request Body

Name	Type	Required	Description
`query`	string	✅	Natural language question
`dataset_ids`	string[]		Datasets to scope the question to. Omit to search every dataset you can see
`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`)
`mode`	`auto` \| `fast` \| `agentic`		How much machinery to use (default `auto`)
`session_id`	string		Attach messages and the workflow trace to an Intelligence session
`run_id`	string		Your own run identifier, used to re-attach to a dropped event stream
`max_steps`	integer		Cap on tool steps for this question (1–24)
`deadline_seconds`	number		Wall-clock ceiling before Intelligence answers with what it has (5–600)

Modes

Mode	Behaviour
`auto`	Default. Intelligence plans its own approach and uses tools only when the question needs them. Simple questions take the single-pass path and are as fast as `fast`.
`fast`	One retrieval pass, no tools. Lowest and most predictable latency; cannot read whole documents or compute over data.
`agentic`	Always run the tool loop, even for questions the planner would have answered directly. Mostly useful for evaluation.

Conversation History Item:

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

cURL (Streaming)
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 of our product?",
    "dataset_ids": ["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 -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?",
    "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. The first chunk arrives immediately, before any model call, so you can show progress from the moment the request lands.

data: {"chunk_type":"event","content":"Received your question","metadata":{"run_id":"3f9c...","seq":1,"phase":"received","action":"query.received","status":"ok"}}
data: {"chunk_type":"event","content":"3 datasets: Contracts, Invoices, Wiki","metadata":{"seq":2,"phase":"resolve","action":"catalog.ready","status":"ok"}}
data: {"chunk_type":"event","content":"Plan: compute over Contracts","metadata":{"seq":3,"phase":"plan","action":"plan.ready","status":"ok"}}
data: {"chunk_type":"event","content":"Searching for \u201ccontracts executed\u201d","metadata":{"seq":4,"phase":"act","action":"tool.search","status":"started","step":1,"tool":"search"}}
data: {"chunk_type":"event","content":"Found 47 results across 1 dataset","metadata":{"seq":5,"phase":"act","action":"tool.search","status":"ok","step":1,"tool":"search","ms":412}}
data: {"chunk_type":"text","content":"Fourteen contracts ","metadata":{}}
data: {"chunk_type":"text","content":"were executed last week.","metadata":{}}
data: {"chunk_type":"citation","content":"","metadata":{"sources":[{"name":"acme-msa.pdf","relevance":0.94}]}}
data: {"chunk_type":"done","content":"","metadata":{"run_id":"3f9c...","status":"succeeded"}}

Chunk Types:

Type	Description
`event`	A step in the workflow trace: what Intelligence is doing right now
`text`	Text content of the answer
`artifact`	A chart, table or file produced during the run
`citation`	Source citations for the answer
`metadata`	Run metadata
`error`	Error message
`done`	Stream complete. Always last, and sent exactly once
`image` · `audio` · `video` · `code` · `visualization`	Reserved media chunk types

event chunk metadata

Field	Description
`run_id`	Identifies this run. Pass it to `/intelligence/runs/{run_id}/events` to replay the trace
`seq`	Monotonic sequence number within the run
`phase`	`received` · `resolve` · `plan` · `route` · `act` · `synthesize` · `done`
`action`	Machine-readable name, e.g. `tool.search`, `plan.ready`
`status`	`started` · `ok` · `warning` · `error`
`step`	Tool step number, when the event belongs to one
`tool`	Tool name, when the event belongs to a tool call
`ms`	Elapsed milliseconds, on completion events
`detail`	Tool-specific structured detail

content carries the same human-readable sentence as metadata.summary; render either.

Ordering guarantees

done is always the final event and appears exactly once. citation is always sent before done, so a client can treat done as "everything needed to persist this exchange has arrived".

Partial answers

Intelligence bounds every run by tokens, steps and wall clock. When a bound is hit it answers from what it has gathered rather than failing, and says so:

a warning-status event explains what was cut short,
metadata.partial is true,
metadata.budget.degraded_reasons lists the reasons,
the answer itself notes the incomplete coverage.

Run Trace

GET /intelligence/runs/{run_id}

Returns the status of a streaming run: running, succeeded, failed, rate_limited or cancelled.

GET /intelligence/runs/{run_id}/events?after={seq}

Replays the workflow trace for a run, returning only events after seq. Use this to re-attach after a dropped SSE connection: keep the last seq you saw, reconnect, and resume from there.

{
  "run_id": "3f9c...",
  "status": "succeeded",
  "events": [{ "seq": 5, "phase": "act", "action": "tool.search", "summary": "Found 47 results across 1 dataset" }],
  "last_seq": 5,
  "answer": "Fourteen contracts were executed last week."
}

Runs are retained for a short reconnect window (15 minutes) and are only visible to the organization that started them. Durable history lives on the session (/intelligence/sessions/{id}/events).

Filters and dataset schemas

When Intelligence needs to filter — "contracts executed last week", "invoices over $10,000" — it reads the dataset's typed metadata schema from GET /datasets/{id} and writes filters against fields that actually exist. Range filters (gte, lt) require a numeric field: a date ingested as a string cannot be range-filtered, and Intelligence will say so rather than returning an empty result. Declare date fields as i64 epoch values (see Datasets) to make date questions answerable.

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

Intelligence Query​

Request Body​

Non-Streaming Response​

Streaming Response (SSE)​

Partial answers​

Run Trace​

Persistent Sessions​

Create a session​

List sessions​

Get a session​

Delete a session​

Append a message​

List messages​