Admin API

Authentication and HTTP

The base URL is https://z8data.com. Use your own service URL for another deployment. Send Authorization: Bearer <admin-key> on every Admin request. The token is case-sensitive. The Bearer scheme is not case-sensitive. Use one space before the token, with no extra text, spaces, commas, or second key.

The admin key can create, list, get, and delete database files and read Telemetry. DB keys cannot use Admin routes. The admin key cannot query SQL. Use the DB API with a DB read/write key to create tables and change data. Both DB keys cover every database; there are no user or per-database keys.

Authentication runs before JSON parsing or database path access. Missing or invalid keys return 401 with WWW-Authenticate: Bearer. A valid key with the wrong role returns 403. Keys are never returned by the APIs or shown on the website.

Database success and handled error responses use JSON and Cache-Control: no-store. Admin routes do not set CORS allow headers. Call them from a server-side client or the same origin. See the Telemetry section for its separate error format and cache headers.

Next.js also provides OPTIONS and HEAD for these GET routes. OPTIONS needs no key and returns 204 with an Allow header: DELETE, GET, HEAD, OPTIONS, POST for databases, or GET, HEAD, OPTIONS for Telemetry and health. It sets no CORS allow headers or explicit Cache-Control header.

HEAD uses the GET handler with no response body. On the database route, authentication runs first, then an authorized HEAD returns 400 because the database handler only accepts GET, POST, and DELETE. Telemetry HEAD checks the admin key and collects or reuses a snapshot. Health HEAD returns 200. Use GET for the documented read operations. Framework 405 responses do not use the database JSON error format.

Server key settings and rotation

Set these three server-only variables in .env. The values below are placeholders:

1Z8DATA_ADMIN_KEY=<admin-key>
2Z8DATA_WRITE_KEY=<db-read-write-key>
3Z8DATA_READ_KEY=<db-read-only-key>

All three values must be nonempty and different. Whitespace and commas are invalid. The service reads the values from the process environment; local Next.js loads .env and Docker Compose passes it through env_file. There are no hard-coded fallback keys. The .env file stays tracked by this project.

To rotate a key, edit .env and restart the local app. For Docker, recreate the app container with the command below. A later key change does not need an image rebuild. A plain container restart keeps its old environment.

1docker compose up -d --force-recreate app

Keys are read when the server module loads and validated on the first protected request. Missing, duplicate, or malformed settings block access to all protected routes. Database routes return 500 INTERNAL_ERROR. Telemetry raises a server error before its handler runs; this configuration failure does not have a stable API response body. The public health route does not validate keys.

Database identity and URL fields

1{"dir":"prod","filename":"app.db"}

The pair identifies one database. There is no generated ID or per-database key. Both strings must contain valid Unicode. Names are not trimmed or repaired. File name case follows the server filesystem.

Use / between folder names. Absolute paths, leading or trailing slashes, empty path parts, ., .., backslashes, colons, and NUL characters are rejected. A filename cannot contain a slash. Names ending in -wal, -shm, or -journal are reserved, with any letter case.

Paths must stay inside the database root. Symbolic links in database paths and hard links to database or sidecar files are rejected. Text such as ?mode=ro inside a filename stays filename text; it is not a SQLite connection option.

POST accepts exactly these two JSON fields. GET-one and DELETE use exactly one dir and one filename query field. Their order does not matter. Unknown fields, repeated fields, or only one identity field return 400 INVALID_REQUEST. List uses no query fields at all.

URL-encode query values once. The server decodes them once. For a root database, use ?dir=&filename=app.db. A plus sign in a URL query means a space; encode a literal plus as %2B. Use curl --data-urlencode for names with special characters. JSON strings are not URL-decoded.

Database response objects have only dir and filename. They include no generated ID, schema, size, timestamps, key, account data, or absolute server path. Get and list check file paths; they do not run an integrity check or inspect table schemas.

Storage, concurrency, and shutdown

The database root is .data/databases locally and /var/lib/app/databases in Docker. dir is relative to this root. Old files beside it are not imported, exposed, or deleted. Startup creates no metadata database or application tables. The old log/dataset routes are removed and do not redirect to these APIs.

Use one app process per storage folder. The service owns database creation and deletion. Do not replace or edit files externally while it runs. Filesystem case and Unicode behavior can differ between a Mac and Linux; use consistent names in requests.

Database work shares the worker admission limits: 1,000 pending tasks, 10 MiB of estimated task bytes, and a 5-second wait to start. Admin database requests can return queue errors too. Lifecycle calls can also wait for accepted work and connection cleanup, so the queue wait is not a total HTTP timeout.

Graceful shutdown stops accepting new database work, waits for accepted operations, checkpoints writable connections, and closes workers. Docker keeps database files in its named volume. After startup, data remains and memory counters start again. See the repository README for deployment and volume commands.

Database errors

1{"error":{"code":"DATABASE_NOT_FOUND","message":"Database not found","statementIndex":null}}

DB query and Admin database errors have exactly these three fields inside error. Use code to handle an error. Messages use fixed text and omit SQL, keys, parameter values, stack traces, and server file paths. There are no partial results.

statementIndex starts at zero. It identifies the failed statement, including invalid statement input. It is null for request, auth, path, queue, database open, transaction begin or commit, and Admin errors. A rollback failure also returns a null index with INTERNAL_ERROR.

* above includes the primary code and its extended codes. A known extended code is kept, such as SQLITE_CONSTRAINT_UNIQUE. An unknown extended code falls back to its primary code. Telemetry uses the separate string error format shown on the Admin API page.