---
title: "REST API overview"
description: "Compare the Studio Builder API and per-app Runtime API, fetch per-caller OpenAPI documents, and see how builders reach app records."
canonical: "https://grid82.com/docs/developers/rest/overview"
updated: "2026-11-20"
---

# REST API overview

Grid82 exposes two REST APIs built from the same route registry as the CLI and MCP servers. Both share identical response envelopes, cursor pagination, error codes, idempotency semantics, and contract versioning.

|              | **Builder API (Studio)**                                                             | **App API (Runtime)**                                                                     |
| ------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| Base URL     | `https://studio.grid82.app/v1`                                                       | `https://{suite}.grid82.app/{app}/v1`                                                     |
| Manages      | Organisations, suites, apps, tables, fields, roles, users, domains, pages, workflows | Records, views, comments, files, SQL queries, approvals, personal pages/workflows, events |
| Credentials  | Studio builder keys and Studio OAuth grants                                          | App keys (`Settings -> Connections`) and suite OAuth grants                               |
| OpenAPI spec | Public: `https://studio.grid82.app/v1/openapi.json`                                  | Per caller: `https://{suite}.grid82.app/{app}/v1/openapi.json`                            |
| Reference    | [Builder API](/docs/builder-api/apps/list)                                           | [App API](/docs/app-api/records/list)                                                     |

Suites attached to custom hostnames serve the App API directly on that hostname (for example `https://portal.yourcompany.com/crm/v1`).

## Per-caller OpenAPI for apps

An app's OpenAPI document is generated dynamically for the authenticated caller:

- `tableId` enumerations include only tables your roles can open.
- Record payload schemas list only the fields you are allowed to read and edit.
- Unauthenticated calls to `/{app}/v1/openapi.json` return `401`.

Because of this, the [App API reference](/docs/app-api/records/list) in these docs presents the **generic contract** without app-specific tables or columns. To generate a strongly typed client for your own app and role, download your caller-specific spec:

```bash
curl "https://your-suite.grid82.app/your-app/v1/openapi.json" \
  -H "Authorization: Bearer $GRID82_TOKEN" > app-openapi.json
```

Generic OpenAPI specs are also hosted statically at [`/docs/openapi/app.json`](/docs/openapi/app.json) and [`/docs/openapi/builder.json`](/docs/openapi/builder.json).

## Accessing data as a builder

Builders are not automatic members of their apps in Runtime, and do not need to be. Use the Builder API routes under `/v1/apps/{appId}/tables/{tableId}/records` and `/v1/apps/{appId}/sql/*` to read, query, or import data cleanly under your builder identity.
