Skip to Content
We are live but in Staging 🎉
API ReferenceDatabases (Serverless)

Databases (Serverless) — API Reference

Package: dodil.vbase.v1 · Service: VBaseService

This is the generally available VBase surface. A serverless database is a Milvus database allocated for your organization on shared, managed infrastructure — you get a connection endpoint and a db_name, and you do everything else with the Milvus SDK. You never manage Milvus pods, users, or RBAC; VBase owns all of that.

gRPC reaches every method at dodil.vbase.v1.VBaseService/<Method>; the HTTP gateway mirrors each one. Authenticate with Authorization: Bearer <IAM token> (Auth and Access).

RPCHTTP
AllocateDatabasePOST /v1/vbase/databases
GetServiceGET /v1/vbase/{service_id}
GetServiceAccessGET /v1/vbase/{service_id}/access
ListServicesGET /v1/vbase/list/{organization_id}
DeleteDatabaseDELETE /v1/vbase/databases
HealthCheckGET /v1/vbase/healthz

The allocate → poll → connect flow

AllocateDatabase is asynchronous. It returns immediately with a service whose service_status is CREATING. The database is not connectable until it reaches RUNNING. The flow is:

  1. AllocateDatabase → returns a service_id and status CREATING.
  2. Poll GetService with that service_id until service_status is RUNNING (or surfaces an error state).
  3. GetServiceAccess → returns the endpoint, port, and db_name.
  4. Point the Milvus SDK at endpoint:port with that db_name and your bearer token, then create collections, build indexes, and search.
AllocateDatabase ──▶ CREATING ──(poll GetService)──▶ RUNNING ──▶ GetServiceAccess ──▶ endpoint + port + db_name ──▶ Milvus SDK

service_status is a ServiceStatus enum. The states you will see for a serverless database:

StatusMeaning
CREATINGAllocation in progress. Not yet connectable.
RUNNINGReady. Use GetServiceAccess and connect.
DELETING / DELETEDTeardown in progress / complete.
ERRORAllocation failed.

AllocateDatabase

Allocates a new serverless database for your organization. Returns immediately — see the flow above. Requires the AllocateServerlessDatabase scope.

Request

curl -sS -X POST "https://api.dev.dodil.io/v1/vbase/databases" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "acme-corp",
    "name": "product-search"
  }'

Response

{
  "database": {
    "serviceId": "svc-7f3a9c2e",
    "serviceName": "product-search",
    "serviceType": "DATABASE",
    "serviceStatus": "CREATING",
    "createAt": "2026-05-29T10:00:00Z",
    "organizationId": "acme-corp"
  },
  "response": { "success": true }
}

Capture database.serviceId — you need it for every subsequent call.

GetService

Returns the current ServiceInfo, including service_status. Poll this after AllocateDatabase until the status is RUNNING. Requires the GetVBaseService scope.

Request

curl -sS "https://api.dev.dodil.io/v1/vbase/svc-7f3a9c2e" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

{
  "service": {
    "serviceId": "svc-7f3a9c2e",
    "serviceName": "product-search",
    "serviceType": "DATABASE",
    "serviceStatus": "RUNNING",
    "createAt": "2026-05-29T10:00:00Z",
    "organizationId": "acme-corp"
  },
  "response": { "success": true }
}

A simple poll loop:

until [ "$(curl -sS "https://api.dev.dodil.io/v1/vbase/$SVC" \
  -H "Authorization: Bearer $DODIL_TOKEN" | jq -r .service.serviceStatus)" = "RUNNING" ]; do
  sleep 3
done

GetServiceAccess

Returns the connection details for a RUNNING database. This is what you hand to the Milvus SDK. Requires the GetVBaseServiceAccess scope.

Request

curl -sS "https://api.dev.dodil.io/v1/vbase/svc-7f3a9c2e/access" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

{
  "access": [
    {
      "serviceId": "svc-7f3a9c2e",
      "endpoint": "product-search.vbase.dev.dodil.io",
      "port": 443,
      "dbName": "db_7f3a9c2e"
    }
  ],
  "response": { "success": true }
}

The three fields you need:

FieldUse with the Milvus SDK
endpointThe host. Combine with port as the connection URI.
portThe port — typically 443 (TLS).
db_nameThe Milvus database name to select on connect.

Next: Connect with the Milvus SDK using these values plus your bearer token, then create a collection and search.

ListServices

Lists the databases (and any dedicated clusters) in an organization. Supports status filtering and pagination. Requires the ListVBaseService scope.

Request

curl -sS "https://api.dev.dodil.io/v1/vbase/list/acme-corp" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

{
  "services": [
    {
      "serviceId": "svc-7f3a9c2e",
      "serviceName": "product-search",
      "serviceType": "DATABASE",
      "serviceStatus": "RUNNING",
      "createAt": "2026-05-29T10:00:00Z",
      "organizationId": "acme-corp"
    }
  ],
  "totalCount": 1,
  "response": { "success": true }
}

DeleteDatabase

Deletes a serverless database. Identified by database_id (the service_id from allocation). Requires the DeleteServerlessDatabase scope.

Request

curl -sS -X DELETE "https://api.dev.dodil.io/v1/vbase/databases" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "databaseId": "svc-7f3a9c2e" }'

Response

common.MsgResp { success, message?, code? } — success: true on a queued deletion. The service moves through DELETING to DELETED.

HealthCheck

Liveness probe for the VBase control plane. No authentication context is required for the health path. To check the health of an allocated database instead, use the Milvus SDK against its endpoint (or dodil vbase status — see the CLI Guide).

Request

curl -sS "https://api.dev.dodil.io/v1/vbase/healthz"

Response

{ "status": "ok", "service": "vbase", "timestamp": "1748512800" }

See also

OverviewRunCommand (Advanced)