API reference

Base URL https://api.lakehousebox.com. JSON in, JSON out. Every failure is {"error": {"code", "message", …}} with, where it helps, remedy, field, limit, current, available, retry_after_seconds or attempts_left, and always a request_id to quote when writing to us; unexpected failures are 500 with the same id. Request bodies are limited to 1 MB.

Authentication

Send Authorization: Bearer al_live_… with the API key itself, or a token from POST /v1/tokens (RS256, 900 s), or a token from an identity provider the deployment trusts. There are three kinds of principal: humans (created by signup), agents (created by an organisation admin, optionally confined to warehouses) and the operator. Keys look like al_live_<key id>_<secret>; only the hash is stored; ten wrong secrets for one key id from one address within ten minutes answer 429 with Retry-After.

Words: a catalog in the account page, the CLI and these docs is a warehouse in the API (/v1/warehouses, warehouse_id, my_level); the API keeps that name until a versioned rename adds /v1/catalogs aliases.

The Iceberg catalog at https://catalog.lakehousebox.com and the object store at https://s3.lakehousebox.com are separate surfaces with their own credential, the catalog's catalog_credential from GET /v1/connection. They never accept LakehouseBox API keys.

Idempotency

POST /v1/projects, /v1/warehouses and /v1/tables take an Idempotency-Key header (any string). A replay returns the original response; the same key on a different endpoint is 409 idempotency_key_reused.

Identifiers

Wherever a project_id or warehouse_id is expected, the name you chose is accepted too; an unknown value is a 404 that names both accepted forms and the command that lists them. Two warehouses with one name in different projects make the name ambiguous (409 ambiguous_name with candidates).

Health and identity

GET /.well-known/openid-configuration → 200

OpenID metadata for the tokens this API issues (client_credentials, RS256).

Auth none
Response issuer, jwks_uri, token_endpoint, grant_types_supported

GET /jwks.json → 200

The RS256 public key that verifies tokens from POST /v1/tokens.

Auth none
Response keys[{kty, use, alg, kid, n, e}]

POST /v1/tokens → 200

Exchange an API key for a short-lived bearer token for THIS API. Optional: every authenticated route also accepts the API key itself as the bearer. The Iceberg catalog never accepts either; it takes the warehouse's catalog_credential.

Auth none
Request {"api_key": "al_live_…"}
Response access_token (JWT), token_type: Bearer, expires_in: 900, principal_id
Errors 401 invalid_api_key, 401 api_key_revoked, 401 account_deleted (the account was deleted; WWW-Authenticate: Bearer error="invalid_token"), 403 principal_suspended, 429 rate_limited after 10 wrong secrets for one key id within 600 s (Retry-After header)

GET /healthz → 200

Liveness: the state database answers and the catalog answers /v1/config.

Auth none
Response ok, catalog_ok, issuer, kid

Signup and recovery

POST /v1/signup/start → 202

Step 1 of 2 of the email-code signup: a six-digit code is mailed to the address; nothing is created yet. The signup FORM sends full_name, organization_name and handle too: the organisation is created pending (its handle reserved) and verify activates it. An address on a claimed, open domain joins that organisation instead (will_join).

Auth none
Request {"email": "you@example.com", "workspace"?: "acme", "full_name"?: "Ana Lopez", "organization_name"?: "Acme Labs", "handle"?: "acme-labs"}
Response email, workspace, delivery (email|log), organization{org_id, name, handle, status: pending} (form), will_join{org_id, name, handle} (claimed domain), terms{version, url, privacy_url, note}, next, note, expires_in (600 s), code_length (6)
Errors 400 invalid_value (email; handle: reason invalid|reserved, suggestion), 409 handle_taken (suggestion), 409 already_exists (the address has an account; recover the key instead), 429 rate_limited (5 starts per hour per address; or a code less than 60 s old, with retry_after_seconds), 502 mail_error
CLI lhbox signup --email …

POST /v1/signup/verify → 201

Step 2 of 2: the right code creates the account, its API key, an organisation (owned by you unless an invitation or an open verified domain places you elsewhere), a project named after the workspace, a warehouse named `lake`, and returns the connection recipe.

Auth none
Request {"email": …, "code": "123456", "accept_terms": true, "engine": "duckdb"} (engine: duckdb|pyiceberg|spark, default duckdb)
Response api_key (shown once), api_key_note, principal_id, project_id, warehouse_id, organization{org_id, role, joined_via}, connection{as GET /v1/connection}, next[], terms{version, accepted, url}
Errors 404 no_pending_signup, 410 code_expired, 401 invalid_code (attempts_left; five attempts, then a new code is needed), 400 terms_required (accept_terms must be exactly true), 409 already_exists
CLI lhbox signup --email … --code … --accept-terms --save

POST /v1/signup → 201

The one-call, UNVERIFIED signup for local development stacks. The managed service answers 403 verification_required: use /v1/signup/start + /verify.

Auth none
Request {"email", "workspace", "engine", "accept_terms"}
Response as /v1/signup/verify
Errors 403 verification_required on the managed service

GET /v1/handles/{handle} → 200

Is this organisation handle free? For the signup form as you type (per-address rate limit). Handles: one character, or 3-40 lowercase letters, digits and dashes, starting and ending with a letter or digit; never two dashes in a row (`--` separates the handle from the catalog name in the organisation's storage bucket names, <handle>--<catalog>); app, api, docs, legal, admin, lhbox, www, s3, catalog and auth are reserved.

Auth none
Response handle, valid, available, reason (invalid|double_dash|reserved|taken|null), suggestion (a free handle near it), pattern, note (with reason double_dash: why)
Errors 429 rate_limited

POST /v1/recover/start → 202

Lost API key: a code to the account's email. The answer is identical whether or not the address has an account, so accounts cannot be enumerated here.

Auth none
Request {"email": …}
Response email, delivery (email when a code was mailed; smtp when the address has no account and nothing was sent; log on a development stack), expires_in (600 s), next
Errors 429 rate_limited (same 5/hour/address budget as signup; retry_after_seconds when a code is under 60 s old)
CLI lhbox recover --email …

POST /v1/recover/verify → 200

The right code mints a NEW API key. Earlier keys keep working until revoked.

Auth none
Request {"email": …, "code": "123456"}
Response api_key (shown once), key_id, principal_id, note
Errors 404 no_pending_recovery, 410 code_expired, 401 invalid_code (attempts_left)
CLI lhbox recover --email … --code … --save

Login and sessions

POST /v1/auth/signup → 202

The signup form: a pending account and a pending organisation (handle reserved), and a set-password mail with a link to /app/welcome?token=… valid 3 days. Nothing is usable until the link sets a password. An address with a pending invitation joins the inviting organisation instead (the organisation fields are ignored, nothing is reserved; will_join says so with via: invitation), an address on a claimed and open domain joins that organisation as a member (via: domain); the invitation wins when both apply. The code path for agents and the CLI stays at POST /v1/signup/start.

Auth none
Request {"email": …, "full_name": …, "organization_name": …, "handle": …, "return_to": "/app/…"} (return_to optional: a path under /app/ on this site the welcome page continues to after the password is set, e.g. the device consent screen)
Response 202: email, delivery (email | log), expires_in (259200), organization{org_id, name, handle, status: pending} or will_join{org_id, name, handle, role, via: invitation|domain} + note_join, terms, next, note (when the link went to the log: why), return_to
Errors 400 invalid_value (handle grammar or a reserved word; suggestion carries a free one), 409 handle_taken, 409 already_exists (the address has finished signing up: log in), 429 rate_limited (5 per hour per address; one re-send per minute), 502 mail_error

POST /v1/auth/password/set → 200

The set-password link: verifies the address, stores the argon2id hash, activates the pending organisation with the person as admin (or joins the inviting organisation with the invited role, or the open-domain one as a member -- a joiner provisions nothing: the organisation's default catalog is theirs), records the Terms version the form showed, and returns a session with warehouse{warehouse_id, name, project_id, created} and next.

Auth none
Request {"token": …, "password": …} (12 to 256 characters, not containing the address or the organisation name)
Response access_token (RS256, 15 min, claims sub/email/kind/sid), token_type, expires_in, refresh_token (30 days sliding), refresh_expires_in, session_id, principal_id, principal, organization{…, role, joined_via}, terms, next
Errors 400 password_too_short | password_too_long | password_contains_identity (the link is not spent), 401 invalid_login_token (unknown or already used), 410 token_expired

POST /v1/auth/login → 200

Email and password to a session. The same 401 for an unknown address, a wrong password and an account without a password (a constant-time compare against a dummy hash in every case).

Auth none
Request {"email": …, "password": …}
Response the session shape of POST /v1/auth/password/set
Errors 401 invalid_login, 403 principal_suspended, 429 rate_limited (10 failures per address per hour, retry_after_seconds; 120 attempts per caller address per hour)

POST /v1/auth/refresh → 200

A new access token and a rotated refresh token; the session's expiry slides 30 days. Presenting the refresh token that was just rotated out revokes the whole session (theft signal).

Auth none
Request {"refresh_token": …}
Response the session shape, with the new refresh_token
Errors 401 invalid_refresh_token | refresh_reused | session_revoked | session_expired

POST /v1/auth/logout → 200

Revokes the session, by its refresh token or by the access token in Authorization (sid claim). The access token itself expires within 15 minutes.

Auth none
Request {"refresh_token": …} or Authorization: Bearer <access token>
Response revoked, session_id

GET /v1/auth/sessions → 200

The caller's live sessions: where and when they logged in; `current` marks the one making the call.

Auth Authorization: Bearer <API key or token>
Response sessions[{session_id, created_at, last_used_at, expires_at, user_agent, ip, current}], count

DELETE /v1/auth/sessions/{session_id} → 200

Revokes one of the caller's sessions.

Auth Authorization: Bearer <API key or token>
Response session_id, revoked: true
Errors 404 session_not_found (also for another account's session)

POST /v1/auth/password/reset/start → 202

A 30-minute reset link to /app/reset?token=… by mail. 202 with the same body whether or not the address has an account. An account created through an identity provider that has no password yet gets the same link, which sets its first password.

Auth none
Request {"email": …}
Response email, delivery, expires_in (1800), next
Errors 429 rate_limited (5 per hour per caller address, shared with signup)

POST /v1/auth/password/reset → 200

The reset link: a new password, every session revoked, a notice mailed; returns a fresh session.

Auth none
Request {"token": …, "password": …}
Response the session shape plus sessions_revoked, first_password
Errors 400 password_* (the link is not spent), 401 invalid_login_token, 410 token_expired

POST /v1/auth/password/change → 200

A logged-in human changes their password; every OTHER session is revoked; a notice is mailed.

Auth Authorization: Bearer <API key or token>
Request {"current_password": …, "new_password": …}
Response changed: true, other_sessions_revoked, password_changed_at
Errors 401 invalid_login (wrong current password), 400 password_*, 409 no_password_set (identity-provider account: use the reset link), 403 forbidden (a token has no password)

POST /v1/auth/device → 200

RFC 8628 device authorisation for the CLI, asking for a CONNECTION (docs/agent-setup.md): a device code to poll with and an 8-character user code (no ambiguous glyphs) for the human to approve at /app/device. client_name is the agent the approval creates (default the hostname), requested_level what it asks for (default write), warehouses which catalogs at which level ([{name | warehouse_id, level}], from `login --catalog NAME[:LEVEL]`; resolved within the approver's organisation when the code is read; default the organisation's default catalog at requested_level). warehouse_ids (ids or names, all at requested_level) is the older spelling and still accepted.

Auth none
Request {"client": "cli", "hostname": …, "client_name": …, "requested_level": "read|write", "warehouses": [{"name": …, "level": …}]} (all optional)
Response device_code, user_code (XXXX-XXXX), verification_uri, verification_uri_complete, expires_in (900), interval (5), client_name, requested_level, warehouse_ids, warehouses
Errors 429 rate_limited (60 per hour per caller address), 400 invalid_value
CLI lhbox login [--no-wait]

GET /v1/auth/device/pending → 200

The consent screen's content for a pending code (humans only; nothing is decided by reading it): the agent's name, EVERY catalog of the organisation the caller holds something on -- `requested` marks the ones the CLI named, `level` the level the agent would hold there (the requested one, capped by the caller's own; null when not requested) -- and `requested` as the list the page sends back.

Auth Authorization: Bearer <API key or token>
Request ?user_code=XXXX-XXXX
Response user_code, client, hostname, client_name, requested_level, level, organization, warehouses[{warehouse_id, name, level, my_level, my_via, capped, pending, requested}], requested[{warehouse_id, name, level}], expires_in
Errors 404 device_code_not_found (mistyped, expired or already decided), 403 forbidden (a token), 409 org_required, 404 warehouse_not_found (the CLI named a catalog that is not the caller's), 409 ambiguous_name

POST /v1/auth/device/approve → 200

A logged-in human connects the CLI as an AGENT of the organisation -- a token named after the machine, member role, holding exactly the catalogs and levels chosen in `warehouses` (the consent page's picker; each level capped by the approver's own) -- or refuses it with deny: true. The older pair still works: level lowers the requested level (never raises it), warehouse_ids narrows the set. An organisation without a catalog gets "demo_data" first. The answer is approved, not connected: the agent exists once the machine polls (claimed: false; GET /v1/auth/device/status follows it). Only humans; a token approving would hand out a key of the token.

Auth Authorization: Bearer <API key or token>
Request {"user_code": …, "warehouses": [{"warehouse_id" | "name": …, "level": "read|write"}], "deny": false}
Response approved, claimed: false, user_code, client, hostname, client_name, label, requested_level, connection{name, level, org_id, warehouses[{warehouse_id, name, level}]}, expires_in, note
Errors 404 device_code_not_found (mistyped, expired or already decided), 403 forbidden (a token; or a warehouse the approver holds nothing on), 404 warehouse_not_found, 409 org_required

GET /v1/auth/device/status → 200

Where a CLI login stands, for the page that approved it: pending | approved | denied | used | expired, and `claimed` (the machine collected its key). Approving is not connecting -- the agent is created when the machine polls -- so the page says "waiting for <agent> to pick up its key" until this says claimed. A pending code is visible to any signed-in human (as the consent read is); a decided one only to the human who decided it. `expired` is an approval nobody collected within the code's 15 minutes.

Auth Authorization: Bearer <API key or token>
Request ?user_code=XXXX-XXXX
Response user_code, status, claimed, client, hostname, client_name, expires_in, connection{name, org_id, agent_id (once claimed), warehouses[{warehouse_id, name, level}]} | null
Errors 404 device_code_not_found, 403 forbidden (a token), 400 invalid_value

POST /v1/auth/device/token → 200

The CLI polls until the human decides. The RFC's error names travel as error.code in the usual envelope: authorization_pending (keep polling), slow_down (interval grows by 5 s), expired_token, access_denied. Once approved: the key of the NEW AGENT (never the person's), labelled "cli <hostname>", shown once, with the connection it holds. Revoking the agent revokes the connection.

Auth none
Request {"device_code": …}
Response api_key, key_id, label, principal_id (the agent's), kind: agent, token_type: api_key, connection{agent_id, name, org_id, role, warehouses[{warehouse_id, name, level}], created_by, grants}, note
Errors 400 authorization_pending | slow_down | expired_token | access_denied | invalid_grant
CLI lhbox login | lhbox login --resume [--wait]

Remote MCP: OAuth 2.1 authorization server

GET /.well-known/oauth-authorization-server → 200

RFC 8414 metadata an MCP host reads to authorise against the remote MCP server: issuer, authorization/token/revocation endpoints, jwks_uri, scopes_supported, code + PKCE S256 only, public clients (token_endpoint_auth_methods_supported: none), Client ID Metadata Documents supported, iss on authorization responses, and the deprecated registration_endpoint while dynamic registration is on.

Auth none
Response issuer, authorization_endpoint, token_endpoint, revocation_endpoint, jwks_uri, registration_endpoint, scopes_supported, response_types_supported [code], grant_types_supported [authorization_code, refresh_token], code_challenge_methods_supported [S256], token_endpoint_auth_methods_supported [none], client_id_metadata_document_supported, authorization_response_iss_parameter_supported

GET /.well-known/jwks.json → 200

The RS256 public key(s) that verify every token this API signs (kid on every key and every token; two keys during a rotation). The same document as GET /jwks.json, at the path the MCP server's token verifier uses.

Auth none
Response keys[{kty, use, alg, kid, n, e}]

GET /oauth/authorize → 200

The authorization endpoint. The MCP host opens the person's browser here; the client is identified by a Client ID Metadata Document (client_id = its https URL, fetched server-side behind an SSRF guard and cached) or a registered client_id. redirect_uri must be one the client lists (exact; loopback on any port), response_type=code, code_challenge + code_challenge_method=S256 and resource (the MCP server's URL) are required. A bad client or redirect_uri is a 400 (never a redirect); every other error is a 302 to the redirect_uri with error, error_description, state and iss. On success: 302 to the consent page (/app/authorize?request=<id>), where the logged-in person decides.

Auth none
Request ?client_id=<https URL or dcr_…>&redirect_uri=…&response_type=code&code_challenge=…&code_challenge_method=S256&resource=<MCP server URL>&scope=<space-separated>&state=…
Response 302 to the consent page, or 302 to redirect_uri with error (unsupported_response_type, invalid_request, invalid_target, invalid_scope), state, iss
Errors 400 invalid_client (unknown client, or a metadata document that is not https, names a private or local address, redirects to another host, exceeds 64 KiB, is not JSON or does not match), 400 invalid_request (redirect_uri not registered), 429 rate_limited (120 per hour per address). Flat RFC 6749 shape: {error, error_description}

GET /v1/oauth/authorize/pending → 200

The consent page's content for a pending authorization (a logged-in human, via a session): who is asking (client_name, client_uri, logo_uri, the host of its metadata URL, how it registered), the scopes as sentences, the MCP server the token is for, the organisation and the catalogs the person may grant with the level proposed (capped by their own), and the token record already bound to this client if any (the picker's initial state). Nothing is decided by reading it.

Auth Authorization: Bearer <API key or token>
Request ?request_id=<from the consent page URL>
Response request_id, expires_at, expires_in, client{client_id, client_name, client_uri, logo_uri, host, registration (cimd|dynamic)}, scopes[], scope, scope_descriptions{}, resource, redirect_host, person{}, organization{org_id, name, handle, role}, warehouses[{warehouse_id, name, my_level, my_via, level, granted, default}], existing{agent_id, name, role, grants} | null, organizations[], default_org_id
Errors 404 oauth_request_not_found, 410 oauth_request_expired (15 minutes), 410 oauth_request_decided, 403 session_required (an API key instead of a login session), 403 forbidden (a token), 409 org_required

POST /v1/oauth/authorize/decision → 200

The logged-in human allows or denies. Allowing creates a TOKEN RECORD of kind mcp in the organisation -- or reuses the one bound to (you, client_id) and replaces its grants -- named after the client and you, holding exactly the grants chosen (each capped by your own level; a catalog you hold nothing on is refused), member role unless you are an admin and ask otherwise; then mints a single-use authorization code (10 minutes). The token appears in the organisation's tokens list and is revoked there, which ends its refresh and access tokens at once.

Auth Authorization: Bearer <API key or token>
Request {"request_id": …, "allow": true, "grants": [{"warehouse_id": …, "level": "read|write"}], "org_id"?: …, "role"?: "member|admin"} or {"request_id": …, "allow": false}
Response allowed, redirect_to (the client's redirect_uri with code, state and iss; on deny error=access_denied, state, iss), client{}, scope[], expires_in, token{agent_id, name, org_id, role, kind: mcp, grants[], capped[], reused, connection{}}, note
Errors 404 oauth_request_not_found, 410 oauth_request_expired | oauth_request_decided, 403 session_required, 403 forbidden (a token; or a catalog you hold nothing on), 403 insufficient_role (a member asking for an admin token), 404 warehouse_not_found | org_not_found, 409 org_required, 429 rate_limited

POST /oauth/token → 200

The token endpoint (form-encoded or JSON; public clients send client_id, never a secret). grant_type=authorization_code with code, code_verifier (PKCE S256), client_id, redirect_uri and resource -> an RS256 access token for the MCP server (aud = resource, sub = the mcp token record, act.sub = the person, scope, client_id, kind mcp, 15 minutes) and a refresh token (30 days sliding). A code is single use; presenting it twice revokes the tokens it produced. grant_type=refresh_token with refresh_token and client_id -> a new pair, the refresh token rotated; presenting the rotated-out one again revokes the whole family. A narrower scope may be asked for on refresh.

Auth none
Request grant_type=authorization_code&code=…&code_verifier=…&client_id=…&redirect_uri=…&resource=… or grant_type=refresh_token&refresh_token=…&client_id=…[&scope=…]
Response access_token (JWT), token_type: Bearer, expires_in (900), refresh_token, refresh_expires_in, scope
Errors RFC 6749 §5.2 flat shape {error, error_description}: 400 invalid_request | invalid_grant (unknown, used, expired or foreign code; wrong verifier; unknown, rotated, revoked or expired refresh token; the token record revoked) | invalid_scope | invalid_target | unsupported_grant_type, 401 invalid_client, 429 rate_limited

POST /oauth/revoke → 200

RFC 7009: a client that logs out revokes its refresh token (or an access token, whose session is revoked: every access token of that session is then refused by the API and its refresh token is dead). 200 with {} whatever the token, as the RFC says. The person's own revocation is the tokens list on the account page.

Auth none
Request token=…[&token_type_hint=refresh_token|access_token]
Response {}

POST /oauth/register → 201

RFC 7591 dynamic registration, the DEPRECATED fallback for hosts that cannot publish a Client ID Metadata Document. Public clients only: https redirect URIs, loopback http on any port, or a native app's private-use scheme. Registrations unused for 90 days are pruned. Off when AL_OAUTH_ALLOW_DCR is false.

Auth none
Request {"client_name": …, "redirect_uris": […], "grant_types"?: [authorization_code, refresh_token], "response_types"?: [code], "token_endpoint_auth_method"?: "none", "client_uri"?, "logo_uri"?, "application_type"?: "web|native", "software_id"?}
Response 201: client_id (dcr_…; no secret), client_id_issued_at, client_name, redirect_uris, grant_types, response_types, token_endpoint_auth_method: none, application_type, client_uri, logo_uri, software_id, note
Errors 400 invalid_client_metadata | invalid_redirect_uri, 403 access_denied (registration disabled), 429 rate_limited (20 per hour per address)

Projects and catalogs (warehouses in the API)

POST /v1/projects → 201

A project is the placement boundary: provider and region are fixed at creation and never change. Today there is one placement: hetzner, the deployment's own region.

Auth Authorization: Bearer <API key or token>
Request {"name": …, "provider"?, "region"?, "org_id"?} Header Idempotency-Key: any string
Response project_id, name, provider, region, placement_immutable: true, org_id
Errors 409 already_exists (name in use by you; project_id in the body), 400 unsupported_placement (available[]), 400 org_required (you belong to several organisations), 404 org_not_found, 409 idempotency_key_reused
CLI lhbox project create --name …

GET /v1/projects → 200

Projects you own or reach through an organisation you belong to.

Auth Authorization: Bearer <API key or token>
Response projects[{project_id, name, provider, region, org_id, created_at}]
CLI lhbox project list

POST /v1/warehouses → 201

A warehouse is one Iceberg catalog: one table bucket named <organisation handle>--<catalog name, _ mapped to -> (overture--data; u-<8 hex of the principal id>--<catalog> outside an organisation) plus one storage identity confined to it by the catalog. Also a blob bucket (<handle>--<catalog>--blobs) for non-Iceberg files. Catalogs created before 2026-09-20 keep w-<uuid> / b-<uuid>; the response and every row name the buckets as they are (bucket, blob_bucket). Bucket names are DNS names of at most 63 characters, so the catalog name is bounded per handle (400 name_too_long_for_bucket says the maximum) and may not end in _; catalog names are unique per organisation (docs/permissions-and-access.md, "Names").

Auth Authorization: Bearer <API key or token>
Request {"project_id": <id or name>, "name": …, "default_format_version": 2} (2 default, or 3: the Iceberg format version LakehouseBox's own create paths -- POST /v1/tables without format_version, the MCP create_table tool, table import -- give new tables here; an engine's own CREATE TABLE is honoured as sent) Header Idempotency-Key
Response warehouse_id, name, project_id, project, provider, region, catalog_uri, warehouse (s3://<bucket>/), warehouse_name (the table bucket), bucket, blob_bucket, default_format_version, maintenance{compaction: true, target_file_size_mb: 128, snapshot_retention_days: 7, max_snapshots: 20, disableable: false}, storage_measurement{status: scheduled, in_seconds: 120, then} (the control plane measures the new catalog itself ~2 minutes after creation; until then its storage rows say measuring: true), status: ready | provisioning, storage_probe{table, blob, seconds} (provision = allocate: creation ends with a tenant-signed PUT + DELETE of a 0-byte object in each bucket -- 'ok', or the store's status and words, e.g. '500 InternalError ...'; on any refusal the catalog IS created and answers status: provisioning with retry_after_seconds: 30 and a remedy; the control plane retries every 30 s for 10 min and flips it to ready; GET /v1/connection answers 503 provisioning until then)
Errors 400 invalid_name (not a SQL-friendly name, or a name ending in _ whose bucket would end in -; suggestion), 400 name_too_long_for_bucket (the mapped bucket would exceed 63 characters; max_name_length for this owner, bucket_would_be), 400 invalid_value (default_format_version not 2 or 3; versions{} says who writes each), 409 already_exists (the name in this project, or in another project of the organisation: bucket, warehouse_id), 409 name_reserved_until_teardown (a deleted catalog of that name is still tearing down; poll, Retry-After 5), 409 bucket_leftover_from_deletion (a finished teardown left the bucket at the store; an operator removes it), 409 creation_in_progress (the same bucket is being provisioned right now; Retry-After 5), 409 limit_exceeded (warehouses per project; limit_value, current), 409 quota_exceeded (the organisation is over its storage limit; current, limit_value, scope), 404 project_not_found, 502 storage_error (safe to retry with the same idempotency key)
CLI lhbox catalog create <name> [--project …] [--default-format-version 2|3]

POST /v1/warehouses/{warehouse_id}/rotate → 200

Replace both of the warehouse's catalog credentials (the read/write identity t-<uuid> and the read-only t-<uuid>-ro). Each new key is issued before the old one is deleted, so there is never a moment without a working key. The old READ/WRITE key is deleted before the answer: it and every catalog token minted from it are refused at once. The old READ-ONLY key (it could only read) is deleted by the background worker right after the answer -- one IAM write, about 10 s at the host's current identity count, later only if a catalog deletion's teardown is queued ahead of it -- and audited as warehouse.rotate_complete. Storage sessions already vended run out on their own within 900 s. Why the split: every IAM write costs the store a 10 s propagation deadline.

Auth Authorization: Bearer <API key or token>
Response warehouse_id, warehouse_name, catalog_credential{client_id, client_secret}, catalog_credential_ro{client_id, client_secret}, previous_client_id, previous_revoked, previous_client_id_ro, previous_revoked_ro (false at the answer), previous_ro_revocation{status: queued, audit, expected}, rotated_at, note, warning (only if the old read/write key could not be deleted)
Errors 404 warehouse_not_found, 409 ambiguous_name (two warehouses share the name; candidates[])
CLI lhbox catalog rotate <name or id>

DELETE /v1/warehouses/{warehouse_id} → 202

Delete a warehouse for good, with its name typed in the body. Irreversible, in two steps. Before the 202: the catalog is gone for every caller and out of every list, every grant on it is revoked, its usage samples go, a public warehouse's anonymous-read policy is removed, warehouse.delete is audited. In the background (usually within a minute; one worker, so a queue of deletions runs in turn): tables dropped as the tenant, both buckets and the identities (the read-only one where it was ever needed) with their policies removed, then warehouse.delete_complete with the table count and every storage step, and the tombstone GET /v1/warehouses/{id} reports (404, state deleting -> deleted, the counts). Until the teardown reaches the identities, a recipe already in an engine's hands can still reach the catalog and the bucket directly. Why: every IAM write costs the store a 10 s propagation deadline and this route made six of them while the person waited. The nightly backup copy ages out within its retention window (14 days).

Auth Authorization: Bearer <API key or token> — admin of the organisation
Request {"confirm": "<the warehouse name, exactly>"}
Response 202 status: deleting, warehouse_id, name, project_id, bytes_at_deletion, measured_at, grants_removed, usage_samples_removed, tables_dropped: null, storage: null, storage_complete: null, poll (GET /v1/warehouses/{id}), note
Errors 400 confirmation_required (confirm_with names the expected value), 403 forbidden (not an admin), 404 warehouse_not_found, 404 warehouse_deleted (state, counts: already gone), 409 delete_in_progress (Retry-After: 5; the teardown is running)
CLI lhbox catalog delete <name> --confirm

POST /v1/warehouses/{warehouse_id}/uploaders → 201

A write-only credential for the catalog's blob bucket (<handle>--<catalog>--blobs; b-<uuid> on older catalogs; the answer's `bucket`), for a relay, a camera, a field device or a partner that only drops files: one IAM identity u-<warehouse_uuid>-<short> whose policy allows exactly s3:PutObject on arn:aws:s3:::<blob bucket>/<prefix>* (single and multipart uploads) and, only with list: true, s3:ListBucket on the blob bucket conditioned on s3:prefix <prefix>* (the device must list with ?prefix=). Nothing on the table bucket, no reads, no deletes, no catalog access (a catalog token minted from the pair is refused). The secret is in this answer once and is never stored. Cost: 2 IAM writes at the store (CreateUser, CreateAccessKey), each a propagation deadline of up to 10 s at the host's current identity count, plus the two statements merged into the blob bucket's policy (an S3 call); nothing is re-put later.

Auth Authorization: Bearer <API key or token> — write level on the catalog
Request {"name": …, "prefix"?: "photos/2026/", "list"?: false, "expires_at"?: null}
Response uploader_id, warehouse_id, warehouse_name, name, prefix, list, iam_user, access_key_id, secret_access_key (once), endpoint, bucket, region, scope, policy, iam_writes, expires_at, created_at, created_by, status, recipe{aws_cli, python_boto3, curl_presign_note}, note
Errors 400 bad_name / invalid_value (prefix grammar, list, expires_at), 403 forbidden (read level), 404 warehouse_not_found, 409 already_exists (an active uploader of that name), 502 storage_error
CLI lhbox catalog uploader create <catalog> --name relay --prefix photos/ [--list] (--save FILE | --show-key)

GET /v1/warehouses/{warehouse_id}/uploaders → 200

The catalog's uploaders without their secrets (never stored); revoked ones only with ?include_revoked=true.

Auth Authorization: Bearer <API key or token> — read level on the catalog
Response warehouse_id, warehouse_name, bucket, count, uploaders[{uploader_id, name, prefix, list, iam_user, access_key_id, created_by, created_at, expires_at, revoked_at, status: active|expired|revoked}], note
Errors 404 warehouse_not_found
CLI lhbox catalog uploader list <catalog> [--all]

DELETE /v1/warehouses/{warehouse_id}/uploaders/{uploader_id} → 200

Revoke an uploader (by id or name): its access key is deleted at the store FIRST, so every request signed with it is refused from then on (a multipart upload in flight cannot complete), then its statements come off the blob bucket's policy and its identity is deleted: 2 IAM writes before the answer (3 for an uploader made before 2026-09-21, whose inline policy is deleted too). Idempotent: a revoked uploader answers 200 with already_revoked and retries whatever step is still pending. A catalog's deletion removes its uploaders' identities too.

Auth Authorization: Bearer <API key or token> — write level on the catalog
Response the uploader's row (status: revoked, revoked_at), revoked, already_revoked, storage{access_key, bucket_policy | user_policy, user}, iam_writes, note, warning (only if the key could not be deleted)
Errors 403 forbidden (read level), 404 warehouse_not_found / uploader_not_found
CLI lhbox catalog uploader revoke <catalog> --uploader <id|name>

POST /v1/sinks → 201

An ingest sink for ONE existing, unpartitioned table: producers without an engine POST JSON arrays to its send route with the send-only key this answer shows once; the roller appends what is waiting to the table every roll_seconds (default 300, floor 60), or sooner when roll_bytes (32-64 MiB) or inactivity_seconds say so, stamping __ingest_ts. One sink per table. No IAM write and no catalog commit at creation: the first roll adds the optional __ingest_ts column and the metadata-retention properties. The send key is a hash on the sink row, never a principal: it can neither become a token nor hold a grant.

Auth Authorization: Bearer <API key or token> — write level on the catalog
Request {"name": …, "table": "<ns>.<table>", "warehouse": "<id or name>", "roll_seconds"?: 300, "roll_bytes"?: 67108864, "inactivity_seconds"?: null}
Response sink_id, name, table, warehouse_id, warehouse_name, bucket, state, roll{seconds, bytes, inactivity_seconds, count}, prefix, ingest_url, send_url, send_key (once), send_key_id, table_changes{add_column, partition: none, properties, applied}, lag{}, received{}, rejects{}, iam_writes: [], created_at, note
Errors 400 bad_name / invalid_value, 403 forbidden (read level), 404 warehouse_not_found / table_not_found (with the namespace's tables), 409 sink_exists / already_exists / partitioned_table_unsupported, 404 not_found while sinks are off
CLI lhbox sink create <catalog> --table <ns>.<table> [--roll-seconds 300] [--roll-bytes N] [--inactivity-seconds N] (--save FILE | --show-key)

GET /v1/sinks → 200

The sinks of every catalog the caller can see (or of one with ?warehouse=), with lag, last roll and rejects; never a key. ?include_deleted=true adds the deleted ones.

Auth Authorization: Bearer <API key or token> — read level
Response count, sinks[{sink_id, name, table, warehouse_id, state, disabled_reason, roll{}, prefix, lag{batches_waiting, bytes_waiting, oldest_waiting_at, seconds_behind}, received{}, last_roll{}, rejects{}, created_at}], note
Errors 404 warehouse_not_found
CLI lhbox sink list [--catalog <id or name>]

GET /v1/sinks/{sink_id} → 200

One sink by id or name: state, roll policy, lag (bytes and batches waiting, seconds behind), last roll (at, batches, rows, rejected_rows, snapshot_id, seconds), rejects counters and where the rejects files are, totals received.

Auth Authorization: Bearer <API key or token> — read level on its catalog
Response the sink's row as in GET /v1/sinks plus warehouse_name, bucket
Errors 404 sink_not_found, 409 ambiguous_name
CLI lhbox sink get <sink id or name>

DELETE /v1/sinks/{sink_id} → 202

Delete a sink: its send key is refused from now on, batches still waiting are discarded (the roller purges the intake prefix on its next tick; rejects files age out after 7 days), the table is untouched. 202.

Auth Authorization: Bearer <API key or token> — write level on its catalog
Response the sink's row (state: deleted, deleted_at), pending_batches_discarded, note
Errors 403 forbidden (read level), 404 sink_not_found
CLI lhbox sink delete <sink id or name> [--discard-pending]

POST /v1/sinks/{sink_id} → 202

The send route. Body: a JSON array of objects (<= 16 MiB); header Idempotency-Key: the batch id (1-128 chars of A-Z a-z 0-9 . _ : -). Each element's bytes are stored unchanged, one per line, as ONE NDJSON object under _sink/<sink_id>/<batch_id>.ndjson in the catalog's blob bucket, written as the catalog's own identity: no IAM write, no catalog call, one small S3 PUT. The same batch id again answers 200 duplicate without writing. Elements that are not objects are rejected here (reasons[]); whether a row fits the table's schema is decided at the roll and shows in GET /v1/sinks/{id} rejects. Intake bytes are metered as ingest_bytes (GET /v1/usage), not as storage.

Auth Authorization: Bearer <API key or token> — an API key or a token here is 403 send_only
Request [ {…}, {…}, … ] with headers Authorization: Bearer <send_key>, Idempotency-Key: <batch id>, Content-Type: application/json
Response 202 {accepted, rejected, reasons[{index, reason, got}], batch_id, sink_id, bytes, received_at, state: pending, note} | 200 {duplicate: true, batch_id, accepted, rejected, bytes, received_at, state: pending|committed}
Errors 400 not_an_array / empty_batch / missing_idempotency_key / invalid_batch_id, 401 invalid_key, 403 send_only, 404 sink_not_found (deleted), 409 sink_disabled / quota_exceeded, 413 batch_too_large, 502 storage_error (safe to retry with the same batch id)
CLI lhbox sink send <sink id> batch.json [--batch-id <id>]

POST /v1/warehouses/{warehouse_id}/public → 200

Make a warehouse PUBLIC at the storage level: admin only, the warehouse name typed in the body. One plain bucket policy lets anyone read every object (data files and all retained metadata) with no credentials; writes stay refused and the catalog stays private. Its bytes move to the 50 GB public tier; 409 quota_exceeded (tier public) when that would overflow.

Auth Authorization: Bearer <API key or token>
Request {"confirm": "<the warehouse name, exactly>"}
Response warehouse_id, name, project_id, public: true, public_since, public_url, public_note, public_by, policy, tier: public, public_storage_bytes{…}, public_read{…}, bucket_quotas{quotas, errors}, note
Errors 400 confirmation_required, 403 forbidden (not an admin), 404 warehouse_not_found, 409 quota_exceeded (tier public)
CLI lhbox catalog publish <name> --confirm

DELETE /v1/warehouses/{warehouse_id}/public → 200

Make a public warehouse private again: admin only. The bucket policy is removed and anonymous reads are refused at once; bytes return to the private tier.

Auth Authorization: Bearer <API key or token>
Response warehouse_id, name, project_id, public: false, public_since: null, public_url: null, was_public, policy_removed, tier: private, storage_bytes{…}, bucket_quotas{quotas, errors}, note
Errors 403 forbidden (not an admin), 404 warehouse_not_found
CLI lhbox catalog unpublish <name>

PUT /v1/warehouses/{warehouse_id}/lifecycle → 200

Set the S3 lifecycle rules of the catalog's BLOB bucket (never the table bucket), replacing what was configured: each rule expires the objects under a prefix after N days (24 h each from the object's last write) or on a date, and/or aborts multipart uploads not completed after N days. The control plane writes the S3 LifecycleConfiguration XML and PUTs it as the tenant (the blob-bucket policy written at creation grants exactly that), then reads it back. The store's lifecycle worker passes daily and after every restart: deletion up to 24 h after an object is due, permanent; the storage meter follows at the next hourly sample or POST …/measure. Refused before the store sees it: expire_days 0 (the store accepts it and never fires it), any transition (no storage classes: 501 at the store), unknown fields, more than 1000 rules or 1 MiB. Tag and size filters are boto3's with the catalog credential; GET parses them back.

Auth Authorization: Bearer <API key or token> — write level on the catalog
Request {"rules": [{"id"?: "camera-90d", "prefix"?: "camera/", "expire_days"?: 90, "expire_date"?: "2026-12-31", "abort_incomplete_multipart_days"?: 7, "enabled"?: true}, …]}
Response warehouse_id, name, bucket (the blob bucket), configured: true, rules[{id, prefix, enabled, expire_days, expire_date, abort_incomplete_multipart_days, expressible}], count, xml_bytes, note
Errors 400 invalid_value (expire_days 0 or not a whole number, both expiry forms, unknown field with `accepted`, duplicate ids, empty rules, the prefix grammar) / not_supported (a transition), 403 forbidden (read level), 404 warehouse_not_found, 413 too_large (over 1 MiB of XML), 502 storage_error
CLI lhbox catalog lifecycle set <catalog> --prefix camera/ --expire-days 90 [--abort-multipart-days 7]

GET /v1/warehouses/{warehouse_id}/lifecycle → 200

The lifecycle rules configured on the catalog's blob bucket, read from the store as the tenant and parsed back -- rules set with boto3 included: tags, size_greater_than / size_less_than and `other` (a Disabled Transition, NoncurrentVersionExpiration) appear on the rule and `expressible` says whether PUT here could re-create it. configured: false with an empty list when none is set. ?include_xml=true adds the stored document verbatim.

Auth Authorization: Bearer <API key or token> — read level on the catalog
Response warehouse_id, name, bucket, configured, rules[…], count, note, xml (only with ?include_xml=true)
Errors 404 warehouse_not_found, 502 storage_error
CLI lhbox catalog lifecycle get <catalog> [--xml]

DELETE /v1/warehouses/{warehouse_id}/lifecycle → 200

Remove every lifecycle rule from the catalog's blob bucket (DELETE ?lifecycle as the tenant). Idempotent: 200 with had_rules false when none was configured. Objects a rule already deleted are gone.

Auth Authorization: Bearer <API key or token> — write level on the catalog
Response warehouse_id, name, bucket, configured: false, had_rules, rules_removed, rules: [], count: 0, note
Errors 403 forbidden (read level), 404 warehouse_not_found, 502 storage_error
CLI lhbox catalog lifecycle clear <catalog>

GET /v1/warehouses/{warehouse_id}/grants → 200

Who holds what on the warehouse: explicit grants and the implicit ones (admins write via admin, members read via membership, the creator write via creator, a legacy unconfined agent write via agent). A level of none is a membership read an admin revoked for this warehouse.

Auth Authorization: Bearer <API key or token> — any member of the organisation
Response [{principal_id, kind, display, level (read|write|none), via, granted_by, granted_at}]
Errors 404 warehouse_not_found
CLI lhbox catalog grants <name or id>

PUT /v1/warehouses/{warehouse_id}/grants/{principal_id} → 200

Grant read or write on a warehouse to a member or an agent of the organisation. A read grant yields read-only catalog and storage credentials (t-<uuid>-ro); a write grant the read/write ones.

Auth Authorization: Bearer <API key or token> — admin, or a human holding write (granting at most their own level)
Request {"level": "read"|"write"}
Response warehouse_id, principal_id, kind, display, level, via, granted_by
Errors 400 invalid_value, 403 forbidden (level, can_grant[]), 404 principal_not_found (not in this organisation)
CLI lhbox catalog grant <name or id> --principal … --level read|write

DELETE /v1/warehouses/{warehouse_id}/grants/{principal_id} → 200

Revoke a grant. Revoking a member's implicit membership read records level none for this warehouse; an admin's implicit write cannot be revoked (change their role).

Auth Authorization: Bearer <API key or token> — admin, or the person who made the grant
Response warehouse_id, principal_id, kind, display, revoked{level, via}, level, via
Errors 403 forbidden, 404 grant_not_found, 409 implicit_grant
CLI lhbox catalog revoke <name or id> --principal …

GET /v1/warehouses → 200

The catalogs you can see, ids and names side by side: every catalog of your organisation(s) and of the projects you own (a member token: exactly the catalogs it was granted), or those of one project with ?project=. Each row carries its project_id.

Auth Authorization: Bearer <API key or token>
Request ?project=<id or name> (optional)
Response project, project_id (null without ?project), catalog_uri, warehouses[{name, warehouse_id, warehouse (s3://<bucket>/), bucket, blob_bucket (the two storage bucket names as they are: <handle>--<catalog> and …--blobs, or w-/b-<uuid> on older catalogs), project_id, project, created_at, my_level (read|write|none), my_via, status (ready | provisioning: its storage has not accepted a write yet), default_format_version (2|3), stored{bytes, table_bytes, blob_bytes, objects, blob_objects, complete, measured_at, stale_after (when the hourly sweep will have replaced the figure), source: sweep|creation|on_demand, unmetered, measuring (no sample yet and the first measurement is on its way)}, public, public_since, public_url}], count, limit (per project), headroom (null without ?project)
Errors 404 project_not_found
CLI lhbox catalog list [--project …]

GET /v1/warehouses/{warehouse_id} → 200

One catalog by id or by name: the same row as the list, plus the bucket name and placement.

Auth Authorization: Bearer <API key or token>
Request the path holds the warehouse_id or the catalog's name
Response name, warehouse_id, warehouse (s3://<bucket>/), warehouse_name (the table bucket), bucket, blob_bucket, project_id, project, created_at, my_level, my_via, status (ready | provisioning), default_format_version (2|3), stored{bytes, table_bytes, blob_bytes, objects, blob_objects, complete, measured_at, stale_after, source, unmetered, measuring}, public, public_since, public_url (public_note while public), catalog_uri, provider, region
Errors 404 warehouse_not_found (not yours; a member token: no grant on it), 404 warehouse_deleting / warehouse_deleted (a catalog you could see, by id: state, requested_at, completed_at, tables_dropped, bytes_at_deletion, grants_removed, usage_samples_removed, storage{step: ok|HTTP n}, storage_complete, tables_refused -- the counts once the background teardown has run), 409 ambiguous_name (two catalogs of that name: candidates[] lists their ids)
CLI lhbox catalog get <name or id>

PATCH /v1/warehouses/{warehouse_id} → 200

Change a catalog's settings: today default_format_version (2|3), the Iceberg format version LakehouseBox's OWN create paths give a new table -- POST /v1/tables without format_version, the MCP create_table tool, table import. An engine's own CREATE TABLE is honoured as sent, never upgraded; existing tables are unchanged. Sending the value already set changes and audits nothing. Audited as warehouse.update (changes, previous).

Auth Authorization: Bearer <API key or token> — admin or a write holder on the catalog
Request {"default_format_version": 3} (the path holds the warehouse_id or the catalog's name)
Response the row of GET /v1/warehouses/{id} (name, warehouse_id, warehouse, warehouse_name, project_id, project, created_at, my_level, my_via, default_format_version, the public fields, catalog_uri) plus updated[] (the fields that changed), previous{default_format_version}, format{writers[], readers[], note} for the default now in force, note
Errors 400 missing_field (empty body), 400 invalid_field (a setting other than default_format_version; accepts[]), 400 invalid_value (not 2 or 3; versions{} says who writes each), 403 forbidden (read level; can_grant[] names who can), 404 warehouse_not_found, 409 ambiguous_name
CLI lhbox catalog update <name or id> --default-format-version 2|3

POST /v1/warehouses/{warehouse_id}/measure → 200

Measure the catalog's storage NOW instead of waiting for the hourly sweep: bytes and objects of its table bucket and its blob bucket (both as the row names them), listed as the tenant, summed and stored as a usage sample (source: on_demand) that GET /v1/usage, GET /v1/warehouses and the account page show until the sweep's next sample. Why it exists: the sweep lists warehouses at its start and measures each once an hour, so a load that landed after a catalog's sample read the old figure for up to an hour (2026-09-20: 1,818 bytes for 63 minutes after a 2.9 GB load). Same objects as the sweep counts, two differences stated in `note`: taken before the sweep's snapshot expiry and compaction, and a dropped table's files count until they are purged. Quota enforcement (the bucket quota, the 409s) still follows the sweep's sample. At most 50 listing pages (50,000 objects) per bucket: past that partial: true and bytes is a lower bound. Once a minute per catalog. Audited as warehouse.measure.

Auth Authorization: Bearer <API key or token> — read level on the catalog
Request the path holds the warehouse_id or the catalog's name; no body
Response name, warehouse_id, measured_at, stale_after (measured_at + the sweep interval), source: on_demand, bytes, table_bytes, blob_bytes, objects, blob_objects, complete, partial, pages, page_cap, blob_bucket: listed|unprovisioned, seconds, tier, storage{current, limit, headroom, measured_at, stale_after, over_limit, …}, public_storage{…}, bucket_quotas{…}, note
Errors 404 warehouse_not_found (not yours; a member token: no grant on it), 409 ambiguous_name, 429 rate_limited (retry_after_seconds; Retry-After header: measured less than a minute ago -- read the figure from GET /v1/usage), 502 storage_error (the listing was refused; safe to retry at once, no rate-limit mark is set)
CLI lhbox catalog measure <name or id>

Tables, credentials and connection recipes

POST /v1/tables → 201

Create an Iceberg table through the catalog, as the warehouse's own identity. The namespace is created on demand. Engines can also create tables directly (DuckDB CREATE TABLE, PyIceberg create_table); this route exists for a schema with field ids, identifier fields and a chosen format version.

Auth Authorization: Bearer <API key or token>
Request {"warehouse_id": <id or name>, "namespace": …, "name": …, "schema": <Iceberg struct schema JSON>, "format_version": 3} (optional: 2 or 3; WITHOUT it the catalog's default_format_version applies, 2 unless changed with PATCH /v1/warehouses/{id}; geometry/geography columns need 3; GET /v1/config/formats says which engines write each) Header Idempotency-Key
Response table (ns.name), warehouse_id, warehouse, namespace, name, table_uuid, location, format_version (the real one), format_version_requested, format_version_source (request | catalog_default), format_version_honoured, writers[], readers[], note (who writes and who only reads that version, from GET /v1/config/formats); for v3 also warnings[] and v3_columns[{name, type}] when the schema has geometry/geography columns
Errors 400 missing_field, 400 invalid_value (format_version not 2 or 3: versions{} says who writes each; or a geometry/geography column with an effective format version of 2: remedy says --format-version 3, catalog update --default-format-version 3, or WKB in a binary column), 404 warehouse_not_found, 409 quota_exceeded (over the storage limit), 4xx/502 catalog_error (catalog_status, catalog_type, catalog_message)
CLI lhbox table create --catalog … --namespace … --name … --column name:type …

GET /v1/namespaces → 200

Namespaces in a catalog, read from the catalog service.

Auth Authorization: Bearer <API key or token>
Request ?warehouse=<id or name> (warehouse or warehouse_id: both spellings name the catalog, by id or by name, on every route below)
Response warehouse, warehouse_id, namespaces[{namespace}]
CLI lhbox namespace list --catalog …

GET /v1/tables → 200

Every table in a catalog, or in one namespace.

Auth Authorization: Bearer <API key or token>
Request ?warehouse=<id or name>&namespace=<optional> (or warehouse_id=)
Response warehouse, warehouse_id, namespaces_searched[], tables[{namespace, name, table}]
Errors 404 namespace_not_found (available[])
CLI lhbox table list --catalog … [--namespace …]

GET /v1/table → 200

Schema, the real format version and counts, read from the table's current metadata. rows is NET of delete files: the snapshot summary's total-records minus its position and equality delete counts when the writer left them, else counted from the manifest list and the delete manifests (rows_source says which path). Position deletes remove one row each, so the net is exact; with equality deletes (predicates) rows_is_exact is false and rows_note says why. identifier_field_ids are not a primary key: the catalog accepts duplicate rows.

Auth Authorization: Bearer <API key or token>
Request ?warehouse=<id or name>&namespace=…&name=… (or warehouse_id=)
Response table, namespace, name, warehouse, warehouse_id, table_uuid, location, format_version, schema[{id, name, type, required}], identifier_field_ids[], partition_spec, snapshots, current_snapshot_id, rows, data_files, delete_files, rows_source (snapshot_summary | snapshot_summary_net_of_deletes | manifest_list | manifests | manifests_net_of_deletes | no_snapshot | no_manifest_list), rows_is_exact; when delete files exist also rows_gross, position_delete_rows, equality_delete_rows and, if inexact, rows_note; writers[], readers[], note (who writes and who only reads the version the table has, from GET /v1/config/formats); warnings[] for v3; properties{} (the table's Iceberg properties: format-version, geo.* for an imported GeoParquet, whatever PATCH /v1/table set)
Errors 404 namespace_not_found, 404 table_not_found (available[])
CLI lhbox table get --catalog … --namespace … --name …

PATCH /v1/table → 200

Set and/or remove table properties: ONE commit through the catalog (Iceberg REST commitTable with set-properties / remove-properties, as the catalog's own identity), visible to every engine on its next load. Write holders only; audited table.update with the previous values. `lhbox table import` uses it to keep a GeoParquet's `geo` metadata as geo.encoding, geo.crs, geo.columns, geo.primary_column (the convention in docs/engines). The format version is not a property this route changes.

Auth Authorization: Bearer <API key or token>
Request {"warehouse_id": <id or name>, "namespace": …, "name": …, "properties": {"geo.crs": "EPSG:4326", …}, "remove": ["key", …]} (properties and/or remove; values are strings -- numbers and booleans are stringified, nested objects refused; keys 1-128 chars of letters, digits, ".", "_", "-")
Response table (ns.name), namespace, name, warehouse, warehouse_id, properties{} (after the commit), set[] (keys set), removed[] (keys asked to be removed), metadata_location
Errors 400 missing_field (neither properties nor remove, or both empty), 400 invalid_value (a bad key, a nested value, a value over 32768 characters, or format-version: reserved[] says which keys are), 403 forbidden (read level), 404 namespace_not_found, 404 table_not_found, 4xx/502 catalog_error (the catalog's own refusal, relayed: catalog_status, catalog_type, catalog_message)
CLI lhbox table set-properties --catalog … --namespace … --name … --property key=value … [--remove key …]

POST /v1/credentials → 200

Short-lived storage credentials scoped to ONE table's object prefix, vended by the catalog to the warehouse's read/write identity. For direct S3 access from a script; engines that load tables through the catalog obtain these themselves. Write holders only: a vended session is read/write whoever asks for it (measured, docs/security.md), so a read holder is refused and pointed at the static read-only credential in GET /v1/connection.

Auth Authorization: Bearer <API key or token>
Request {"warehouse_id": <id or name>, "namespace": …, "name": …} ("warehouse" is accepted for the same field)
Response table, location, scope, level (write), identity (t-<uuid>), storage{s3.access-key-id, s3.secret-access-key, s3.session-token, s3.endpoint, s3.session-token-expires-at-ms and the other s3.* keys the catalog vends}, expires_at, notes[] (only when the endpoint had to be rewritten for your network)
Errors 403 forbidden (level read or none; remedy names the grant command or /v1/connection), 404 namespace_not_found, 404 table_not_found, 409 quota_exceeded (over the storage limit: no new write credential; reading through the catalog credential still works), 502 catalog_error
CLI lhbox credentials --catalog … --namespace … --table …

GET /v1/connection → 200

A paste-ready recipe for your engine, with the catalog credential of the identity matching your level inside: write holders get t-<uuid> (reads and writes), read holders get t-<uuid>-ro (the catalog refuses its commits, the store its PUT/DELETE). The snowflake recipe is always the read-only identity (static keys, ALLOW_WRITES = FALSE). LakehouseBox is never in the query path: the engine talks to the catalog and the object store directly.

Auth Authorization: Bearer <API key or token>
Request ?warehouse_id=<id or name>&engine=duckdb (or warehouse=; duckdb default, pyiceberg, spark, snowflake)
Response engine, catalog_uri, warehouse (s3://<bucket>/), warehouse_name (the table bucket: <handle>--<catalog>, or w-<uuid> on older catalogs), level (read|write), level_via, identity (t-<uuid> | t-<uuid>-ro), catalog_credential{client_id, client_secret, oauth2_server_uri, grant: client_credentials, note}, storage_endpoint, blob_bucket (<handle>--<catalog>--blobs), blob_note, blob_example_python, token_endpoint, token_exchange{…}, warehouse_id, project_id, format_version_hint{default (the catalog's default_format_version), note, versions{"2", "3": {writers, readers, note}}} (always present; the note says the catalog prefers 3 when it does), notes[] (the first says the level), and per engine: sql (duckdb, snowflake) | python (pyiceberg) | conf{spark.sql.catalog.<alias>.*} (spark); catalog_alias (duckdb, spark: the catalog's name, else lake) -- two catalogs' recipes paste into one session without colliding
Errors 400 unsupported_engine (available[]), 403 forbidden (no grant on the warehouse; can_grant[] names who can), 404 warehouse_not_found, 503 provisioning + Retry-After: 30 (the catalog's storage has not accepted a write yet: status, retry_after_seconds, remedy; retry after it -- the control plane probes again every 30 s for 10 min)
CLI lhbox connect --catalog … --engine duckdb|pyiceberg|spark|snowflake

GET /v1/config/formats → 200

Which Iceberg format versions a table here can have, the default for LakehouseBox's own create paths, and for each version the engines that write it and those that only read it -- the ONE list (FORMAT_WRITERS in the control plane) every other sentence about format versions is rendered from. Public, like /v1/auth/config: a CLI, an agent or a page reads this instead of carrying its own list. Version strings are machine-parseable, `<engine>[>=<version>[+<lib>-<version>]]` (duckdb>=1.5.5, spark>=3.5+iceberg-1.11, pyiceberg>=0.12, spark); the prose is in note. A catalog's own default is default_format_version on GET /v1/warehouses/{id}.

Auth none
Response default (2), versions{"2": {writers[], readers[], note}, "3": {writers[], readers[], note}}, v3_only_types[] (geometry, geography), note

Organisations

GET /v1/orgs → 200

The organisations you belong to and your role in each; for a token, the organisation that owns it and the token's role.

Auth Authorization: Bearer <API key or token>
Response organizations[{org_id, name, handle, status, role (admin|member), domain_join, domains[{domain, verified_via}], members, created_at}]
CLI lhbox org list

PATCH /v1/orgs/{org_id} → 200

Rename the organisation, or let people whose verified email is on a claimed domain join as members.

Auth Authorization: Bearer <API key or token> — admin of the organisation
Request {"name"?, "domain_join"?: true|false}
Response the organisation as in GET /v1/orgs
Errors 403 insufficient_role, 400 no_domain (claim a domain first)
CLI lhbox org set [--name …] [--domain-join on|off]

POST /v1/orgs/{org_id}/domains → 201

Claim an email domain. The proof is your own verified address on that domain; public mail domains (gmail.com, outlook.com, …) are never claimable; a domain belongs to one organisation.

Auth Authorization: Bearer <API key or token> — admin
Request {"domain": "yourcompany.com"}
Response the organisation
Errors 400 public_mail_domain, 403 domain_not_yours, 409 domain_claimed
CLI lhbox org domain --domain …

DELETE /v1/orgs/{org_id}/domains/{domain} → 200

Release a claimed domain. Members who joined through it stay; nobody new joins through it, and domain join switches itself off when no domain is left.

Auth Authorization: Bearer <API key or token> — admin
Response the organisation, plus removed: <domain>
Errors 404 domain_not_found

GET /v1/orgs/{org_id}/members → 200

Who is in the organisation.

Auth Authorization: Bearer <API key or token> — any member
Response org_id, members[{principal_id, role, created_at, display_name, email, kind}]
CLI lhbox org members

PATCH /v1/orgs/{org_id}/members/{member_id} → 200

Change a member's role. Two roles, admin and member ("owner" is accepted as an alias for admin for one version and never returned). An organisation always keeps at least one admin.

Auth Authorization: Bearer <API key or token> — admin
Request {"role": "admin"|"member"}
Response org_id, principal_id, role
Errors 404 member_not_found, 409 last_admin
CLI lhbox org role --principal … --role admin|member

DELETE /v1/orgs/{org_id}/members/{member_id} → 200

Remove a member (admin), or leave the organisation (your own principal_id). The last admin can do neither.

Auth Authorization: Bearer <API key or token> — admin, or any member removing themselves
Response org_id, principal_id, removed: true, left
Errors 404 member_not_found, 403 insufficient_role, 409 last_admin

POST /v1/orgs/{org_id}/invitations → 201

Invite an address. The token is returned once (and mailed when the deployment has a mail sender). If the address signs up later, the invitation is applied automatically.

Auth Authorization: Bearer <API key or token> — admin
Request {"email": …, "role": "member"|"admin"}
Response org_id, email, role, token (shown once), mailed, expires_in (7 days), accept_with, note
CLI lhbox org invite --email … --role member|admin

POST /v1/orgs/invitations/accept → 200

Redeem an invitation. The caller's email must be the invited one.

Auth Authorization: Bearer <API key or token>
Request {"token": …}
Response the organisation
Errors 404 invitation_not_found, 410 invitation_expired, 403 invitation_for_someone_else
CLI lhbox org accept --token …

Agents

POST /v1/orgs/{org_id}/agents → 201

A token (shown as "agent"): a machine identity of the organisation with its own API key, revocable on its own, holding exactly the grants given here and an organisation role (admin or member, default member) the organisation routes evaluate exactly as a human member's -- so an agent can do everything a human can. An empty or omitted grants list means no warehouse until granted (a warehouse a member token was not granted is 404 for it; an admin token sees every warehouse with its level, and may grant itself). Admins give any grants and either role; members at most their own level on each warehouse and the member role only. Role governs the organisation, grants govern data. Tokens never count for last-admin protection. The pre-contract `warehouses`/`warehouse_ids` list is read as write grants for one more version and answered with a `deprecation` note.

Auth Authorization: Bearer <API key or token> — admin, or a member within their own grants and role (a token is the member or admin it was made)
Request {"name": …, "role"?: "admin"|"member", "grants"?: [{"warehouse_id": …, "level": "read"|"write"}, …]}
Response agent_id, name, org_id, role, grants[{warehouse_id, name, level}], created_by, created_by_display, created_at, last_used_at, suspended, warehouses (legacy), api_key (shown once), key_id, note
Errors 400 invalid_value (grants, role), 403 forbidden (a level above your own: your_level, requested), 403 insufficient_role (an admin token from a member), 404 warehouse_not_found (not in this organisation), 409 already_exists (name)
CLI lhbox agent create --name … [--role admin|member] [--grant <warehouse_id>:read|write …]

GET /v1/orgs/{org_id}/agents → 200

The organisation's tokens with their role and grants, who created each and when its key was last used.

Auth Authorization: Bearer <API key or token> — any member
Response org_id, agents[{agent_id, name, role, grants[{warehouse_id, name, level}], created_by, created_by_display, created_at, last_used_at, suspended, warehouses (legacy), note (legacy unconfined agents)}]
CLI lhbox agent list

GET /v1/orgs/{org_id}/agents/{agent_id} → 200

One token by id or by name: the same view as the list (grants as [{warehouse_id, name, level}] on every agent route since 2026-09-21), its connection block, creator and last use. Never the key.

Auth Authorization: Bearer <API key or token> — any member
Response the token as in GET /v1/orgs/{org_id}/agents
Errors 404 agent_not_found
CLI lhbox agent get <id or name>

PATCH /v1/orgs/{org_id}/agents/{agent_id} → 200

Edit a token's name, grants and/or role; the path names the agent by id or by name. The grants list replaces the current one and is capped by the editor's own grants, the role by the editor's own role (an admin is uncapped; a token never edits itself unless it is an admin). Editing a legacy unconfined agent confines it. Audited with the previous role.

Auth Authorization: Bearer <API key or token> — admin, or the member who created it
Request {"name"?: …, "role"?: "admin"|"member", "grants"?: [{"warehouse_id": …, "level": …}]}
Response the token as in GET
Errors 400 missing_field, 403 forbidden, 403 insufficient_role, 404 agent_not_found, 409 already_exists
CLI lhbox agent update --agent <id or name> [--name …] [--role admin|member] [--grant <warehouse_id>:read|write …]

DELETE /v1/orgs/{org_id}/agents/{agent_id} → 200

Every key of the agent is revoked and the agent suspended: it stops at once. The path names the agent by id or by name.

Auth Authorization: Bearer <API key or token> — admin, or the member who created it
Response agent_id, revoked: true
Errors 404 agent_not_found
CLI lhbox agent revoke --agent <id or name>

API keys, terms and account

GET /v1/auth/config → 200

What a browser or a CLI needs to log a human in: whether the deployment serves the email + password login (password_login; the form at /app/, docs/login.md) and the external OpenID Connect issuers a self-hosted deployment trusts (AL_OIDC_ISSUERS; device-code endpoints). The account page shows the form, the "Log in with <issuer>" button, or both, from this answer.

Auth none
Response issuer, password_login (true when the deployment serves POST /v1/auth/login), external_issuers[{issuer, client_id, authorization_endpoint, token_endpoint, device_authorization_endpoint, jwks_uri}], api_key_exchange

POST /v1/api-keys → 201

Another API key for the caller (for a second machine, a CI job). Shown once.

Auth Authorization: Bearer <API key or token>
Request {"label": "ci"}
Response api_key, key_id, label, principal_id, note
CLI lhbox api-key create --label …

GET /v1/api-keys → 200

The caller's keys, by id: never the secret.

Auth Authorization: Bearer <API key or token>
Response api_keys[{key_id, label, created_at, last_used_at, revoked_at}]
CLI lhbox api-key list

DELETE /v1/api-keys/{key_id} → 200

Revoke one of your keys. The key id is the part between al_live_ and the second underscore.

Auth Authorization: Bearer <API key or token>
Response key_id, revoked: true
Errors 404 api_key_not_found
CLI lhbox api-key revoke --key-id …

POST /v1/onboard → 200

For a caller who arrived with a key or an identity-provider token: make sure an organisation, a project and a warehouse named `lake` exist and hand back the recipe. First login without a signup: organization_name + handle name the organisation (a handle is derived from the name when absent); an address on a claimed, open domain joins that organisation instead and the response says so. Idempotent: an existing organisation and warehouse are returned, not duplicated.

Auth Authorization: Bearer <API key or token>
Request {"engine"?: "duckdb", "accept_terms"?: true, "organization_name"?, "handle"?, "org_id"?}
Response created (bool), warehouse_id, connection, project_id (when created), organization{org_id, name, handle, status, role, joined_via (created|domain|invitation|signup-form|member)}, terms{version, accepted, url}, note
Errors 400 terms_required (a human who has not accepted the current Terms), 400 invalid_value (handle), 409 handle_taken (suggestion)

GET /v1/terms → 200

The Terms version in force and whether you accepted it.

Auth Authorization: Bearer <API key or token>
Response current_version, terms_url, privacy_url, accepted_current, history[{version, accepted_at, via}]
CLI lhbox terms

POST /v1/terms/accept → 200

Record acceptance of the current Terms version. A person's act: a token (kind agent or mcp) is refused; Terms bind the account holder and a token needs no acceptance of its own.

Auth Authorization: Bearer <API key or token>
Request {"version"?: <the current version>}
Response accepted: true, version
Errors 403 not_a_person (a token), 409 terms_version_mismatch
CLI lhbox terms --accept

DELETE /v1/me → 200

Delete your account. Immediate: every API key revoked, every session revoked, identities unlinked, memberships removed, agents of organisations left empty stopped; a credential of the deleted account answers 401 account_deleted from then on. Data of organisations left without members is erased within 30 days and leaves backups within 14 more (Terms).

Auth Authorization: Bearer <API key or token>
Request {"confirm": "<your email>"}
Response deleted: true, principal_id, keys_revoked, organisations_left_empty[], warehouses_to_purge[], note
Errors 400 confirmation_required, 409 last_admin (make someone else an admin first)
CLI lhbox account delete --confirm <your email>

Usage and limits

GET /v1/usage → 200

Every limit, the current value and the headroom. Storage is metered hourly by maintenance (the latest sample of every warehouse in the scope, summed; 'unmetered' until the first sample, which the control plane takes itself ~2 minutes after a catalog is created); every storage figure carries measured_at and stale_after (when the sweep will have replaced it), and POST /v1/warehouses/{id}/measure refreshes one catalog now. The storage limit applies to the organisation, or to the project when it has none. Over the limit, warehouse and table creation and credential vending answer 409 quota_exceeded and the buckets go read-only at the next enforcement pass. Read this before provisioning; an agent should never meet a limit by failing. Per warehouse it also shows usage that is NOT billed today: the latest footprint split by bucket, one row per UTC day for the last `days` days (the day's last footprint, and the S3 requests and bytes in/out counted that day from SeaweedFS's per-bucket counters), the footprint trend over the window and the window's traffic totals. `traffic` is null with a `traffic_note` until two consecutive hourly samples carry counters; no object keys and no query contents are collected.

Auth Authorization: Bearer <API key or token>
Request ?project_id=<optional id or name>&days=<1..30, default 7: the per-catalog history length>
Response principal_id, limits{storage_bytes, public_storage_bytes, objects, tables, namespaces, warehouses, projects, catalog_operations_per_month, commits_per_month, min_seconds_between_commits, snapshot_retention_days, max_snapshots_per_table}, limits_detail{<limit>: {value, enforced: true|false, enforcement}} (storage, catalogs per project, projects per account and snapshot retention are enforced; tables, namespaces, objects and commit spacing are guidelines: engines commit straight to the catalog), limits_note, history_days, projects[{project_id, name, org_id, warehouses{current, limit, headroom}, warehouse_ids[], storage_bytes{current, limit, headroom, unmetered, measured_at, stale_after, complete, scope, scope_id, warehouses_metered, warehouses, over_limit}, public_storage_bytes{…}, warehouse_storage[{warehouse_id, name, tier, public, bytes, objects, measured_at, unmetered, stale_after, source: sweep|creation|on_demand, measuring, buckets{table, blob}, table_bytes, blob_bytes, blob_objects, complete, history[{day, bytes, objects, blob_bytes, blob_objects, complete, measured_at, samples, requests, requests_failed, bytes_in, bytes_out, intervals}], trend{days, from, to, bytes_from, bytes_to, bytes_delta, objects_delta, days_measured} | null, traffic{days, requests, requests_failed, bytes_in, bytes_out, intervals, resets, since, to, source} | null, traffic_note}]}], organizations[{org_id, storage_bytes{…}, public_storage_bytes{…}, role (the caller's: a member's or a token's)}], note
CLI lhbox usage [--full] [--catalog <id or name>] [--days N] (also: lhbox whoami; both print a brief object unless --full)

GET /v1/audit → 200

Who did what. Without org_id: your own events. With org_id: an admin sees the organisation's events plus their own; a member only their own within it. Actions include signup.start/verify/complete, recovery.start/verify, api_key.create/revoke, project.create, warehouse.create/rotate, table.create, credentials.vend, org.create/update/domain_claim/invite/invitation_accept/member_join/member_role/member_remove, org.reserve/activate, agent.create/update/revoke, warehouse.grant/grant_revoke/delete/delete_complete/rotate_complete/measure, terms.accept, account.delete, quota.reject.

Auth Authorization: Bearer <API key or token>
Request ?org_id=<optional>&since=<24h|7d|30m|ISO-8601>&action=<name or prefix*>&limit=<1..1000, default 100>
Response events[{id, ts, principal_id, org_id, action, target_type, target_id, ip, request_id, detail{}}], count, limit, scope (own|organization), org_id, since, action, retention_days (400)
Errors 404 org_not_found
CLI lhbox audit [--org …] [--since 24h|7d|30m|<ISO-8601>] [--action credentials.vend|org.*] [--limit N]

Internal (not public)

These exist in the control plane for the operator and for development stacks. They require the deployment's bootstrap secret and the public gateway answers 404 for every /internal/* path. Listed so the surface is complete.

POST /internal/principals → 200

Operator: create a principal and its first key.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

POST /internal/principals/{principal_id}/suspend → 200

Operator: suspend or unsuspend a principal (the enforcement point).

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

POST /internal/api-keys/{key_id}/revoke → 200

Operator: revoke any key.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

POST /internal/selftest/error → 200

Operator tool: raise one unhandled error on purpose to verify the error path end to end.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

GET /internal/signup-codes/{email} → 200

Development stacks without a mail server: read a pending code.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

GET /internal/sinks → 200

For the roller (worker/roll.py): every active or disabled sink with its catalog's key pair, buckets, roll policy and pending ledger, plus the sinks deleted in the last 7 days whose intake prefix it must purge. Empty while AL_SINKS_ENABLED is off.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

POST /internal/sinks/{sink_id}/roll → 200

The roller reports one roll: the batch ids committed (marked committed with the snapshot id), rows, rejected rows, seconds, an optional disabled_reason (table_missing disables the sink); ledger rows committed more than 7 days ago are pruned.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

GET /internal/lifecycle-audit → 200

The table-bucket guard, observable: as the admin, GET ?lifecycle on every catalog's TABLE bucket (expected 404 -- a rule there would be executed by the store's worker against Iceberg data) and GET ?policy on it (no statement may grant a lifecycle action). Lists offenders and errors; ok when both are empty; ?include_blobs=true also counts the blob buckets carrying rules. For the nightly sweep.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

GET /internal/tls-ask → 200

Caddy's on-demand TLS gate for virtual-hosted S3 names (<bucket>.s3.<domain>, the shape Snowflake's S3-compatible volumes need): 200 only for a bucket of an existing warehouse -- its table or blob bucket, looked up by name in the row's bucket / blob_bucket columns, so <handle>--<catalog>, …--blobs and the older w-/b-<uuid> are all served -- under the configured S3 host, 404 otherwise (a deleting catalog included), so nobody can make the gateway mint certificates for arbitrary names. Answers domain, bucket, warehouse_id, kind (tables|blobs), issue. Called on the docker network; never served publicly.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

GET /internal/login-tokens/{email} → 200

Development stacks without a mail server: read a pending set-password or reset link token (purpose=set_password | reset_password). The pattern of /internal/signup-codes.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

POST /internal/usage → 200

The host's hourly maintenance run reports one warehouse's footprint (bytes, objects, blob bytes and objects); recording it recomputes the scope's storage quota.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

GET /internal/tier/plan → 200

The host's hourly tiering job (deploy/on_host_tier.sh) asks which buckets may move to the cold tier: one item per bucket of every ready tier_policy=cold catalog with the backend its tenant hashes to, plus the knobs (quiet_for, full_percent) it passes to volume.tier.upload (research/27).

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path

POST /internal/tier/report → 200

The tiering job reports one run: per bucket the absolute cold footprint after it (cold_bytes, cold_volumes), what moved, seconds and the error text; recorded in tier_state and shown as stored.cold_bytes / cold.

Auth the deployment's bootstrap secret (X-Bootstrap-Secret). Not public: api.lakehousebox.com answers 404 for every /internal/* path