App API
The HTTP API and tabulic.js that apps use to read and write a workspace.
Apps call the API at:
https://app.tabulic.com/w/<handle>/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
<link rel="stylesheet" href="https://app.tabulic.com/w/<handle>/v1/tabulic.css">
<script src="https://app.tabulic.com/w/<handle>/v1/tabulic.js"></script>
<script type="module">
const app = tabulic.app({ name: "Client tracker", access: { tbl_1: "rw" } });
await app.ready(); // resolves once the owner has allowed the app
async function show() {
const { rows } = await app.rows("tbl_1", { keys: "id", limit: 100 });
// each row: { id, values: { col_1: "Acme Corp", … } }
}
await show();
app.onChange(show); // fires whenever the workspace changes; never poll on a timer
async function markActive(rowId) {
const res = await app.update("tbl_1", { ids: [rowId] }, { col_2: "Active" });
// res.status is "applied", or "pending" with res.review_url
}
</script>| 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
{ "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: 0and 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
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.
curl https://app.tabulic.com/w/clients/v1/tables/tbl_1/rows?limit=10 \
-H "Authorization: Bearer tabulic_sk_…"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:
python3 -m http.server 8000Then open http://localhost:8000/your-page.html.