Sapient Base (database)

Products hosted on Sapient’s own infrastructure get a built-in NoSQL document database — Sapient Base — provisioned per product. No third-party database account, no connection pools, no migrations to babysit: your product’s backend talks to it over HTTPS + JSON.

What it enables: durable storage for hosted products. Data survives restarts, redeploys, and scale-to-zero.

How your product gets it

When your factory provisions a database for a product (you approve the infrastructure request), every deploy of that product receives:

Variable	Meaning
DATABASE_URL	the database endpoint — https://<secret>@…/v1/db/<id>; the credential is embedded, treat the whole URL as a secret
MONGODB_URI	alias of DATABASE_URL
SAPIENT_BASE_TOKEN	(not always present) the database secret on its own, for clients that prefer an Authorization: Bearer header

DATABASE_URL is the one to write against: it always arrives, and it already carries the credential. SAPIENT_BASE_TOKEN is a convenience we can only hand over where the platform has somewhere to keep a bare secret, so treat it as optional and fall back to the URL.

Your product’s engineers (the AI ones) code against this automatically — the platform’s connector guidance includes the full API. For the curious, the shape is simple:

# insert a document — the credential rides in the URL
curl -X POST "$DATABASE_URL/tasks" \
  -H 'Content-Type: application/json' -d '{"title":"ship it","status":"todo"}'

# list with a filter
curl "$DATABASE_URL/tasks?f_status=todo&orderBy=title"

Documents are JSON objects (nested objects, arrays, numbers, booleans all supported, up to 256 KiB each). Collections are created on first write. Reads support equality filters, ordering, and limits; documents can be fetched, replaced, merged, or deleted by id.

Making it the default

Settings → Deployment → Default database picks the backend new products start with — Supabase, Mongo Atlas, Firestore, or Sapient Base. Choosing Sapient Base is the one option that needs nothing from you: the other three connect to an account you own, so they ask you to connect or provision an instance and approve the infrastructure. Sapient Base is already running, and a database is cut per product as it is created.

Changing the default never moves a product that already has a database. A product can override the factory default, and its binding is shown on its own deployment settings.

Looking at your data

Settings → Connectors → Sapient Works hosted apps → Open data browser opens the Sapient Base viewer: your databases on the left (one per product), their collections beneath, and the documents in the selected collection on the right. Click a row to see the whole document as JSON.

The table is the newest 50 documents by createdAt. The filter box takes the same equality syntax the API does — f_status=posted, space-separated for more than one — and runs server-side, so it searches the whole collection rather than the rows on screen.

If a product is bound to Sapient Base but the binding does not lead to a database we can open, the viewer says so and names the product, rather than reporting that you have no databases. Usually the binding records the wrong id and your data is untouched; it can also mean the database was removed. Repairing a binding is not something you can do from the control room yet — tell us which product it is and we will re-point it.

It is a read-only view. Nothing here edits or deletes a document: writes belong to your product, through its own credential. For the same reason the viewer never shows your DATABASE_URL — that URL embeds the database secret, and a secret on a screen is a secret you’ve shared.

Browsing your data here doesn’t cost credits.

Scope and limits

Sapient Base is scoped to Sapient-hosted products. Each database is isolated per product with its own secret. Current limits: 256 KiB per document, 200 documents per list call, equality filters only. Products that outgrow it can connect an external database (Supabase, MongoDB Atlas) through the ordinary connector flow instead.