The Base REST API

A bearer key, scoped read or write

Create a key in the app under workspace settings. It is shown once and stored only as a hash.

curl https://bips.ai/v1/bases \
  -H "Authorization: Bearer $BASE_KEY"

A missing key and an insufficient scope both answer 404: a key learns nothing about a base it may not touch. Exceeding the rate limit — 120 requests a minute per key — answers 429 with a Retry-After header.

Cells, keys and pages

A row's values live in cells, keyed by column key — a slug derived from the label when the column is created, and stable afterwards. Renaming a column does not move its key, so an integration written today keeps working after someone tidies the headers.

{
  "id": "9f1c…", "source": "api",
  "cells": { "name": "Ada", "amount": 499, "total": 998 },
  "created_at": "…", "updated_at": "…"
}

Computed columns — formula, lookup, rollup, count, reverse-link — are evaluated on read and merged into cells alongside the stored ones. They are never writable.

Pagination

List endpoints take limit (1–500, default 100) and offset, and answer with the page, the total, and the next offset — or null when there is no next page. Paging happens in the database, not after the fact.

Errors

Flat, machine-first, one snake-case code per failure: not_found, invalid_request, invalid_cell (with field), invalid_options, forbidden_columns (with fields), rate_limited. Batch failures add rows_index and return the rows that did land.

Tables and columns

One row, or five hundred

A batch is one round trip, one history entry and one webhook — not five hundred of each.

curl -X POST "$BASE/v1/bases/$B/tables/$T/rows/batch" \
  -H "Authorization: Bearer $BASE_KEY" -H "content-type: application/json" \
  -d '{"rows":[{"cells":{"name":"Ada"}},{"cells":{"name":"Grace"}}]}'

Rows written this way are stamped source: "api", which is what automation payloads report and what the activity feed shows. Deletes are soft: the row is archived, and the change log can put it back.

Ask in SQL instead of paging

Every table is exposed as a read-only SQLite view named t_<slug>, so aggregates, joins and searches are one request rather than a download and a loop.

curl -X POST "$BASE/v1/bases/$B/query" \
  -H "Authorization: Bearer $BASE_KEY" -H "content-type: application/json" \
  -d '{"sql":"SELECT status, COUNT(*) n FROM t_orders GROUP BY status"}'

A single SELECT or WITH, nothing else, enforced in four independent layers and run inside a transaction that always rolls back. limit defaults to 200 and caps at 1,000.

Views, comments, history

Import and export

Import accepts CSV, TSV, JSON, NDJSON, a markdown table or XLSX — inline in data, as a base64 data: URL, or as a url for Base to fetch (public hosts only, 5 MB cap, every redirect re-checked). Types are inferred conservatively; at most 5,000 rows land per call and truncated tells you when the rest did not.

Signed outbound webhooks

A rule watches a table or a form and POSTs a signed JSON body to your URL when it fires.

What an API key cannot reach

The API is default-deny: a path that is not on its allowlist answers 404 whatever the key. Two things are held back on purpose.

How this API lines up against Airtable's, endpoint by endpoint — including what Base is missing — is written up in the repository as docs/airtable-api-audit.md. Matching Airtable was never the goal; measuring the distance was worth doing anyway.