API: Write

Upsert and delete vectors within a namespace.

Endpoint

POST /v2/namespaces/:namespace

Authentication

All requests require a Bearer token:

Authorization: Bearer bv_live_your_api_key

Request Body

{
  "upsert_rows": [
    {
      "id": 1,
      "vector": [0.1, 0.2, 0.3],
      "title": "My document",
      "category": "article"
    }
  ],
  "deletes": [100, 101, 102]
}

Fields

Field	Type	Required	Description
`upsert_rows`	array	No	Rows to upsert. Each row has `id`, `vector`, and any custom attributes
`upsert_rows[].id`	number	Yes	Unique row identifier
`upsert_rows[].vector`	number[]	Yes	Vector embedding (must match namespace dimensions)
`deletes`	number[]	No	Row IDs to delete
`distance_metric`	string	No	Distance metric (`"cosine"`, `"euclidean"`). Defaults to `"cosine"`

Response

{
  "rows_affected": 3,
  "rows_upserted": 1,
  "rows_deleted": 2
}

Batch Import (JSONL)

For large imports, use the JSONL endpoint:

POST /v2/namespaces/:namespace/import/jsonl

Content-Type: text/plain

Each line is a JSON object:

{"id": 1, "vector": [0.1, 0.2, ...], "title": "doc one"}
{"id": 2, "vector": [0.3, 0.4, ...], "title": "doc two"}

Lines starting with # are ignored. Maximum batch size: 1,000 rows.

Example (TypeScript SDK)

import { BudgetVecClient } from "@budgetvec/client";

const client = new BudgetVecClient({
  baseUrl: "https://budgetvec.standupcode.workers.dev",
  apiKey: "bv_live_your_key",
});

const ns = client.namespace("products");

// Upsert
await ns.upsert({
  upsert_rows: [
    { id: 1, vector: embedding, name: "Widget", price: 9.99 },
  ],
});

// Delete
await ns.upsert({
  deletes: [1, 2, 3],
});