---
title: "REST API overview"
description: "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."
canonical: "https://gtable.app/docs/api/overview"
updated: "2026-10-05"
---

# REST API overview

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](/docs/builder-api/apps/list)                            | [App API](/docs/app-api/records/list)                                  |

## 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](/docs/app-api/records/list) 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:

```bash
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`](/docs/openapi/app.json) and
[`/docs/openapi/builder.json`](/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](/docs/builder-api/data/records-list).

## Before you write code

- [Conventions](/docs/api/conventions): the envelope, records on the wire, pagination.
- [Errors](/docs/api/errors): the codes to switch on.
- [Retries and idempotency](/docs/api/idempotency): make a write safe to repeat.
- [Versioning](/docs/api/versioning): what can change, and how you are told.