SkimmerDB Docs
API reference

Namespaces

Named sets of documents, one per user, task or project.

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

Create a namespace

POST /v1/namespaces

An idle one costs only the bytes it stores (free plan: up to 1,000 namespaces; pro: no limit). Give it vector to store embeddings with a metric of your choice. Optional: writing documents to a name that doesn't exist makes the namespace.

Body application/json

namestringrequired1 to 64 of a-z, 0-9, '-', '_' and '.'.
vectorVectorConfigGive the namespace vectors (fixed for its life). Leave out for text only.
vector.dimsintegerrequiredYour embeddings' length.
vector.metric"cosine" | "euclidean"Default "cosine".
embedEmbedConfigEmbed documents' text with a model and the tenant's own key: the namespace gets vectors of the model's length.
embed.provider"openai" | "voyage" | "gemini" | "cohere" | "skimmerdb"requiredopenai, voyage, gemini or cohere: with the tenant's own key for it (PUT /v1/embedding-keys/{provider}; the provider bills the tenant, SkimmerDB charges nothing). skimmerdb: hosted, SkimmerDB embeds with voyage-3.5-lite at Voyage's price, no margin (metered as embed_tokens; the free plan includes some).
embed.modelstringThe provider's embedding model (default: text-embedding-3-small for openai, voyage-3.5-lite for voyage and skimmerdb, gemini-embedding-001 for gemini, embed-v4.0 for cohere). skimmerdb takes voyage-3.5-lite only.
embed.dimsintegerAt creation: the vectors' length to ask the model for (default: the model's own, up to 2,048). Models that make several lengths (OpenAI's text-embedding-3, Voyage's 3.5, Gemini's, Cohere's embed-v4.0) take it.

Answer

embedEmbedConfigDocuments written with text and no vector are embedded with this model (with the tenant's own provider key, or hosted); search takes semantic.
embed.provider"openai" | "voyage" | "gemini" | "cohere" | "skimmerdb"openai, voyage, gemini or cohere: with the tenant's own key for it (PUT /v1/embedding-keys/{provider}; the provider bills the tenant, SkimmerDB charges nothing). skimmerdb: hosted, SkimmerDB embeds with voyage-3.5-lite at Voyage's price, no margin (metered as embed_tokens; the free plan includes some).
embed.modelstringThe provider's embedding model (default: text-embedding-3-small for openai, voyage-3.5-lite for voyage and skimmerdb, gemini-embedding-001 for gemini, embed-v4.0 for cohere). skimmerdb takes voyage-3.5-lite only.
embed.dimsintegerAt creation: the vectors' length to ask the model for (default: the model's own, up to 2,048). Models that make several lengths (OpenAI's text-embedding-3, Voyage's 3.5, Gemini's, Cohere's embed-v4.0) take it.
vectorVectorConfig
vector.dimsintegerYour embeddings' length.
vector.metric"cosine" | "euclidean"Default "cosine".
namestring
docs_writtenintegerDocuments written to it so far (puts and deletes).
bytes_writteninteger
stored_bytesintegerWhat its objects take in object storage now (metered as storage).
created_atstringRFC 3339, UTC.

Status codes

201Created
400Malformed: not the JSON expected.
401No key, or an unknown or revoked one.
402The free plan's included usage this period is used up (queries, query CPU, object-storage reads, bytes returned, writes or storage; the message says which), or its namespace count or daily namespace creations are reached (code namespace_limit): upgrade to pro.
403The key's scope or namespaces don't allow it, or the tenant is suspended.
409Exists already, or not possible in this state.
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.
503Object storage failed: retry (nothing was written, unless the code is write_unknown: then it may have been; retrying a write is safe).
curl -s https://api.skimmerdb.com/v1/namespaces \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"support"}'
from skimmerdb import SkimmerDB
from skimmerdb._api.api.namespaces import create_namespace
from skimmerdb._api.models import CreateNamespace

db = SkimmerDB()  # SKIMMERDB_KEY
answer = create_namespace.sync(client=db.api, body=CreateNamespace.from_dict({"name":"support"}))
import { SkimmerDB } from "skimmerdb";
import { createNamespace } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await createNamespace({ client: db.client, body: {"name":"support"} });
201 answer
{
  "name": "support",
  "docs_written": 0,
  "bytes_written": 0,
  "stored_bytes": 0,
  "created_at": "2026-10-06T09:00:00Z"
}

List namespaces

GET /v1/namespaces

By name, a page at a time.

Parameters

afterstring · queryThe next of the previous page.
limitinteger · queryNamespaces a page.

Answer

namespacesNamespace[]
namespaces[].embedEmbedConfigDocuments written with text and no vector are embedded with this model (with the tenant's own provider key, or hosted); search takes semantic.
namespaces[].embed.provider"openai" | "voyage" | "gemini" | "cohere" | "skimmerdb"openai, voyage, gemini or cohere: with the tenant's own key for it (PUT /v1/embedding-keys/{provider}; the provider bills the tenant, SkimmerDB charges nothing). skimmerdb: hosted, SkimmerDB embeds with voyage-3.5-lite at Voyage's price, no margin (metered as embed_tokens; the free plan includes some).
namespaces[].embed.modelstringThe provider's embedding model (default: text-embedding-3-small for openai, voyage-3.5-lite for voyage and skimmerdb, gemini-embedding-001 for gemini, embed-v4.0 for cohere). skimmerdb takes voyage-3.5-lite only.
namespaces[].embed.dimsintegerAt creation: the vectors' length to ask the model for (default: the model's own, up to 2,048). Models that make several lengths (OpenAI's text-embedding-3, Voyage's 3.5, Gemini's, Cohere's embed-v4.0) take it.
namespaces[].vectorVectorConfig
namespaces[].vector.dimsintegerYour embeddings' length.
namespaces[].vector.metric"cosine" | "euclidean"Default "cosine".
namespaces[].namestring
namespaces[].docs_writtenintegerDocuments written to it so far (puts and deletes).
namespaces[].bytes_writteninteger
namespaces[].stored_bytesintegerWhat its objects take in object storage now (metered as storage).
namespaces[].created_atstringRFC 3339, UTC.
nextstringPass as after for the next page (empty: no more).

Status codes

200OK
401No key, or an unknown or revoked one.
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.
curl -s https://api.skimmerdb.com/v1/namespaces \
  -H "Authorization: Bearer $KEY"
from skimmerdb import SkimmerDB
from skimmerdb._api.api.namespaces import list_namespaces

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

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await listNamespaces({ client: db.client });
200 answer
{
  "namespaces": [
    {
      "name": "support",
      "docs_written": 2,
      "bytes_written": 120,
      "stored_bytes": 2817,
      "created_at": "2026-10-06T09:00:00Z"
    }
  ],
  "next": ""
}

Change a namespace's embedding model

PATCH /v1/namespaces/{name}

Sets, changes or removes the model documents' text is embedded with (the tenant's own provider key; see Embeddings). A namespace's vector length is fixed: the model must make vectors of it (409 embedding_dims otherwise, and for a namespace made without vectors). Documents already written keep their vectors.

Parameters

namestring · pathrequiredThe namespace's name.

Body application/json

embedEmbedConfig | nullrequiredSet or change the embedding model (it must make vectors of the namespace's length), or null to stop embedding.

Answer

embedEmbedConfigDocuments written with text and no vector are embedded with this model (with the tenant's own provider key, or hosted); search takes semantic.
embed.provider"openai" | "voyage" | "gemini" | "cohere" | "skimmerdb"openai, voyage, gemini or cohere: with the tenant's own key for it (PUT /v1/embedding-keys/{provider}; the provider bills the tenant, SkimmerDB charges nothing). skimmerdb: hosted, SkimmerDB embeds with voyage-3.5-lite at Voyage's price, no margin (metered as embed_tokens; the free plan includes some).
embed.modelstringThe provider's embedding model (default: text-embedding-3-small for openai, voyage-3.5-lite for voyage and skimmerdb, gemini-embedding-001 for gemini, embed-v4.0 for cohere). skimmerdb takes voyage-3.5-lite only.
embed.dimsintegerAt creation: the vectors' length to ask the model for (default: the model's own, up to 2,048). Models that make several lengths (OpenAI's text-embedding-3, Voyage's 3.5, Gemini's, Cohere's embed-v4.0) take it.
vectorVectorConfig
vector.dimsintegerYour embeddings' length.
vector.metric"cosine" | "euclidean"Default "cosine".
namestring
docs_writtenintegerDocuments written to it so far (puts and deletes).
bytes_writteninteger
stored_bytesintegerWhat its objects take in object storage now (metered as storage).
created_atstringRFC 3339, UTC.

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).
409Exists already, or not possible in this state.
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 PATCH https://api.skimmerdb.com/v1/namespaces/support \
  -H "Authorization: Bearer $KEY" \
  -d '{"embed":{"provider":"openai","model":"text-embedding-3-small"}}'
from skimmerdb import SkimmerDB
from skimmerdb._api.api.namespaces import update_namespace
from skimmerdb._api.models import NamespacePatch

db = SkimmerDB()  # SKIMMERDB_KEY
answer = update_namespace.sync("support", client=db.api, body=NamespacePatch.from_dict({"embed":{"provider":"openai","model":"text-embedding-3-small"}}))
import { SkimmerDB } from "skimmerdb";
import { updateNamespace } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await updateNamespace({ client: db.client, path: { name: "support" }, body: {"embed":{"provider":"openai","model":"text-embedding-3-small"}} });

Get a namespace

GET /v1/namespaces/{name}

Parameters

namestring · pathrequiredThe namespace's name.

Answer

embedEmbedConfigDocuments written with text and no vector are embedded with this model (with the tenant's own provider key, or hosted); search takes semantic.
embed.provider"openai" | "voyage" | "gemini" | "cohere" | "skimmerdb"openai, voyage, gemini or cohere: with the tenant's own key for it (PUT /v1/embedding-keys/{provider}; the provider bills the tenant, SkimmerDB charges nothing). skimmerdb: hosted, SkimmerDB embeds with voyage-3.5-lite at Voyage's price, no margin (metered as embed_tokens; the free plan includes some).
embed.modelstringThe provider's embedding model (default: text-embedding-3-small for openai, voyage-3.5-lite for voyage and skimmerdb, gemini-embedding-001 for gemini, embed-v4.0 for cohere). skimmerdb takes voyage-3.5-lite only.
embed.dimsintegerAt creation: the vectors' length to ask the model for (default: the model's own, up to 2,048). Models that make several lengths (OpenAI's text-embedding-3, Voyage's 3.5, Gemini's, Cohere's embed-v4.0) take it.
vectorVectorConfig
vector.dimsintegerYour embeddings' length.
vector.metric"cosine" | "euclidean"Default "cosine".
namestring
docs_writtenintegerDocuments written to it so far (puts and deletes).
bytes_writteninteger
stored_bytesintegerWhat its objects take in object storage now (metered as storage).
created_atstringRFC 3339, UTC.

Status codes

200OK
401No key, or an unknown or revoked one.
404No such namespace, document, key or tenant (or one this key may not see: the same answer).
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.
curl -s https://api.skimmerdb.com/v1/namespaces/support \
  -H "Authorization: Bearer $KEY"
from skimmerdb import SkimmerDB
from skimmerdb._api.api.namespaces import get_namespace

db = SkimmerDB()  # SKIMMERDB_KEY
answer = get_namespace.sync("support", client=db.api)
import { SkimmerDB } from "skimmerdb";
import { getNamespace } from "skimmerdb/api";

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

Delete a namespace

DELETE /v1/namespaces/{name}

Its documents are deleted from storage right after.

Parameters

namestring · pathrequiredThe namespace's name.

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).
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.
curl -s -X DELETE https://api.skimmerdb.com/v1/namespaces/support \
  -H "Authorization: Bearer $KEY"
from skimmerdb import SkimmerDB
from skimmerdb._api.api.namespaces import delete_namespace

db = SkimmerDB()  # SKIMMERDB_KEY
answer = delete_namespace.sync("support", client=db.api)
import { SkimmerDB } from "skimmerdb";
import { deleteNamespace } from "skimmerdb/api";

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