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:
{
"data": [],
"meta": { "nextCursor": null, "hasMore": false }
}{
"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:
{
"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 to200) and followmeta.nextCursorascursorwhilemeta.hasMoreistrue. Invalid cursors return422. - Sorting and paging note. Cursors paginate by creation order; combining
sortswith 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
baseRevisionwhen replacing a role’s permissions or rule set (roles.setPermissions,rules.set). - Pass
baseVersionwhen updating a page’s code or updating a specific record (using the record’s latestchangesetId). - 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:
DELETE /v1/apps/{appId}/tables/{tableId}?confirm=Old%20deals&acknowledge=true