Developers · pilot contracts

Bobby DB is an API-first product

Bobby DB is built to be read by applications, not by people clicking through a UI. The REST surface is implemented and answers for authorized pilot operators holding a key.

Authorized pilot operators

Implementation status

The versioned REST surface, key issuance, per-key rate limiting and usage accounting are implemented, and reachable only with a key the operator issued. They are not generally available and cannot be signed up for. The MCP interface is deferred.

No key has been issued and no release published in production, so every credential and value in an example below is unmistakably fake.

Base URL

One versioned prefix. A breaking change becomes a new version rather than a silent change to an existing one.

Base URL

https://bobbydb.com/api/v1

Implemented and served behind an API key. Without a key the surface refuses the request rather than returning data.

Example credential

bdb_public_example_replace_me

A deliberately fake placeholder. An authorized pilot operator replaces it with the key issued to them. Keys always travel in a header, never in a URL.

Request mechanics

The behaviours a client can design against.

API keysAuthorized pilot operators: Every request, including reads of free public data, will carry a key in an Authorization header. Keys are never accepted in a URL, a query string or a path segment, because URLs end up in logs, referrers and browser history.
Read and write scopesAuthorized pilot operators: A key is issued with read scope or write scope. A read key can list and fetch releases; a write key can create drafts, run imports and request releases. Publication still requires human review.
Current versus pinned releaseAuthorized pilot operators: Without a release parameter, a read follows the collection's current release. With one, the read is pinned to an exact immutable version and never changes underneath a build.
Cursor paginationAuthorized pilot operators: Lists are paged by opaque cursor rather than numeric offset, so a page stays stable while a collection grows and a client can resume exactly where it stopped.
Batch readsAuthorized pilot operators: Several keys can be fetched in one request instead of a request per key, which is the common shape when a product boots and needs many reference values at once.
ETag and If-None-MatchAuthorized pilot operators: Release reads are designed to be strongly cacheable. A client stores the ETag and revalidates; an unchanged release answers with a not-modified response and no body.
Idempotency keysAuthorized pilot operators: Retryable writes accept a client-supplied idempotency key so a network retry cannot duplicate an import or a draft change.
Request IDsAuthorized pilot operators: Every response carries a request identifier. Quoting it lets a support conversation refer to one exact request instead of a description of one.
Rate limitsAuthorized pilot operators: Limits are applied per workspace and per key, and are designed to answer with an explicit rate-limit status and retry guidance rather than a silent failure.
MCPAuthorized pilot operators: Deferred, and not in service. Its address answers one stated refusal on every method, exposes no data and lists no tool. It will be built only under separate authorization and verification.

Authorized pilot operators

Copyable examples

Placeholder key, placeholder collection slug. The surface is implemented, so these shapes are real, but they succeed only with a key the operator issued.

List entries, current releasesynthetic example

curl "https://bobbydb.com/api/v1/collections/example-collection/entries?limit=100" \
  -H "Authorization: Bearer bdb_public_example_replace_me"

Cursor pagination; the key stays in the Authorization header.

Pin an exact releasesynthetic example

curl "https://bobbydb.com/api/v1/collections/example-collection/entries?release=example-release-version" \
  -H "Authorization: Bearer bdb_public_example_replace_me"

A pinned read is reproducible: the release content can never change.

Revalidate with an ETagsynthetic example

curl -i "https://bobbydb.com/api/v1/collections/example-collection/entries" \
  -H "Authorization: Bearer bdb_public_example_replace_me" \
  -H 'If-None-Match: "example-etag-value"'

An unchanged release is designed to answer 304 with no body.

Batch readsynthetic example

curl -X POST "https://bobbydb.com/api/v1/collections/example-collection/entries:batch" \
  -H "Authorization: Bearer bdb_public_example_replace_me" \
  -H "Content-Type: application/json" \
  -d '{"keys":["example.first.key","example.second.key"]}'

Fetch several keys in one round trip instead of one request per key.

Retryable writesynthetic example

curl -X POST "https://bobbydb.com/api/v1/collections/example-collection/drafts/entries" \
  -H "Authorization: Bearer bdb_public_example_replace_me" \
  -H "Idempotency-Key: example-idempotency-key-0001" \
  -H "Content-Type: application/json" \
  -d '{"key":"example.first.key","value":{"example":true}}'

The idempotency key makes a retry safe after a timeout.

Error shapesynthetic example

{
  "error": {
    "code": "unprocessable",
    "message": "Entry value does not satisfy the collection schema.",
    "request_id": "example-request-id-0001"
  }
}

Every error is designed to carry a stable code and the request ID.

Authorized pilot operators

Error taxonomy

Stable machine-readable codes, so a client branches on a code rather than parsing prose.

Bobby DB error codes returned at the delivery boundary.
Code	HTTP	Meaning
invalid_request	400	The request shape, parameters or body failed validation.
unauthenticated	401	No key was supplied, or the key is unknown or revoked.
forbidden	403	The key is valid but its scope or workspace does not allow this action.
not_found	404	The workspace, collection, release or key does not exist for this caller.
conflict	409	The write conflicts with current state, for example a competing release.
unprocessable	422	The content is well-formed but fails the collection's schema.
rate_limited	429	The per-key or per-workspace limit was exceeded; retry guidance included.
internal_error	500	An unexpected server fault. The request ID identifies the occurrence.

Not yet available

MCP is deferred

There is no MCP interface to integrate with today, and this page will not describe one as though there were.

What answers today

Not yet available

The MCP address answers one stated refusal on every method, including a JSON-RPC initialize. It lists no tool, exposes no data, reads no database and holds no credential.

What it will require

Not yet available

When MCP is built, it will sit behind the same keys, scopes, workspace boundary, rate limits and usage accounting as REST, and it will be read-only. None of that exists yet, and nothing about it is scheduled here.

Documentation index Security position