Records Overview

Every table you declare automatically exposes a complete REST API for its records. There is no resolver to write and no endpoint to register — the moment a table exists in your config, its records collection is reachable under /api/tables/:tableId/records. This page documents the shared API surface: the URL layout, the response envelope, authorship metadata, and the cross-cutting rules (authentication, permissions, formatting) that every records endpoint obeys.

Records are the rows of a table. Tables define the columns (fields); records hold the values. The Records API is the canonical read/write path for that data — pages render it, forms write to it, automations react to it, and external integrations consume it.

Endpoint surface

:tableId accepts either the numeric table id or the table name/slug. All endpoints accept and return JSON.

Detailed behavior is split across focused pages: CRUD & upsert, filtering, sorting & pagination, batch operations, history & comments, soft delete & trash, real-time subscriptions, and import/export.

The fields envelope

Record write bodies use the canonical Airtable-style envelope: a fields object mapping field names to values.

POST /api/tables/contacts/records
{
  "fields": {
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}

A successful create returns 201 Created with the stored record, including its generated id and authorship metadata:

{
  "id": "42",
  "fields": {
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "createdBy": "user-uuid-123",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

A record from a table declaring AI fields carries one more sibling of fields: an _aiCompute block reporting whether each AI value is the model's answer or the locally computed fallback. It is omitted entirely for every other table.

List response envelope

GET .../records returns a paginated envelope, never a bare array:

{
  "records": [{ "id": "1", "fields": {} }],
  "pagination": { "total": 128, "limit": 20, "offset": 0 }
}

records is the page of results; pagination carries the total matching-row count plus the limit/offset that produced this page. See Filtering, Sorting & Pagination for the full query-parameter grammar.

Authorship metadata

The API automatically stamps and exposes authorship on every write. These fields are server-controlled and read-only — values supplied in a request body are ignored, so the audit trail cannot be forged.

createdBy, updatedBy, and deletedBy resolve to the authenticated user's ID. They are surfaced through dedicated user-audit field types (created-by, updated-by, deleted-by) and the updated-at system field auto-bumps the timestamp on every write — enabling the optimistic-locking contract.

Cross-cutting rules

Every records endpoint enforces the same guarantees:

Display vs raw formatting

By default, field values are returned raw (the stored value). Pass ?format=display to receive human-readable, locale- and timezone-aware values (formatted currency, dates, durations, attachment display names). The raw form is preferred for programmatic clients; the display form is preferred for direct rendering. See Record formatting for the controls.

Related pages

• CRUD & Upsert — create, read, update, delete, upsert, formatting
• Filtering, Sorting & Pagination — query parameters
• Batch Operations — bulk create/update/delete
• Record History & Comments — change log and collaboration
• Soft Delete & Restore — trash and recovery
• Real-Time Subscriptions — WebSocket/SSE/poll
• Import & Export — CSV/JSON and clipboard
• API Reference — the generated endpoint catalog