Build

REST API

HTTP gateway endpoints, request formats, auth headers, and response semantics.

Overview

The managed cloud exposes a REST gateway for vector operations. Every request is authenticated with a project API key and routed to your project's runtime.

Base URL

Your project's REST API base URL is shown in the console under Settings after provisioning completes. It looks like:

base url

https://your-instance.kyrodb.cloud:51051

Authentication

Send your API key in either header format:

x-api-key: <key>
authorization: Bearer <key>

Endpoints

Method	Endpoint	Description
`POST`	`/v1/vectors/upsert`	Insert or update vectors
`POST`	`/v1/vectors/search`	k-NN similarity search
`POST`	`/v1/vectors/query`	Fetch vector by ID
`POST`	`/v1/vectors/update`	Update metadata by ID
`DELETE`	`/v1/vectors/delete`	Delete vector by ID

Upsert

terminal

curl -X POST "$KYRODB_API_BASE_URL/v1/vectors/upsert" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $KYRODB_API_KEY" \
  -H "x-idempotency-key: upsert-batch-001" \
  -d '{
    "namespace": "products",
    "vectors": [
      {
        "id": "sku-1",
        "values": [0.11, 0.22, 0.33, 0.44],
        "metadata": {
          "name": "Widget A",
          "category": "hardware"
        }
      },
      {
        "id": "sku-2",
        "values": [0.55, 0.66, 0.77, 0.88],
        "metadata": {
          "name": "Widget B",
          "category": "software"
        }
      }
    ]
  }'

Search

terminal

curl -X POST "$KYRODB_API_BASE_URL/v1/vectors/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $KYRODB_API_KEY" \
  -d '{
    "namespace": "products",
    "vector": [0.11, 0.22, 0.33, 0.44],
    "top_k": 10
  }'

Query by ID

terminal

curl -X POST "$KYRODB_API_BASE_URL/v1/vectors/query" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $KYRODB_API_KEY" \
  -d '{
    "namespace": "products",
    "id": "sku-1"
  }'

Update Metadata

terminal

curl -X POST "$KYRODB_API_BASE_URL/v1/vectors/update" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $KYRODB_API_KEY" \
  -d '{
    "namespace": "products",
    "id": "sku-1",
    "metadata": {
      "category": "premium-hardware",
      "updated_at": "2025-01-15"
    }
  }'

Delete

terminal

curl -X DELETE "$KYRODB_API_BASE_URL/v1/vectors/delete" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $KYRODB_API_KEY" \
  -d '{
    "namespace": "products",
    "id": "sku-1"
  }'

Request Rules

All request bodies are JSON.
namespace is optional and defaults to default.
Vector IDs must be strings.
Embeddings must be finite numeric arrays matching your project dimension.
Batch upsert size is capped server-side.
Mutating requests can include x-idempotency-key for replay-safe retries.

Responses

Status	Meaning	Retry?
`200`	Success	—
`400`	Invalid request body or vector payload	No
`401`	Missing or invalid API key	No
`403`	API key scope does not allow this operation	No
`404`	Route not found	No
`429`	Rate limit exceeded	Yes, with backoff
`500`	Internal server error	Maybe
`503`	Service temporarily unavailable	Yes

Python SDK

For production applications, we recommend the Python SDK which provides typed responses, automatic retries, circuit breakers, and streaming batch operations over gRPC.