Skip to main content

VectorDB quickstart

In about five minutes you will create a vector index, insert two points, run a similarity search, and clean up. You can do everything below with curl; the console offers the same flow visually.

Before you begin​

  • You have a platform account and can sign in. If not, ask your administrator for an account or an invitation link — see Create an account.
  • You have installed the platformctl CLI and run platformctl login.
  • You know your project ID (a UUID). You can read it from the console URL: open your project at https://console.codyhill.dev and copy the UUID from #/projects/<uuid>/....

The platform is in alpha and there is no public API hostname yet. Reach the VectorDB API either through an endpoint your administrator gives you, or by letting the CLI port-forward for you. Set up your shell:

export CAI_VECTORDB_API="http://localhost:18080"   # your admin-provided or port-forwarded endpoint
export TOKEN="$CAI_TOKEN"                          # cached by 'platformctl login'
export PROJECT="00000000-0000-0000-0000-000000000000"  # your project UUID
export VDB="$CAI_VECTORDB_API"
Prefer clicking?

Everything in this quickstart is also available in the console under Data services → VectorDB in your project. The CLI itself is read-only for VectorDB (platformctl vectordb list and get); creating indexes and writing points happens through the API or the console.

Step 1: Create an index​

Only name is required. We use 4 dimensions here so the demo vectors are short enough to type; real embedding models produce hundreds or thousands of dimensions (the default is 1536).

curl -sX POST "$VDB/v1/projects/$PROJECT/indexes" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"docs","dimensions":4,"distance":"cosine"}'

You should see (HTTP 201):

{"name":"docs","resource_path":"projects/<short>/indexes/docs","collection":"p_<short>_docs","dimensions":4,"distance":"cosine","state":"pending","ready":false,...}

The index is created asynchronously. state starts at pending and moves to ready once the platform has built the underlying storage.

Step 2: Wait for it to be ready​

curl -s "$VDB/v1/projects/$PROJECT/indexes/docs" \
  -H "Authorization: Bearer $TOKEN"

You should see:

{"name":"docs","state":"ready","ready":true,"collection_status":"green","points_count":0,...}

Repeat until "ready": true. If you write points before that, the API answers with a clear 409:

{"error":"index is not ready yet; its collection has not been created","request_id":"..."}

Step 3: Insert points​

A point is a vector plus an optional JSON payload and an optional id. Ids must be unsigned integers or UUID strings; leave the id out and the platform generates a UUID.

curl -sX POST "$VDB/v1/projects/$PROJECT/indexes/docs:upsert" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"points":[
        {"id":1,"vector":[0.1,0.2,0.3,0.4],"payload":{"tag":"alpha"}},
        {"vector":[0.9,0.8,0.7,0.6],"payload":{"tag":"beta"}}]}'

You should see:

{"index":"docs","upserted_count":2}

What failure looks like​

Every vector must match the index's width exactly. Send a 3-number vector into this 4-dimension index and the whole batch is rejected — no partial writes:

{"error":"point 0 has 3 dimensions; index \"docs\" expects 4","request_id":"..."}

This is the most common first-run error with real embeddings too: it means your embedding model's output size doesn't match the index. Create a new index with the right dimensions — the value cannot be changed later.

Query with a vector, ask for the top 5 nearest, and filter to points whose payload has tag = alpha:

curl -sX POST "$VDB/v1/projects/$PROJECT/indexes/docs:query" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"vector":[0.1,0.2,0.3,0.4],"top_k":5,
       "filter":{"must":[{"key":"tag","match":{"value":"alpha"}}]}}'

You should see:

{"index":"docs","results":[{"id":1,"score":1.0,"payload":{"tag":"alpha"}}]}

The query vector is identical to point 1's vector, so with cosine distance its score is a perfect 1.0. Point 2 exists but is filtered out by the payload filter.

Step 5: Browse and check with the CLI​

Scroll lists points in id order without needing a query vector — handy for eyeballing what's stored:

curl -sX POST "$VDB/v1/projects/$PROJECT/indexes/docs:scroll" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"limit":50}'

You should see:

{"index":"docs","points":[{"id":1,"payload":{"tag":"alpha"}},{"id":"<generated-uuid>","payload":{"tag":"beta"}}]}

And confirm the index from the CLI:

platformctl vectordb list

You should see:

NAME  DIMENSIONS  DISTANCE  STATE  READY  POINTS
docs  4           cosine    ready  yes    2

Clean up​

Deleting an index destroys the index and every vector in it. There is no undo and no snapshot. Index deletion requires the project admin role.

curl -sX DELETE "$VDB/v1/projects/$PROJECT/indexes/docs" \
  -H "Authorization: Bearer $TOKEN" -w '%{http_code}\n'

You should see:

204

Next steps​

  • Indexes and points — dimensions, distance metrics, ids, payloads, and what's immutable.
  • Search — filters, scores, thresholds, and browsing in depth.
  • Use with agents — give a deployed agent long-term memory.
  • API reference — the complete endpoint list.