Vector indexes

A vector index makes text searchable by meaning. There are two kinds. An asset index embeds the text content of one of your discovered assets, through its connection. A knowledge index embeds documents drawn from the networks knowledge store, scoped to the networks and versions you select.

Building is where the work happens. An asset index builds in the background — you create it, start a build, then poll its status — because embedding every chunk is slow. A knowledge index builds synchronously. Once an index is built, Run a semantic search ranks its chunks against a query.

Every index and its chunks are private to you. Asset indexes and knowledge indexes are listed and built through separate endpoints and cannot be crossed over.

The vector index object

A vector index and its build state.

Attributes

id string

Unique identifier for the index.
name string

Human-readable name.
sourceType string

asset for an index over a discovered asset, or vault for an index over network knowledge.
connectionId nullable string

Connection the source asset belongs to. Null for knowledge indexes.
assetId nullable string

Asset being indexed. Null for knowledge indexes.
scopeType nullable string

For knowledge indexes, the scope: network_version, network_all_versions, or visible_selection. Null for asset indexes.
scopeRef nullable string

For knowledge indexes, the resolved reference to the scoped networks. Null for asset indexes.
chunkSize integer

Maximum characters per chunk.
chunkOverlap integer

Characters of overlap between consecutive chunks.
embeddingModel string

Identifier of the embedding model used to build the index.
status string

Build state: draft, running, success, or failed.
documentCount integer

Number of chunks (asset index) or source documents (knowledge index) in the last build.
lastBuiltAt string

When the index last finished building, or an empty string if never built.
meta object

Build metadata; for knowledge indexes this records the scoped networks and versions.
createdAt string

When the index was created.
updatedAt string

When the index was last updated.

The vector index object

{
  "id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
  "name": "Customer notes index",
  "sourceType": "asset",
  "connectionId": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "assetId": "7a2d9e10-4c3b-4a1e-9f8d-2b6c1e0f5a3d",
  "scopeType": null,
  "scopeRef": null,
  "chunkSize": 500,
  "chunkOverlap": 50,
  "embeddingModel": "bge-large-en-v1.5",
  "status": "success",
  "documentCount": 1240,
  "lastBuiltAt": "2026-09-01T12:05:00Z",
  "meta": {},
  "createdAt": "2026-09-01T12:00:00Z",
  "updatedAt": "2026-09-01T12:05:00Z"
}

List indexes

GET /data-api/v1/vectors/indexes

Returns your asset-backed vector indexes.

Returns your asset indexes, most recently updated first. Knowledge indexes are returned by List knowledge indexes.

Authentication: Bearer token How it works

Parameters

No parameters.

Returns

Returns a list of vector index objects in data.

Request

curl "$VDF_BASE_URL/data-api/v1/vectors/indexes" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
      "name": "Customer notes index",
      "sourceType": "asset",
      "connectionId": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "assetId": "7a2d9e10-4c3b-4a1e-9f8d-2b6c1e0f5a3d",
      "scopeType": null,
      "scopeRef": null,
      "chunkSize": 500,
      "chunkOverlap": 50,
      "embeddingModel": "bge-large-en-v1.5",
      "status": "success",
      "documentCount": 1240,
      "lastBuiltAt": "2026-09-01T12:05:00Z",
      "meta": {},
      "createdAt": "2026-09-01T12:00:00Z",
      "updatedAt": "2026-09-01T12:05:00Z"
    }
  ]
}

Create an index

POST /data-api/v1/vectors/indexes

Defines an asset-backed vector index.

Creates an index definition in draft status against one of your assets. It holds no chunks until you start a build with Build an index.

Authentication: Bearer token How it works

Body parameters application/json

name string Required

Human-readable name.
connectionId string Required

Connection the source asset belongs to.
assetId string Required

Asset to index.
chunkSize integer

Maximum characters per chunk.

Defaults to 500.
chunkOverlap integer

Characters of overlap between consecutive chunks.

Defaults to 50.
embeddingModel string

Embedding model identifier. Defaults to the deployment's configured embedding model.

Returns

Returns the created vector index object in data.

Errors

400 name, connectionId, or assetId is missing.
404 The connection or asset does not belong to you.

Request

curl -X POST "$VDF_BASE_URL/data-api/v1/vectors/indexes" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer notes index",
    "connectionId": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "assetId": "7a2d9e10-4c3b-4a1e-9f8d-2b6c1e0f5a3d",
    "chunkSize": 500,
    "chunkOverlap": 50
  }'

Response 200

{
  "success": true,
  "data": {
    "id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
    "name": "Customer notes index",
    "sourceType": "asset",
    "connectionId": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "assetId": "7a2d9e10-4c3b-4a1e-9f8d-2b6c1e0f5a3d",
    "scopeType": null,
    "scopeRef": null,
    "chunkSize": 500,
    "chunkOverlap": 50,
    "embeddingModel": "bge-large-en-v1.5",
    "status": "draft",
    "documentCount": 0,
    "lastBuiltAt": "",
    "meta": {},
    "createdAt": "2026-09-01T12:00:00Z",
    "updatedAt": "2026-09-01T12:00:00Z"
  }
}

Update an index

PUT /data-api/v1/vectors/indexes/{index_id}

Updates an asset index you own.

Updates the fields you supply. Changing the source or chunking does not rebuild the index; start a new build with Build an index.

Authentication: Bearer token How it works

Path parameters

index_id string Required

Identifier of the index to update.

Body parameters application/json

name string

New name.
connectionId string

Move the index to a different connection you own.
assetId string

Index a different asset you own.
chunkSize integer

Maximum characters per chunk.
chunkOverlap integer

Characters of overlap between consecutive chunks.
embeddingModel string

Embedding model identifier.

Returns

Returns the updated vector index object in data.

Errors

404 No index with this id belongs to you, or the target connection or asset does not belong to you.

Request

curl -X PUT "$VDF_BASE_URL/data-api/v1/vectors/indexes/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer notes index v2",
    "chunkSize": 800
  }'

Response 200

{
  "success": true,
  "data": {
    "id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
    "name": "Customer notes index v2",
    "sourceType": "asset",
    "connectionId": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "assetId": "7a2d9e10-4c3b-4a1e-9f8d-2b6c1e0f5a3d",
    "scopeType": null,
    "scopeRef": null,
    "chunkSize": 800,
    "chunkOverlap": 50,
    "embeddingModel": "bge-large-en-v1.5",
    "status": "success",
    "documentCount": 1240,
    "lastBuiltAt": "2026-09-01T12:05:00Z",
    "meta": {},
    "createdAt": "2026-09-01T12:00:00Z",
    "updatedAt": "2026-09-01T12:20:00Z"
  }
}

Build an index

POST /data-api/v1/vectors/indexes/{index_id}/build

Starts a background build of an asset index.

Extracts text from the asset, splits it into chunks, embeds each chunk, and stores the results. The build runs in the background: this call returns immediately with the index in running status. Poll Retrieve index status until it reaches success or failed. The connection's connector must support extraction to a vector index.

Authentication: Bearer token How it works

Path parameters

index_id string Required

Identifier of the index to build.

Body parameters application/json

maxRows integer

Maximum source rows to read.

Defaults to 500.
textColumns array of strings

Columns to draw text from. Defaults to the asset's text-like columns.
textTemplate string

Template that composes each chunk's text from column values, referencing columns by name.

Returns

Returns the index object with its status set to running in data.

Errors

404 No index with this id belongs to you, or its asset or connection no longer exists.
400 The index is a knowledge index, the connector does not support extraction to a vector index, or its configuration is incomplete.
409 A build is already running for this index.
500 The build could not be started.

Request

curl -X POST "$VDF_BASE_URL/data-api/v1/vectors/indexes/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/build" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "maxRows": 500
  }'

Response 200

{
  "success": true,
  "data": {
    "id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
    "name": "Customer notes index",
    "sourceType": "asset",
    "connectionId": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "assetId": "7a2d9e10-4c3b-4a1e-9f8d-2b6c1e0f5a3d",
    "scopeType": null,
    "scopeRef": null,
    "chunkSize": 500,
    "chunkOverlap": 50,
    "embeddingModel": "bge-large-en-v1.5",
    "status": "running",
    "documentCount": 0,
    "lastBuiltAt": "",
    "meta": {},
    "createdAt": "2026-09-01T12:00:00Z",
    "updatedAt": "2026-09-01T12:03:00Z"
  }
}

Retrieve index status

GET /data-api/v1/vectors/indexes/{index_id}/status

Returns the current state of an asset index.

Returns the index object, including its status and documentCount. Poll this after starting a build; the count climbs as chunks are embedded.

Authentication: Bearer token How it works

Path parameters

index_id string Required

Identifier of the index.

Returns

Returns the vector index object in data.

Errors

404 No index with this id belongs to you.

Request

curl "$VDF_BASE_URL/data-api/v1/vectors/indexes/1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b/status" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "success": true,
  "data": {
    "id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
    "name": "Customer notes index",
    "sourceType": "asset",
    "connectionId": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "assetId": "7a2d9e10-4c3b-4a1e-9f8d-2b6c1e0f5a3d",
    "scopeType": null,
    "scopeRef": null,
    "chunkSize": 500,
    "chunkOverlap": 50,
    "embeddingModel": "bge-large-en-v1.5",
    "status": "success",
    "documentCount": 1240,
    "lastBuiltAt": "2026-09-01T12:05:00Z",
    "meta": {},
    "createdAt": "2026-09-01T12:00:00Z",
    "updatedAt": "2026-09-01T12:05:00Z"
  }
}

List knowledge indexes

GET /data-api/v1/vectors/vault-indexes

Returns your knowledge indexes — those built over the networks knowledge store — most recently updated first.

Authentication: Bearer token How it works

Parameters

No parameters.

Returns

Returns a list of vector index objects with sourceType of vault in data.

Request

curl "$VDF_BASE_URL/data-api/v1/vectors/vault-indexes" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "2a3b4c5d-6e7f-4809-9a0b-1c2d3e4f5a6b",
      "name": "Support networks knowledge",
      "sourceType": "vault",
      "connectionId": null,
      "assetId": null,
      "scopeType": "network_version",
      "scopeRef": "support-triage@3",
      "chunkSize": 500,
      "chunkOverlap": 50,
      "embeddingModel": "bge-large-en-v1.5",
      "status": "success",
      "documentCount": 86,
      "lastBuiltAt": "2026-09-01T13:05:00Z",
      "meta": {
        "networkId": "support-triage",
        "version": "3",
        "networkIds": [],
        "limitRuns": 25
      },
      "createdAt": "2026-09-01T13:00:00Z",
      "updatedAt": "2026-09-01T13:05:00Z"
    }
  ]
}

Create a knowledge index

POST /data-api/v1/vectors/vault-indexes

Defines a vector index over network knowledge.

Creates a knowledge index in draft status, scoped to networks in the knowledge store. Choose a scopeType and supply the matching references: a single network and version, all versions of a network, or an explicit selection of networks. Build it with Build a knowledge index.

Authentication: Bearer token How it works

Body parameters application/json

name string Required

Human-readable name.
scopeType string Required

Which knowledge to include.
Possible values
- network_version
- network_all_versions
- visible_selection
networkId string

Network to scope to, for network_version and network_all_versions.
version string

Network version, for network_version.
networkIds array of strings

Explicit list of networks, for visible_selection.
limitRuns integer

Maximum runs per network version to draw documents from.

Defaults to 25.
chunkSize integer

Maximum characters per chunk.

Defaults to 500.
chunkOverlap integer

Characters of overlap between consecutive chunks.

Defaults to 50.
embeddingModel string

Embedding model identifier. Defaults to the deployment's configured embedding model.

Returns

Returns the created vector index object with sourceType of vault in data.

Errors

400 name is missing, scopeType is missing or invalid, or the references needed for the chosen scope could not be resolved.

Request

curl -X POST "$VDF_BASE_URL/data-api/v1/vectors/vault-indexes" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support networks knowledge",
    "scopeType": "network_version",
    "networkId": "support-triage",
    "version": "3"
  }'

Response 200

{
  "success": true,
  "data": {
    "id": "2a3b4c5d-6e7f-4809-9a0b-1c2d3e4f5a6b",
    "name": "Support networks knowledge",
    "sourceType": "vault",
    "connectionId": null,
    "assetId": null,
    "scopeType": "network_version",
    "scopeRef": "support-triage@3",
    "chunkSize": 500,
    "chunkOverlap": 50,
    "embeddingModel": "bge-large-en-v1.5",
    "status": "draft",
    "documentCount": 0,
    "lastBuiltAt": "",
    "meta": {
      "networkId": "support-triage",
      "version": "3",
      "networkIds": [],
      "limitRuns": 25
    },
    "createdAt": "2026-09-01T13:00:00Z",
    "updatedAt": "2026-09-01T13:00:00Z"
  }
}

Build a knowledge index

POST /data-api/v1/vectors/vault-indexes/{index_id}/build

Builds a knowledge index from the scoped network documents.

Fetches the documents for the index's scope from the networks knowledge store, chunks and embeds them, and stores the results. Unlike an asset index, this build runs synchronously and returns the finished index. You may override the scope, chunking, and embedding model on the build call.

Authentication: Bearer token How it works

Path parameters

index_id string Required

Identifier of the knowledge index to build.

Body parameters application/json

scopeType string

Override the scope for this build.
Possible values
- network_version
- network_all_versions
- visible_selection
networkId string

Override the scoped network.
version string

Override the scoped network version.
networkIds array of strings

Override the explicit network selection.
limitRuns integer

Override the maximum runs per network version.
chunkSize integer

Override the chunk size.
chunkOverlap integer

Override the chunk overlap.
embeddingModel string

Override the embedding model.

Returns

Returns the finished index object with its status, documentCount, and build metadata in data.

Errors

404 No index with this id belongs to you.
400 The index is not a knowledge index.
502 The knowledge document service was unreachable or returned an invalid response.
500 The build failed.

Request

curl -X POST "$VDF_BASE_URL/data-api/v1/vectors/vault-indexes/2a3b4c5d-6e7f-4809-9a0b-1c2d3e4f5a6b/build" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 200

{
  "success": true,
  "data": {
    "id": "2a3b4c5d-6e7f-4809-9a0b-1c2d3e4f5a6b",
    "name": "Support networks knowledge",
    "sourceType": "vault",
    "connectionId": null,
    "assetId": null,
    "scopeType": "network_version",
    "scopeRef": "support-triage@3",
    "chunkSize": 500,
    "chunkOverlap": 50,
    "embeddingModel": "bge-large-en-v1.5",
    "status": "success",
    "documentCount": 86,
    "lastBuiltAt": "2026-09-01T13:05:00Z",
    "meta": {
      "networkId": "support-triage",
      "version": "3",
      "networkIds": [],
      "limitRuns": 25,
      "chunkCount": 512
    },
    "createdAt": "2026-09-01T13:00:00Z",
    "updatedAt": "2026-09-01T13:05:00Z"
  }
}

Retrieve knowledge index status

GET /data-api/v1/vectors/vault-indexes/{index_id}/status

Returns the current state of a knowledge index.

Returns the knowledge index object, including its status and documentCount.

Authentication: Bearer token How it works

Path parameters

index_id string Required

Identifier of the knowledge index.

Returns

Returns the vector index object in data.

Errors

404 No index with this id belongs to you.
400 The index is not a knowledge index.

Request

curl "$VDF_BASE_URL/data-api/v1/vectors/vault-indexes/2a3b4c5d-6e7f-4809-9a0b-1c2d3e4f5a6b/status" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"

Response 200

{
  "success": true,
  "data": {
    "id": "2a3b4c5d-6e7f-4809-9a0b-1c2d3e4f5a6b",
    "name": "Support networks knowledge",
    "sourceType": "vault",
    "connectionId": null,
    "assetId": null,
    "scopeType": "network_version",
    "scopeRef": "support-triage@3",
    "chunkSize": 500,
    "chunkOverlap": 50,
    "embeddingModel": "bge-large-en-v1.5",
    "status": "success",
    "documentCount": 86,
    "lastBuiltAt": "2026-09-01T13:05:00Z",
    "meta": {
      "networkId": "support-triage",
      "version": "3",
      "networkIds": [],
      "limitRuns": 25
    },
    "createdAt": "2026-09-01T13:00:00Z",
    "updatedAt": "2026-09-01T13:05:00Z"
  }
}

Run a semantic search

POST /data-api/v1/search/semantic

Ranks an index's chunks against a query and returns the closest matches.

Embeds the query and ranks the chunks of one of your indexes by cosine similarity, returning the closest matches. Works against both asset and knowledge indexes. topK is clamped to at most 50.

Authentication: Bearer token How it works

Body parameters application/json

indexId string Required

Identifier of the index to search.
query string Required

Natural-language query text.
topK integer

Number of matches to return, at most 50.

Defaults to 10.
includeEmbedding boolean

Include the stored embedding vector of each match.

Defaults to false.
embeddingPreviewDims integer

When including embeddings, return only this many leading dimensions of each vector instead of the full vector.

Returns

Returns a ranked list of matching chunks. Each has chunkId, score, text, sourceRef, indexId, indexName, assetId, connectionId, textLength, createdAt, and updatedAt; when embeddings are stored, embeddingDim and embeddingNorm; and, when requested, embedding or embeddingPreview in data.

Errors

400 indexId or query is missing.
404 No index with this id belongs to you.

Request

curl -X POST "$VDF_BASE_URL/data-api/v1/search/semantic" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "indexId": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
    "query": "customers reporting slow checkout",
    "topK": 5
  }'

Response 200

{
  "success": true,
  "data": [
    {
      "chunkId": "6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c",
      "score": 0.8123,
      "text": "Customer reported checkout taking over 30 seconds during peak hours.",
      "sourceRef": "public.customer_notes:id=8842",
      "indexId": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b",
      "indexName": "Customer notes index",
      "assetId": "7a2d9e10-4c3b-4a1e-9f8d-2b6c1e0f5a3d",
      "connectionId": "b3f1c2e4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "createdAt": "2026-09-01T12:05:00Z",
      "updatedAt": "2026-09-01T12:05:00Z",
      "textLength": 68,
      "embeddingDim": 1024,
      "embeddingNorm": 0.999998
    }
  ]
}

Vector indexes

Attributes

Parameters

Returns

Body parameters application/json

Returns

Errors

Path parameters

Body parameters application/json

Returns

Errors

Path parameters

Body parameters application/json

Returns

Errors

Path parameters

Returns

Errors

Parameters

Returns

Body parameters application/json

Returns

Errors

Path parameters

Body parameters application/json

Returns

Errors

Path parameters

Returns

Errors

Body parameters application/json

Returns

Errors

Request a Demo

Thank You!