Grid82
grid82.comJoin the waitlist
DevelopersConventions

Request and response conventions

JSON envelopes, wire formats per field type, strict input validation, cursor pagination, optimistic concurrency, and safe deletion headers.

Response envelopes

All endpoints return a consistent JSON object with data (and optional meta / warnings), or a structured error object:

JSON
{
  "data": [],
  "meta": { "nextCursor": null, "hasMore": false }
}
JSON
{
  "error": {
    "code": "validation_failed",
    "message": "Unknown field key: Stagee",
    "details": {}
  }
}

Always switch on error.code, not error.message (see Errors and rate limits).

Records on the wire

Returned records always key cells by permanent field ID (fld_...). List responses include meta.fields mapping each visible field ID to its current display name so UI clients can render column labels in one request:

JSON
{
  "data": [
    {
      "id": "rec_4nqw8e2hzk7s",
      "created_at": "2026-09-05T16:53:39.058Z",
      "fld_dd7kbtsjuhdc": "Northwind Enterprise Renewal",
      "fld_jx99fwfvhv3x": 48000
    }
  ],
  "meta": {
    "hasMore": false,
    "nextCursor": null,
    "fields": {
      "fld_dd7kbtsjuhdc": "Name",
      "fld_jx99fwfvhv3x": "Amount"
    }
  }
}

Special field wire formats

Field typeRead formatWrite format
link[{ "id": "rec_...", "label": "..." }]Array of record IDs ["rec_..."] (replaces visible links)
user, createdBy, modifiedBy[{ "id": "usr_...", "label": "..." }]user only: ID, email, or exact name (or array)
attachment[{ "id", "name", "size", "mime", "url", ... }]Descriptor array returned by files.upload
select, multiselectOption ID ("opt_...") or array of option IDsOption IDs ("opt_..."), never display labels
percentFraction (0.15 for 15%)Fraction (0.15)
durationInteger milliseconds (3600000 for 1 hour)Integer milliseconds
dateISO 8601 UTC stringYYYY-MM-DD or ISO timestamp with timezone (Z or +02:00)

Writing by field ID or exact name

On records.create and records.update, you may pass either field IDs or exact current field names as keys. Unknown keys are rejected loudly with 422 validation_failed. System stamps (id, created_at) in an echoed object are ignored on writes.

Strict validation and cursor pagination

  • No silent unknown fields. Unknown query parameters or body keys fail with 422 validation_failed.
  • Cursor pagination. Pass limit (up to 200) and follow meta.nextCursor as cursor while meta.hasMore is true. Invalid cursors return 422.
  • Sorting and paging note. Cursors paginate by creation order; combining sorts with multi-page cursor traversal can shift records across page boundaries. For complete sorted datasets, paginate unsorted or query via /v1/sql/query.

Optimistic concurrency (baseRevision / baseVersion)

  • Pass baseRevision when replacing a role’s permissions or rule set (roles.setPermissions, rules.set).
  • Pass baseVersion when updating a page’s code or updating a specific record (using the record’s latest changesetId).
  • If another writer modified the target first, the API rejects the overwrite with 409 conflict.

Destructive confirmations

Deleting an organisation, suite, app, table, or field requires passing its exact current name in ?confirm=.... Deleting a table or field also returns an impact report and requires acknowledge=true when dependent pages, formulas, views, or rules exist:

HTTP
DELETE /v1/apps/{appId}/tables/{tableId}?confirm=Old%20deals&acknowledge=true

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search Grid82 documentation and read it in full, instead of answering from memory.

https://grid82.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://grid82.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.