Documentation

When to use Bog

Use Bog for a small agent notebook, shared reading list, or script state. Store JSON objects under keys and read them through HTTP or MCP. This is a working prototype; keep a separate copy of important data. SQL, direct browser app access, app-user authentication, and durable event replay are outside this release.

Pricing and limits

Free tier: this prototype is free to use, with open GitHub signup, self-serve API credentials, no payment card, and no sales contact. Each ordinary workspace defaults to three Bogs, with 16 MiB of logical JSON record storage per Bog. Approved uncapped allowances still obey host capacity and per-Bog storage limits.

Authenticate first

Read the deployment's authentication guide for the active mode. With native GitHub authentication, sign in through GitHub and create a named agent credential in the console, or follow the device approval flow in that guide. MCP uses a Bog bearer credential at /mcp; OAuth-capable clients can use the self-hosted authorization-code flow with PKCE and named read/write scopes described in that guide. An operator-only deployment requires a privately supplied credential.

Keep credentials in a local secret store or environment, never in chat or URLs. Set BOG_URL to this site's origin and BOG_TOKEN to your credential. Management credentials can create Bogs; a single-Bog app credential cannot. Authenticated account requests default to the personal workspace; use ?workspace_id=UUID to select another workspace.

OAuth resource discovery

REST OAuth clients use this service origin, without a trailing slash, as the resource identifier and discover /.well-known/oauth-protected-resource. MCP clients use the origin plus /mcp and discover /.well-known/oauth-protected-resource/mcp. Authorization and token exchange must use the same resource. Newly issued REST-only tokens cannot be used at MCP; existing MCP tokens retain their REST compatibility. Both paths enforce the same workspace membership and read/write permissions.

Create a Bog

Send a stable, unique idempotency key for each intended creation. Reuse that key when retrying the same request. Save the returned Bog ID as BOG_ID.

curl "$BOG_URL/v1/bogs" \
  -H "Authorization: Bearer $BOG_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: reading-list-001' \
  -d '{"name":"reading-list","template":"records-v1"}'

Write and read a record

A write replaces the object stored at the key. Use a management, delegated-agent, or matching single-Bog write credential. Reads also accept matching read credentials.

curl -X PUT "$BOG_URL/v1/bogs/$BOG_ID/docs/dune" \
  -H "Authorization: Bearer $BOG_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Dune","status":"to-read"}'

curl "$BOG_URL/v1/bogs/$BOG_ID/docs/dune" \
  -H "Authorization: Bearer $BOG_TOKEN"

Wait for a change

Acquire a cursor first, then pass the returned opaque cursor to a subsequent request. Each wait is limited to 25 seconds. Initial state acquisition can separately take up to 25 seconds, even with timeout=0. If the response indicates reset, refetch your records. This is a change notification, not durable event history.

curl "$BOG_URL/v1/bogs/$BOG_ID/changes?timeout=0" \
  -H "Authorization: Bearer $BOG_TOKEN"

curl --get "$BOG_URL/v1/bogs/$BOG_ID/changes" \
  --data-urlencode "cursor=$BOG_CURSOR" --data-urlencode 'timeout=25' \
  -H "Authorization: Bearer $BOG_TOKEN"

Explore the contract

Operations and limits · Templates · OpenAPI · Agent entry point · API catalog

Respect error responses and retry guidance. If startup fails with a capacity error, retain the returned Bog ID and retry creation with the same name, idempotency key and body after active operations finish. Unused warm workers are automatically reclaimed when another Bog needs capacity; ongoing database operations are protected. Do not create new names or keys to recover. A record or view request can also start that same Bog once capacity is free; describe alone does not restart it. Never treat an authentication failure as evidence that a private resource exists.

Organizations and uncapped Bogs

In the console, choose Create organization to make a shared workspace, then invite staff through People. Select that workspace explicitly when using HTTP or MCP. Workspaces normally allow three Bogs. Platform operators can enable Uncapped Bogs for an account's personal workspace or for a shared organization. A flag grants no new access; the host's overall capacity and each Bog's 16 MiB storage limit still apply. Workspace discovery returns the effective bog_limit; null means uncapped. Only signed-in human platform operators see Platform allowances controls. Delegated agents cannot change allowances or create organizations.

API versions and deprecation

The HTTP data API uses the major version /v1. Additive fields may appear within that version; clients should tolerate unknown response fields. Incompatible changes to stable data operations will use a new major API version. Before retiring a published version, we will publish migration instructions here and use Deprecation, Sunset, and a Link to those instructions on affected responses. No version is currently scheduled for removal. This prototype has no guaranteed notice period or service-level agreement. Authentication and discovery protocols are described separately in the authentication guide.

Free, self-serve testing

When GitHub signup is enabled, sign in and create API credentials yourself in the console, or approve an agent through the device flow. No payment card or sales conversation is required. Test against a disposable Bog in your own workspace; there is no separate sandbox. Ordinary workspace and storage limits apply to test Bogs too. A signed-in workspace owner can delete a disposable Bog by confirming its exact ID.

Browser agents

Browsers that support WebMCP can discover the service and its templates on this page. The signed-in console also exposes tools to list workspaces, inspect allowances and schemas, preview up to 20 records, create a Bog, and prepare private app access. Preparing access returns only a nonsecret reference, safe in tool results or conversation; it grants no access by itself. Review it in the console and explicitly download the private configuration, or let an authorized agent run the private helper with its own authorization cache. Any required device approval must be an explicit human action. The helper writes credentials privately, without exposing the installed file to conversation. Browser tools never redeem or download credentials. A tool uses your personal workspace unless it names another workspace explicitly. These tools never return cookies or credential secrets. Use HTTP or remote MCP on browsers without WebMCP.

Supported interfaces and limits

Bog supports HTTP JSON and MCP. There is no GraphQL endpoint or GraphQL schema. Authenticated responses report the actual request limit through the structured RateLimit-Policy and RateLimit headers, plus compatibility fields RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset; an exhausted request allowance returns Retry-After. Public discovery is not subject to that account request bucket, so its responses do not invent account quotas.

Diagnose a Bog through your agent

Call MCP bog_metrics or GET /v1/bogs/{id}/metrics?window=1h for request counts, errors, sampled latency, active change waiters, cached worker state and limits. Windows are 5m or 1h. Reading diagnostics does not wake a sleeping worker. Check observed_since, window_complete and truncated: rolling observations reset on manager restart and are bounded. Long-poll duration includes intentional waiting; write-acknowledgment-to-release latency is reported separately where measurable.

App credentials see their own traffic only. Workspace members can additionally use bog_events or GET /v1/bogs/{id}/events?limit=50 for operational history. Follow the opaque next_cursor; reset means history was lost. Retention is at most seven days, 1,000 events per Bog and 20,000 service-wide. This history contains no records or record-change replay. Browser agents have the same read-only tools in supported, signed-in consoles.