SkimmerDB Docs
API reference

Keys

API keys: scopes, namespaces, caps.

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 keys

GET /v1/keys

The tenant's live keys. Needs an admin key without namespace limits or caps, or the owner's login.

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/keys \
  -H "Authorization: Bearer $KEY"
from skimmerdb import SkimmerDB
from skimmerdb._api.api.keys import list_keys

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

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await listKeys({ client: db.client });

Make an API key

POST /v1/keys

The key is in the answer only. Scopes: read: list namespaces, search, count, get documents, warm, SQL, usage. write: also create and delete namespaces, write, update, delete and import documents. admin: also make, list, change and revoke keys, and billing. Only an admin key without namespace limits or caps (or the owner's login) can manage keys, so a read or write key can't make more.

Body application/json

namestringA label (default: default).
scope"read" | "write" | "admin"read: list namespaces, search, count, get documents, warm, SQL, usage. write: also create and delete namespaces, write, update, delete and import documents. admin: also make, list, change and revoke keys, and billing. Only an admin key without namespace limits or caps (or the owner's login) can manage keys, so a read or write key can't make more. Default "write".
namespacesstring[]The namespaces the key may use: names or prefix* (default: all).
rate_per_sintegerRequests a second (0: no cap of its own).
cap_queriesintegerQueries a billing period (0: none).
cap_writesintegerDocuments written or deleted a billing period (0: none).

Answer

idinteger
namestring
keystringThe key itself: shown only here. Send it as Authorization: Bearer .
prefixstring
scopestring
namespacesstring[]

Status codes

201Created
401No key, or an unknown or revoked one.
403The key's scope or namespaces don't allow it, or the tenant is suspended.
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).
curl -s https://api.skimmerdb.com/v1/keys \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"my agent"}'
from skimmerdb import SkimmerDB
from skimmerdb._api.api.keys import create_key
from skimmerdb._api.models import KeyRequest

db = SkimmerDB()  # SKIMMERDB_KEY
answer = create_key.sync(client=db.api, body=KeyRequest.from_dict({"name":"my agent"}))
import { SkimmerDB } from "skimmerdb";
import { createKey } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await createKey({ client: db.client, body: {"name":"my agent"} });
201 answer
{
  "id": 7,
  "name": "my agent",
  "key": "tb_3q2-Xw9Lk2bFz0aQvP1mYc7RnT4sUe8d",
  "prefix": "tb_3q2-Xw9",
  "scope": "write",
  "namespaces": []
}

Revoke a key

DELETE /v1/keys/{id}

At once (an MCP connection's key too).

Parameters

idstring · 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/keys/t-1 \
  -H "Authorization: Bearer $KEY"
from skimmerdb import SkimmerDB
from skimmerdb._api.api.keys import revoke_key

db = SkimmerDB()  # SKIMMERDB_KEY
answer = revoke_key.sync("t-1", client=db.api)
import { SkimmerDB } from "skimmerdb";
import { revokeKey } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await revokeKey({ client: db.client, path: { id: "t-1" } });

Change a key's namespaces and caps

PUT /v1/keys/{id}/limits

Parameters

idstring · pathrequired

Body application/json

namespacesstring[]
rate_per_sinteger
cap_queriesinteger
cap_writesinteger

Status codes

204Done (no body)
400Malformed: not the JSON expected.
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).
curl -s -X PUT https://api.skimmerdb.com/v1/keys/t-1/limits \
  -H "Authorization: Bearer $KEY" \
  -d '{"namespaces":["agent-7-*"],"rate_per_s":5,"cap_queries":50000,"cap_writes":10000}'
from skimmerdb import SkimmerDB
from skimmerdb._api.api.keys import set_key_limits
from skimmerdb._api.models import KeyLimits

db = SkimmerDB()  # SKIMMERDB_KEY
answer = set_key_limits.sync("t-1", client=db.api, body=KeyLimits.from_dict({"namespaces":["agent-7-*"],"rate_per_s":5,"cap_queries":50000,"cap_writes":10000}))
import { SkimmerDB } from "skimmerdb";
import { setKeyLimits } from "skimmerdb/api";

const db = new SkimmerDB(); // SKIMMERDB_KEY
const { data } = await setKeyLimits({ client: db.client, path: { id: "t-1" }, body: {"namespaces":["agent-7-*"],"rate_per_s":5,"cap_queries":50000,"cap_writes":10000} });