---
title: "Request and response conventions"
description: "JSON envelopes, wire formats per field type, strict input validation, cursor pagination, optimistic concurrency, and safe deletion headers."
canonical: "https://grid82.com/docs/developers/rest/conventions"
updated: "2026-11-20"
---

# Request and response conventions

## 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](/docs/developers/rest/errors)).

## 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 type                        | Read format                                      | Write 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`, `multiselect`           | Option ID (`"opt_..."`) or array of option IDs   | Option IDs (`"opt_..."`), never display labels                |
| `percent`                         | Fraction (`0.15` for 15%)                        | Fraction (`0.15`)                                             |
| `duration`                        | Integer milliseconds (`3600000` for 1 hour)      | Integer milliseconds                                          |
| `date`                            | ISO 8601 UTC string                              | `YYYY-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
```
