Records

Live records, oldest first, keyset-paged

GET /api/tables/{tableId}/records

Access: record:read on the table (see ACTIONS for the minimum role); personal access tokens need data.records:read.

Parameters

Responses

• 200 Success
  • records array of object required
    • id string (uuid) required
    • tableId string (uuid) required
    • version integer required
    • fields object required
    • createdAt string (date-time) required
    • createdBy string (uuid) | null required
    • updatedAt string (date-time) required
    • updatedBy string (uuid) | null required
  • nextCursor string (uuid) | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Create one record ({ fields }) or up to 1,000 ({ records })

POST /api/tables/{tableId}/records

Access: record:create on the table (see ACTIONS for the minimum role); personal access tokens need data.records:write.

Parameters

Request body

object

Responses

• 201 Success

  object

• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Patch up to 1,000 records in one transaction

PATCH /api/tables/{tableId}/records

Access: record:update on the table (see ACTIONS for the minimum role); personal access tokens need data.records:write.

Parameters

Request body

• records array of object required
  • id string (uuid) required
  • fields object required
  • ifVersion integer
• clientOpId string
• typecast boolean

Responses

• 200 Success
  • records array of object required
    • id string (uuid) required
    • tableId string (uuid) required
    • version integer required
    • fields object required
    • createdAt string (date-time) required
    • createdBy string (uuid) | null required
    • updatedAt string (date-time) required
    • updatedBy string (uuid) | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Filter, sort, group, page and aggregate records (a view query)

POST /api/tables/{tableId}/records/query

Access: record:read on the table (see ACTIONS for the minimum role); personal access tokens need data.records:read.

Parameters

Request body

• viewId string (uuid)
• query object
  • filter object
    • conjunction "and" | "or"
    • conditions array of object required
  • sorts array of object
    • fieldId string (uuid) required
    • direction "asc" | "desc"
  • groupBy array of object
    • fieldId string (uuid) required
    • direction "asc" | "desc"
  • fields array of string (uuid)
  • search string
  • timeZone string
  • within array of object
    • fieldId string (uuid) required
    • operator "is" | "isNot" | "contains" | "doesNotContain" | "isEmpty" | "isNotEmpty" | "=" | "!=" | … required
    • value any
  • dateRange object
    • from string required
    • to string required
    • fields array of object required
      • startFieldId string (uuid) required
      • endFieldId string (uuid) | null
• offset integer
• limit integer
• cursor string
• count boolean
• groups boolean
• aggregates array of object
  • fieldId string (uuid) required
  • fn "count" | "empty" | "filled" | "unique" | "sum" | "avg" | "min" | "max" required
• rowColors array of object
  • color "green" | "amber" | "blue" | "red" | "violet" | "teal" | "pink" | "slate" | … required
  • filter object required
    • conjunction "and" | "or"
    • conditions array of object required

Responses

• 200 Success
  • records array of object required
    • id string (uuid) required
    • tableId string (uuid) required
    • version integer required
    • fields object required
    • createdAt string (date-time) required
    • createdBy string (uuid) | null required
    • updatedAt string (date-time) required
    • updatedBy string (uuid) | null required
  • offset integer | null required
  • total integer | null required
  • nextCursor string | null required
  • groups array of object
    • key array of any required
    • count integer required
  • aggregates object
  • rowColors object
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Move up to 1,000 records to the trash

POST /api/tables/{tableId}/records/delete

Access: record:delete on the table (see ACTIONS for the minimum role); personal access tokens need data.records:write.

Parameters

Request body

• recordIds array of string (uuid) required
• clientOpId string

Responses

• 200 Success
  • records array of object required
    • id string (uuid) required
    • deleted true required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Restore up to 1,000 records from the trash

POST /api/tables/{tableId}/records/restore

Access: record:delete on the table (see ACTIONS for the minimum role); personal access tokens need data.records:write.

Parameters

Request body

• recordIds array of string (uuid) required
• clientOpId string

Responses

• 200 Success
  • records array of object required
    • id string (uuid) required
    • tableId string (uuid) required
    • version integer required
    • fields object required
    • createdAt string (date-time) required
    • createdBy string (uuid) | null required
    • updatedAt string (date-time) required
    • updatedBy string (uuid) | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Read a record

GET /api/tables/{tableId}/records/{recordId}

Access: record:read on the table (see ACTIONS for the minimum role); personal access tokens need data.records:read.

Parameters

Responses

• 200 Success
  • id string (uuid) required
  • tableId string (uuid) required
  • version integer required
  • fields object required
  • createdAt string (date-time) required
  • createdBy string (uuid) | null required
  • updatedAt string (date-time) required
  • updatedBy string (uuid) | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)

Patch the given cells of a record

PATCH /api/tables/{tableId}/records/{recordId}

Access: record:update on the table (see ACTIONS for the minimum role); personal access tokens need data.records:write.

Parameters

Request body

• fields object required
• ifVersion integer
• clientOpId string
• typecast boolean

Responses

• 200 Success
  • id string (uuid) required
  • tableId string (uuid) required
  • version integer required
  • fields object required
  • createdAt string (date-time) required
  • createdBy string (uuid) | null required
  • updatedAt string (date-time) required
  • updatedBy string (uuid) | null required
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

Move a record to the trash

DELETE /api/tables/{tableId}/records/{recordId}

Access: record:delete on the table (see ACTIONS for the minimum role); personal access tokens need data.records:write.

Parameters

Responses

• 204 Success, no content
• 401 Not signed in
• 403 Signed in, but the role is too low
• 404 No such resource, or no access to it
• 429 Too many requests: a rate limit was reached (see Retry-After)