Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
HTTP API Contract
This document records the HTTP shape DBBASIC Object Server should preserve while the public server is rebuilt.
The goal is compatibility. Existing clients, MCP tools, Scroll, scripts, and automation should not need a new API shape just because the internals become cleaner.
Examples use:
http://127.0.0.1:8001
Do not replace these examples with private LAN IPs, cloud IPs, customer domains, or deployment-specific station names.
Client Defaults
Existing clients expect JSON by default and commonly send:
Accept: application/json
Authorization: Token <token>
Authentication is required for source, state, logs, versions, object creation, source updates, rollback, and destructive deletes. Basic object execution may be public or authenticated depending on server policy and the object being called.
The current public ASGI slice enforces that sensitive read surface with the temporary admin token from DBBASIC_ADMIN_TOKEN by default. A deployment can opt in to DBBASIC_ENABLE_SESSION_ADMIN_GATES=true so active DBBASIC sessions with an admin role can pass the same gate. Source update and rollback also require DBBASIC_ENABLE_SOURCE_WRITES=true. The real role, object, and row permission system still needs to replace this temporary admin boundary before general use.
Correlation IDs
Every HTTP response includes:
X-DBBASIC-Correlation-ID: <uuid-v4>
Clients may send their own UUIDv4 correlation ID:
X-DBBASIC-Correlation-ID: 123e4567-e89b-42d3-a456-426614174000
Missing, empty, or invalid values are replaced with a server-generated UUIDv4. The response header always contains the accepted value. Source update responses, rollback responses, and execution error bodies also include correlation_id.
The same ID is written into source version metadata, source-change entries, object-owned runtime logs, execution error logs, and permission audit entries when those records are created inside the request. Scroll and AI tools can use that ID to connect one user action to the source version, logs, permission decision, and runtime error it produced.
Resource IDs
New DBBASIC-facing URL and API resources should use UUIDv4 IDs by default:
- record IDs
- account and user IDs
- session/action/change IDs
- package install and restore IDs
- external links and imported resource handles
Imported systems may keep legacy compatibility IDs. For example, a Django table with integer primary keys can be imported with its old ID preserved in a compatibility column, while the DBBASIC route-facing id should be UUIDv4 for new records. This keeps URLs non-enumerable, makes exports easier to merge, and avoids coupling object packages to one database sequence.
The current identity registry generates UUIDv4 account IDs, user IDs, and session IDs when the server creates them. It still accepts existing string account/user IDs and legacy sess_... session rows so old clients, Scroll prototypes, and migration tools do not break while the public runtime is being extracted.
Health
Plain health is a public liveness check:
GET /health
Response:
{
"status": "ok"
}
Detailed health is for operators, Scroll, and future cluster routing:
GET /health?capacity=true
Authorization: Token <token>
Response:
{
"status": "ok",
"version": "0.0.1",
"station_id": "standalone",
"uptime": "2h 10m",
"requests": 120,
"errors": 0,
"rps": 1.4,
"objects": {
"count": 4
},
"capacity": {
"requests": {
"in_flight": 1,
"max": 64,
"available": 63,
"limited": true
},
"object_executions": {
"in_flight": 0,
"max": 8,
"available": 8,
"limited": true
}
},
"checks": {
"storage": {
"status": "ok"
}
}
}
GET /health?metrics=true returns the same detailed health payload plus a metrics object with request counts, status counts, response timing, top paths, and recent HTTP errors. This preserves the older dashboard/Scroll direction without exposing those details through the public liveness route.
Admin Status
Admin status is the compact operator snapshot Scroll and staging dashboards can use instead of stitching together many routes on first load:
GET /admin/status
Authorization: Token <token>
Response:
{
"status": "ok",
"timestamp": "2026-01-01T00:00:00+00:00",
"version": "0.0.1",
"station_id": "standalone",
"health": {
"status": "ok",
"metrics": {}
},
"inventory": {
"objects": 4,
"collections": 2,
"schemas": 2,
"packages": 3
},
"capabilities": {
"source_writes": {
"enabled": false,
"env": "DBBASIC_ENABLE_SOURCE_WRITES"
},
"file_writes": {
"enabled": false,
"env": "DBBASIC_ENABLE_FILE_WRITES",
"max_bytes": 1048576,
"max_bytes_env": "DBBASIC_MAX_OBJECT_FILE_BYTES"
},
"package_installs": {
"enabled": false,
"env": "DBBASIC_ENABLE_PACKAGE_INSTALLS"
},
"permission_enforcement": {
"enabled": false,
"requested": false,
"blocked": true,
"env": "DBBASIC_ENABLE_PERMISSION_ENFORCEMENT"
},
"identity": {
"trusted_headers_enabled": false,
"require_known_identity_users": true,
"session_login_enabled": false,
"session_login_token_configured": false,
"session_admin_gates_enabled": false,
"session_admin_gates_env": "DBBASIC_ENABLE_SESSION_ADMIN_GATES"
}
},
"packages": [
{
"id": "system-dashboard",
"name": "System Dashboard",
"version": "0.1.0",
"status": "installed",
"install": {
"installed_count": 1,
"installable_count": 1,
"safe_to_install": true,
"install_enabled": false,
"warnings": []
},
"changes": {
"total": 1,
"latest": {
"action": "installed"
}
}
}
],
"permissions": {
"enforcement_enabled": false,
"audit_enabled": false,
"readiness": {
"ready": false
},
"warnings": []
}
}
If the server is degraded, the route may return 503 with the same response shape and "status": "degraded". This route is admin-token gated because it contains configuration, package, and capacity details.
Daemon Status
Daemon status is the read-only operator snapshot for the scheduler, queue, event delivery, and cleanup primitives:
GET /daemon/status
Authorization: Token <token>
Response:
{
"status": "ok",
"timestamp": "2026-01-01T00:00:00+00:00",
"daemon": {
"mode": "polling",
"croniter_available": true,
"object_roots": {
"count": 1
},
"triggers": {
"scheduler": {
"object_id": "scheduler",
"source_present": true
},
"queue": {
"object_id": "queue",
"source_present": true
},
"events": {
"object_id": "events",
"source_present": true
}
}
},
"scheduler": {
"object_id": "scheduler",
"source_present": true,
"tasks": {
"total": 2,
"active": 1,
"due": 1,
"future": 0,
"invalid": 0,
"next_run": 1767225600,
"next_run_iso": "2026-01-01T00:00:00+00:00"
}
},
"queue": {
"object_id": "queue",
"source_present": true,
"messages": {
"total": 3,
"pending_visible": 1,
"pending_delayed": 1,
"expired_pending": 0,
"invalid": 0
}
},
"events": {
"object_id": "events",
"source_present": true,
"events": {
"total": 10,
"latest": {
"id": "evt_123",
"event_type": "collection.record.created",
"timestamp": 1767225600
}
},
"subscriptions": {
"total": 2,
"by_delivery_status": {
"ok": 1,
"failed": 1
},
"pending_deliveries": 1
}
},
"cleanup": {
"event_retention": {
"keep_count": 1000,
"keep_seconds": 604800
},
"rate_limit_files": 0
}
}
This endpoint does not execute daemon work or expose event payloads. It reads the same TSV state that the daemon uses so Scroll can show due scheduler tasks, visible/delayed queue messages, failed subscription delivery, event retention, and cleanup pressure without requiring a separate queue dashboard service.
Daemon Scheduler And Queue Controls
Scheduler and queue controls are admin-token gated. They operate on the same data/state/scheduler/state.tsv and data/state/queue/state.tsv files that object_daemon.py already polls, so the HTTP API can manage work without introducing Celery, Redis, Flower, or a second queue service.
These routes redact task/message payloads by default. Pass include_payload=true only on trusted operator screens.
GET /daemon/scheduler/tasks?status=active&limit=100&offset=0
POST /daemon/scheduler/tasks
PATCH /daemon/scheduler/tasks/{task_id}
DELETE /daemon/scheduler/tasks/{task_id}
GET /daemon/queue/messages?status=pending&queue_name=default&limit=100&offset=0
POST /daemon/queue/messages
PATCH /daemon/queue/messages/{message_id}
DELETE /daemon/queue/messages/{message_id}
Authorization: Token <token>
Create one scheduled task:
{
"object_id": "system_dashboard",
"method": "POST",
"type": "onetime",
"schedule": "2026-07-01T12:00:00Z",
"payload": {
"refresh": true
}
}
Response:
{
"status": "ok",
"task": {
"id": "018ff3f4-5f80-4df0-8e25-bcf6ad6fda01",
"object_id": "system_dashboard",
"method": "POST",
"type": "onetime",
"schedule": "2026-07-01T12:00:00Z",
"status": "active",
"next_run": 1782907200,
"payload_present": true
}
}
Patch examples:
{"status": "paused"}
{"next_run": "2026-07-01T13:00:00Z"}
Enqueue one message:
{
"object_id": "system_dashboard",
"method": "POST",
"queue_name": "default",
"priority_level": 5,
"payload": {
"refresh": true
}
}
Response:
{
"status": "ok",
"message": {
"id": "2de66c27-149b-475b-a6f0-0c08a8d850f5",
"queue_name": "default",
"message": {
"object_id": "system_dashboard",
"method": "POST",
"payload_present": true
},
"priority_level": 5,
"status": "pending"
}
}
Queue patch actions:
{"action": "cancel"}
{"action": "retry"}
These controls are for trusted operators. They do not change the rule that untrusted object execution still needs a stronger worker boundary, quotas, and permission enforcement before public signup is safe.
Rate Limits
When DBBASIC_RATE_LIMIT_REQUESTS is set above zero, the server rate-limits non-health traffic before reading request bodies or running object code. Plain GET /health is excluded so load balancers and uptime checks keep working under pressure.
The current public server uses a valid admin token as the rate-limit identity for admin requests. Other requests use the client IP address. Proxy headers such as X-Forwarded-For are ignored unless DBBASIC_RATE_LIMIT_TRUST_PROXY_HEADERS is enabled on a server that is only reachable through a trusted reverse proxy.
Limit response:
429 Too Many Requests
Retry-After: 30
{
"status": "error",
"error": "Rate limit exceeded",
"retry_after": 30,
"limit": 1000,
"window_seconds": 60
}
Identity
Scroll and gateway code can inspect the subject the object server will use for permission checks:
GET /identity
Authorization: Token <token>
Response:
{
"status": "ok",
"subject": {
"user_id": "7",
"account_id": "acme",
"roles": ["sales"],
"subscriptions": ["pro"],
"authenticated": true
},
"auth": {
"method": "trusted_headers",
"trusted_headers_enabled": true,
"trusted_headers_present": true
},
"permissions": {
"enforcement_enabled": true,
"enforcement_requested": true,
"enforcement_blocked": false,
"audit_enabled": true
}
}
Current auth methods are:
anonymous- no trusted identity was accepted.admin_token-Authorization: Token <DBBASIC_ADMIN_TOKEN>or Bearer matched
the server admin token.
session_token-Authorization: Token <session-token>or Bearer matched an
active file-backed DBBASIC identity session.
trusted_headers-DBBASIC_PERMISSION_TRUST_HEADERS=trueand at least one
X-DBBASIC-* identity header was present.
Trusted identity headers are ignored unless explicitly enabled. This keeps the current staging server safe while giving future login/session gateways and Scroll one stable endpoint for the active account, user, roles, and subscriptions.
Identity Accounts And Users
The server has a small file-backed identity registry so sessions can be minted from known users instead of every client inventing its own subject payload. These routes are admin-gated.
Accounts are stored under data/identity/accounts.tsv:
GET /identity/accounts
Authorization: Token <admin-token>
POST /identity/accounts
Authorization: Token <admin-token>
Content-Type: application/json
{
"account_id": "acme",
"name": "Acme Corp",
"subscriptions": ["pro"]
}
Users are stored under data/identity/users.tsv:
GET /identity/users
Authorization: Token <admin-token>
GET /identity/users?account_id=acme
Authorization: Token <admin-token>
POST /identity/users
Authorization: Token <admin-token>
Content-Type: application/json
{
"user_id": "u_7",
"account_id": "acme",
"email": "alice@example.com",
"display_name": "Alice",
"roles": ["sales"],
"subscriptions": ["team"]
}
Single-record reads are:
GET /identity/accounts/acme
GET /identity/users/u_7
status can be active or disabled. Disabled accounts and users cannot mint new sessions.
User Passwords
Users can have one password credential for browser/password login. Hashes are stored separately from user records under data/identity/credentials.tsv (scrypt, owner-only file permissions), so user payloads never include credential material. Both routes are admin-token gated, and the admin alias form works through the reverse proxy for Scroll:
POST /identity/users/{user_id}/password
POST /admin/identity/users/{user_id}/password
Authorization: Token <admin-token>
Content-Type: application/json
{"password": "at least 8 characters"}
Response returns only user_id, operation (created or replaced), and updated_at — never the password or hash. DELETE on the same paths removes the credential:
DELETE /identity/users/{user_id}/password
DELETE /admin/identity/users/{user_id}/password
Authorization: Token <admin-token>
Unknown users return 404. Passwords must be 8 to 1024 characters.
Identity Sessions
The server can mint scoped subject tokens for Scroll, gateways, or controlled apps. Sessions are stored under data/identity/sessions.tsv. Only token hashes are written to disk; the raw token is returned once at creation time.
Create a session:
POST /identity/sessions
Authorization: Token <admin-token>
Content-Type: application/json
{
"user_id": "7",
"account_id": "acme",
"roles": ["sales"],
"subscriptions": ["pro"],
"label": "scroll desktop",
"ttl_seconds": 86400
}
Response:
{
"status": "ok",
"session": {
"session_id": "9d4fe8bd-6859-43ef-8f83-f7063c54f7bc",
"user_id": "7",
"account_id": "acme",
"roles": ["sales"],
"subscriptions": ["pro"],
"label": "scroll desktop",
"created_at": "2026-06-30T18:00:00Z",
"expires_at": "2026-07-01T18:00:00Z",
"revoked_at": null,
"active": true
},
"token": "returned-once"
}
If user_id already exists in data/identity/users.tsv, omitted account_id, roles, and subscriptions are filled from the registered user and account. This lets Scroll or a login gateway mint a session without duplicating policy metadata in every request. If DBBASIC_REQUIRE_KNOWN_IDENTITY_USERS=true, the server rejects sessions for unknown users.
For a non-admin login gateway or local trusted client, the current-session route can mint a session for an existing active user when DBBASIC_ENABLE_SESSION_LOGIN=true:
POST /identity/session
Authorization: Token <session-login-token>
Content-Type: application/json
{
"user_id": "7",
"label": "scroll desktop",
"ttl_seconds": 86400
}
This route always requires the user to exist in data/identity/users.tsv. It also requires DBBASIC_SESSION_LOGIN_TOKEN; this token is separate from the admin token so a login gateway can mint sessions without broad admin access. It accepts only user_id, label, and ttl_seconds; caller-supplied account_id, roles, or subscriptions are rejected. The session subject is loaded from the registered user and account so a login request cannot grant itself stronger permissions. This is a session-mint primitive, not password authentication.
Password Login
For direct password authentication, the same route accepts a credential login when DBBASIC_ENABLE_PASSWORD_LOGIN=true. No Authorization header is required; the password is the credential:
POST /identity/session
Content-Type: application/json
{"email": "alice@example.com", "password": "correct horse battery"}
The body must contain exactly one of email or user_id, plus password, and may include label and ttl_seconds. Role, account, and subscription overrides are rejected. The password is verified against the scrypt hash in data/identity/credentials.tsv set through the password routes above. Email matching is case-insensitive and must resolve to exactly one active user.
Success returns 201 with the same session-plus-one-time-token shape as other session mints. Any failure — unknown user, wrong password, disabled user or account — returns a uniform 401 Invalid credentials after a short fixed delay, so callers cannot probe which accounts exist. The global rate limiter also applies. Password login availability (enabled flag plus at least one active user) counts as a non-admin identity path for permission enforcement readiness.
Repeated failures lock the identifier: after DBBASIC_LOGIN_LOCKOUT_ATTEMPTS failed attempts (default 5) within DBBASIC_LOGIN_LOCKOUT_WINDOW_SECONDS (default 900), further attempts — even with the correct password — return 429 Too many failed attempts (the browser form redirects to /login?error=locked). A successful login resets the count; the lock clears on its own when the window passes. Locked attempts are recorded as login_locked ops events rather than new failures, so hammering a locked identifier does not extend the lock. Set attempts to 0 to disable. The counters are the login_failed rows in the ops event feed — GET /admin/ops?kind=auth&identifier=... shows exactly why an identifier is locked.
List sessions:
GET /identity/sessions
Authorization: Token <admin-token>
Revoke a session:
DELETE /identity/sessions/{session_id}
Authorization: Token <admin-token>
Inspect the current session with a session token:
GET /identity/session
Authorization: Token <session-token>
Revoke the current session with the same token:
DELETE /identity/session
Authorization: Token <session-token>
The current-session route does not accept the admin token as a user session. It is for Scroll, app clients, and login gateways that need a stable non-admin session lifecycle.
Session Cookies
Browser clients can present the session token in a dbbasic_session cookie instead of an Authorization header. Cookie tokens resolve to the same session subject for permission checks, /identity, and the current-session routes. An Authorization header always takes precedence over the cookie, and the admin token is never accepted from a cookie.
Cookie-authenticated non-GET requests are checked against the request origin: when an Origin (or Referer) header is present and its host does not match the request Host, the request is rejected with 403 Cross-origin cookie request rejected. Together with SameSite cookie attributes set at login, this is the server's CSRF posture for cookie sessions. Header-authenticated requests are not origin-checked.
Browser Login Pages
When DBBASIC_ENABLE_PASSWORD_LOGIN=true, the server serves a built-in browser login flow:
GET /login
GET /login?next=/dashboard
POST /login (application/x-www-form-urlencoded: email, password, next)
POST /logout
GET /login renders a minimal HTML sign-in form; an active session redirects away instead of re-rendering. POST /login verifies the password, mints a session, sets the dbbasic_session cookie (HttpOnly, SameSite=Lax, Path=/, Secure unless DBBASIC_COOKIE_SECURE=false for plain-HTTP local development), and redirects with 303 to the sanitized next path (same-origin absolute paths only; anything else falls back to /). Failures redirect back to /login?error=1 after the same fixed delay as JSON password login, without revealing whether the email exists. JSON bodies are rejected; API clients should use POST /identity/session. POST /logout revokes the cookie session, clears the cookie, and redirects to /login. The login and logout routes never accept or mint admin tokens.
Self-Service Signup
Off by default. DBBASIC_ENABLE_SIGNUP=true opens it, and DBBASIC_ENABLE_PASSWORD_RESET=true opens password reset (useful on its own for operator-created users). Both are browser forms beside /login:
GET /signup form: email (no password, no name)
POST /signup -> 303 /signup?sent=1
GET /verify?token=... form: optional name, password, "Confirm my email"
POST /verify (token, password, name) -> sets them, signs the new user in, 303 to
DBBASIC_AUTH_LANDING_PATH (default /)
GET /reset form: email
POST /reset -> 303 /reset?sent=1
GET /reset/confirm?token=... form: new password
POST /reset/confirm (token, password) -> 303 /login?reset=1
Signup refuses to run (403 page, reasons listed under identity in GET /admin/capabilities as signup_blockers) until all of these hold:
DBBASIC_ENABLE_PASSWORD_LOGIN=true, or a new user could never sign in;- permission enforcement is on, or a stranger's account would not be limited
to their own data;
- no permission rule gives the
registeredprincipal anything without a
collection, object or row filter. The starter policy's "signed-in users can read and run objects" is such a rule: right for invited users, wrong once anyone with an email address is "registered";
- email can go out:
DBBASIC_SMTP_MODEconfigured, theapp-emailpackage
installed, and the email_enabled feature flag not off;
DBBASIC_PUBLIC_URLis this server'shttps://address. Emailed links are
built from it, never from the request's Host header, which would let anyone aim a reset link at their own domain.
Reset needs the same except the policy and enforcement checks.
What happens:
- A signup creates its own account and a user with status
pending, with no
password and no name, which, like disabled, cannot sign in or hold a session. The form takes neither because a stranger could type someone else's address with a password or name of their own: the owner who clicked the link would have confirmed the stranger's login. The mailbox holder chooses both on the page the emailed link opens, and only then is the user active. A confirm link only ever completes a pending user: it never changes the password of an account already in use. Signing up again for an address that has not confirmed sends a fresh link (and retires the old one). A password posted to /signup anyway is ignored. Signing in to a pending user fails like any wrong password; the login page points at the emailed link.
- Links are single use, expire (confirmation 48 hours, reset 1 hour), and a
new link retires the previous one. Only their SHA-256 is stored, in data/identity/email_tokens.tsv (owner-only). Used and expired rows are dropped on every write, so the file holds at most one row per user and purpose.
- Opening a link only shows a form; the
POSTuses it. Mail scanners open
links by themselves and must not confirm an address or reset a password.
- The server's own pages send
<meta name="referrer" content="strict-origin">:
only the origin ever goes in a Referer, so the ?token= in /verify and /reset/confirm links never leaks. (no-referrer made browsers send Origin: null with a form post, which the same-origin check refuses.)
DBBASIC_AUTH_LANDING_PATHsets where a browser goes after confirming an
address, and after a password sign-in that had no next: a path on this site starting with a single /, default /. A value that is not such a path is ignored and listed in signup_blockers.
- The forms never say whether an address has an account. A signup for a taken
address emails that address "you already have an account" with sign-in and reset links; a reset for an unknown address sends nothing. Both answer the form the same way as the ordinary case.
- A reset sets the new password, revokes every session the user had, and ends
the login lockout's run of failures. Disabled users are never sent a link.
- Limits, all failing closed: 5 signups and 10 reset requests per IP per hour,
and 3 emails per address per hour. Cross-site form posts are refused.
Ops events (GET /admin/ops?kind=auth): signup_created, signup_pending, signup_exists, email_verified, password_reset_requested, password_reset.
Session tokens normally only supply the active subject used by permission checks. Admin-token gates remain admin-token-only by default. When a deployment sets DBBASIC_ENABLE_SESSION_ADMIN_GATES=true, active sessions whose subject has one of the policy admin roles can pass the same admin gate. The explicit source-write gate is still separate and must also be enabled for source update or rollback routes.
Permissions Policy
The public server now has a persisted permission policy shape. The endpoints are admin-gated while broader login and account management mature.
GET /permissions/policy
Authorization: Token <token>
Response:
{
"status": "ok",
"policy": {
"access_mode": "role_based",
"roles": {},
"user_roles": {},
"rules": [],
"admin_roles": ["admin", "superuser"]
}
}
Update:
PUT /permissions/policy
Authorization: Token <token>
Content-Type: application/json
{
"policy": {
"access_mode": "role_based",
"roles": {"sales": {"label": "Sales"}},
"user_roles": {"7": ["sales"]},
"rules": [
{
"effect": "allow",
"principal": "role:sales",
"actions": ["read"],
"collection": "contacts",
"row_filter": {"owner_id": "$user_id"}
}
],
"admin_roles": ["admin"]
}
}
The policy is stored under data/permissions/policy.json. Missing policy files load as a conservative role_based policy with no grants.
Permissions Status
Scroll and operators can inspect whether the active identity and permission configuration is ready for enforcement:
GET /permissions/status
Authorization: Token <admin-token>
Response:
{
"status": "ok",
"permissions": {
"enforcement_enabled": false,
"enforcement_requested": false,
"enforcement_blocked": false,
"allow_unready_enforcement": false,
"audit_enabled": true,
"trusted_headers_enabled": false,
"require_known_identity_users": true,
"admin_token_configured": true,
"session_login_enabled": true,
"session_login_token_configured": true
},
"identity": {
"accounts": {"count": 1, "active": 1, "disabled": 0},
"users": {"count": 3, "active": 3, "disabled": 0},
"sessions": {"count": 2, "active": 1, "revoked": 1}
},
"policy": {
"valid": true,
"policy_file_exists": true,
"access_mode": "role_based",
"rules_count": 4,
"allow_rules": 3,
"deny_rules": 1
},
"readiness": {
"can_enable_enforcement": true,
"blockers": []
},
"warnings": []
}
This endpoint is intentionally read-only. DBBASIC_ENABLE_PERMISSION_ENFORCEMENT=true requests enforcement, but the server only makes enforcement_enabled effective when readiness.can_enable_enforcement is true. If readiness is blocked, enforcement_requested is true, enforcement_enabled is false, and enforcement_blocked is true. The explicit recovery/test override is DBBASIC_ALLOW_UNREADY_PERMISSION_ENFORCEMENT=true.
Readiness currently requires an admin recovery token, a valid policy, an available non-admin identity path for identity-gated modes, and at least one allow grant for role_based policy. The accepted identity paths are trusted proxy headers, guarded session login for existing users, or an already-active DBBASIC session.
Permissions Check
Scroll and admin tools can ask the server to evaluate one permission decision. This is useful for previewing draft rules and for future "test as role" screens.
POST /permissions/check
Authorization: Token <token>
Content-Type: application/json
{
"subject": {
"user_id": "7",
"account_id": "customer-acme",
"roles": ["sales"],
"subscriptions": ["pro"]
},
"action": "read",
"collection": "contacts",
"object_id": null,
"record": null
}
If the request includes a policy object, the server evaluates against that inline policy without saving it. Otherwise it evaluates against the persisted policy. The optional now field accepts an ISO timestamp for previewing temporary access windows.
Response:
{
"status": "ok",
"decision": {
"allowed": true,
"reason": "sales reps only see own contacts",
"code": "allowed",
"http_status": 200,
"row_filter": {"owner_id": "$user_id"},
"fields": null,
"denied_fields": []
}
}
When a paid entitlement is missing, the decision can include:
{
"allowed": false,
"reason": "subscription required",
"code": "payment_required",
"http_status": 402,
"row_filter": {},
"fields": null,
"denied_fields": []
}
Permission Route Enforcement
Permission policy checks can be applied to object and collection-record routes when explicitly requested:
DBBASIC_ENABLE_PERMISSION_ENFORCEMENT=true
The request becomes effective only when /permissions/status reports no readiness blockers, unless DBBASIC_ALLOW_UNREADY_PERMISSION_ENFORCEMENT=true is also set. When enforcement is effective, denied route checks return the http_status, reason, and code from the permission decision before object source, state, logs, versions, execution, or collection-record data work runs.
Audit-only mode records the same decisions without changing responses:
DBBASIC_ENABLE_PERMISSION_AUDIT=true
Audit entries are written as JSON lines under:
data/permissions/audit.jsonl
Trusted identity headers are off by default and should only be enabled behind a trusted auth gateway or reverse proxy:
DBBASIC_PERMISSION_TRUST_HEADERS=true
Supported headers are X-DBBASIC-User-Id, X-DBBASIC-Account-Id, X-DBBASIC-Roles, and X-DBBASIC-Subscriptions.
Collection record read routes use the read action. Collection record write routes use create, update, and delete. In enforcement mode the server applies row filters before pagination, evaluates detail and write requests against the selected record, blocks owner-changing updates that would escape the allowed row filter, and redacts fields / denied_fields from returned records. Audit-only mode can log write decisions, but it does not grant mutation access without the admin token.
Operators and Scroll can read recent audit entries through an admin-gated endpoint:
GET /permissions/audit?limit=100
Authorization: Token <token>
Optional filters:
actionobject_idcollectionallowed=true|falseenforced=true|false
Response:
{
"status": "ok",
"entries": [
{
"timestamp": "2026-06-29T00:00:00Z",
"method": "GET",
"object_id": "site_home",
"collection": "site",
"action": "execute",
"enforced": false,
"decision": {"allowed": false, "code": "forbidden"}
}
],
"count": 1
}
Optimistic Concurrency (_rev / If-Match)
Record updates are last-write-wins by default. To make a read-then-write safe against a concurrent writer, send back the _rev you read.
Reading a rev. A single-record read returns it as a sibling of record, never a field inside it:
{"status": "ok", "collection": "tasks", "record": {"id": "t1", "status": "open"},
"_rev": "a1b2c3…"}
A list read returns a parallel revs map, keyed by record id, covering exactly the rows in the returned window:
{"status": "ok", "collection": "tasks",
"records": [{"id": "t1", "status": "open"}, {"id": "t2", "status": "open"}],
"count": 2, "total": 57, "limit": 100, "offset": 0,
"revs": {"t1": "a1b2c3…", "t2": "d4e5f6…"}}
It is a map rather than a _rev on each row so the record shape stays a contract: a rev must never collide with a schema field, and must never be echoed back on write.
Using one. Send If-Match: <rev> (or an expected_rev body field) on PUT. The rev is compared inside the write lock, before validation:
- match → the write proceeds
- mismatch → 409, and nothing is written
PUT /collections/tasks/records/t1
If-Match: a1b2c3…
{"status": "assigned", "assigned_to": "agent-A"}
Why it exists — the claim. Two agents both read a task as open and both write assigned. Without a precondition both succeed and whoever lands second silently overwrites the first; both believe they hold it and neither can tell. With If-Match, the second finds the row changed, gets a 409, re-reads, and moves on. The rev captures "the record I read is still the record on disk", which necessarily includes every field — so no per-field guard is needed.
Because the revs map ships with the list, an agent can find work and claim it without re-reading each candidate first.
Notes.
- Omitting
If-Matchis still valid and still last-write-wins. The
precondition is opt-in per write, never mandatory.
- The rev is computed over the full stored record, before any
field-level permission trimming. A caller who cannot see a field still gets a rev that depends on it — which only ever fails closed, and discloses nothing about the value.
DBBASIC_ENABLE_CONCURRENCY=falseturns the feature off: preconditions
are ignored (never a 409) and revs is omitted from list payloads.
Object List
GET /objects?format=json
Authorization: Token <token>
Response:
{
"status": "ok",
"objects": [
{
"object_id": "basics_counter",
"path": "basics/counter.py",
"owner": "system"
}
],
"count": 1
}
Clients should accept either a top-level list or an object with an objects field. New server code should prefer the object form above.
Admin Object Inspection
/objects remains the runtime surface: object execution and public object routes live there. Scroll and operator dashboards should use the admin inspection surface so staging can expose read-only object metadata without opening broad object execution routes at the reverse proxy.
GET /admin/objects
POST /admin/objects
Authorization: Token <token>
GET returns the same response shape as GET /objects?format=json. POST is the admin/operator alias for POST /objects; it creates a new object without requiring the reverse proxy to expose the broader runtime /objects collection route. Creation still requires DBBASIC_ENABLE_SOURCE_WRITES=true and the admin gate.
GET /admin/objects/{object_id}
GET /admin/objects/{object_id}?metadata=true
GET /admin/objects/{object_id}?source=true&format=json
PUT /admin/objects/{object_id}?source=true
POST /admin/objects/{object_id}/execute
GET /admin/objects/{object_id}?state=true
GET /admin/objects/{object_id}?logs=true&format=json&limit=100
GET /admin/objects/{object_id}?versions=true&limit=10
GET /admin/objects/{object_id}?version=1
GET /admin/objects/{object_id}?source_changes=true&limit=100
GET /admin/objects/{object_id}?changes=true&limit=100
GET /admin/objects/{object_id}?files=true
GET /admin/objects/{object_id}?file=report.txt
Authorization: Token <token>
If no inspection query is supplied, the server returns metadata. The admin inspection surface never executes the object. PUT ...?source=true is the admin/operator alias for source edits and uses the same DBBASIC_ENABLE_SOURCE_WRITES plus admin gate as the runtime source update route. POST .../execute is the admin/operator execution route and requires the admin gate before running object code. It accepts a JSON body:
{
"method": "GET",
"payload": {}
}
method may be GET, POST, PUT, or DELETE; payload must be a JSON object and defaults to {}. Unsupported query flags return a 400 response so a client cannot accidentally turn an operator view into an execution endpoint.
Admin Changes
Scroll and operator dashboards can read a single normalized activity stream instead of querying every changelog separately.
GET /admin/changes?kind=file&object_id=site_home&limit=100&offset=0
Authorization: Token <token>
Supported filters:
kind:source,file,record, orpackageobject_id: source and file changes for one objectcollection: record changes for one collectionrecord_id: record changes for one recordpackage_id: package changes for one packagefile: file changes for one object-owned file
Response:
{
"status": "ok",
"changes": [
{
"kind": "file",
"change_id": "123e4567-e89b-42d3-a456-426614174000",
"timestamp": "2026-01-01T00:00:00+00:00",
"action": "file_update",
"actor": "api",
"summary": "File updated: reports/out.csv",
"correlation_id": "123e4567-e89b-42d3-a456-426614174001",
"target": {
"object_id": "site_home",
"file_name": "reports/out.csv",
"file_size": 42
},
"change": {}
}
],
"count": 1,
"total": 1,
"limit": 100,
"offset": 0,
"has_more": false,
"filters": {
"kind": "file",
"object_id": "site_home",
"collection": null,
"record_id": null,
"package_id": null,
"file": "reports/out.csv"
}
}
Each entry keeps the original changelog payload under change. Clients should render kind, timestamp, actor, summary, target, and correlation_id first, then expand change for detail views.
Admin File Inspection
Object-owned files live under the local runtime data directory:
data/files/{object_id}/
The compatibility object route can still list or download one object's files, but Scroll and operator dashboards should prefer the admin file inspection surface so staging can expose read-only file posture without exposing broad object execution routes.
GET /admin/files
GET /admin/files?object_id=site_home
GET /admin/files?object_id=site_home&file=report.txt
GET /admin/files/{object_id}
GET /admin/files/{object_id}?file=report.txt
Authorization: Token <token>
GET /admin/files returns a paginated cross-object inventory:
{
"status": "ok",
"files": [
{
"object_id": "site_home",
"name": "report.txt",
"size": 1200,
"modified": 1760000000.0
}
],
"count": 1,
"total": 1
}
Supported query parameters:
object_idnarrows the inventory to one object.limitdefaults to100and is capped at1000.offsetdefaults to0.filedownloads one object-owned file and requires an object id.
Read routes are admin-token gated. Write routes are additionally disabled unless DBBASIC_ENABLE_FILE_WRITES=true is set. Public staging should leave file writes off until permissions, quota, and review policy are intentionally enabled.
Create one object-owned file:
POST /admin/files/{object_id}
Authorization: Token <token>
Content-Type: application/json
{
"name": "reports/monthly.txt",
"content_base64": "aGVsbG8="
}
Overwrite an existing object-owned file:
PUT /admin/files/{object_id}
Authorization: Token <token>
Content-Type: application/json
Delete one object-owned file:
DELETE /admin/files/{object_id}?file=reports/monthly.txt
Authorization: Token <token>
Successful write responses return the file metadata, operation, and correlation id:
{
"status": "ok",
"message": "File created: reports/monthly.txt",
"object_id": "site_home",
"operation": "created",
"file": {
"object_id": "site_home",
"name": "reports/monthly.txt",
"size": 5,
"modified": 1760000000.0
},
"correlation_id": "07fb51ef-1a0d-43dd-a82f-2ec756b7cd90"
}
POST rejects existing files with 409. PUT overwrites. Empty names, absolute paths, null bytes, and .. traversal are rejected with 400. File content is capped by DBBASIC_MAX_OBJECT_FILE_BYTES and the request body is still capped by DBBASIC_MAX_REQUEST_BYTES.
Admin Ops Events
The operational event feed records object execution failures and auth activity in one admin-gated stream:
GET /admin/ops
GET /admin/ops?limit=100
GET /admin/ops?kind=execution_error
GET /admin/ops?kind=auth&event=login_failed
GET /admin/ops?identifier=alice@example.com
Authorization: Token <token>
Events are newest-first. execution_error entries carry object_id, method, error_type, a truncated message, the caller's user_id, and the correlation_id linking back to source versions and object logs. auth entries carry event (login_succeeded, login_failed, logout, session_minted), the attempted identifier on failures, user_id on successes, auth_method, and session label. Rows never contain passwords, tokens, or hashes. The feed lives in data/ops/events.jsonl, capped to the most recent 5000 rows. Failed-login rows are queryable per identifier, which is the data the future login-lockout gate will read.
MCP Endpoint
AI agents can operate the server through MCP (Model Context Protocol) instead of raw HTTP. The endpoint speaks JSON-RPC 2.0 over HTTP POST (the Streamable HTTP transport):
POST /api/mcp
Authorization: Token <admin-token-or-admin-role-session-token>
Content-Type: application/json
Supported methods: initialize (protocol negotiation, returns an mcp-session-id header), tools/list, tools/call, and notifications/* (acknowledged with 202). The gate is the same admin gate as the rest of the admin surface: the deployment token always works, and an admin-role session token works when DBBASIC_ENABLE_SESSION_ADMIN_GATES=true.
Register with Claude Code:
claude mcp add dbbasic --transport http \
--url https://your-host/api/mcp \
--header "Authorization: Bearer YOUR_SESSION_TOKEN"
The tool catalog wraps the existing admin surface — objects (list/read/create/update-source/execute, state, logs, metadata, changes), collections and records (list/get/create/update/delete), schemas (get/update/rollback), cross-collection search (global_search), the unified change history, and admin status. Every tool call is dispatched back through the server's own routing with the caller's credentials, so tools inherit the same gates, capability flags (source writes, package installs), permission checks, audit trail, and correlation ids as external HTTP callers. Tool results carry the underlying http_status plus the route's JSON response, and failures set isError.
Give each agent its own identity instead of the deployment token: create a user (for example agent-claude) with the admin role, mint a labeled session, and connect with that bearer token, so /admin/changes distinguishes agent actions from operator actions.
Service Keys (Per-User AI Provider Keys)
Users store API keys for AI providers so the server can call providers on their behalf. The contract is write-only: set a key, list which services have one, delete one — key material never appears in any response, never lives in record collections, and stays out of portable backups (it sits beside credentials.tsv in the owner-only identity directory).
GET /identity/users/{user_id}/service-keys -> {"services": [{"service", "created_at", "updated_at"}]}
PUT /identity/users/{user_id}/service-keys {"service": "anthropic", "key": "sk-..."}
DELETE /identity/users/{user_id}/service-keys/{service}
A signed-in user manages their own keys (session token or cookie; cookie writes require a same-origin request); the admin gate covers operator use. Set/remove events land in the ops feed without key material.
AI Chat (The Shell's Brain)
One conversation turn against an AI provider, using the caller's stored service key, with optional MCP tool calling:
POST /api/ai/chat
Authorization: Bearer <session-token> (or the session cookie)
{"message": "find my notes about the flywheel",
"model": "anthropic:claude-haiku-4-5",
"tools": ["global_search", "get_record"],
"max_rounds": 6}
Models are named service:model; the service picks which stored key is used (anthropic, openai). tools names a subset of the MCP tool catalog — handing small models only a few tools keeps their context small, and the subset is per-request configuration. When the model calls a tool, the server dispatches it through its own routing with the caller's credentials, so the AI can do exactly what the caller could do directly — permission checks, row filters, and the audit trail all apply.
Response: {"reply", "model", "rounds", "tool_calls": [{name, arguments, http_status}], "usage": {input_tokens, output_tokens}}, plus "truncated": true when the round limit stopped a tool loop.
Requires DBBASIC_ENABLE_AI_CHAT=true and a signed-in session; callers without a stored key for the model's service get a pointed 400. Timeout per provider round: DBBASIC_AI_TIMEOUT_SECONDS (default 60); default model: DBBASIC_AI_DEFAULT_MODEL.
Text-to-Speech
POST /api/tts
Authorization: Bearer <session-token> (or the session cookie)
{"text": "one note matches", "voice": "en-us", "engine": "local"}
Response: audio bytes (audio/wav for engine: "local", audio/mpeg for engine: "openai") on success, or {"status": "error", "error"} on failure. engine is optional ("local" default, or "openai" — uses the caller's stored openai service key, no engine ever silently falls back to the other). Requires DBBASIC_ENABLE_TTS=true and a signed-in session. text capped at 800 characters (413 beyond). DBBASIC_TTS_CLOUD_TIMEOUT_SECONDS bounds the cloud path (default 30). See docs/shell-and-ai.md's "Voice" section for engine details and caching.
Speech-to-Text
POST /api/stt
Authorization: Bearer <session-token> (or the session cookie)
Content-Type: audio/webm
<raw audio bytes>
Response: {"status": "ok", "text": "..."} or the usual error shape. Body is raw audio bytes (not JSON) in whatever format Content-Type says. Cloud-only — no local engine — calls OpenAI's transcription API with the caller's stored openai service key. Requires DBBASIC_ENABLE_STT=true (off by default even when TTS is on: this costs money per utterance, not per occasional reply) and a signed-in session. Capped at 10MB per clip (413 beyond). DBBASIC_STT_TIMEOUT_SECONDS bounds the call (default 30).
Reader
POST /api/read
Authorization: Bearer <session-token> (or the session cookie)
{"url": "https://example.com/article"}
Response: {"status": "ok", "title", "text", "links": [{n, label, href}], "final_url", "truncated"} or the usual error shape. Fetches server-side, strips HTML to readable text, numbers links in document order. SSRF-hardened (every hostname, including redirect hops, resolved and checked before the socket opens; http/https only; fails closed on any resolution ambiguity) — see object_reader.py. Requires DBBASIC_ENABLE_READER=true and a signed-in session. Also offered as the read_page MCP tool for /api/ai/chat — see docs/shell-and-ai.md's "Reading the Web" section.
Files as a Folder (WebDAV)
Your own files (the files collection, the same ones /api/files serves) as a folder any desktop can mount: Linux (davfs2, or the file manager's "Connect to Server"), macOS Finder, Windows.
/dav/ the root: holds one folder, files/
/dav/files/ your files, one entry per file record
/dav/files/{name} one file
Sign in with any user name and one of your API keys (dbk_..., from /identity/users/{user_id}/api-keys) as the password, over HTTP Basic; Authorization: Bearer dbk_... works too. Account passwords and session tokens are refused (a password here would be a login without the login's rate limits), and cookies are ignored, so a browser session cannot write here from another site.
| Method | Does |
|---|---|
OPTIONS | DAV: 1, no sign-in needed |
PROPFIND | lists (Depth 0, 1 or infinity; the tree is two levels) |
GET, HEAD | a file (single byte ranges, ETag, If-None-Match); a folder URL gives an HTML index |
PUT | creates a file, or replaces the bytes of the one with that name (same record) |
DELETE | removes the record and its bytes |
MOVE | renames (Overwrite: F refuses to replace; a case-only rename is a rename) |
COPY | a new file with the same bytes |
PROPPATCH | 207 with 403 for every property: none are writable |
MKCOL, LOCK, UNLOCK | 405: there are no folders and no locks |
Writes pass the same gates as /api/files and the collection routes (quota, permission policy, before-write hooks). If-Match and If-None-Match: * make a PUT, DELETE or MOVE conditional (412 when they do not hold). Only the caller's own files are listed, even ones others can read. Duplicate filenames show as name (2).ext, oldest first; the records are not renamed. Files are served with Content-Security-Policy: sandbox, and as attachments unless they are a safe inline type.
Without locks the server is WebDAV class 1: davfs2 needs use_locks 0, and Finder mounts it read-only.
Requires DBBASIC_ENABLE_WEBDAV=true and DBBASIC_ENABLE_USER_FILES=true. A PUT may be larger than DBBASIC_MAX_REQUEST_BYTES, up to DBBASIC_WEBDAV_MAX_FILE_BYTES (default 50MB, read into memory whole), and the user files quota still applies (507 when a replacement would exceed it, 413 for a new file).
Mail Sync (IMAP, Inbound)
New mail in a person's own IMAP mailboxes, copied into their inbox (app-messaging's message_threads, messages, message_recipients). Package app-mail-sync; pure logic in object_mail.py, the I/O in the scheduled object system_mail_sync.
Turning it on:
- The operator sets
DBBASIC_ENABLE_MAIL_SYNC=true. Off otherwise; the
pass then does nothing and its report names the variable. A feature_flags row mail_sync_enabled = off stops it again without a redeploy.
- Install
app-messaging, thenapp-mail-sync(it declares its schedule,
every two minutes, and its home-page count).
- The person opens
/mail/accounts, adds the account (server, port,ssl
or starttls, user name, optional folders) and saves its password there. The password goes to their identity vault as the service imap-<account id> (PUT /identity/users/{user_id}/service-keys); it is never a record field, and the page only shows whether it is set.
What it does and does not do:
- Folders are opened read-only (EXAMINE) and messages fetched with
BODY.PEEK[], so nothing is marked read on the server. is_read is the server's \Seen flag when the message was copied. Messages are chosen by UID, so mail already read in another program is still copied.
- The first sync of a folder takes the newest 200 messages of the last 30
days. Each pass then copies at most 50 messages and 25 MB per account; a message over 10 MB is copied as headers with a line saying so. Every connection has a 30 second timeout.
- Blank folders means INBOX plus the Sent folder (found by its
\Sent
attribute), written back to the account. Mail in Sent, or from the account's own address, is outbound.
- Replies are threaded by
In-Reply-ToandReferences, only among the
same person's messages, never by subject. The same message in two people's mailboxes is two rows.
- Folder, UID,
Referencesand the list headers (List-Unsubscribe,
List-Unsubscribe-Post, List-Id, Precedence) are kept in mail_synced_messages. They are stored, not acted on: the server opens no URL from a message and sends no mail.
- A failure (refused login, unreachable server, missing folder) is written
on the account as sync_attempts and sync_error; the account then waits longer between tries (2 minutes doubling to 30), and after three failures in a row it is counted on the home page. Setting sync_attempts to 0, or saving the password again, tries at once.
- The server connects only to public addresses unless
DBBASIC_MAIL_SYNC_ALLOW_PRIVATE_HOSTS=true, so a member cannot use an account to probe the server's own network. security: plain (no TLS) is allowed only to this machine itself.
How big it gets: one messages row, its recipient rows and one mail_synced_messages row per message that arrives after the first window, and nothing twice (every id is derived from the owner, the account and the Message-ID). Nothing is trimmed, so the inbox grows as the mailbox does, and so does the change log for those collections unless DBBASIC_CHANGE_LOG_RETENTION_DAYS is set. An account with nothing new writes nothing; its last_synced_at is refreshed at most hourly.
Not built: sending, AI triage, unsubscribing, attachments (named at the end of the body, not copied), and following flag changes after a message was copied.
Backups
Runtime backups are tar/gzip archives of the whole data directory. They contain everything — records, identity, credentials, service keys — so the surface is strictly admin-gated (admin token or admin-role session; never public):
GET /admin/backups -> {backups: [{id, created_at, size, kind, scope}], count, schedule}
POST /admin/backups -> {backup: {id, created_at, size, kind, scope}} (creates one now, 201)
GET /admin/backups/{id}/download -> the archive bytes (application/gzip, attachment)
kind is manual (created on demand), package (auto restore point before a package install; scope is the package), or restore-point. The /admin/status capabilities.backups block reports {available, can_create, can_download, can_restore, scheduled, schedule} so clients gate their buttons off real capability. Restore over HTTP is not exposed yet (can_restore: false); use the object_backup.py restore CLI, which is deliberately a deliberate, on-box operation.
Automatic backups are a config option, not on by default. A scheduled run is an external timer (systemd/cron) calling object_backup.py create; DBBASIC_BACKUP_SCHEDULE records the operator's intent so clients can show it. On-demand create and download always work regardless.
Realtime Push (Websocket)
Clients get live record-change signals over a websocket at /ws, so open pages auto-update the instant something changes — no polling. The durable event log (see the runtime contract) remains as the poll-based fallback.
WebSocket wss://your-host/ws
Connect with your session (the dbbasic_session cookie is sent automatically; a bearer/admin token also works). Anonymous connections are closed. Then speak a tiny JSON protocol:
// client -> server
{"action": "subscribe", "collections": ["notifications", "notes"]}
{"action": "unsubscribe", "collections": ["notes"]}
{"action": "ping"}
// server -> client
{"type": "welcome", "user": "dan"}
{"type": "subscribed", "collections": ["notifications", "notes"]}
{"type": "record", "collection": "notes", "record_id": "…", "action": "created"}
{"type": "pong"}
The record message is a signal, not data — only the collection, record id, and action travel, never the record body. The client refetches through the normal permission-enforced API. Two guarantees follow the same rules as reads: you can only subscribe to a collection you may read, and with enforcement on you only receive events for records your row filters would let you see (a private note's change is never signalled to another user). Requires DBBASIC_ENABLE_REALTIME (default on); the reverse proxy must forward websocket upgrades (Caddy does by default). Single-process deployment assumption applies — see asgi-realtime-direction.
The shared nav (/nav) and every app page already use this. The notification bell subscribes to notifications and updates live (with a 20s poll as backup); each list page (/notes, /tasks, /contacts, …) subscribes to its own collection and re-renders when a record it can see changes — in another tab, by another user, or by an agent — over the same single shared socket. Any page opts in with one line: window.dbbasicSubscribe(collection, handler).
Global Search
Records can be searched across every collection whose schema declares searchable fields (see the schema field contract's search section):
GET /api/search?q=flywheel+growth&limit=10
GET /api/search?q=flywheel&collections=notes,tasks
Authorization: Token <token-or-session> (or the dbbasic_session cookie)
The query is split on whitespace; every term must match at least one searchable field (case-insensitive substring), and a short hex-ish query also matches record ids by prefix. Results come back per collection with no ranking:
{
"status": "ok",
"query": "flywheel growth",
"limit": 10,
"results": {
"notes": [{"id": "n1", "content": "flywheel growth loop"}],
"tasks": []
},
"total_count": 1
}
Each result record is trimmed to the schema's search.result_fields (default: id plus the schema's views.list_fields, falling back to the searchable fields). Search runs inside the permission engine: with enforcement on, collections the caller cannot read are skipped entirely, row filters hide other users' records, and field permissions redact fields before results are returned — the same subject resolution as record reads (admin token, session token, or session cookie). Without permission checks the endpoint stays behind the admin gate. Malformed search sections surface in a warnings list instead of failing the whole request.
Admin Collection And Schema Inspection
/collections and /schemas remain the data and schema API surfaces. Scroll and operator dashboards should use the admin inspection aliases for read-only collection, record, changelog, schema, and schema-version views. This lets a public staging reverse proxy expose inspection routes without exposing the broad write-capable collection and schema routes.
GET /admin/collections
GET /admin/collections/{collection}
GET /admin/collections/{collection}/records
GET /admin/collections/{collection}/records/{record_id}
GET /admin/collections/{collection}/changes
GET /admin/collections/{collection}/records/{record_id}/changes
GET /admin/schemas
GET /admin/schemas/{collection}
GET /admin/schemas/{collection}?versions=true&limit=10
GET /admin/schemas/{collection}?version=1
Authorization: Token <token>
The responses match the underlying read-only GET /collections* and GET /schemas* responses.
Admin Collection Record Writes
Operator screens can create, update, and delete collection records through narrow admin aliases without exposing the broad write-capable /collections/* routes through the reverse proxy:
POST /admin/collections/{collection}/records
PUT /admin/collections/{collection}/records/{record_id}
DELETE /admin/collections/{collection}/records/{record_id}
Authorization: Token <token>
These aliases route to the same handlers as POST /collections/{collection}/records, PUT /collections/{collection}/records/{record_id}, and DELETE /collections/{collection}/records/{record_id}, so request bodies, responses, schema validation, field permissions, record change history, and permission enforcement behave identically. Writes require the admin token (or enforced permission policy when enforcement is enabled).
Other write methods on /admin/collections* paths — including collection create or delete — remain unsupported and return 405.
Admin Storage And Compaction
Compaction observability and control for append-mode collections (see storage-modes.md):
GET /admin/storage
POST /admin/collections/{collection}/compact
Authorization: Token <token>
GET /admin/storage returns stats for every collection whose schema currently declares "storage": "append":
{
"status": "ok",
"append_collections": [
{
"collection": "events_log",
"storage": "append",
"physical_rows": 41200,
"live_rows": 9800,
"dead_rows": 31400,
"bloat_ratio": 3.204,
"file_bytes": 5872000,
"sidecar_present": true,
"compaction_flagged": false
}
]
}
This route is deliberately cheap: it never folds a collection's records.tsv to answer, preferring a warm in-process cache entry or the id→offset sidecar's own row count. A collection neither can answer comes back as an estimated entry instead of paying an O(file) parse on a status call — file_bytes is still real, but physical_rows, live_rows, dead_rows, and bloat_ratio are null and "estimated": true is set. bloat_ratio is dead_rows / max(live_rows, 1), rounded to 3 decimal places. A classic-mode collection is never included.
POST /admin/collections/{collection}/compact runs object_records.compact_collection under the same gate that protects other mutating admin record routes (admin token, or enforced permission policy when enforcement is enabled — there is no single record for this operation, so the collection-level write check is the whole check):
{
"status": "ok",
"collection": "events_log",
"rows_before": 41200,
"rows_after": 9800,
"bytes_before": 5872000,
"bytes_after": 1398600,
"duration_ms": 812.4
}
Returns 400 for a collection not currently in append storage mode (nothing to compact) and 404 for an unknown collection. Compaction also runs automatically — on a write, once a collection's dead-row ratio and size cross their thresholds, and on a timer if the optional daemon (object_daemon.py) is running — see storage-modes.md for the envs (DBBASIC_APPEND_COMPACT_MIN_ROWS, DBBASIC_COMPACTION_INTERVAL_SECONDS, DBBASIC_COMPACTION_BLOAT_RATIO). The /admin/status capabilities.storage block reports {"append_collections": <count>}.
Admin Schema Writes
Operator screens can replace and roll back collection schemas through narrow admin aliases without exposing the broad write-capable /schemas/* routes through the reverse proxy:
PUT /admin/schemas/{collection}
POST /admin/schemas/{collection}
Authorization: Token <token>
These aliases route to the same handlers as PUT /schemas/{collection} and POST /schemas/{collection}, so request bodies, responses, schema normalization, and schema version history behave identically. PUT replaces the schema and records a new schema version. POST supports action-style operations; the only supported action is {"action": "rollback", "version_id": <id>}. Both writes require the admin token.
Other write methods on /admin/schemas* paths — including schema delete — remain unsupported and return 405. The admin aliases still do not install packages or expose broad /objects execution routes.
Admin Identity Inspection
/identity/accounts, /identity/users, and /identity/sessions remain the identity management API surfaces. Scroll and operator dashboards should use the admin inspection aliases for read-only account, user, and session views. This lets public staging expose identity posture without exposing identity creation, arbitrary session minting, or session revocation.
GET /admin/identity/accounts
GET /admin/identity/accounts/{account_id}
GET /admin/identity/users
GET /admin/identity/users?account_id=acme
GET /admin/identity/users/{user_id}
GET /admin/identity/sessions
GET /admin/identity/sessions/{session_id}
Authorization: Token <token>
The responses match the underlying read-only GET /identity/accounts*, GET /identity/users*, and GET /identity/sessions* responses. These admin aliases are admin-token gated and read-only, with one write exception: the password set/reset aliases (POST/DELETE /admin/identity/users/{user_id}/password, documented under User Passwords). They still do not create accounts or users, mint sessions, or revoke sessions.
Collections
GET /collections
Authorization: Token <token>
Response:
{
"status": "ok",
"collections": [
{
"name": "site",
"object_count": 2,
"file_count": 1,
"state_object_count": 1,
"log_object_count": 1,
"has_records": true,
"owners": ["system"],
"kinds": {"system": 2},
"permission": {
"access_mode": "role_based",
"rule_count": 1,
"allow_count": 1,
"deny_count": 0,
"actions": ["execute", "read"],
"principals": ["role:admin"]
}
}
],
"count": 1
}
Read one collection with object details:
GET /collections/{collection}
Authorization: Token <token>
Response:
{
"status": "ok",
"collection": {
"name": "site",
"object_count": 1,
"file_count": 0,
"state_object_count": 0,
"log_object_count": 0,
"has_records": false,
"owners": ["system"],
"kinds": {"system": 1},
"permission": {
"access_mode": "role_based",
"rule_count": 0,
"allow_count": 0,
"deny_count": 0,
"actions": [],
"principals": []
},
"objects": [
{
"object_id": "site_home",
"path": "site/home.py",
"owner": "system",
"kind": "system",
"state_count": 0,
"has_logs": false,
"file_count": 0
}
]
}
}
Collections are a derived view over object source IDs, source folders, object state/files/log presence, record-file presence, and permission rules. The server does not store a separate collection table yet. This keeps the existing /objects contract stable while giving tools such as Scroll a cleaner grouping API.
The public server keeps collection summary routes read-only and admin-token gated for now. Missing collections return 404; unsafe collection names return 400.
Collection Records
List records:
GET /collections/{collection}/records?limit=100&offset=0
Authorization: Token <token>
By default this route is admin-token gated. If DBBASIC_ENABLE_PERMISSION_AUDIT=true or DBBASIC_ENABLE_PERMISSION_ENFORCEMENT=true is set, the route uses the persisted permission policy instead. Enforcement uses the read action with the collection name, applies row filters before limit / offset, and redacts fields according to the matching decision.
Response:
{
"status": "ok",
"collection": "contacts",
"records": [
{
"id": "c1",
"first_name": "Ada",
"last_name": "Lovelace"
}
],
"count": 1,
"total": 1,
"limit": 100,
"offset": 0,
"has_more": false
}
Read one record:
GET /collections/{collection}/records/{record_id}
Authorization: Token <token>
The detail route is also admin-token gated by default. With permission enforcement enabled, the server loads the record, checks the same read permission against that record, and then applies field allow/deny rules before returning it.
Response:
{
"status": "ok",
"collection": "contacts",
"record": {
"id": "c1",
"first_name": "Ada",
"last_name": "Lovelace"
}
}
Record files live under:
data/collections/{collection}/records.tsv
The TSV file must have a header row and an id column. Values are returned as strings.
For new DBBASIC-created records, the server generates a UUIDv4 id when the request omits one. During migrations, imported rows may preserve legacy integer or slug IDs for compatibility, but new public routes and generated UI should not assume sequential IDs.
Create one record:
POST /collections/{collection}/records
Authorization: Token <token>
Content-Type: application/json
{
"first_name": "Grace",
"last_name": "Hopper"
}
Response:
{
"status": "ok",
"collection": "contacts",
"record": {
"id": "8c2d4de7-89fe-45f7-9cf9-f0f42610e7be",
"first_name": "Grace",
"last_name": "Hopper"
}
}
Successful creates return 201. Explicit record IDs are still accepted for imports and compatibility. Duplicate record IDs return 409.
Update one record:
PUT /collections/{collection}/records/{record_id}
Authorization: Token <token>
Content-Type: application/json
{
"last_name": "Lovelace",
"email": "ada@example.com"
}
The record id cannot be changed.
Delete one record:
DELETE /collections/{collection}/records/{record_id}
Authorization: Token <token>
Response:
{
"status": "ok",
"collection": "contacts",
"record": {
"id": "c1",
"first_name": "Ada",
"last_name": "Lovelace"
},
"deleted": true
}
Missing collections or records return 404; unsafe collection, record, or field names return 400. Missing subscription entitlements can return 402 Payment Required when the active policy requires them. By default all record mutations require the admin token. With DBBASIC_ENABLE_PERMISSION_ENFORCEMENT=true, mutations can also be authorized by persisted policy rules using create, update, and delete.
If data/schemas/{collection}.json exists, POST and PUT mutations validate known fields before the TSV write. Required fields, create defaults, basic scalar types, enum values, length/numeric/pattern rules, and computed/read-only fields are enforced by the server. Unknown fields are still accepted so tools can add data before a schema is complete.
When DBBASIC_ENABLE_PERMISSION_ENFORCEMENT=true, schema field permissions are also enforced for collection records. Fields resolved as hidden are removed from GET responses. Submitted fields resolved as read or hidden are rejected with 403:
{
"status": "error",
"error": "Record field 'margin' is not editable for this subject",
"code": "forbidden",
"denied_fields": ["margin"]
}
Read collection record change history:
GET /collections/{collection}/changes?limit=100&offset=0
Authorization: Token <token>
Read change history for one record:
GET /collections/{collection}/records/{record_id}/changes?limit=100&offset=0
Authorization: Token <token>
Response:
{
"status": "ok",
"collection": "contacts",
"record_id": "c1",
"changes": [
{
"change_id": "0f8b5e96-d8b5-4a0d-8b7d-c3c2e2092d24",
"timestamp": "2026-06-29T12:00:00+00:00",
"collection": "contacts",
"record_id": "c1",
"action": "update",
"actor": "admin",
"message": "Updated record",
"changed_fields": ["name"],
"before": {"id": "c1", "name": "Ada"},
"after": {"id": "c1", "name": "Ada Lovelace"}
}
],
"count": 1,
"total": 1,
"limit": 100,
"offset": 0,
"has_more": false
}
Successful POST, PUT, and DELETE record mutations append JSONL entries under:
data/record_changes/{collection}/changes.jsonl
This is the durable audit and admin-history surface. When record events are enabled, successful POST, PUT, and DELETE mutations also publish collection.record.created, collection.record.updated, and collection.record.deleted events from the same change entry.
Events
Events are the daemon-compatible notification surface for triggers, listeners, webhooks, and future worker-style objects. They are intentionally separate from record change history. Change history is the durable audit trail; events are the delivery queue.
Collection record mutations publish metadata-only events by default. Set DBBASIC_ENABLE_RECORD_EVENTS=false to turn that off. Event payloads include the change id, collection, record id, action, actor, timestamp, and changed field names; they intentionally do not copy full before or after snapshots until subscriber permissions are enforced.
The current endpoints are admin-gated:
GET /events?event_type=collection.record.created&limit=100&offset=0
DELETE /events?keep_count=1000&keep_seconds=604800
Authorization: Token <token>
Response:
{
"status": "ok",
"events": [
{
"id": "789f0c18-7845-4620-a2b0-8bbad752f91b",
"event_type": "collection.record.created",
"payload": {
"change_id": "0f8b5e96-d8b5-4a0d-8b7d-c3c2e2092d24",
"collection": "contacts",
"record_id": "c1",
"action": "create",
"actor": "admin",
"timestamp": "2026-06-29T12:00:00Z",
"changed_fields": ["id", "name"]
},
"source": "record_changes",
"actor": "admin",
"timestamp": 1782734400,
"created_at": "2026-06-29T12:00:00Z"
}
],
"count": 1,
"total": 1,
"limit": 100,
"offset": 0,
"has_more": false
}
Publish one event:
POST /events
Authorization: Token <token>
Content-Type: application/json
{
"event_type": "collection.record.created",
"source": "record_changes",
"payload": {"collection": "contacts", "record_id": "c1"}
}
Successful publishes return 201.
Prune the delivery queue:
DELETE /events?keep_count=1000&keep_seconds=604800
Authorization: Token <token>
Response:
{
"status": "ok",
"retention": {
"deleted": 12,
"kept": 1000,
"scanned": 1012,
"protected": 1,
"corrupt_deleted": 0,
"keep_count": 1000,
"keep_seconds": 604800
}
}
keep_count=0 disables count-based pruning. keep_seconds=0 disables age-based pruning. Subscriptions are never deleted by event pruning, and the event referenced by a subscription last_event_id is protected to avoid surprise replay. Failed delivery attempts are protected too, so the daemon and Scroll can still see the pending retry event. Configure the default publish/daemon cleanup policy with DBBASIC_EVENT_KEEP_COUNT and DBBASIC_EVENT_KEEP_SECONDS.
Subscriptions are stored in the same daemon-compatible events object state:
GET /events/subscriptions?event_type=collection.record.created
POST /events/subscriptions
DELETE /events/subscriptions?event_type=collection.record.created&subscriber_id=scroll
Authorization: Token <token>
Create or replace a subscription:
{
"event_type": "collection.record.created",
"subscriber_id": "scroll",
"callback_url": "https://example.com/hooks/dbbasic"
}
Response:
{
"status": "ok",
"subscription": {
"id": "scroll",
"event_type": "collection.record.created",
"callback_url": "https://example.com/hooks/dbbasic",
"created_at": 1782734400,
"created_at_iso": "2026-06-29T12:00:00Z",
"created_by": "admin",
"last_event_id": null,
"delivery": {
"status": "idle",
"attempts": 0,
"successes": 0,
"failures": 0,
"last_attempted_event_id": null,
"last_attempt_at": null,
"last_attempt_at_iso": null,
"last_success_event_id": null,
"last_success_at": null,
"last_success_at_iso": null,
"last_failure_event_id": null,
"last_failure_at": null,
"last_failure_at_iso": null,
"last_status_code": null,
"last_error": null
}
}
}
The daemon updates delivery after each callback attempt. Successful delivery sets status=ok and advances last_event_id; failed delivery sets status=failed, records the last error/status, and leaves last_event_id unchanged so the event can be retried.
Delivery status is exposed separately so Scroll and operator dashboards can show pending, delivered, and failed work without loading event payloads or callback secrets:
GET /events/deliveries?event_type=collection.record.created&pending=true
GET /events/deliveries?delivery_status=failed
Authorization: Token <token>
Response:
{
"status": "ok",
"deliveries": [
{
"id": "scroll",
"subscriber_id": "scroll",
"event_type": "collection.record.created",
"callback_url_present": true,
"pending": true,
"pending_count": 2,
"last_event_id": null,
"next_pending_event": {
"id": "789f0c18-7845-4620-a2b0-8bbad752f91b",
"event_type": "collection.record.created",
"source": "record_changes",
"actor": "admin",
"timestamp": 1782734400,
"created_at": "2026-06-29T12:00:00Z"
},
"latest_pending_event": {
"id": "98b9fd7c-9e38-48a6-9134-153473c0172a",
"event_type": "collection.record.created",
"source": "record_changes",
"actor": "admin",
"timestamp": 1782734460,
"created_at": "2026-06-29T12:01:00Z"
},
"delivery": {
"status": "failed",
"attempts": 1,
"successes": 0,
"failures": 1,
"last_attempted_event_id": "789f0c18-7845-4620-a2b0-8bbad752f91b",
"last_attempt_at": 1782734401,
"last_attempt_at_iso": "2026-06-29T12:00:01Z",
"last_status_code": 500,
"last_error": "callback failed"
}
}
],
"count": 1,
"total": 1,
"limit": 100,
"offset": 0,
"has_more": false
}
callback_url is redacted by default. Trusted detail views may request include_callback_url=true. Event payloads are also excluded by default; use include_events=true&event_limit=10 only for trusted operator/detail views.
Packages
Packages are DBBASIC bundles: objects, schemas, permissions, seed data, and migrations collected under one package directory. GitHub can host the source, but Scroll/Object Server should inspect and later install packages through the DBBASIC API so backups, dry-runs, changelogs, and rollback points stay part of the object loop.
The first public package surface can list packages, return dry-run plans, and perform conservative installs when both admin auth and the explicit package install flag are enabled. Dry-runs and installs append compact package changelog rows so operators can see which packages were reviewed, installed, or rejected.
Package directory shape:
packages/{package_id}/
dbbasic-package.json
objects/
schemas/
permissions/
seed/
migrations/
List packages:
GET /packages
Authorization: Token <token>
Response:
{
"status": "ok",
"packages": [
{
"id": "hello-world",
"name": "Hello World",
"version": "0.1.0",
"description": "Small package proving DBBASIC package discovery and dry-run planning.",
"status": "available",
"object_count": 1,
"schema_count": 0,
"permission_count": 0,
"seed_count": 0,
"migration_count": 0,
"dependency_count": 0
}
],
"count": 1
}
Read one manifest:
GET /packages/{package_id}
Authorization: Token <token>
Response:
{
"status": "ok",
"package": {
"id": "hello-world",
"name": "Hello World",
"version": "0.1.0",
"description": "Small package proving DBBASIC package discovery and dry-run planning.",
"compatibility": {"object_server": ">=0.0.1"},
"dependencies": [],
"objects": [
{"id": "hello_world", "path": "objects/hello/world.py"}
],
"schemas": [],
"permissions": [],
"seed": [],
"migrations": []
}
}
Dry-run a future install/update:
GET /packages/{package_id}?dry_run=true
Authorization: Token <token>
Response:
{
"status": "ok",
"dry_run": {
"package": {
"id": "hello-world",
"name": "Hello World",
"version": "0.1.0",
"description": "Small package proving DBBASIC package discovery and dry-run planning.",
"status": "available",
"object_count": 1,
"schema_count": 0,
"permission_count": 0,
"seed_count": 0,
"migration_count": 0,
"dependency_count": 0
},
"mode": "dry_run",
"install_enabled": false,
"safe_to_install": true,
"objects": [
{
"id": "hello_world",
"path": "objects/hello/world.py",
"exists": true,
"action": "create",
"installed": false
}
],
"schemas": [],
"permissions": [],
"seed": [],
"migrations": [],
"warnings": []
},
"change": {
"change_id": "0a34c2e6-3144-4900-8f99-fd7c7ec77c61",
"timestamp": "2026-06-30T12:00:00+00:00",
"package_id": "hello-world",
"package_version": "0.1.0",
"action": "dry_run",
"actor": "admin",
"message": "Dry run package install",
"details": {
"safe_to_install": true,
"install_enabled": false,
"objects": {"create": 1},
"schemas": {},
"permissions": {},
"seed": {},
"migrations": {},
"warnings": []
}
}
}
Install a reviewed package:
POST /packages/{package_id}/install
Authorization: Token <token>
Content-Type: application/json
{"allow_replace": false}
Package installs require:
DBBASIC_ADMIN_TOKEN=...
DBBASIC_ENABLE_PACKAGE_INSTALLS=true
The first install implementation is deliberately narrow:
- object files are written under the configured object root
- schema JSON is validated and written under
data/schemas/ - seed TSV is written only when
data/collections/{collection}/records.tsv
does not already exist
- replacing objects or schemas requires
{"allow_replace": true} - package permissions and migrations are rejected until merge/run semantics are
explicit
- a runtime restore point is created before any live object, schema, or seed
file is changed
Response:
{
"status": "ok",
"install": {
"package": {
"id": "hello-world",
"name": "Hello World",
"version": "0.1.0",
"description": "Small package proving DBBASIC package discovery and dry-run planning.",
"status": "available",
"object_count": 1,
"schema_count": 0,
"permission_count": 0,
"seed_count": 0,
"migration_count": 0,
"dependency_count": 0
},
"mode": "install",
"install_enabled": true,
"allow_replace": false,
"safe_to_install": true,
"objects": [
{
"id": "hello_world",
"path": "objects/hello/world.py",
"exists": true,
"action": "create",
"installed": false,
"status": "written",
"destination": "hello/world.py"
}
],
"schemas": [],
"permissions": [],
"seed": [],
"migrations": [],
"warnings": [],
"restore_point": {
"path": "data/backups/20260630T120100Z-package-hello-world.tar.gz",
"format_version": 1,
"created_at": "2026-06-30T12:01:00Z",
"files": 14,
"bytes": 12345,
"warnings": []
}
},
"changes": {
"requested": {
"change_id": "c0c3f4a6-8b10-47cb-8309-b381354f6cc0",
"action": "install_requested"
},
"installed": {
"change_id": "c77681de-5b1e-4a5e-adc9-16701ca230f5",
"action": "installed"
}
},
"restore_point": {
"path": "data/backups/20260630T120100Z-package-hello-world.tar.gz",
"format_version": 1,
"created_at": "2026-06-30T12:01:00Z",
"files": 14,
"bytes": 12345,
"warnings": []
}
}
Restore a package install restore point:
POST /packages/{package_id}/restore
Authorization: Token <token>
Content-Type: application/json
{"change_id": "c77681de-5b1e-4a5e-adc9-16701ca230f5", "confirm": "restore-runtime"}
Package restore requires:
DBBASIC_ADMIN_TOKEN=...
DBBASIC_ENABLE_PACKAGE_RESTORE=true
The change id must point at a recorded package change with restore-point metadata. The server restores that runtime snapshot with overwrite and prune-extra enabled, then appends restore_requested and rolled_back package change rows. This is intentionally a whole-runtime rollback, not a selective package uninstall, and the restore path must live under the configured backup directory.
Response:
{
"status": "ok",
"restore": {
"backup_path": "data/backups/20260630T120100Z-package-hello-world.tar.gz",
"objects_dir": "objects",
"data_dir": "data",
"files": 14,
"bytes": 12345,
"overwritten": true,
"pruned_files": 3,
"pruned_dirs": 2
},
"restore_point": {
"path": "data/backups/20260630T120100Z-package-hello-world.tar.gz",
"format_version": 1,
"created_at": "2026-06-30T12:01:00Z",
"files": 14,
"bytes": 12345,
"warnings": []
},
"from_change": {
"change_id": "c77681de-5b1e-4a5e-adc9-16701ca230f5",
"action": "installed"
},
"changes": {
"requested": {
"change_id": "9fd9b09c-22bf-41c2-b6ee-3a96ca195fef",
"action": "restore_requested"
},
"rolled_back": {
"change_id": "9a63dcde-ec78-426b-8787-f1e8ec401190",
"action": "rolled_back"
}
}
}
Read package changelog:
GET /packages/{package_id}/changes?limit=100&offset=0
Authorization: Token <token>
Response:
{
"status": "ok",
"package_id": "hello-world",
"changes": [
{
"change_id": "0a34c2e6-3144-4900-8f99-fd7c7ec77c61",
"timestamp": "2026-06-30T12:00:00+00:00",
"package_id": "hello-world",
"package_version": "0.1.0",
"action": "dry_run",
"actor": "admin",
"message": "Dry run package install",
"details": {
"safe_to_install": true,
"install_enabled": false,
"objects": {"create": 1},
"schemas": {},
"permissions": {},
"seed": {},
"migrations": {},
"warnings": []
}
}
],
"count": 1,
"total": 1,
"limit": 100,
"offset": 0,
"has_more": false
}
Package ids are route-safe lowercase names such as hello-world or crm-starter. Package manifests use relative paths only. Absolute paths, .., null bytes, unsupported permission/migration writes, and unsafe source/data destinations are rejected at this layer.
Schemas
GET /schemas
Authorization: Token <token>
Response:
{
"status": "ok",
"schemas": [
{
"name": "invoices",
"title": "Invoices",
"source": "manual",
"version": 1,
"field_count": 4
}
],
"count": 1
}
Read one schema:
GET /schemas/{collection}
Authorization: Token <token>
Response:
{
"status": "ok",
"message": "Schema updated to version 1",
"version_id": 1,
"collection": "invoices",
"schema": {
"name": "invoices",
"title": "Invoices",
"source": "manual",
"version": 1,
"fields": [
{
"name": "customer_id",
"type": "relation",
"required": true,
"relation": {"collection": "contacts"},
"validation": {"not_null": true}
},
{
"name": "total",
"type": "computed",
"required": false,
"computed": "sum(line_items)"
},
{
"name": "cost_price",
"type": "currency",
"required": false,
"permissions": {"admin": "edit", "sales": "hidden"},
"ui": {"section": "totals"}
}
],
"field_count": 3
}
}
Replace one manual schema:
PUT /schemas/{collection}
Content-Type: application/json
Authorization: Token <token>
Request:
{
"schema": {
"title": "Invoices",
"ui": {"default_view": "form"},
"views": [{"name": "invoice_admin", "type": "form"}],
"fields": [
{
"name": "invoice_date",
"type": "date",
"required": true,
"layout": {"column": 1}
},
{
"name": "margin",
"type": "currency",
"permissions": {"admin": "edit", "sales": "hidden"}
}
]
}
}
Response:
{
"status": "ok",
"schema": {
"name": "invoices",
"title": "Invoices",
"source": "manual",
"version": 1,
"fields": [
{"name": "invoice_date", "type": "date", "required": true},
{
"name": "margin",
"type": "currency",
"required": false,
"permissions": {"admin": "edit", "sales": "hidden"}
}
],
"field_count": 2,
"ui": {"default_view": "form"},
"views": [{"name": "invoice_admin", "type": "form"}]
}
}
List schema versions:
GET /schemas/{collection}?versions=true&limit=10
Authorization: Token <token>
Response:
{
"status": "ok",
"collection": "invoices",
"versions": [
{
"version_id": 2,
"timestamp": "2026-06-29T12:00:00",
"author": "admin",
"message": "Add margin field",
"hash": "..."
},
{
"version_id": 1,
"timestamp": "2026-06-29T11:50:00",
"author": "admin",
"message": "Initial schema",
"hash": "..."
}
],
"count": 2
}
Read one schema version:
GET /schemas/{collection}?version=1
Authorization: Token <token>
Response:
{
"status": "ok",
"collection": "invoices",
"version": {
"version_id": 1,
"timestamp": "2026-06-29T11:50:00",
"author": "admin",
"message": "Initial schema",
"hash": "...",
"content": "{...}",
"schema": {
"name": "invoices",
"title": "Invoices",
"source": "manual",
"version": 1,
"fields": [],
"field_count": 0
}
}
}
Rollback is non-destructive. It creates a new latest version containing the old schema content and then replaces the live schema file:
POST /schemas/{collection}
Content-Type: application/json
Authorization: Token <token>
Request:
{
"action": "rollback",
"version_id": 1,
"author": "admin",
"message": "Restore first invoice form"
}
Response:
{
"status": "ok",
"message": "Rolled back schema to version 1",
"version_id": 1,
"new_version_id": 3,
"collection": "invoices",
"schema": {
"name": "invoices",
"title": "Invoices",
"source": "manual",
"version": 1,
"fields": [],
"field_count": 0
}
}
Schema files live under:
data/schemas/{collection}.json
data/schema_versions/{collection}/metadata.tsv
data/schema_versions/{collection}/vN.json
Manual schemas can be replaced through the admin-token gated PUT route. Writes are atomic file replacements under data/schemas/, and each write records a schema version. If a collection has no manual schema, the server may return an empty derived schema for that collection so Scroll can still show the collection and later attach fields. Missing schemas return 404; unsafe schema names return 400.
Schema permissions and ui fields are preserved for generated admin screens. With permission enforcement enabled, schema permissions also refine record reads and writes after the broader server policy has allowed the row.
Create Object
POST /objects
Content-Type: application/json
Authorization: Token <token>
Request:
{
"object_id": "site_home",
"code": "def GET(request):\n return {\"status\": \"ok\"}\n",
"author": "admin",
"message": "Create home object",
"description": "Optional client-provided description"
}
Response:
{
"status": "ok",
"object_id": "site_home",
"message": "Object created: site_home",
"version_id": 1,
"correlation_id": "123e4567-e89b-42d3-a456-426614174001"
}
Creation is intentionally gated. It requires DBBASIC_ENABLE_SOURCE_WRITES=true and the same admin gate used by source updates. A configured DBBASIC_ADMIN_TOKEN always works; an active DBBASIC session with an admin role can also pass the gate only when DBBASIC_ENABLE_SESSION_ADMIN_GATES=true.
Clients can choose one of these creation shapes:
object_idcreates that exact object ID, such assite_home.nameplusowner_user_idcreatesu_<owner_user_id>_<name>, such as
u_42_deals.
namewith an admin session whoseuser_idis numeric also creates
u_<session_user_id>_<name>.
namewithout a user owner creates a system object usingnameas the object
ID.
The first source write creates version 1, appends a source_create change entry, and the object can be executed immediately through GET/POST/PUT/DELETE /objects/{object_id}. Existing object IDs return 409. The description field is stored in source-change details for tools like Scroll.
Execute Object
GET /objects/{object_id}
POST /objects/{object_id}
PUT /objects/{object_id}
DELETE /objects/{object_id}
GET passes query parameters to the object. POST, PUT, and DELETE pass a JSON body when present.
Compatibility details from the working prototype:
POSTmerges query parameters into the JSON body without overriding body keys.POSTwith a non-JSON body passes raw bytes as thebodyfield plus query
parameters.
PUTandDELETEreject invalid JSON bodies with400.- request bodies over
DBBASIC_MAX_REQUEST_BYTESare rejected with413. - rate-limited requests are rejected with
429. - full request or object execution capacity is rejected with
503. - object executions over
DBBASIC_OBJECT_TIMEOUT_SECONDSare rejected with504. POSTwith{"action": "rollback"}is reserved for rollback.PUT /objects/{object_id}?source=trueis reserved for source updates.
Example:
POST /objects/basics_counter
Content-Type: application/json
{
"action": "increment"
}
Execution responses are object-defined. The server should pass successful object results through without wrapping them in a new envelope.
Compatibility response shapes:
- normal dicts return JSON
- dicts with
content_typeandbodyreturn raw HTTP responses (status, headers, body)tuples return low-level HTTP responses- strings return
text/html; charset=utf-8 - bytes return
application/octet-stream
Example HTML object response:
def GET(request):
return {
"content_type": "text/html; charset=utf-8",
"body": "<!doctype html><h1>DBBASIC</h1>",
}
Example tuple response:
def POST(request):
return (201, [("Content-Type", "text/plain")], [b"created"])
On server-side execution failure, return a non-2xx status with:
{
"status": "error",
"error": "Execution failed: ..."
}
Future structured error fields may be added, but existing clients must still be able to read the error field.
If DBBASIC_OBJECT_TIMEOUT_SECONDS is set above zero, the public ASGI server runs object methods in a subprocess. When the timeout expires, the worker is terminated and the client receives:
504 Gateway Timeout
{
"status": "error",
"error": "Execution failed: GET timed out for object basics_slow after 5 seconds"
}
The timeout is a wall-clock boundary. It is not a complete CPU or memory sandbox.
Objects named in DBBASIC_TRUSTED_IN_PROCESS_OBJECTS keep the fast in-process execution path even when timeouts are enabled. This is for reviewed server-owned objects, such as a high-traffic public homepage. Do not use it for unreviewed user code.
Source
GET /objects/{object_id}?source=true&format=json
Authorization: Token <token>
Response:
{
"status": "ok",
"object_id": "basics_counter",
"source": "def GET(request):\n return {\"status\": \"ok\"}\n"
}
HTML source rendering can exist for browsers, but JSON must stay available with format=json or an Accept: application/json request.
Update Source
PUT /objects/{object_id}?source=true
Content-Type: application/json
Authorization: Token <token>
Request:
{
"code": "def GET(request):\n return {\"status\": \"updated\"}\n",
"author": "api",
"message": "Updated via client"
}
Response:
{
"status": "ok",
"message": "Code updated to version 2",
"version_id": 2,
"object_id": "u_42_deals"
}
The update must save a source version, write the source file, and leave enough information for clients to show the new version number.
The current public server keeps this endpoint closed by default. Local development source writes require:
DBBASIC_ENABLE_SOURCE_WRITES=true
DBBASIC_ADMIN_TOKEN=replace-with-a-local-dev-token
The token value shown here is a placeholder. Real deployments must generate a server-specific secret outside the source tree. Production code should replace that temporary gate with the real auth and permission system before this endpoint is exposed to users.
State
GET /objects/{object_id}?state=true
Authorization: Token <token>
Response:
{
"status": "ok",
"object_id": "basics_counter",
"state": {
"count": 3
}
}
State is currently read from:
data/state/{object_id}/state.tsv
Rows may be key<TAB>value or key<TAB>value<TAB>timestamp. The public server currently exposes state read-only.
Metadata
GET /objects/{object_id}?metadata=true
Authorization: Token <token>
Response:
{
"status": "ok",
"object_id": "basics_counter",
"metadata": {
"object_id": "basics_counter",
"source_path": "basics/counter.py",
"owner": "system",
"kind": "system",
"last_modified": 1760000000.0,
"state_count": 1,
"state_keys": ["count"],
"log_count": 3,
"file_count": 1,
"version_count": 2
}
}
The public server reports source paths relative to the object source root, not absolute local filesystem paths. Metadata may grow over time. Existing clients expect the top-level metadata field.
Files
GET /objects/{object_id}?files=true
Authorization: Token <token>
Response:
{
"status": "ok",
"object_id": "site_home",
"files": [
{
"name": "report.txt",
"size": 1200,
"modified": 1760000000.0
}
],
"count": 1
}
Download one object-owned file:
GET /objects/{object_id}?file=report.txt
Authorization: Token <token>
The server reads files from:
data/files/{object_id}/
Filenames are validated before filesystem access. Empty names, absolute paths, null bytes, and .. traversal are rejected with 400. Missing files return 404.
This public object route stays read-only for files. Scroll and operator dashboards should use /admin/files* for file inventory, downloads, and the separately gated admin write workflow.
Logs
GET /objects/{object_id}?logs=true&format=json&limit=100
Authorization: Token <token>
Response:
{
"status": "ok",
"object_id": "basics_counter",
"logs": [
{
"entry_id": "a1",
"timestamp": "2026-01-01T00:00:00",
"level": "DEBUG",
"message": "GET completed successfully",
"method": "GET",
"status": "success",
"duration_ms": "1.25"
}
],
"count": 1
}
Optional query parameters:
levelfilters by exact log level, such asINFOorERROR.limitdefaults to100in the public ASGI server.
Logs are currently read from:
data/logs/{object_id}/log.tsv
data/logs/{object_id}/log-*.tsv
data/logs/{object_id}/log-*.tsv.gz
The TSV header defines the fields. The normal fields are entry_id, timestamp, level, and message; object code may add extra columns such as method, status, duration_ms, error_type, error, or user_id.
The public ASGI server appends one execution log entry after each object method run. Successful runs use level=DEBUG and status=success; failed runs use level=ERROR, status=error, and include error fields. The endpoint itself remains read-only.
Log storage may rotate and gzip old logs on disk. The HTTP response shape does not change; clients still receive JSON log entries. Transport compression for large log responses should be handled through normal HTTP compression, such as a reverse proxy honoring Accept-Encoding, rather than changing this JSON shape.
Source Changes
GET /objects/{object_id}?source_changes=true&limit=100&offset=0
Authorization: Token <token>
Response:
{
"status": "ok",
"object_id": "basics_counter",
"changes": [
{
"change_id": "123e4567-e89b-42d3-a456-426614174000",
"timestamp": "2026-01-01T00:00:00",
"object_id": "basics_counter",
"action": "source_update",
"version_id": 2,
"from_version_id": null,
"actor": "api",
"message": "Updated via client",
"correlation_id": "123e4567-e89b-42d3-a456-426614174001",
"details": {}
}
],
"count": 1,
"total": 1,
"limit": 100,
"offset": 0,
"has_more": false
}
History is newest first and does not include source content. Use the versions endpoint to inspect or restore source snapshots. Source changes are the operator activity timeline for source edits and rollbacks.
Object Changes
GET /objects/{object_id}?changes=true&kind=source&limit=100&offset=0
Authorization: Token <token>
This returns the normalized source/file timeline for one object. The admin inspection equivalent is:
GET /admin/objects/{object_id}?changes=true&limit=100&offset=0
Authorization: Token <token>
Response:
{
"status": "ok",
"object_id": "basics_counter",
"changes": [],
"count": 0,
"total": 0,
"limit": 100,
"offset": 0,
"has_more": false
}
kind can be omitted or set to source or file. Use /admin/changes when a global activity stream needs record and package changes too.
Versions
GET /objects/{object_id}?versions=true&limit=10
Authorization: Token <token>
Response:
{
"status": "ok",
"object_id": "basics_counter",
"versions": [
{
"version_id": 2,
"timestamp": "2026-01-01T00:00:00",
"author": "api",
"message": "Updated via client",
"hash": "..."
}
],
"count": 1
}
History is newest first and does not include source content.
Specific Version
GET /objects/{object_id}?version=2
Authorization: Token <token>
Response:
{
"status": "ok",
"object_id": "basics_counter",
"version": {
"version_id": 2,
"timestamp": "2026-01-01T00:00:00",
"author": "api",
"message": "Updated via client",
"hash": "...",
"content": "def GET(request):\n return {\"status\": \"ok\"}\n"
}
}
Rollback
POST /objects/{object_id}
Content-Type: application/json
Authorization: Token <token>
Request:
{
"action": "rollback",
"version_id": 1,
"author": "api",
"message": "Rollback to version 1"
}
Response:
{
"status": "ok",
"message": "Rolled back to version 1",
"version_id": 1,
"new_version_id": 3,
"object_id": "u_42_deals"
}
Rollback is non-destructive. The server should create a new latest version from the old source, write that source to the object file, and preserve history.
The historical response reports the requested rollback version in version_id. Future responses may add new_version_id, but must not remove version_id without a client migration.
The current public server supports new_version_id and uses the same temporary source-write gate as source updates:
DBBASIC_ENABLE_SOURCE_WRITES=true
DBBASIC_ADMIN_TOKEN=replace-with-a-local-dev-token
The token value shown here is a placeholder. Real deployments must generate a server-specific secret outside the source tree. Production code should replace that temporary gate with the real auth and permission system before rollback is exposed to users.
Destroy Object
DELETE /objects/{object_id}?destroy=true
Authorization: Token <token>
Response:
{
"status": "ok",
"message": "Object destroyed: u_42_deals",
"object_id": "u_42_deals"
}
Destructive delete must be authenticated and authorization-checked.
Routing Compatibility
The historical server supports explicit station routing:
GET /objects/{object_id}@{station_id}
The public v1 server does not need to promise distributed correctness, but code should not accidentally treat @ routing as a normal object ID. If station routing is disabled, return a clear error instead of executing the wrong object.
Compatibility Rules
- Keep
/objectsand/objects/{object_id}as the main HTTP surface. - Keep query flags such as
source=true,state=true, andversions=true. - Keep
PUT /objects/{object_id}?source=truefor source updates. - Keep rollback as
POST /objects/{object_id}withaction=rollback. - Keep top-level fields existing clients read:
status,error,object_id,
objects, source, state, metadata, logs, versions, version, version_id, message, and count.
- Add fields only when old clients can ignore them safely.
- Do not require clients to move to a new path such as
/api/v1without a
compatibility layer.