---
name: opti-deploy
description: Deploy a web app to the Optimizely Deploy Portal and get a shareable, employee-only URL — with a database, file uploads, server-side AI, keyed API calls and scheduled work already attached, so a page needs no backend of its own. Use whenever the user asks to "deploy", "share", "publish", "host", "ship", or "put online" something they (or you) just built — without making them specify the folder, files, or format.
---
# Optimizely Deploy Portal
Deploy apps to an internal sharing URL gated by Microsoft sign-in. You upload static files; the PLATFORM supplies the backend — a database, file storage, server-side AI, API calls that hold the credential, and scheduled work — so "it needs a backend" is not a reason to refuse. You have a focused tool surface — deploy, list, rename/re-share, delete, check your connection, and request more slots — see the tables below. Use them confidently; the user does **not** need to tell you which folder to upload or how to package it.
A project may also have a **draft** — one unpublished working copy at
`/{owner}/{slug}/draft/`, written by Site Builder. It is served with the REAL database,
identity and API connections, and is visible only to the owner and their maintainers, even
when the project itself is public. You cannot create, publish or discard one through these
tools; the user does that in Site Builder or on their project page — where **Publish**
makes it the next version (keeping the draft) and **Discard** throws it away. On a project
that has never been published, discarding removes the project, because the draft is all
there is. An unpublished project never counts against the deployment limit.
**Links to share** when someone asks what the portal is, how to start, or how to connect:
- Setup & help (public, no sign-in): https://deploy.optimizely.com/start
- Deploy tokens — create, list, revoke (sign-in): https://deploy.optimizely.com/settings/tokens
- Portal / dashboard: https://deploy.optimizely.com
## When to invoke
Trigger on intent, not exact wording. Any of these means *call the tool*:
- "Deploy it / this / that" · "Share it with the team" · "Publish it" · "Host it" · "Ship it" · "Put it online"
- "Make a sharable link" · "Send me a URL" · "Make this live"
- After you've finished a build/preview the user reacted positively to ("nice", "ship it")
- "Put this report somewhere I can send" · "Give me a link to these notes" — a **written document counts**, see below
If the request is ambiguous (e.g. user has multiple projects and didn't say which), ask **one** short clarifying question. Otherwise, proceed.
## Design constraints — factor these in *while building*, not just at deploy
When you know something is destined for this portal, design for it from the first line of code. You ship **static files** to a **sign-in-gated, organization-readable** URL — but the page is not on its own: the platform gives it a database, file storage, AI, credential-backed API calls and schedules. What you cannot do is run **your own server process**:
- **Never hardcode secrets** — API keys, tokens, DB connection strings, private keys. Anything in the client ships verbatim and is readable by any signed-in employee (public pages) or everyone on the allowlist (private pages), so a real secret is effectively leaked. Uploads are scanned and will flag these, but don't rely on the scanner — keep them out from the start.
- **It needs to summarise, classify, or extract? There's a model, with no key.** `Opti.ai()` — see below. It can also **search the web** and **run code** when the question needs it, so live facts and real arithmetic are both available with no setup. It's off until the owner (or a maintainer they named) enables it per project, and it costs per call, so batch and put it behind a button.
- **It needs to SHOW what a SharePoint document says — a panel, a table, a chart?** Do NOT route
that through the model. `Opti.sharepoint.search(query)` and `Opti.sharepoint.read(url)` hand the
page the content directly: no tokens, no allowance, nothing summarised, nothing to hallucinate.
No owner switch is needed for this — see below — and it reads as the VISITOR. Use `Opti.ai()`
for a QUESTION, this for the CONTENT.
- **The source is a spreadsheet?** `read()` returns `{ columns, rows }` for `.xlsx`, `.xlsm`,
`.csv` and `.tsv` — one object per row, keyed by column name — and `{ text }` for everything
else. So a chart is `rows.map((r) => Number(r.revenue))` with no CSV parsing. ⚠️ Every cell is a
STRING: convert the columns you use, or an order code `007` becomes `7`. ⚠️ Do NOT ask the model
to total a column it read as prose — measured, that is wrong by ~0.4% and looks right; read the
rows and do the arithmetic in the page.
- **Render from `doc.columns`, never from names you expect.** Sheets hold whatever their owners
typed, so build the table's headings from `columns` and look values up by those names. A file's
NAME tells you nothing about its columns.
- **What is read:** the first **visible** tab (hidden tabs are skipped unless no visible tab can
be read; `doc.sheets` lists every visible one). The header is the row the sheet's own filter
starts on, otherwise the first row with anything in it — so a title typed above the header
becomes the header; check `columns`. Blank rows are dropped; a blank heading comes back as
`columnN`.
- **Values as the sheet stores them:** a DATE is Excel's serial number (`45123`), a boolean is
`TRUE`/`FALSE`, a broken formula is its error text (`#NAME?` — show it as blank). An image in
a cell cannot be read.
- **A file in SharePoint or OneDrive?** Always `Opti.sharepoint.read(url)` — it needs no connection
and no setting, and reads as each visitor. ⛔ **Do not build an `Opti.call()` connection to
Microsoft Graph to read a file**: a connection reads with ONE stored credential for every visitor,
so the file is shown to people it was never shared with. A link copied from the browser's address
bar works, including OneDrive `/:x:/r/personal/…` links.
- ⭐ **Just SHOWING a SharePoint document needs no setting at all.** `Opti.sharepoint.search()` and
`.read()` work on any project, because they run on the reader's own Microsoft access — there is
nothing for an owner to switch on. Prefer this whenever the page wants the CONTENT.
- **Handle the sign-in failure, and do NOT redirect on it.** The thrown error carries
`needsReconnect`; when true, `e.reconnectUrl` takes them to Microsoft and back to your page.
Offer it as a link — a visitor came to read your page, and bouncing them without a click loses
whatever they were doing. When it is false, signing in again has already been tried and failed,
so showing the link would loop. Either way they can fix it at Settings → Microsoft connection.
- **It needs the MODEL to answer from documents in SharePoint?** That half does need a tick: the
owner ticks *The model may search SharePoint* (project → AI tab), and `Opti.ai()` searches and reads while it
answers — **as whoever opens the page**, so each reader gets only their own access. Word,
PowerPoint, PDF, text and Markdown read as text; Excel and CSV read as rows. It needs a recent
Microsoft sign-in. See `Opti.ai()` below.
- **It needs to answer from the owner's own documents?** Write an **assistant** in Settings → Assistants (https://deploy.optimizely.com/settings/assistants) — a brief plus files (handbooks, notes, PDFs, spreadsheets; the portal routes each one — prose is quoted, spreadsheets are computed in a sandbox) — then **tick it on** for the project (its AI tab, like an API connection) and call `Opti.ai('…', { assistant: 'name' })`. An assistant is owner-scoped and reusable across projects; a name the project has not been granted is refused.
- **It needs to store or collect data? You have a database.** Don't fake it with `localStorage`, don't invent a backend, don't tell the user it's impossible — use **Collections** (see below). It's built in, needs no key, and every write is attributed to the signed-in employee.
- **If the app needs some *other* API:** a **publishable / domain-restricted key** (the kind meant for the browser) can ship in the page. A real secret cannot — but the portal will now **hold it for you**: the user saves the credential once in their project's *API connections* panel and the page calls it by name with `Opti.call()` (see below). So "it needs a server-side key" is no longer a reason to give up or to ship the secret.
- **A client-side router needs `Opti.basePath`.** Plain static builds just work — the portal rewrites root-relative paths and injects ``. A router is the exception, because it reads the prefix in JS: pass `Opti.basePath` as the basename (`createBrowserRouter(routes, { basename: Opti.basePath })`, `createWebHistory(Opti.basePath)`). Get this wrong and nothing looks wrong — it renders perfectly in every local preview and every deep link 404s once deployed, which reads as "the app is broken" rather than "a setting is missing". **Don't derive the prefix from owner/app**: the same page is also served at `/go/{vanity}` and `/{owner}/{app}/v{N}`, where that guess is wrong. `Opti.basePath` is always the prefix the visitor actually arrived on.
- **No server process of your own** — no SSR, no Express, no API routes you wrote; produce a static build (Next.js `output: 'export'`, SvelteKit `adapter-static`, etc.). That is the *only* real limit: data, files, AI, keyed API calls and schedules are all provided for you.
- Assume the page is **organization-internal at most** — public to signed-in Optimizely employees by default, or restricted to a named allowlist. Never publicly reachable.
A flagged value that's genuinely client-safe (e.g. a publishable key) is fine to ship — explain it to the user, then deploy with `allow_secrets: true`. The scan is a warning with an override, **never a hard block**.
## Available tools
### Deploy
**Decide first: is there content of the user's to deploy** — a page you generated in this chat, a file on disk, or a build folder (`dist/`, `out/`, `build/`)?
- **Real build →** `prepare_upload` (the fast, default path).
- **Small / chat artifact, and you can't run a networked upload →** `deploy` (inline).
- **You wrote a report, summary or notes →** deploy the **`.md` itself**. Do not wrap it in HTML: an upload with a root `.md` and no `index.html` is rendered into a themed, shareable page by the portal, with a link that previews in Teams. Several root `.md` files become one page with a nav across them, README first. The `.md` files are kept exactly as uploaded.
- **You have a set of finished HTML pages and no index →** deploy them as they are. Several root `.html` files get a contents page linking to each; a single root `.html` is served as the site itself. You do not need to hand-write an `index.html` to make a folder of pages shareable.
- **No content, user just wants a demo →** generate a small Hello-World `index.html` yourself and `deploy` it. There is no separate sample tool.
| Tool | When to use |
|---|---|
| `prepare_upload` | **Default for any real build, and the FAST path.** Returns a `bash_command` (a `curl` with a single-use token) plus `upload_url`. The bundle uploads straight from disk and **never enters your context** — so it's fast and has no size-through-the-model cost. Run the `bash_command` in a shell; if you have code execution with network but no shell, POST the zip to `upload_url` directly using the same token (it's embedded in `bash_command`). Use for `dist/`, `build/`, `out/`, image/binary-heavy uploads, or anything beyond the inline cap. |
| `deploy` (inline) | **In-chat fallback for when you genuinely can't run a networked upload** (no shell *and* code execution can't reach the network — **Opal is exactly this**: it has no outbound network of its own, so every byte travels as model tokens). Prefer **`zip_base64`** (base64 of a zipped build) over the per-file `files` array. ⚠️ **It's slow**: the payload travels as model tokens, so generation time scales with size — keep it to a small page/app. The soft cap (~200 KB) is on the *sent* (compressed) payload — **measured**, and it is compressed size, so a 10 MB folder that zips to 10 KB is fine while a 300 KB image is not. Anything larger, multi-file-heavy, or image/binary → use `prepare_upload` if you have a shell, and otherwise send the person to the dashboard rather than retrying. |
Both accept optional `visibility` + `allowed_emails` — see **Sharing & visibility** below. (Teams are set with `update_deployment` after the deploy.)
### Manage
| Tool | When to use |
|---|---|
| `list_deployments` | "What did I deploy last week?" "Do I already have one called X?" "What's the URL of my pricing page?" "Which of my pages are private?" Read-only; returns name, URL, version, size, and sharing state (public/private + allowlist + team names + locked) for each. (View counts are deliberately not exposed.) |
| `update_deployment` | Rename, add a description, pin/unpin, **change sharing** (private/public + allowlist + **teams** by name), **lock** it (`locked: true` — "hide it while I finish it": an override that suspends sharing without overwriting it), or claim a **short link** (`vanity` → `/go/your-name`). No re-upload; the URL stays stable. |
| `read_data` | **Read what a deployed app has COLLECTED.** No args → every collection + record counts. `app` + `collection` → the records, each stamped with who submitted it. Use for *"summarise the survey responses"*, *"how many signed up?"*, *"what did people say?"* — you do **not** need to build a dashboard to answer a question about the data. Read-only. Also reports a `profile` per collection — its field NAMES, its modes, and whether it holds one row per person — which is what tells you whether a page should call `add()` or `save()`, and whether the field you were about to write is the one already there. `fields` is a sample, so compare `sampled` with `records` before treating it as a schema. |
| `rollback_deployment` | "That deploy broke it, put the old one back." Switches which retained version is served — a pointer flip, live immediately, URL unchanged. No `version` → the one before the live one. **Reversible**: the version you leave stays retained, so the same call goes forward again. Prefer this to re-uploading. |
| `delete_deployment` | "Delete my pricing-v1 demo." **Always confirm with the user before calling.** Cannot be undone — **and it deletes the app's collected data too.** |
### Account & quota
| Tool | When to use |
|---|---|
| `whoami` | "Am I connected? How many slots left?" Sanity-check the connection + show slot usage and recent activity. Good first call in fresh chats. |
## What you can't do — and how to hand it over
Some things are deliberately **browser-only**: they involve a secret, someone else's
access, or spending. No tool does them, so don't imply one might. Every deploy
result carries **`manage_url`** (the project page) and **`data_url`** (its Data tab)
— **paste the link** when you send someone to do one of these. "Open your project
page" without a link is how a good instruction becomes a support ticket.
| What | Where | Say it when |
|---|---|---|
| Let colleagues **read** collected data *(owner-only by default)* | `data_url` → **Access** → *Read: anyone who can open the app* | **always**, if the page you built displays entries |
| Get pinged on each submission | save the webhook once in **Settings → Channels**, then `data_url` → **Notify** → pick that channel | you built a form a human must act on |
| A digest instead of a ping per entry | `data_url` → **Automations** tab → the digest recipe *(a channel, an inbox, or both — email alone is fine)* | the collection will be busy |
| Tell someone the moment a specific entry arrives | `data_url` → **Automations** → trigger **Whenever an entry arrives**, with a condition | only some entries matter, and they can't wait |
| Refresh data on a timer, so the page reads it already-fresh | project page → **Automations** → look at **An API** *(needs an API connection that allows GET — not a channel)* | you built a page that shows data from another system |
| Put a result back into another system — raise the ticket, not just mention it | project page → **Automations** → set **…and send it on to** to one of their API connections *(it must allow POST)* | the automation should DO something, not only tell somebody |
| Turn **on AI** | `manage_url` → **AI** | you wrote any `Opti.ai()` |
| Save an API credential | **Settings → API connections** (`/settings/connections`) | you wrote any `Opti.call()` |
| Announce deploys in a channel or by email | `manage_url` → **Announce new versions** | they want release notes |
| Let a project USE a saved credential | `manage_url` → **API connections** → tick it | the credential exists but the page gets `forbidden` |
| Add an **editor** (co-maintainer) | `manage_url` → **Who can open it** → *Editor access* | "X should be able to update this too" |
| Tag it so people can find it | `manage_url` → the tags beside the note, or on its card | it belongs to a set (`survey`, `dashboard`, `docs`) |
| Approve an access request | the **notification bell**, top right | someone was refused entry |
| Deploy from GitHub on push | dashboard → **Deploy from GitHub** | they want CI deploys |
| Create a project a **team** owns, not a person | `https://deploy.optimizely.com/{workspace}` → **Projects** → the uploader | they said "the team's", "ours", or "it should outlast me" |
**Browse needs no opt-in any more.** Every public project is listed for the whole org
automatically — there is no "list it" tick, and telling someone to look for one sends
them hunting for a control that does not exist. If they want a page *unfindable*, the
answer is to make it **private** or **Only me**; "public but nobody will stumble on it"
is no longer a state that exists.
**Not on this list, on purpose:** sharing (public/private + allowlist), renaming,
pinning, locking and short links. `update_deployment` does all of those — **do them**
instead of sending anyone to a page.
## When there is no page — a data project
⚠️ **Not every request has a front end in it.** "Somewhere for Zendesk to send tickets",
"pull the on-call roster every morning", "a weekly summary of what came in", "raise a ticket
when one arrives" — none of
those need a page, and building one to satisfy the shape of a deploy is the wrong answer.
A **data project** is a project with a name and no files. Its URL 404s on purpose. Say so
plainly rather than apologising for it: it has no Open button, no short link and no
visitor analytics, because there is nothing to visit.
You cannot create one with a tool — it is one browser step. Send them to the dashboard,
under the upload bar: **"No page? Collect data instead."** Then, on its **Automations**
tab, they name a collection and get three things:
- **an inbound URL** another system sends to. A token is **append-only unless its owner
ticks a box** when minting it, and it can **never read** — that is the property that makes
handing one to a vendor tool safe, because the URL itself is the credential and it ends up
in proxy logs and CI output. What a token may do:
- `POST /api/ingest/{token}/{collection}` — add a record
- `POST …/{collection}/batch` — up to 200 add/update/remove in one call, each reported
separately (a 500-row sync is 3 calls, not 500)
- `PUT …/{collection}/{key}` — **replace** the record at a key you choose *(needs "let it
update records")*
- `PATCH …/{collection}/{key}` — **merge**: the fields you send are set, the ones you leave
out are untouched, and `null` removes one *(same tick-box)*
- `DELETE …/{collection}/{key}` — remove a record **written by a feed** (any feed in this project, not only this one) *(needs "let it remove
records"; a key already gone answers `deleted: false`, so a repeated cleanup is safe)*
⚠️ **`PATCH` is the one to reach for when a sender wants to change one field**, precisely
because there is no read: without it they must hold a full copy of every record on their
side and send it back whole, which drifts. This was a real support thread.
⚠️ **`batch` is the ONE door whose body is not the record.** Everywhere else the body IS the
record; a batch item is an envelope with the record under `data`. A bare record is refused,
and so is an item with fields BESIDE `data` — that used to store the inner part and drop
the rest silently. A batch where SOME items landed answers `200` with the detail per item; one where
**nothing** landed answers **`422`** — it used to answer `200`, and a sender checking only the
status code reported success while storing nothing. Tell people to read the body either way.
This was the second support thread, and guessing this shape is what caused it:
```
POST …/{collection}/batch
[ { "data": { "account": "Acme" } }, ← add, id generated
{ "key": "acct-1", "data": { "account": "Acme" } }, ← replace at that key
{ "op": "patch", "key": "acct-2", "data": { "x": 1 } },
{ "op": "delete", "key": "acct-3" } ]
→ { "accepted": 3, "failed": 1, "created": 1, "updated": 2, "unchanged": 0,
"results": [ …, { "index": 3, "error": "…" } ] }
```
⚠️ **`created` vs `unchanged` is how a sync learns it is duplicating.** Adding 2,000 rows
and updating the same 2,000 both answer `accepted: 2000`; if a feed re-sends the same
records and keeps reporting `created`, it is sending no `key` and the collection grows
every run. Tell people to key on the business id.
```
```
- **a scheduled fetch** that calls one of their API connections and keeps the reply —
either the latest value, or a record per run they can chart
- **a digest** of what arrived, to a channel, an inbox, or both — on a timer, or the
moment an entry lands
Everything it collects is readable in the **Data** tab and by `Opti.collection()` from any
page they deploy later — including a separate dashboard app that reads it. Deploying files
to a data project turns it into an ordinary project and keeps the data.
## Sharing & visibility
Every page is **public by default** — any signed-in Optimizely employee with the link can open it (legacy pages included). A page can instead be **private**: only the owner, admins, and an allowlist of `@optimizely.com` emails.
- **Set it at deploy time** — pass `visibility: 'private'` (and `allowed_emails: [...]`) to `deploy` or `prepare_upload`. This only applies to a *new* deployment; a re-deploy keeps the current setting.
- **Change it anytime** — `update_deployment` with `visibility` and/or `allowed_emails`. The allowlist you pass **replaces** the existing one (send everyone who should have access, not just additions). Switching to `public` clears the allowlist. People newly added are notified they've been granted access — everybody added at once shares a single email, not one each.
- **Share with a GROUP instead of a list** — `allowed_groups: ['Onboarding group']` on `deploy`, `prepare_upload` or `update_deployment`. Groups are **named lists of people the user keeps under Settings → Groups**, and they are the better answer whenever the audience is a group that will change: an allowlist is a snapshot, so a new joiner has to be added to every project separately, which is why so much ends up public. Add someone to the team once and they can open every project it's on — *including ones shared before they joined*.
- Refer to teams **by name**, not by id. You can only use teams the user already owns; if the name doesn't match, the error lists theirs.
- You **cannot create or edit a group** — there is no tool for it, deliberately. You may share
*with* a group the user already keeps; making one is theirs. Point them at **Settings → Groups**.
- `list_deployments` shows which teams a private page is shared with, by name.
- Non-org emails and the owner's own address are dropped automatically. Someone not on the portal yet gains access the moment they first sign in.
- Approving/declining incoming access *requests* happens in the dashboard (the notification bell), not through these tools.
- **Letting someone else UPDATE a page** (deploy new versions, not just view it) is a separate thing — "editors". If asked to give a colleague update/maintainer rights (e.g. "let Abbey keep this updated while I'm on leave"), there is **no tool for it**: tell the user to open the project page and add the person under **Editor access**. An editor deploys at the same link and manages the app's data/sharing, but can't rename, delete, or move the short link.
### Workspaces — when the work should outlive the person
A **workspace** is a namespace with people in it, and it **OWNS** the projects created in it.
That is the difference from everything above: a group shares *your* project with colleagues and
an editor may update *your* project, but both still leave it belonging to you. A project made in
a workspace belongs to the workspace, lives at `/{workspace}/{slug}/`, and stays exactly where it
is when whoever built it changes team or leaves. Its collections, connections and AI budget are
the workspace's too.
Roles are the workspace's own, and are **not** project roles: **Admin** (manages the workspace and
deploys to anything in it), **Creator** (adds new projects, and may only update the ones they made
— so a team of eight cannot overwrite each other's live sites), **Can view** (opens everything).
**These tools reach a workspace** — pass **`workspace: ''`** to `deploy` or
`prepare_upload` and the WORKSPACE owns the result. `list_deployments` returns the projects a
workspace owns that you may deploy to, each carrying `workspace`, and `update_deployment` takes
the same field.
⚠️ **`whoami` NAMES THE ONES YOU MAY USE, AND IT IS THE ONLY RELIABLE SOURCE.** Workspaces are
deliberately not enumerable — a slug you may not add work to is refused without saying whether
it exists — so do not guess one from a project URL or from what somebody typed. A slug you were
not given is a refusal, not a discovery mechanism.
⚠️ **Omitting it creates a PERSONAL project**, which is the failure to watch for: if somebody
says "put this in the team workspace" and you deploy without `workspace`, it succeeds and makes
something that belongs to them alone — a 200 that reads as the thing they asked for and is not.
- **Making a workspace is still theirs to do** — there is no tool for it, deliberately: the
address comes out of the same pool as everybody's username and cannot be changed afterwards.
Point them at `https://deploy.optimizely.com/workspaces`; anyone can, and it needs no approval.
- **An existing personal project cannot be moved into one.** A project belongs to a workspace
from birth — its data is stored under that name from the first write — so the answer is to
deploy it into the workspace as a new project, not to look for a transfer that does not exist.
- You *can* still build the thing. Build it, deploy it to their own namespace if they want to see
it now, and tell them the one step that moves ownership is theirs to take.
## Collections — your app's database (no backend, no API key)
A deployed app is static, but it is **not** stateless: the portal gives every app a
read/write data store. **Reach for this whenever the app needs to collect or persist
anything** — a survey, a feedback form, a signup list, a poll, a shared to-do, a
dashboard's saved rows. Do **not** substitute `localStorage`, a fake in-memory array,
or "you'd need a backend for that."
Add the SDK, then use it:
```html
```
**Writing many rows — `addAll()`, the write-side counterpart to `all()`.** A loop calling
`add()` once per row is the wrong shape above a handful: it is one request each, nothing
records that it happened, and a closed tab leaves the job half done.
```js
const usage = Opti.collection('usage')
// ⭐ `{ key }` IS THE WHOLE POINT — each row is addressed by YOUR OWN id, so a
// re-run UPDATES in place instead of appending. Without it every run appends,
// so a "refresh" button doubles the collection on every click and answers 200.
const res = await usage.addAll(rows, { key: 'id' })
// → { accepted, failed, created, updated, unchanged, deleted, results }
await usage.addAll(rows, { key: 'id' }, (batch, done, total) => { // progress
bar.value = done / total
})
```
`created` / `updated` / `unchanged` are four different facts, not one total: `accepted: 3000`
cannot tell a sync it is about to double the collection, and `unchanged: 3000` is what a
second run of the same data should say. Chunking is handled for you — pass every row.
⚠️ **A row missing the `key` field THROWS rather than appending.** Falling back to `add()`
would turn one absent field into a silent duplicate on every run, which is the failure this
method exists to prevent.
**Bringing the RELATED record with each row — `join`.** Two collections, one read: the rows you
asked for, each carrying the record its id points at.
```js
const rows = await Opti.collection('contacts').list({
join: { collection: 'accounts', on: 'account_id', fields: ['name', 'tier'] },
})
rows[0].related // { name: 'Acme', tier: 'gold' }
rows[0].data.name // the CONTACT's name — `related` is a sibling, never merged in
```
`on` names the field on the row you are reading whose value is the related record's key — the KEY it was saved under (`doc(key)`, `addAll(rows, { key })`, an ingest `key`) or its record id.
It never matches a field of the other record, and finds at most one: a teammate's many usage rows are
not a join. Without
`fields` you get the whole related record. A row whose relation is missing — or that you are not
allowed to see — arrives with `relatedNote` explaining why, rather than looking complete.
⚠️ You only get what YOU may read: the joined collection is checked against your own access, the
same way the rows themselves are. It is a lookup by id, not a search, so the cost does not grow
with the size of the other collection — ids are deduped, and a read that needs more than a couple
of hundred distinct lookups says `join.truncated`.
**Ask a question instead of downloading everything.** The server answers it across every
page, so the count is about the collection rather than about what you fetched — reach for this
before pulling every row and filtering in JS:
```js
const open = await Opti.collection('tickets')
.list({ where: { path: 'status', op: 'eq', value: 'open' } })
// `page()` also returns `total` — how many MATCHED, not how many exist
const { records, total } = await Opti.collection('tickets')
.page({ where: { path: 'amount', op: 'gt', value: 500 } })
```
Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `empty`, `notEmpty` — the same
set the automation conditions use — plus `in` for reads: `{ path: 'vau_id', op: 'in', value: ['a', 'b'] }`.
Updates, deletes and automations refuse `in`. `empty`/`notEmpty` take no value. A bounded scan reports
`scanned` and `truncated`, so a stopped-early answer never reads as a complete one.
⚠️ **When the scan stops early**, `list()`/`page()` say `truncated: true` (`total` is then a floor) and
`all({ where })` **throws** rather than hand back part of the matches. That is the one time to read
without `where` — `all({ fields })`, only the fields you use — and filter in the page.
⚠️ **`where` takes an ARRAY, ANDed — that is how a range is written**, since one condition
cannot carry two bounds. Up to four. There is no `OR`: the same question is what `PATCH` and
`DELETE` take, and narrowing is the safe direction.
```js
await Opti.collection('usage').page({ where: [
{ path: 'week', op: 'gte', value: '2026-01-01' },
{ path: 'week', op: 'lte', value: '2026-09-14' },
] })
```
⚠️ **`gt`/`gte`/`lt`/`lte` compare as numbers when both sides are numbers and as TEXT
otherwise**, so ISO dates order correctly — `2026-09` after `2026-01`. This is why a date range
works at all; it used to match nothing and answer `200` with an empty list, which reads exactly
like "no data in that range".
⚠️ **`fields` narrows what each record carries** — `page({ fields: ['name', 'team'] })`. The
question is still asked of the whole record and `total` is unaffected, so this is payload size
only. Reach for it when a row holds something long the page is not drawing; the 8 MB response
cap means fat rows make a big `limit` quietly return fewer.
⚠️ **`all()` takes the same options** — `all({ where: … })`, or `all(opts, onPage)` to render
progressively. It previously accepted a filter and silently ignored it, returning the whole
collection; passing something it cannot use now throws rather than answering wrongly.
**Two collections together — a total per group, a one-to-many lookup.** Read both with `all()`, only the
fields the page uses, and join in the page with a `Map` on the shared field; a few thousand rows take
milliseconds. `join` finds ONE record by key, so it cannot total or collect many.
```js
const [usage, teams] = await Promise.all([
Opti.collection('usage').all({ fields: ['vau_id', 'credits'] }),
Opti.collection('teammates').all({ fields: ['vau_id', 'org'] }),
])
const orgOf = new Map(teams.map((t) => [t.data.vau_id, t.data.org]))
const byOrg = {}
for (const { data: u } of usage) {
const org = orgOf.get(u.vau_id) ?? 'Unknown'
byOrg[org] = (byOrg[org] ?? 0) + u.credits
}
```
Zero-JS forms are wired automatically — this is often all a survey needs:
```html
```
### Pick the right shape — this is the thing to get right
Three ways to address a record. Choosing wrong is the most common mistake: an app
that should hold **one row per person** ends up appending a new row every time
someone hits save, and their "profile" quietly becomes a pile of drafts.
| You're building | Use | Why |
|---|---|---|
| A survey, feedback, a guestbook — **a stream of many** | `add()` / `list()` | Each submission is its own record |
| Preferences, an RSVP, a profile, a personal tracker — **one row per person, updatable** | `save()` / `mine()` | The row's id comes from the session, so a person always writes to *their* row |
| A shared board, who's on call, settings, a team to-do — **one shared thing** | `doc(key)` | One named document several people edit |
```js
// One row per person. Call save() as often as you like — it REPLACES, never appends.
const prefs = Opti.collection('preferences')
await prefs.save({ theme: 'dark' })
const mine = await prefs.mine() // → record | null
await prefs.forget() // delete YOUR row — the "reset my settings" button
// One shared thing that several people edit at once.
const board = Opti.collection('state').doc('kanban')
await board.update(b => ({ ...b, tasks: [...(b?.tasks ?? []), task] }))
```
⚠️ **For anything several people edit, use `doc(key).update(fn)`, not `set()`.**
`update` re-reads, applies your change and writes it back with a guard, retrying
if someone got there first. A plain `set()` overwrites whatever they just did, and
their edit disappears with no error and no trace.
**One response per person** (a poll, a vote, an RSVP) is a property of the
*collection*, not of your code: the owner sets it in the Data tab, and then even a
plain `