REST API overview
Compare the Studio Builder API and per-app Runtime API, fetch per-caller OpenAPI documents, and see how builders reach app records.
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 | App API |
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:
tableIdenumerations 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.jsonreturn401.
Because of this, the App API reference 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:
curl "https://your-suite.grid82.app/your-app/v1/openapi.json" \
-H "Authorization: Bearer $GRID82_TOKEN" > app-openapi.jsonGeneric OpenAPI specs are also hosted statically at /docs/openapi/app.json and /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.