REST API overview
Two REST APIs, the Builder API on the Studio and the App API of every app, with one envelope, one versioning scheme and one set of error codes.
gtable has two REST APIs, one per plane, built from the same registry as the MCP tools and the CLI. They share their conventions: the envelope, pagination, errors, idempotency and versioning work the same on both.
| Builder API | App API | |
|---|---|---|
| Base URL | https://studio.gtable.app/v1 | https://{suite}.gtable.app/{app}/v1 |
| For | builders: organisations, suites, apps, schema, rules, people, domains | anyone invited into an app: records, views, comments, files, SQL, undo |
| Credentials | Studio keys, Studio OAuth | your key in that app, or an OAuth connection to the suite |
| OpenAPI | public, https://studio.gtable.app/v1/openapi.json | per person, https://{suite}.gtable.app/{app}/v1/openapi.json |
| Reference | Builder API | App API |
The App API is generated for you
An app’s OpenAPI document is generated on every request from the schema the caller can see. Its
tableId parameter is a closed list of your tables, and each table’s record is typed with only
the fields you can read. Someone with a different role gets a different document from the same
URL. There is no anonymous copy.
So the App API reference here is the generic contract: every operation and its shape, with no table and no field named. To generate a client, or to give an agent exact types, fetch your own:
curl "https://your-suite.gtable.app/your-app/v1/openapi.json" \
-H "Authorization: Bearer $GTABLE_TOKEN"The generic contracts are also published here, for tools that want a file:
/docs/openapi/app.json and
/docs/openapi/builder.json.
Builders reach data through the Studio
A builder is not a member of their own apps by default, and does not need to be. The Builder API
reads and writes any app’s records under /v1/apps/{appId}/…, with every write recorded under
the builder’s name. See Data, as the builder.
Before you write code
- Conventions: the envelope, records on the wire, pagination.
- Errors: the codes to switch on.
- Retries and idempotency: make a write safe to repeat.
- Versioning: what can change, and how you are told.