# Introduction (https://tabulic.com/docs) Give the apps you build with Claude and ChatGPT a real database. Tabulic keeps the data for the apps you build with Claude, ChatGPT and other AI tools. Your tables live in one place, so they stay put across chats and devices, and every AI you connect sees the same data. Every change is recorded under the name of whoever made it. Big changes wait for your approval, and anything can be undone. ## How it works 1. **Connect Tabulic to your AI.** Add it as a connector in Claude, ChatGPT, Claude Code, Cursor or any app that supports MCP. It takes about a minute. 2. **Ask for what you need.** “Make me a client tracker with name, email, status and monthly fee.” Your AI creates the tables and fills them in. 3. **Use it, check it, undo it.** Open your workspace to browse and edit the tables, approve what’s waiting, and roll back anything you don’t like. ## What you get - **A real database for your AI.** Tables with typed columns, not a spreadsheet glued to a chat. - **Apps on top.** Your AI can build you a small web app on your tables and publish it inside your workspace. No hosting, no API keys. - **A full change history.** What changed, when, and which AI, app or person did it. - **Approvals for risky changes.** Deletes, bulk edits and dropping tables wait until you say yes. - **Undo for everything.** Roll back one change, or everything from a single chat. - **Your data, portable.** Download a workspace as one file, history included. ## Where to go next - [Get started](https://tabulic.com/docs/getting-started): Sign up, connect your AI and make your first table. - [Use cases](https://tabulic.com/docs/use-cases): Ideas and prompts for what to build. - [Concepts](https://tabulic.com/docs/concepts): How workspaces, agents, apps and changesets fit together. - [Reference](https://tabulic.com/docs/reference/mcp-tools): Every MCP tool and the App API, for developers and agents. > **Docs for AI agents** > > The whole documentation is available as plain text at [llms.txt](https://tabulic.com/llms.txt) (an index) and [llms-full.txt](https://tabulic.com/llms-full.txt) (every page). Point your agent at it. --- # Getting started (https://tabulic.com/docs/getting-started) Connect Tabulic to Claude or ChatGPT and make your first table in a few minutes. ## 1. Sign up and make a workspace Go to [app.tabulic.com](https://app.tabulic.com) and sign in with your email. Tabulic sends you a link; there’s no password. Then create a **workspace**: one set of tables, such as your clients and invoices. Give it a **handle**, a short name like `clients`. The handle is part of the workspace’s address (`app.tabulic.com/w/clients`) and never changes. > You can skip this step and let your AI create the workspace for you later, if you allow it to when you connect. ## 2. Connect your AI Every AI app uses the same connector address: ```txt title="Connector address" https://mcp.tabulic.com ``` **Claude** On claude.ai or in the Claude desktop app: 1. Open **Settings → Connectors** and choose **Add custom connector**. 2. Name it Tabulic, paste the connector address, choose **Add**, then **Connect**. 3. Sign in with your email if asked, then approve the connection (see below). 4. In a chat, open the tools menu under the message box and check that Tabulic is on. **ChatGPT** 1. Open **Settings → Connectors**. If you don’t see **Create**, turn on **Developer mode** under **Advanced**. 2. Choose **Create**, paste the connector address and pick **OAuth**. 3. Sign in and approve the connection (see below). 4. Turn the connector on in a chat. **Claude Code** Run this in your terminal: ```bash claude mcp add --transport http tabulic https://mcp.tabulic.com ``` Then type `/mcp` inside Claude Code, choose **tabulic** and sign in. **Other apps** Cursor, VS Code, Codex, Gemini and other apps that support MCP work the same way: add a remote MCP server of the **HTTP (streamable)** type with the connector address, then sign in when asked. ### Approve the connection When you connect, Tabulic asks you to **name the agent**, for example “Claude” or “ChatGPT”. That name goes on every change it makes. By default the agent may read and change your workspaces, create tables and publish app pages. Choose **Customize** to narrow that for each workspace (no access, read only, read and write, or also make tables), or tick **May create workspaces** to let it make new ones. You can change all of this later. ## 3. Ask for something Start a new chat and talk to your AI as usual: > “Make me a client tracker in Tabulic with name, email, status and monthly fee, and add these clients: …” > “Mark Acme as inactive.” > “Which clients pay more than $500 a month?” Your AI creates the tables and fills them in. Open your workspace at [app.tabulic.com](https://app.tabulic.com) to see them. You can sort, filter and edit cells yourself, too. ## 4. Review and undo Now try something bigger: > “Delete the inactive clients.” Deletes wait for you by default. Your AI tells you a change is waiting, often with a **Review and approve** button. Open it on the **Changes** screen to see each row before and after, then choose **Approve** or **Reject**. Changed your mind about something that already happened? Open it on **Changes** and choose **Roll back**. > **Warning** > > Your AI can ask for approval but can never give it. Only you can approve, on Tabulic’s own screens. ## 5. Build an app (optional) Ask your AI to put a page on top of your tables: > “Build me a page to track my clients on my Tabulic workspace.” It publishes the page inside your workspace and sends you a link. Open it, choose **Allow**, and bookmark it. See [Build an app](https://tabulic.com/docs/guides/build-an-app) for more. ## Next steps - [Use cases](https://tabulic.com/docs/use-cases): What people build with Tabulic, with prompts to copy. - [Review and undo](https://tabulic.com/docs/guides/review-and-undo): Approvals, rollbacks and conflicts in detail. - [Control what AI can do](https://tabulic.com/docs/guides/control-access): Scopes and approval rules for each agent. --- # Use cases (https://tabulic.com/docs/use-cases) Ideas for what to build with Tabulic, with prompts you can copy into Claude or ChatGPT. Anything you’d keep in a spreadsheet, you can hand to your AI with Tabulic underneath. Here are some starting points. Each one comes with a prompt to copy; change the details to fit your work. > Start every prompt in a chat where Tabulic is connected. Mentioning “Tabulic” or “my Tabulic workspace” helps your AI pick the right tools. ## Sales and clients ### Client tracker and deals pipeline Keep every client, their contact details and the next step in one place, with deals moving through stages. > “Set up a sales CRM in my Tabulic workspace: a contacts list and a deals pipeline with stage, value, owner and next step. Then build me a page to work with them.” Later, in any chat: “Move the Northwind deal to Negotiation and set the next step to ‘send revised quote’.” “Which deals over $10k haven’t moved in two weeks?” **Why Tabulic:** the pipeline is the same in every chat, and if your AI updates the wrong deal, you roll it back in one click. ### Quotes and proposals Track which proposals went out, to whom, for how much, and which ones need a follow-up. > “Make a proposals table in Tabulic with client, amount, sent date, status and follow-up date. Add the three proposals from the email I pasted.” ## Operations ### Inventory and reorders Stock levels, suppliers and reorder points, updated as things sell. > “Track our stock in Tabulic: product, SKU, supplier, quantity on hand and reorder level. Then tell me which products are below their reorder level.” **Why Tabulic:** a bulk update like “set every Acme product to 0 stock” waits for your approval before it touches anything. ### Vendors and contract renewals Never miss a renewal again. > “Create a vendors table with contract value, renewal date, notice period and owner. Which contracts need notice in the next 60 days?” ### Equipment checkout Laptops, cameras or tools: who has what, and since when. > “Build me an equipment checkout page on Tabulic: items, who has each one, when they took it and when it’s due back.” ## People and hiring ### Hiring pipeline Candidates, interview stages, interviewers and feedback. > “Set up a hiring pipeline in Tabulic for our two open roles: candidates with role, stage, source and interview dates, plus a feedback table linked by candidate name.” Later: “Summarize the feedback for every candidate in the final stage.” ### Onboarding checklists A checklist per new starter, so nothing slips. > “Make an onboarding tracker: new starters, start date, and a tasks table with owner, due date and done. Add our standard 12 tasks for Priya, who starts on the 3rd.” ## Marketing and content ### Content calendar Posts, authors, channels and publish dates, and what’s next at a glance. > “Build a content calendar in Tabulic with title, channel, author, status and publish date, and a page that shows the next two weeks.” ### Customer feedback inbox Paste feedback in as it arrives and let your AI tag it. > “Add these 30 support messages to a feedback table in Tabulic, and tag each one with product area, sentiment and whether it’s a bug or a request.” Later: “What were the top three requests this month?” **Why Tabulic:** adding 30 rows applies at once, but if the tagging goes wrong you can roll back the whole batch as one changeset. ## Finance ### Invoices and payments Who owes what, and what’s overdue. > “Make an invoices table in Tabulic with client, amount, issue date, due date and paid. Which invoices are overdue, and by how much in total?” ### Expenses by project > “Track expenses in Tabulic by project, category, amount and date, and give me this month’s totals per project.” ## Research and data work ### Lead and competitor research Let your AI gather information into a table you can review, instead of a wall of chat text. > “Research 20 accounting software companies for small businesses and save them to Tabulic with name, website, pricing model and target customer.” ### Clean up a messy import Paste in a messy list and have your AI tidy it, with every change reviewable. > “Import this CSV into a contacts table in Tabulic, then find duplicates and merge them.” **Why Tabulic:** merging duplicates means deleting rows, so it waits for you. You see exactly which rows go before you approve. ### Weekly reports Ask questions across tables. Your AI can run read-only SQL over your data. > “Using my Tabulic workspace, compare this month’s closed deals with last month’s, by owner.” ## Advanced: more than one AI, scripts and apps ### Several AIs on the same data Connect Claude, ChatGPT and Claude Code to the same workspace. Each one is a separate **agent** with its own name, access and approval rules. For example: Claude Code builds the tables and the app; ChatGPT on your phone adds entries; a read-only agent writes the weekly summary. ### Scripts and nightly syncs An app doesn’t have to be a web page. Give a script a **secret key** and it can read and write your tables over the [App API](https://tabulic.com/docs/reference/app-api), for example to copy new orders from your shop every night. Its changes carry its own name and can be rolled back like any other. ### A small internal tool Combine the ideas above: tables for requests, an approvals page your AI built, and a script that sends a summary every morning. Tabulic is the database underneath all three. - [Get started](https://tabulic.com/docs/getting-started): Connect your AI and try one of these. - [Build an app](https://tabulic.com/docs/guides/build-an-app): Turn any of these into a web page. --- # Build an app (https://tabulic.com/docs/guides/build-an-app) Have your AI build a web page on your tables and publish it inside your workspace. Your AI can build you a small web app on top of your tables, such as a client tracker, an approvals page or a stock counter, and publish it inside your Tabulic workspace. There’s nothing to host and no keys to manage. ## Ask for it In a chat with Tabulic connected: > “Build me a page to track my clients on my Tabulic workspace.” Your AI reads Tabulic’s app guide, makes any tables the app needs, writes the page and publishes it. It sends you a link like: ```txt https://app.tabulic.com/w/clients/apps/client-tracker ``` > If your AI says it can’t publish pages, open the agent on the **Agents** screen in your workspace and tick **May publish app pages**. If it says it has no `publish_page` tool at all, disconnect Tabulic in your AI’s connector settings, connect it again (choosing the agent you already have), and start a new chat. ## Open and allow it 1. **Open the link.** You’re already signed in to your workspace, so the app opens right there. 2. **Allow it.** The first time, Tabulic asks above the page whether to let the app in. It shows which agent published it and which tables and columns it wants. Untick anything it shouldn’t touch, then choose **Allow**. 3. **Bookmark it.** If a later version of the page asks for more, Tabulic asks you again and shows what changed. Only you can open your apps. Your apps are listed on the **Apps** screen of your workspace. ## Change it Ask any connected AI, even in a new chat: “Add a ‘last contacted’ column to my client tracker page.” It reads the current page, edits it and publishes a new version. If an update breaks something, open the app’s **Settings** on the **Apps** screen. **Its page** lists every version with who published it and when; **Restore** brings an older one back. ## What an app can and can’t do An app is its own **actor**, with its own name, like an agent. Everything it changes shows up under its name on **Changes**, and you can roll it back. - **Its writes apply at once by default.** Someone clicking a button can’t wait for an approval. You can make some kinds wait, such as deletes, in the app’s **Settings**. - **It only reads and writes rows.** It never creates tables or changes columns; the agent that built it does that first. - **It runs in a sandbox.** The page can’t send your data anywhere except through Tabulic, as the app, with the access you allowed. It never sees a password or key. Two things a browser can’t stop: a link the page opens when you click goes wherever the page says, and could carry what the page shows. Don’t click links in an app you don’t trust. > **Tips for good apps** > > - Ask for the page to “match Tabulic’s look”. It does by default, in light or dark mode. > - Pages can’t use `alert()` or `confirm()`, and anything they should remember belongs in a table, not in the browser. > - A page updates itself when the data changes, including changes your AI makes in a chat. ## Other kinds of apps - **Hosted elsewhere.** A page on your own site can sign in to Tabulic and use the same API. - **Scripts and servers.** Give an app a **secret key** on its **Settings** page and call the API from code. - **Claude artifacts.** An artifact in claude.ai can use your Tabulic connector directly. Its changes are then the agent’s (“Claude”), not an app’s. See the [App API reference](https://tabulic.com/docs/reference/app-api) for the details, and [Apps](https://tabulic.com/docs/concepts/apps) for how they work. ## Remove an app In the app’s **Settings**: - **Unpublish** takes the page down. The app and its history stay; publishing the same name again brings it back. - **Delete app** disconnects it everywhere, stops its keys and unpublishes its page. What it did stays on **Changes** under its name and can still be rolled back. --- # Review and undo (https://tabulic.com/docs/guides/review-and-undo) See what your AI changed, approve what’s waiting, and roll back anything. Everything that changes in your workspace is on the **Changes** screen: newest first, with the agent, app or person who did it. ## Changes come in groups An AI’s changes are grouped into **changesets**, usually one per request. “Add these five clients and mark Acme inactive” becomes one changeset you can review and undo as a unit. Your AI can also name a group, such as “Import from March CSV”, so it’s easy to find with **Search labels**. ## Approve what’s waiting Some changes wait for you instead of applying. By default these are: - deleting rows - changing more than 10 rows at once - removing a column or table - changing a column’s type When a change waits, your AI tells you, often with a **Review and approve** button right in the chat (in Claude, ChatGPT, VS Code and Cursor). The button opens the change in Tabulic. 1. Open the waiting changeset at the top of **Changes**. 2. Check each row before and after. 3. Choose **Approve** to apply it, or **Reject** to drop it. Nothing in a waiting changeset touches your data until you approve. If rows changed after the AI asked, approving shows you what’s different and asks again. If new rows that match were added meanwhile, Tabulic tells you how many and who added them, and leaves them alone. > **Warning** > > Only you can approve, and only on Tabulic’s screens. An AI can’t approve its own changes, even if text in a table tells it to. ## Roll back Open any applied changeset and choose **Roll back…**. Tabulic works out what rolling back would do first: - **Each change is reversed.** Added rows go, deleted rows come back, edited cells return to their old value. - **Your later edits are respected.** If you, an app or another agent changed some of the same cells since, you choose for each cell whether to keep the current value or revert it, or decide for all at once. - **Dropped columns and tables come back with their data.** - **Later AI changes that depend on it go too.** Rolling back the creation of a table also rolls back the AI’s later writes to it. A rollback is itself a changeset, so you can roll back a rollback. ## How far back You can roll changes back for as long as your plan keeps history. After that, Tabulic erases the old values but keeps the record of who changed which rows, and when. See [History and purging](https://tabulic.com/docs/concepts/history). ## Edit tables yourself On **Tables**, double-click a cell to change it, or add rows. Your own edits apply at once, are grouped into your own changesets, and can be rolled back like an AI’s. --- # Control what AI can do (https://tabulic.com/docs/guides/control-access) Choose which tables each agent can see and change, and which of its changes wait for you. Every AI you connect is a separate **agent**, and each one has two sets of settings in each workspace: - **What it may touch** (its [scope](https://tabulic.com/docs/concepts/scope)): which tables and columns it can read or write. - **What waits for you** (its [approval rules](https://tabulic.com/docs/concepts/approval-rules)): which kinds of changes apply at once and which wait for your approval. Only you can change these. An agent can read its own settings but never change them. ## Change what an agent may touch Open the workspace, go to **Agents**, open the agent and choose **What it may touch**. You can set: - whether it may **create tables** and change their columns - whether it may **read every table** - for each table: **no access**, **read**, or **read and write**, optionally limited to some columns An agent always gets read and write on a table it creates. Columns added later stay hidden from an agent limited to some columns, unless it adds them itself. A change applies from the agent’s next request. Changes already waiting stay as they are. > To take an agent out of one workspace entirely, set its access there to **None**. To cut off a connection everywhere at once, use **Disconnect** on your account page; its past changes stay. ## Change what waits for you On the same agent page, open its approval rules. For each kind of change, choose **applies** or **waits**: | Kind of change | Default | |---|---| | Adding or changing a few rows | applies | | Adding many rows | applies | | Changing many rows | waits | | Deleting rows (any number) | waits | | Creating or renaming a table or column | applies | | Removing a table or column, changing a column’s type | waits | “Many rows” means more than the agent’s **bulk threshold** in one request: 10 unless you change it. Fifty single-row changes are fifty small ones. Making more changes wait is always available. Letting more apply at once (for example, letting small deletes through) needs the paid plan; on the free plan, a looser rule acts as the default. Whatever applies at once can still be rolled back. ## Apps have their own settings An app your AI built has the same two kinds of settings, in its **Settings** on the **Apps** screen. Its writes apply at once by default, since someone clicking a button can’t wait. An app never creates tables or changes columns. ## Good setups - **A read-only reporter.** Connect a second agent, give it **read** on everything and no write access, and use it for summaries and questions. - **Hide sensitive columns.** Limit an agent on your Clients table to name, company and status, leaving out email and fee. - **Extra caution during an import.** Set a low bulk threshold so every large edit waits while your AI cleans up data. --- # Move an existing app (https://tabulic.com/docs/guides/move-an-existing-app) Bring an app you already built in Claude or ChatGPT, and its data, into Tabulic. Already built something whose data keeps disappearing between chats, or only lives in one browser? You don’t have to start over. 1. **Connect Tabulic** to Claude or ChatGPT. See [Getting started](https://tabulic.com/docs/getting-started). 2. **Open the chat where you built the app** (or paste the app’s code into a new one) and ask: > “Connect this app to Tabulic and move its data there.” 3. **Your AI sets up the tables** the app needs and copies the data across. Adding rows applies at once, so you can check the tables in your workspace straight away. 4. **Your AI publishes the app** inside your workspace and sends you the link. Open it, choose **Allow**, and bookmark it. From now on, it reads and writes your Tabulic tables. ## Tips - If the data is in a spreadsheet or CSV, paste it in or attach the file and ask: “Import this into a table in Tabulic.” - Ask your AI to label the import (“label it ‘Import from old app’”) so you can find it, or roll it back in one go if something went wrong. - Chat previews and artifacts can’t load Tabulic’s app script. Use the published link instead of the preview to try the app. --- # Your data (https://tabulic.com/docs/guides/your-data) Download a workspace, take it elsewhere, and manage connections. ## Download a workspace **Download** on your account page saves a whole workspace as one file, with its full change history. Nothing in it can be used to sign in: exported copies never carry working keys or tokens. The free, self-hosted Tabulic opens that file on your own computer. ## See and cut off connections Your account page lists your agents, the workspaces each one can reach, and their connections (each app or device it signed in from). - **Disconnect** cuts a connection off immediately. The agent’s past changes stay, with its name on them. - To keep an agent out of one workspace, set its access there to **None** on the **Agents** screen. - An app’s connections and secret keys are in its **Settings** on the **Apps** screen. ## Workspaces Each workspace is a separate set of tables, with its own history, agents’ settings and apps. Use one per area of work, such as `clients`, `hiring` or `inventory`. One connection to your AI reaches every workspace you allow it to. A workspace’s **handle** is part of its address and never changes; its display name can. --- # How Tabulic works (https://tabulic.com/docs/concepts) The model behind Tabulic in one page, for advanced users and AI agents. Tabulic is a data store that AI agents read and write on a person’s behalf, where every change an agent makes can be seen, approved and undone. ## The model ```txt Account (you, signed in by email) ├── Agents one per AI you connect: "Claude", "ChatGPT", "Claude Code"… └── Workspaces each one a self-contained set of tables ├── Tables → Columns (typed) → Rows ├── Apps programs your agents built, acting as themselves ├── Per-agent and per-app settings: Scope + Approval rules └── Change log append-only; every Change, grouped into Changesets ``` - An **actor** is whoever made a change: an **agent**, an **app**, or you, the **owner**. - Every write by an actor becomes one or more **changes** (one per row or schema object, with before and after values), grouped into a **changeset**. - A changeset is either **applied** or **pending**. It’s pending when the actor’s **approval rules** say that kind of write waits. Only the owner can approve. - Any applied changeset can be **rolled back** within the workspace’s **history window**. The rollback is a new changeset by the owner. - What an actor can see and write is its **scope**, set only by the owner. ## Principles 1. **The change log is the source of truth.** Tables are the result of applying it. Rollback applies the reverse of each change. 2. **The owner decides; agents ask.** Approving, rejecting, rolling back and changing scopes or rules are never available to agents as tools. An agent can request approval but can’t grant it. 3. **Nothing is silently lost.** Dropped tables and columns are hidden and kept until the history window passes. A rollback never overwrites a later human or app edit without asking. 4. **Every actor is named.** Agents and apps act under their own name, across reconnections, so the history always says who did what. ## Read on - [Workspaces and agents](https://tabulic.com/docs/concepts/workspaces-and-agents) - [Changes and changesets](https://tabulic.com/docs/concepts/changesets) - [Approval rules](https://tabulic.com/docs/concepts/approval-rules) - [Scope](https://tabulic.com/docs/concepts/scope) - [Apps](https://tabulic.com/docs/concepts/apps) - [History and purging](https://tabulic.com/docs/concepts/history) - [Glossary](https://tabulic.com/docs/concepts/glossary) --- # Workspaces and agents (https://tabulic.com/docs/concepts/workspaces-and-agents) Accounts, workspaces, handles, agents and connections. ## Account You sign in to Tabulic with one email address. Your **account** holds your plan, the workspaces you own and your agents. It lives outside every workspace, so a downloaded workspace carries nothing about your account except the names of the agents in its history. ## Workspace A **workspace** is one self-contained body of data: its tables, rows, change history, apps and the settings for each agent and app in it. Each workspace is stored as a single file. Every workspace has a **handle**: a short name, unique across Tabulic, that is part of its address and never changes. ```txt https://app.tabulic.com/w/ the workspace's screens https://app.tabulic.com/w//apps/ an app's page https://app.tabulic.com/w//v1/ the App API ``` The display name can repeat and can be changed. The owner creates workspaces on their account page, or an agent does with `create_workspace` if the owner allowed it. ## Owner The **owner** is the single person a workspace belongs to, and the only one who can approve or roll back changes, or change what agents and apps may do. The owner’s own writes never wait for approval. ## Agent An **agent** is a named identity under which an AI tool acts, such as “Claude” or “Claude Code”. You name it when you connect the tool. - It belongs to your account. One connection reaches every workspace you let it. - In each workspace it has its own [scope](https://tabulic.com/docs/concepts/scope) and [approval rules](https://tabulic.com/docs/concepts/approval-rules). - It keeps its name and history across reconnections. Reconnect and choose the existing agent to carry on as it. Connect two tools under two names (“Claude”, “ChatGPT”) to tell their changes apart and give them different access. ## Connection A **connection** is one authorization through which a host acts as an agent, or a browser or script acts as an app. Tabulic runs its own OAuth sign-in, so connecting never involves copying a key into a chat. An agent or app can have several connections over time; disconnecting one revokes it at once and leaves the history alone. ## The connector All AI tools use one MCP connector address: ```txt https://mcp.tabulic.com ``` It speaks MCP over Streamable HTTP with OAuth. The server tells every agent, in its instructions: > Tabulic stores tables for the person you work for, in workspaces: call `list_workspaces` first, and name the workspace (its handle) in every other tool. Every change you make is recorded and can be reviewed and rolled back by them. Some writes wait for their approval: when a write comes back with status “pending”, tell the person and do not retry it. To build an app on a workspace’s tables, call `app_guide` first. See the [MCP tools reference](https://tabulic.com/docs/reference/mcp-tools). --- # Changes and changesets (https://tabulic.com/docs/concepts/changesets) How writes are recorded, grouped, approved and rolled back. ## Change A **change** is one recorded modification to one row, or to the schema, with the before and after values of what it touched. Changes are appended to the workspace’s change log and never edited. ## Changeset A **changeset** is a group of changes by one actor that is reviewed and rolled back as a unit. It is always either entirely applied or entirely pending. How writes are grouped: - **By default**, an agent’s consecutive writes group into one changeset per stretch of work, usually one per request. - **`begin_changeset`** starts a new, named group. The label shows on **Changes** and is searchable. - **A batch** (`write_batch`, or `app.batch` for apps) is one call carrying up to 100 inserts, updates and deletes that become exactly one changeset under its label. - **A write that waits** always gets a changeset of its own. For an app, a label begun with `POST /v1/changesets {"label"}` stays on its changesets until a new label or ten idle minutes. Use a batch when writes must stay together. ## Batch A batch is all or nothing: - If every write in it may apply, they all apply. - If any write would wait, the **whole batch waits**, and nothing applies until the owner approves. - One invalid write refuses the whole batch, naming it (`writes[2]: …`). - Every write picks its rows as the batch arrives, **not** after the batch’s earlier writes. A later write in the batch doesn’t see rows an earlier one inserted. ## Pending changeset A **pending changeset** has been requested but not applied, because the actor’s approval rules say that kind of write waits. - Its targets are fixed when it is requested. When approved, it acts on the rows its filter matched then. Matching rows added meanwhile are left; the approval screen says how many and who added them. - If rows it targets changed since, approving shows the difference and asks again. - While an insert waits, its rows don’t exist. An agent’s `query` says how many rows are waiting instead. - The actor can **withdraw** its own pending changeset. A pending changeset left past the history window **expires**: nothing of it was applied, and it is purged. Statuses: `pending`, `applied`, `rejected`, `withdrawn`, `expired`. ## Approval **Approval** is the owner’s decision to apply a pending changeset. It happens only on Tabulic’s screens. In hosts that support MCP Apps, a pending write shows its diff inline in the chat with a link to approve it there; the approval itself never happens in the conversation. ## Rollback A **rollback** undoes an applied changeset by applying the reverse of each of its changes. It is itself a new changeset by the owner, so it can be rolled back too. Each changeset is rolled back at most once; to bring its changes back, roll back the rollback. ### Conflicts A **conflict** is a cell that a rollback would revert, but that the owner or an app has changed since. The owner chooses, per cell, whether to keep the later value or revert. Keeping any cell of a row keeps that row. ### Cascade A **cascade** is the later changes by agents that a rollback also reverses because they depend on what it removes, such as writes to a table whose creation is being rolled back. Later changes by the owner and by apps never cascade; they become conflicts instead. ### Rows added since If rows were added since to a table a rollback brings rows back into, nothing removes them. The rows brought back sit beside them, and the rollback screen says how many were added and by whom. ## Drop A **drop** removes a table or column from view. Its data is kept until the history window passes, so rolling back the drop restores it, along with agents’ access to it. --- # Approval rules (https://tabulic.com/docs/concepts/approval-rules) Which writes apply at once and which wait for the owner, per agent and per app. An **approval rule** is a per-actor setting, for one kind of write, of whether it applies at once or waits as a pending changeset. Each agent and app has its own set in each workspace, plus a **bulk threshold**. ## Kinds of write | Kind | What it covers | Agent default | App default | |---|---|---|---| | `insert` | adding rows, up to the threshold | applies | applies | | `update` | changing rows, up to the threshold | applies | applies | | `delete` | deleting rows, up to the threshold | **waits** | applies | | `bulk-insert` | adding more rows than the threshold in one write | applies | applies | | `bulk-update` | changing more rows than the threshold in one write | **waits** | applies | | `bulk-delete` | deleting more rows than the threshold in one write | **waits** | applies | | `create` | a table or column | applies (always, for now) | n/a | | `rename` | a table or column | applies (always, for now) | n/a | | `drop` | a table or column | **waits** | n/a | | `change-type` | a column’s type | **waits** | n/a | The bulk threshold is **10 rows** unless the owner changes it. It counts rows touched by **one** write; fifty single-row writes are fifty small ones. Apps never change the schema, so only the row kinds apply to them. Their writes apply by default because a person clicking in an app can’t wait for an approval. ## How rules are checked - A rule is checked **when the write is made**. Changing a rule never touches writes already waiting or applied. - In a batch, if any write would wait, the whole batch waits. - A write that waits says which rule held it back (`waits_for`, `reason`) and links to where the owner reviews it (`review_url`). - The owner’s own writes never wait. ## Who sets them Only the owner, on the **Agents** screen (or an app’s **Settings**). An agent can read its own rules with `describe_schema` but never change them. There is no floor: any kind may be set to apply at once, since every change can still be rolled back within the history window. On the hosted service, rules looser than the defaults need the paid plan; on the free plan a looser rule acts as the default. ## For agents When a write comes back with `"status": "pending"`: 1. Tell the person it is waiting for their approval, with the link if there is one. 2. **Don’t retry it.** Retrying creates another pending changeset. 3. Check later with `changeset_status`, or take it back with `withdraw_pending`. --- # Scope (https://tabulic.com/docs/concepts/scope) What each agent and app may see and touch. **Scope** is what an agent or app may touch in a workspace. It is set by the owner, never by the agent or app. ## What a scope contains For an **agent**: - whether it may **change the schema** (create tables, add, rename and drop columns, change types) - whether it may **read every table** - for each table: **none**, **read** (`r`) or **read and write** (`rw`), optionally limited to some columns - whether it may **publish apps’ pages** - on the hosted service, whether it may **create workspaces** For an **app**: per-table `r` or `rw`, optionally limited to some columns. An app never changes the schema. The app asks for access when it signs in (`tabulic.app({ name, access: { tbl_1: "rw" } })`), and the owner can narrow it on the consent screen. ## Rules - **An agent gets read and write on a table it creates**, and a column it adds joins its column list. This is the only way scope grows without the owner. - **Columns added later stay hidden** from an agent limited to some columns, unless it adds them itself. - **Changes apply from the next call.** Writes already waiting stay as they are. - **Drops keep access.** If a table or column is dropped, access to it is kept, so rolling back the drop restores it. - **Scope applies to every read**, including the read-only `sql_query`: tables and columns outside it don’t exist for that agent. ## Defaults A new agent connected with the defaults may read and change every workspace it can reach, create tables and publish app pages. **Customize** on the consent screen narrows this per workspace. An agent you already have keeps its current scope when it reconnects. An agent reads its own scope with `describe_schema`: which tables it may read and write, and whether it may change the schema. --- # Apps (https://tabulic.com/docs/concepts/apps) Programs your agents build, which read and write your tables as themselves. An **app** is a program the owner’s agent built (usually a web page, sometimes a server or script) that reads and writes the workspace’s data, under its own name, for the person using it. ## Apps are actors Like an agent, an app has its own name, [scope](https://tabulic.com/docs/concepts/scope) and [approval rules](https://tabulic.com/docs/concepts/approval-rules). Its changes are recorded under its name and can be rolled back. Unlike an agent: - **Its writes apply at once by default**, because a person clicking in it can’t wait for an approval. The owner can make some kinds wait. - **It never changes the schema.** The agent that built it creates the tables first. - **Its later edits count as the owner’s** when rolling back an agent’s changes: they come up as conflicts, never undone silently, and they never cascade. ## Kinds of app | Kind | Where it runs | How it signs in | |---|---|---| | **Published page** | inside the workspace, at `/w//apps/` | the owner allows it the first time they open it | | **Hosted elsewhere** | any `https` address, or `localhost` | `app.signIn()` sends the owner to Tabulic’s consent page and back | | **Script or server** | anywhere | a secret key, `Authorization: Bearer tabulic_sk_…` | ## Published pages An agent with permission publishes a page with `publish_page({name, title, html})`: one self-contained HTML file. Publishing to the same name makes a new version of the same app. Any agent can update it later: it reads the current HTML with `read_page`, edits it and publishes again. - A newly published app **waits to be allowed**, touching nothing, until the owner first opens it and chooses **Allow**. - If a new version asks for more access, Tabulic asks the owner again. - Every version is kept (within the history window, and always the current one). The owner can **Restore** an older one or **Unpublish**. - Only the owner can open a workspace’s pages. ## The sandbox An app’s page is agent-written code, and a row in your tables could have steered that agent. So every page runs in a sandboxed frame below the workspace’s top bar: - The frame has no address of its own, so it can’t touch Tabulic’s screens or your sign-in. - It may load scripts only from the workspace (`tabulic.js`) and a few public CDNs (cdnjs, jsdelivr, unpkg). - It can’t send requests anywhere, not even to Tabulic. `tabulic.js` hands each call to the page around it, which makes it as the app, with the app’s access. The app’s credentials never reach the page’s code. - Images must be `data:` or `blob:` URLs. `localStorage` doesn’t persist; anything to remember belongs in a table. - `alert()`, `confirm()` and `prompt()` do nothing (`confirm` returns false). Pages ask in their own way, such as a second click. - Links leave with `target="_blank"` or `target="_top"`. What a browser can’t stop: a link or window the page opens on a click goes wherever the page says, and could carry what the page shows. By default a page links `tabulic.css` and looks like Tabulic around it, in light or dark mode. ## Claude artifacts are not apps A Claude artifact can read and write Tabulic through the claude.ai connector. Its writes are then the connector’s agent’s (for example “Claude”), under that agent’s rules, and it only works inside Claude. See the [App API](https://tabulic.com/docs/reference/app-api) for building one. --- # History and purging (https://tabulic.com/docs/concepts/history) How long changes can be rolled back, and what happens after. ## History window The **history window** is how far back a workspace keeps the changes it can roll back, counted from when each changeset was decided (applied, rejected or withdrawn). It depends on your plan on the hosted service; self-hosted, it’s a workspace setting (1 year by default, or forever). ## Purge Once a changeset is past the history window, it is **purged**: - The values in its row changes are erased. - Who changed which rows and columns, and when, is kept. The **Changes** list still shows it. - It can no longer be rolled back. - Storage hidden by a drop goes for good once nothing kept refers to it. - Old versions of app pages go too, except the current one. Purging runs whenever the workspace is opened, and hourly while it is being served. ## Expired A pending changeset that waited past the history window without an approval **expires**. Nothing of it was applied, and it is purged at once. --- # Glossary (https://tabulic.com/docs/concepts/glossary) Every Tabulic term, defined in one place. **Account**: How an owner signs in on the hosted service: one email address, a plan, the workspaces it owns and its agents. **Actor**: Whoever made a change: an agent, an app or the owner. **Agent**: A named identity under which an AI tool acts, such as “Claude”. Belongs to the account, with its own scope and approval rules in each workspace. **App**: A program an agent built that reads and writes the workspace’s data under its own name. Most have a page published in the workspace; others are scripts with a secret key or pages hosted elsewhere. **Approval**: The owner’s decision to apply a pending changeset. Only the owner can give it; an agent can only request it. **Approval rule**: A per-actor setting, for one kind of write, of whether it applies at once or waits. **Batch**: One call carrying up to 100 inserts, updates and deletes that become one changeset, all or nothing. **Bulk write**: One insert, update or delete that touches more rows than the actor’s bulk threshold (10 by default). **Cascade**: Later agent changes that a rollback also reverses because they depend on what it removes. **Change**: One recorded modification to one row or to the schema, with before and after values. **Changeset**: A group of changes by one actor, reviewed and rolled back as a unit. Entirely applied or entirely pending. **Conflict**: A cell a rollback would revert that the owner or an app has changed since. The owner chooses per cell. **Connection**: One authorization through which a host acts as an agent, or a browser or script acts as an app. **Drop**: Removing a table or column from view. Its data is kept until the history window passes. **Expired**: A pending changeset that waited past the history window. Nothing of it applied. **Handle**: The unique, permanent short name of a workspace, part of its address. **History window**: How far back a workspace keeps changes that can be rolled back. **Owner**: The single person a workspace belongs to; the only one who can approve or roll back. **Pending changeset**: A changeset requested but not yet applied, waiting for approval. Its targets are fixed when requested. **Plan**: What an account may use on the hosted service: workspaces, agents, apps, history window, monthly writes and size. **Purge**: Erasing the values of changesets past the history window, keeping who changed what and when. **Rollback**: Undoing an applied changeset by applying the reverse of each change. Itself a new changeset. **Scope**: What an agent or app may touch: tables, columns, read or write, schema changes, publishing pages. Set only by the owner. **Workspace**: One self-contained body of data: tables, rows, change history, apps and per-actor settings. --- # MCP tools (https://tabulic.com/docs/reference/mcp-tools) Every tool Tabulic gives a connected agent, with its inputs and behavior. Connect to `https://mcp.tabulic.com` (MCP over Streamable HTTP, OAuth). Every tool except `list_workspaces` and `create_workspace` takes a **`workspace`** argument: the workspace’s handle. Tables and columns are named by **name**. Write tools answer with a result like: ```json { "status": "applied", "changeset": 42, "rows_affected": 3 } ``` or, when the agent’s [approval rules](https://tabulic.com/docs/concepts/approval-rules) hold it back: ```json { "status": "pending", "changeset": 43, "rows_affected": 25, "waits_for": "bulk-update", "message": "…" } ``` > **Warning** > > On `"status": "pending"`: tell the person, and **don’t retry**. Check later with `changeset_status`. ## Workspaces | Tool | Inputs | Does | |---|---|---| | `list_workspaces` | none | The workspaces you can reach: handle, name, and what you may do in each. Call this first. | | `create_workspace` | `handle`, `name` | Creates a workspace, if the person allowed it. You get full access. `handle`: 3–30 lowercase letters, digits and single hyphens, unique, permanent. | ## Reading | Tool | Inputs | Does | |---|---|---| | `describe_schema` | `workspace` | The tables you can read and their columns, which you may write, whether you may change the schema, and your approval rules. | | `query` | `workspace`, `table`, `filter?`, `sort?`, `limit?` | Rows from one table. `sort`: `[{"column", "desc"?}]`. `limit`: default 100, at most 1000. Says how many inserted rows are still pending. | | `sql_query` | `workspace`, `sql` | One read-only `SELECT` (or `WITH … SELECT`) over your tables by name, with `_row_id` for each row’s ID. At most 1000 rows (`truncated: true` if more matched). Runs on a private copy, limited to your scope. Prefer `query` for simple reads. | ## Writing rows | Tool | Inputs | Default | |---|---|---| | `insert_rows` | `workspace`, `table`, `rows` (each maps column names to values) | applies | | `update_rows` | `workspace`, `table`, `filter`, `values` | applies up to 10 rows, waits above | | `delete_rows` | `workspace`, `table`, `filter` | waits | | `write_batch` | `workspace`, `label`, `writes` | one changeset, all or nothing (below) | `filter` is required for updates and deletes; `{}` selects every row. See [Data types and filters](https://tabulic.com/docs/reference/data-types-and-filters). ### `write_batch` Up to 100 writes, each one of: ```json { "insert": "Orders", "rows": [{ "Item": "Desk", "Qty": 2 }] } { "update": "Holdings", "filter": {}, "values": { "Qty": 0 } } { "delete": "Orders", "filter": { "column": "Status", "op": "=", "value": "void" } } ``` Every write applies, or if any would wait, the whole batch waits. One invalid write refuses the batch. Every write picks its rows as the batch arrives, so it doesn’t see the batch’s earlier writes. ## Grouping and pending changes | Tool | Inputs | Does | |---|---|---| | `begin_changeset` | `workspace`, `label` | Starts a new, named group, so the person reviews and rolls it back as one, e.g. “Import clients”. | | `changeset_status` | `workspace`, `changeset` | Whether one of your changesets is `pending`, `applied`, `rejected`, `withdrawn` or `expired`. | | `withdraw_pending` | `workspace`, `changeset` | Takes back one of your pending changesets. Nothing in it is applied. | There is no tool to approve, reject or roll back. Those are the owner’s, on Tabulic’s screens. ## Schema Needs the **change the schema** permission in your scope, except on tables you created. | Tool | Inputs | Default | |---|---|---| | `create_table` | `workspace`, `table`, `columns: [{name, type}]` | applies; you get read and write on it | | `add_column` | `workspace`, `table`, `column: {name, type}` | applies | | `rename_table` | `workspace`, `table`, `to` | applies; nothing that refers to it breaks | | `rename_column` | `workspace`, `table`, `column`, `to` | applies | | `change_column_type` | `workspace`, `table`, `column`, `type` | waits. Reports which values convert; values that can’t become empty, with the originals kept | | `drop_column` | `workspace`, `table`, `column` | waits; data kept so it can be restored | | `drop_table` | `workspace`, `table` | waits; data kept so it can be restored | Column types: `text`, `number`, `boolean`, `date`, `datetime`. ## Apps | Tool | Inputs | Does | |---|---|---| | `app_guide` | `workspace` | How to build an app on these tables: the API address, the `tabulic.js` script tag, the `tabulic.css` stylesheet, tables’ stable IDs, an example page, the rules, and the pages already published. Creates nothing. **Call this before building an app.** | | `publish_page` | `workspace`, `name`, `title`, `html` | Publishes an app’s page, one self-contained HTML file (at most 1 MB), and returns its `url` and `version`. Same `name` updates it. Needs the **publish app pages** permission. | | `read_page` | `workspace`, `page` (name or link) | The current HTML of a published page, to edit and publish again. Read it right before editing. | ## Inline review Write tools that can wait carry an MCP App resource (`ui://tabulic/changeset`). In hosts that show MCP Apps (Claude, ChatGPT, VS Code, Cursor), a pending write shows its diff in the conversation, with a **Review and approve** button that opens it on Tabulic’s screens. Other hosts show the same as text. ## Recommended agent workflow 1. `list_workspaces`, then `describe_schema` on the one you need. 2. Read with `query`; use `sql_query` for joins and aggregates. 3. For a multi-step task, `begin_changeset` with a clear label, or send related writes as one `write_batch`. 4. If a write is pending, tell the person and stop retrying it. 5. To build a UI, `app_guide` → write the page → `publish_page` → send the person the link. --- # App API (https://tabulic.com/docs/reference/app-api) The HTTP API and tabulic.js that apps use to read and write a workspace. Apps call the API at: ```txt https://app.tabulic.com/w//v1/ ``` Every request carries the app’s access token (handled by `tabulic.js`) or secret key as a bearer token. Tables and columns are named by name or by **stable ID** (`tbl_3`, `col_7`). IDs survive renames, so apps should use them; `app_guide` and `GET /v1/schema` list them. ## tabulic.js ```html ``` | Call | Does | |---|---| | `tabulic.app({ name, access })` | Declares the app and the access it asks for: `{ tbl_1: "r" \| "rw" }`. | | `app.ready()` | Resolves when the app may act. In a published page, Tabulic asks the owner around the page; no sign-in button needed. Elsewhere, returns `false` if not signed in. | | `app.signIn()` | Only for pages hosted elsewhere: goes to Tabulic’s consent page and back. | | `app.rows(table, opts)` | Reads rows: `filter`, `sort`, `limit`, `offset`, `keys: "id"`. | | `app.insert(table, rows)` | Adds rows. | | `app.update(table, filter, values)` | Sets values on the rows `filter` selects. | | `app.delete(table, filter)` | Deletes the rows `filter` selects. | | `app.batch(label, writes)` | One changeset, all or nothing. | | `app.onChange(fn)` | Calls `fn` whenever the workspace changes, its own writes included. | | `app.schema()` | `GET /v1/schema`. | | `app.beginChangeset(label)` | Groups the app’s next writes under a label. | | `app.changesets({ status, q, before })` | The app’s own changesets, newest first. | | `app.withdraw(id)` | Takes back one of its waiting writes. | | `app.signOut()` | Forgets this browser’s tokens. | `tabulic.js` waits out a rate-limit wait of up to 5 seconds by itself. ## REST endpoints | Request | Does | |---|---| | `GET /v1/schema` | The tables and columns the app can see, with IDs, and its approval rules. | | `GET /v1/generation` | A number that moves on every write to the workspace. Poll it, not rows, to know when to read again. | | `GET /v1/tables/{table}/rows` | Rows. Query: `filter` (JSON), `sort=[{"column":…,"desc":true}]`, `limit` (default 100, at most 1000), `offset`, `keys=id` to key values by column ID. | | `POST /v1/tables/{table}/rows` | Insert: `{"rows": [{…}]}` | | `PATCH /v1/tables/{table}/rows` | Update: `{"filter": …, "values": {…}}` | | `DELETE /v1/tables/{table}/rows` | Delete: `{"filter": …}` (or `?filter=`) | | `POST /v1/changesets` | `{"label": "Import"}` groups the app’s next writes under a name. With `"writes": […]`, sends them as one batch. | | `GET /v1/changesets?status=&q=&before=` | The app’s own changesets, newest first, 50 at a time. `q` searches labels; the answer’s `before` gets the next page. | | `GET /v1/changesets/{id}` | Whether one of its writes is still waiting. | | `POST /v1/changesets/{id}/withdraw` | Takes back one of its waiting writes. | Updates and deletes need a filter; `{}` selects every row. ## Write answers ```json { "status": "applied", "changeset": 51, "rows_affected": 1 } ``` A write that waits adds `waits_for`, `reason` and `review_url`. Show the person the link (open it with `target="_top"` from a published page) and don’t retry. - A write that matches nothing answers `rows_affected: 0` and no changeset. - A pending write, once approved, acts on the rows it matched when sent. Rows added meanwhile are left. If they matter, check `GET /v1/changesets/{id}` after approval and send the write again. - A batch answer adds `writes`: each write’s rows affected. ## Batches ```json POST /v1/changesets { "label": "Reset season", "writes": [ { "delete": "tbl_4", "filter": {} }, { "update": "tbl_3", "filter": {}, "values": { "col_14": 10000 } }, { "insert": "tbl_5", "rows": [{ "col_20": "Start" }] } ] } ``` Up to 100 writes. All apply, or if any would wait, the whole batch waits. One invalid write refuses the batch (`writes[2]: …`). Each write picks its rows as the batch arrives. ## Errors Errors answer `{"code", "message"}` with a code of: | Code | Meaning | |---|---| | `unauthorized` | Missing, expired or revoked token or key. | | `not_found` | No such table, column, row or changeset. | | `not_in_scope` | The app may not touch that table or column. | | `invalid` | Bad filter, value or request. | | `limit_reached` | A plan limit was reached. | | `rate_limited` | Too many requests; wait `Retry-After` seconds. | A write to a dropped column says so, e.g. `column col_12 (strategy) of "Traders" was dropped`. ## Secret keys Scripts and servers can’t sign in through a browser. Make a key in the app’s **Settings** → **Secret keys** on the **Apps** screen. It is shown once. ```bash curl https://app.tabulic.com/w/clients/v1/tables/tbl_1/rows?limit=10 \ -H "Authorization: Bearer tabulic_sk_…" ``` > **Warning** > > Never put a secret key in a web page: anyone who loads the page can read it. Revoke a key with **Disconnect**. ## Pages hosted elsewhere A page outside Tabulic loads the same `tabulic.js` and calls `app.signIn()` when `ready()` returns `false`. It must be served over `https`, or over `http` from `localhost` or `127.0.0.1`. Its address is where sign-in returns to, and only that address may read the API’s answers. It won’t work opened as a file, or in a chat’s HTML preview or artifact. To try one locally: ```bash python3 -m http.server 8000 ``` Then open `http://localhost:8000/your-page.html`. --- # Data types and filters (https://tabulic.com/docs/reference/data-types-and-filters) Column types, value formats, and the filter syntax used by MCP tools and the App API. ## Column types | Type | Values | Notes | |---|---|---| | `text` | strings | Also accepts numbers and booleans, stored as their text (`15` → `"15"`), so writers keep working after a column changes from number to text. | | `number` | JSON numbers | | | `boolean` | `true` / `false` | | | `date` | `"YYYY-MM-DD"` | | | `datetime` | RFC 3339, any offset | Stored and returned in UTC, to the millisecond: `"2026-10-31T14:05:00.000Z"`. | Other types accept only their own kind of value. Any cell may be empty (`null`). ### Changing a column’s type `change_column_type` reports which values convert. Values that can’t convert become empty, and the originals are kept, so rolling the change back restores them. By default it waits for approval. ## Filters Filters select rows for `query`, `update_rows`, `delete_rows`, batch writes and the App API. **One condition:** ```json { "column": "Status", "op": "=", "value": "Active" } ``` | `op` | Meaning | |---|---| | `=` `!=` | equal, not equal | | `<` `<=` `>` `>=` | comparisons (numbers, dates, datetimes, text) | | `contains` | text contains the value (text columns only) | | `in` | value is one of a list: `"value": ["Won", "Lost"]` | | `is_null` | the cell is empty | **Rows by ID:** ```json { "ids": [3, 7] } ``` **Combined:** ```json { "and": [ { "column": "Stage", "op": "in", "value": ["Proposal", "Negotiation"] }, { "not": { "column": "Owner", "op": "is_null" } }, { "or": [ { "column": "Value", "op": ">", "value": 10000 }, { "column": "Priority", "op": "=", "value": true } ] } ] } ``` `{}` selects every row. Updates and deletes must pass a filter, so selecting everything is always explicit. In the App API, columns in filters can be named by ID (`col_7`) as well as by name. ## Sorting ```json [{ "column": "Due", "desc": false }, { "column": "Value", "desc": true }] ``` ## SQL `sql_query` takes one `SELECT` or `WITH … SELECT` over your tables by name, with `_row_id` for each row’s ID. It runs read-only on a private copy, sees only what your scope allows, and returns at most 1000 rows. ```sql SELECT Owner, COUNT(*) AS deals, SUM(Value) AS total FROM Deals WHERE Stage = 'Won' GROUP BY Owner ORDER BY total DESC ``` --- # Limits (https://tabulic.com/docs/reference/limits) Technical limits on queries, writes, pages and API requests. | What | Limit | |---|---| | Rows per `query` or `GET …/rows` | 100 by default, at most 1000. The App API pages with `offset`; the MCP `query` tool has no offset, so narrow it with `filter` and `sort` | | Rows per `sql_query` | 1000 (`truncated: true` if more matched) | | Writes per batch | 100 | | Bulk threshold | 10 rows per write, unless the owner changes it | | App page size | 1 MB, one self-contained HTML file | | App requests | 600 a minute per app, its page and secret keys together | | Changesets per list page | 50 | | Workspace handle | 3–30 lowercase letters, digits and single hyphens | | App page name | up to 40 lowercase letters, digits and single hyphens | ## Rate limits Every App API answer has `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (seconds until a request frees up). A `429` answer has `Retry-After`. - `tabulic.js` waits out a wait of up to 5 seconds by itself. - Scripts should wait `Retry-After`, and send many rows in one write rather than one call per row. ## Plan limits How many workspaces, agents and apps you can have, how long history is kept, monthly writes by agents and apps, and workspace size depend on your plan. Your account page shows your current limits. When a limit is reached, writes answer with the `limit_reached` code.