tallpond API Reference

The tallpond gateway is the single authority for every app request: it authenticates the caller, compiles and enforces data access, meters usage, and attributes cost to a payer. This reference documents the HTTP API it exposes and the TypeScript SDK that wraps it.

Model in one line: developers host open-source apps for free; end users pay their own direct usage costs; the app holds no secrets. Every operation is authenticated, access-checked, and metered by the gateway.

Coding agent? docs/agent-skill/SKILL.md (also served at tallpond.com/skill.md) is the fast path — auth modes, error shapes, and what to read before guessing at a failure. tallpond.com/llms.txt indexes the full doc set.

Contents#

Status legend#

• ✅ Available — implemented and covered by tests.
• 🚧 Partial — implemented with a documented limitation.
• 📋 Planned — retained as future platform work, but not yet callable.

Base URL & versioning#

All endpoints are served from the gateway origin (for local development, http://localhost:3000).

• App API is versioned under /v1/* and always requires authentication.
• Auth (/auth/*), deploy (/deploy), and the Stripe webhook (/stripe/webhook) sit outside /v1 and have their own auth schemes.
• GET /health → { "ok": true } (unauthenticated liveness check).

Requests and responses are JSON (Content-Type: application/json) unless noted (the AI streaming response is text/event-stream; the Stripe webhook takes a raw signed body).

Authentication#

Every /v1/* request must present one of:

1. Session cookie (browser SDK). The gateway sets httpOnly cookies during sign-in; the app never sees the token. Cookie-authed requests must also send the header X-Tallpond-Csrf: 1 — browsers only attach custom headers after a CORS preflight, which makes cookie-bearing state changes CSRF-proof. Requests use credentials: include.
2. Bearer token (server-to-server): Authorization: Bearer <access_token>. No CSRF header is required for bearer auth. Several token families are accepted, distinguished by prefix and verified locally with no Ory round-trip: tpa_ (a non-human principal's runtime token), tpt_ (a dev-minted test session), and tpi_ (a function invocation context, minted by the gateway and never by a client).

The gateway validates the token against Ory (introspection when ORY_API_KEY is set — which also yields the app/client id used for per-app budgets — otherwise the public userinfo endpoint). See authentication.md.

Errors#

Errors are JSON with a stable machine-readable error code and a human detail:

{ "error": "forbidden", "detail": "not permitted to create \"messages\"" }

Data-engine (/v1/db, /v1/resources) error codes and their HTTP statuses:

Cross-cutting statuses:

Every response, success or error, carries X-Tallpond-Request-Id — a Cloudflare Ray ID in production. Include it when reporting an issue; it's what a gateway log line keys on.

The SDK rethrows all of these as TallpondError with { message, status, data, requestId }.

Billing & metering (how cost attaches)#

• AI and other high-value ops use per-op escrow: the gateway places a hold that upper-bounds the cost before calling upstream, then captures the actual amount. A request that can't be covered fails 402 before any spend.
• Database ops are sub-threshold, so they use accumulate-and-flush: usage is summed per (payer, app) and written to the ledger as one transaction when it crosses a threshold or the flush interval fires.
• Every op resolves a payer. For private data it's the acting user. For resource data it follows the resource's payer policy (actor / owner); shared (creator-owned) rows always bill their creator. See database.md and schema-and-deploy.md.
• Stored R2 blob bytes and Neon row bytes are charged by a recurring, pro-rated GB-month sweep (storage_at_rest / db_at_rest). Upload charges cover the write operation itself, not future retention. See metering.md.
• Users protect themselves with a per-app monthly spend cap (billing.md).

Known limitations in shipped areas#

These are implemented paths with a deliberate, temporary simplification:

• payer: "split" currently bills the actor (true split settlement needs the app allowance ledger, which lands with visitors — planned).
• File member-removal deletes the removed member's files (remove); per-bucket hide/retain for files is future work (the hidden column is already in place).
• Account deletion deletes resources the user owns outright; optional ownership-transfer is future work.
• Linked files (.link()) carry no room: a mount is a publication across resources, while a room partitions one, so linked files behave as default-room content. Directly uploaded resource files are fully room-scoped.
• .url() requires a session; visitor-sponsored (signed-out) reads land with visitors.

Now shipped (previously listed here): object storage (Stage E), user profiles, author(...), and account deletion (Stage F), plus the tallpond CLI (dev, confirmed production deploy, environment-only test sessions, and typegen). See not-yet-implemented.md for the fuller roadmap.