Vectors

Delete a vector

DELETE /api/v1/apps/{appId}/indexes/{index}/vectors/{id}

Deletes a vector.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, index, id.

Response: no body on success.

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X DELETE "https://node.example.com/api/v1/apps/{appId}/indexes/{index}/vectors/{id}" \
  -H "Authorization: Bearer $TOKEN"

Top-k vector search

POST /api/v1/apps/{appId}/indexes/{index}/vectors:query

The k nearest vectors to the one given (k defaults to 10, at most 1000), by the index’s metric, among those the caller may read, with an optional filter on their metadata.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, index.

Request body (JSON):

Field	Type	Required	Notes
filter	object	no
filter.and	array of object	no
filter.field	string	no
filter.not	object	no	recursive
filter.op	string	no
filter.or	array of object	no
filter.value	any	no
include	array of string	no
k	integer	no
vector	array of number	yes

Response (200, JSON):

Field	Type	Required	Notes
matches	array of object	yes
matches[].distance	number	yes
matches[].id	string	yes
matches[].metadata	object	no
matches[].ref	string	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X POST "https://node.example.com/api/v1/apps/{appId}/indexes/{index}/vectors:query" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vector": []}'

Insert or replace a vector

POST /api/v1/apps/{appId}/indexes/{index}/vectors:upsert

Stores a vector, with optional metadata, replacing any vector with the same id. Its length must be the index’s dimensions. The app provides the embeddings; the node computes none.

Who may call it: The console session (its cookie, and X-CSRF-Token on writes), an API token with a scope for this app (Authorization: Bearer oak_pat_...) or the app’s own access token (Authorization: Bearer ...).

Path parameters: appId, index.

Request body (JSON):

Field	Type	Required	Notes
id	string	no
metadata	object	no
ref	string	no
vector	array of number	yes

Response (200, JSON):

Field	Type	Required	Notes
(body)	object	yes

Errors: 400, 401, 403, 404, 429, as described in errors.

curl -X POST "https://node.example.com/api/v1/apps/{appId}/indexes/{index}/vectors:upsert" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vector": []}'