Skip to Content
We are live but in Staging 🎉
VectorAPI ReferenceEngine

Engine — API Reference

Package: dodil.k3.vector.v1 · Service: VectorService

The vector engine is per-bucket (1:1 with the bucket). It holds the VBase / Milvus connection config + an IAM service account + the list of collections under it. Three provisioning modes — see Core Concepts → Engine for the full type.

RPCHTTP
ConfigureEnginePOST /:bucket/vector
GetEngineGET /:bucket/vector
DeleteEngineDELETE /:bucket/vector
ListVBaseInstancesGET /admin/vbase-instances

gRPC setup — grpcurl, endpoints, reflection, and field-name casing — is covered once in Conventions → Using gRPC.

ConfigureEngine

Creates the engine row + provisions VBase / wires connection details per mode. Returns the freshly created Engine (status typically PENDING or PROVISIONING for auto mode; ACTIVE for external / pick).

Request

Auto mode — K3 provisions everything:

curl -sS -X POST "https://k3.dev.dodil.io/kb-prod/vector" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "kb-prod",
    "mode": "auto"
  }'

External mode — your own VBase cluster:

curl -sS -X POST "https://k3.dev.dodil.io/kb-prod/vector" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "kb-prod",
    "mode": "external",
    "vbaseEndpoint": "vbase.example.com",
    "vbasePort": 19530,
    "vbaseDbName": "my-vec-db"
  }'

Pick mode — reuse an existing VBase service in the org:

curl -sS -X POST "https://k3.dev.dodil.io/kb-prod/vector" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "kb-prod",
    "mode": "pick",
    "serviceId": "vb_svc_existing_a1b2..."
  }'

Response

An Engine row — see Core Concepts → Engine.

Status progression for auto mode: PENDING → PROVISIONING → ACTIVE. Poll with GetEngine; error_message populated when status = ERROR. Typical end-to-end provision under a minute.

GetEngine

Request

curl -sS "https://k3.dev.dodil.io/kb-prod/vector" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

An Engine row (including the bucket’s collections inline) — see Core Concepts → Engine.

DeleteEngine

Removes the engine row + the bucket’s VBase connection config. Does not drop the underlying VBase database by default — set delete_database: true (auto-mode only) for a full teardown.

Request

Keep VBase DB (default — useful if you want to re-attach later):

curl -sS -X DELETE "https://k3.dev.dodil.io/kb-prod/vector" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "kb-prod"
  }'

Full teardown (auto mode only — drops the VBase database too):

curl -sS -X DELETE "https://k3.dev.dodil.io/kb-prod/vector" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "kb-prod",
    "deleteDatabase": true
  }'

Response

Empty (DeleteEngineResponse {}).

Deleting the engine does NOT cascade to:

  • The Milvus collections inside the VBase database (unless delete_database: true)
  • The Scriptum pipelines + ingest rules bound to pipeline-mode collections in this bucket

Clean those up separately if you want a full reset. For pipeline-mode collections, see Pipelines → DeleteRule.

ListVBaseInstances

Lists the VBase services available to the org. Feeds service_id into ConfigureEngine with mode: "pick".

Request

curl -sS "https://k3.dev.dodil.io/admin/vbase-instances" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

{
  "instances": [
    {
      "serviceId": "vb_svc_a1b2...",
      "name": "prod-cluster-us-east-1",
      "status": "running",
      "serviceType": "cluster",
      "createdAt": "2026-05-20T10:00:00Z"
    },
    {
      "serviceId": "vb_svc_c3d4...",
      "name": "dev-shared",
      "status": "running",
      "serviceType": "database",
      "createdAt": "2026-05-15T08:00:00Z"
    }
  ]
}

See also

OverviewCollections