SkimmerDB Docs
API reference

Embeddings

Documents' text and semantic searches embedded with your own OpenAI, Voyage, Gemini or Cohere key, or hosted by SkimmerDB at cost.

Kept in this tab only and sent only to api.skimmerdb.com. Requests run against your account and count as usage. Make a key.

List embedding keys

GET /v1/embedding-keys

The tenant's own provider keys SkimmerDB embeds with (bring your own key): which providers, and a hint of each key. Needs an admin key without namespace limits or caps, or the owner's login (as managing API keys).

Answer

keysEmbeddingKey[]
keys[].providerstringopenai or voyage.
keys[].hintstringThe key's first and last characters: the key itself is never shown again.
keys[].created_atstring
keys[].updated_atstring

Status codes

200OK
401No key, or an unknown or revoked one.
403The key's scope or namespaces don't allow it, or the tenant is suspended.
curl -s https://api.skimmerdb.com/v1/embedding-keys \
  -H "Authorization: Bearer $KEY"
from skimmerdb import SkimmerDB
from skimmerdb._api.api.embeddings import list_embedding_keys

db = SkimmerDB()  # SKIMMERDB_KEY
answer = list_embedding_keys.sync(client=db.api)
import { SkimmerDB } from "skimmerdb";
import { listEmbeddingKeys } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await listEmbeddingKeys({ client: db.client });
200 answer
{
  "keys": [
    {
      "provider": "openai",
      "hint": "sk-…a1b2",
      "created_at": "2026-10-16T09:00:00Z",
      "updated_at": "2026-10-16T09:00:00Z"
    }
  ]
}

Store an embedding key

PUT /v1/embedding-keys/{provider}

Stores (or replaces) the tenant's key for a provider (openai, voyage, gemini or cohere), after checking it with the provider (one tiny embedding with its default model, billed by the provider). Kept encrypted; never shown again. Namespaces with an embedding model (embed) then embed documents' text and semantic searches with it; the provider bills the tenant, SkimmerDB counts the tokens (usage.embed_tokens) and charges nothing for them. Needs an admin key without namespace limits or caps, or the owner's login (as managing API keys).

Parameters

providerstring · pathrequired

Body application/json

keystringrequiredThe provider's API key. Checked with the provider (one tiny embedding), then stored encrypted; never shown again.

Answer

providerstringopenai or voyage.
hintstringThe key's first and last characters: the key itself is never shown again.
created_atstring
updated_atstring

Status codes

200OK
401No key, or an unknown or revoked one.
403The key's scope or namespaces don't allow it, or the tenant is suspended.
404No such namespace, document, key or tenant (or one this key may not see: the same answer).
422Invalid: the message says why (code invalid with fields: which input fields; query_timeout: past the plan's time limit; scan_refused: send scan: true).
429Over the tenant's or the key's rate, concurrency or cap, or writes arriving faster than the namespace commits them (code write_busy): retry after Retry-After seconds.
502Billing (Stripe) is unavailable right now.
curl -s -X PUT https://api.skimmerdb.com/v1/embedding-keys/provider \
  -H "Authorization: Bearer $KEY" \
  -d '{"key":"sk-proj-..."}'
from skimmerdb import SkimmerDB
from skimmerdb._api.api.embeddings import set_embedding_key
from skimmerdb._api.models import EmbeddingKeyRequest

db = SkimmerDB()  # SKIMMERDB_KEY
answer = set_embedding_key.sync("provider", client=db.api, body=EmbeddingKeyRequest.from_dict({"key":"sk-proj-..."}))
import { SkimmerDB } from "skimmerdb";
import { setEmbeddingKey } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await setEmbeddingKey({ client: db.client, path: { provider: "provider" }, body: {"key":"sk-proj-..."} });
200 answer
{
  "provider": "openai",
  "hint": "sk-…a1b2",
  "created_at": "2026-10-16T09:00:00Z",
  "updated_at": "2026-10-16T09:00:00Z"
}

Delete an embedding key

DELETE /v1/embedding-keys/{provider}

Forgets the tenant's key for a provider at once. Writes that need it (text without vectors in a namespace with that provider's model) and semantic searches then answer 422 embedding_key_missing. Needs an admin key without namespace limits or caps, or the owner's login (as managing API keys).

Parameters

providerstring · pathrequired

Status codes

204Done (no body)
401No key, or an unknown or revoked one.
403The key's scope or namespaces don't allow it, or the tenant is suspended.
404No such namespace, document, key or tenant (or one this key may not see: the same answer).
curl -s -X DELETE https://api.skimmerdb.com/v1/embedding-keys/provider \
  -H "Authorization: Bearer $KEY"
from skimmerdb import SkimmerDB
from skimmerdb._api.api.embeddings import delete_embedding_key

db = SkimmerDB()  # SKIMMERDB_KEY
answer = delete_embedding_key.sync("provider", client=db.api)
import { SkimmerDB } from "skimmerdb";
import { deleteEmbeddingKey } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await deleteEmbeddingKey({ client: db.client, path: { provider: "provider" } });