REST API v1

A base's webhooks (never their secrets)

GET /api/v1/bases/{baseId}/webhooks

Access: base:manage_webhooks on the base (see ACTIONS for the minimum role); personal access tokens need webhook:manage.

Parameters

Responses

• 200 Success
  • webhooks array of object required
    • id string (uuid) required
    • baseId string (uuid) required
    • url string required
    • description string required
    • events array of "record.created" | "record.updated" | "record.deleted" | "record.restored" | "field.created" | "field.updated" | "field.deleted" | "field.restored" | … required
    • tableIds array of string (uuid) | null required
    • fieldIds array of string (uuid) | null required
    • enabled boolean required
    • disabledReason "failures" | "creator_access" | null required
    • consecutiveFailures integer required
    • lastDeliveryAt string (date-time) | null required
    • lastSuccess boolean | null required
    • previousSecretExpiresAt string (date-time) | null required
    • createdBy string (uuid) | null required
    • createdAt string (date-time) required
    • updatedAt string (date-time) 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)

Create a webhook; the answer holds its signing secret, shown only this once

POST /api/v1/bases/{baseId}/webhooks

Access: base:manage_webhooks on the base (see ACTIONS for the minimum role); personal access tokens need webhook:manage.

Parameters

Request body

• url string required
• description string
• events array of "record.created" | "record.updated" | "record.deleted" | "record.restored" | "field.created" | "field.updated" | "field.deleted" | "field.restored" | … required
• tableIds array of string (uuid) | null
• fieldIds array of string (uuid) | null
• enabled boolean

Responses

• 201 Success
  • id string (uuid) required
  • baseId string (uuid) required
  • url string required
  • description string required
  • events array of "record.created" | "record.updated" | "record.deleted" | "record.restored" | "field.created" | "field.updated" | "field.deleted" | "field.restored" | … required
  • tableIds array of string (uuid) | null required
  • fieldIds array of string (uuid) | null required
  • enabled boolean required
  • disabledReason "failures" | "creator_access" | null required
  • consecutiveFailures integer required
  • lastDeliveryAt string (date-time) | null required
  • lastSuccess boolean | null required
  • previousSecretExpiresAt string (date-time) | null required
  • createdBy string (uuid) | null required
  • createdAt string (date-time) required
  • updatedAt string (date-time) required
  • secret string
• 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)

Change, enable or disable a webhook, or rotate its secret (returned once)

PATCH /api/v1/bases/{baseId}/webhooks/{webhookId}

Access: base:manage_webhooks on the base (see ACTIONS for the minimum role); personal access tokens need webhook:manage.

Parameters

Request body

• url string
• description string
• events array of "record.created" | "record.updated" | "record.deleted" | "record.restored" | "field.created" | "field.updated" | "field.deleted" | "field.restored" | …
• tableIds array of string (uuid) | null
• fieldIds array of string (uuid) | null
• enabled boolean
• rotateSecret true
• expirePreviousSecret true

Responses

• 200 Success
  • id string (uuid) required
  • baseId string (uuid) required
  • url string required
  • description string required
  • events array of "record.created" | "record.updated" | "record.deleted" | "record.restored" | "field.created" | "field.updated" | "field.deleted" | "field.restored" | … required
  • tableIds array of string (uuid) | null required
  • fieldIds array of string (uuid) | null required
  • enabled boolean required
  • disabledReason "failures" | "creator_access" | null required
  • consecutiveFailures integer required
  • lastDeliveryAt string (date-time) | null required
  • lastSuccess boolean | null required
  • previousSecretExpiresAt string (date-time) | null required
  • createdBy string (uuid) | null required
  • createdAt string (date-time) required
  • updatedAt string (date-time) required
  • secret string
• 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)

Delete a webhook and its delivery log

DELETE /api/v1/bases/{baseId}/webhooks/{webhookId}

Access: base:manage_webhooks on the base (see ACTIONS for the minimum role); personal access tokens need webhook:manage.

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)

A webhook's delivery attempts of the last 7 days, newest first

GET /api/v1/bases/{baseId}/webhooks/{webhookId}/deliveries

Access: base:manage_webhooks on the base (see ACTIONS for the minimum role); personal access tokens need webhook:manage.

Parameters

Responses

• 200 Success
  • deliveries array of object required
    • id string (uuid) required
    • eventId string required
    • eventType string required
    • attempt integer required
    • success boolean required
    • responseStatus integer | null required
    • durationMs integer required
    • responseBody string | null required
    • error string | null required
    • createdAt string (date-time) 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)

Queue a logged delivery's event again, with the same event id

POST /api/v1/bases/{baseId}/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver

Access: base:manage_webhooks on the base (see ACTIONS for the minimum role); personal access tokens need webhook:manage.

Parameters

Responses

• 200 Success
  • queued true required
  • eventId string 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)

Send a signed test event now and answer with the attempt

POST /api/v1/bases/{baseId}/webhooks/{webhookId}/ping

Access: base:manage_webhooks on the base (see ACTIONS for the minimum role); personal access tokens need webhook:manage.

Parameters

Responses

• 200 Success
  • id string (uuid) required
  • eventId string required
  • eventType string required
  • attempt integer required
  • success boolean required
  • responseStatus integer | null required
  • durationMs integer required
  • responseBody string | null required
  • error string | null required
  • createdAt string (date-time) 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)

A base's automations (never their webhook URLs)

GET /api/v1/bases/{baseId}/automations

Access: base:read_automations on the base (see ACTIONS for the minimum role); personal access tokens need automations:read.

Parameters

Responses

• 200 Success
  • automations array of object required
    • id string (uuid) required
    • baseId string (uuid) required
    • name string required
    • description string required
    • enabled boolean required
    • disabledReason "creator_access" | null required
    • trigger object required
    • actions array of object required
    • createdBy string (uuid) | null required
    • lastRunAt string (date-time) | null required
    • lastRunStatus "succeeded" | "failed" | "skipped" | null required
    • nextRunAt string (date-time) | null required
    • createdAt string (date-time) required
    • updatedAt string (date-time) 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)

One automation: its trigger, actions and last run

GET /api/v1/bases/{baseId}/automations/{automationId}

Access: base:read_automations on the base (see ACTIONS for the minimum role); personal access tokens need automations:read.

Parameters

Responses

• 200 Success
  • id string (uuid) required
  • baseId string (uuid) required
  • name string required
  • description string required
  • enabled boolean required
  • disabledReason "creator_access" | null required
  • trigger object required
  • actions array of object required
  • createdBy string (uuid) | null required
  • lastRunAt string (date-time) | null required
  • lastRunStatus "succeeded" | "failed" | "skipped" | null required
  • nextRunAt string (date-time) | null required
  • createdAt string (date-time) required
  • updatedAt string (date-time) 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)

Turn an automation on or off; turning it on makes it run as you

PATCH /api/v1/bases/{baseId}/automations/{automationId}

Access: base:toggle_automations on the base (see ACTIONS for the minimum role); personal access tokens need automations:manage.

Parameters

Request body

• enabled boolean required

Responses

• 200 Success
  • id string (uuid) required
  • baseId string (uuid) required
  • name string required
  • description string required
  • enabled boolean required
  • disabledReason "creator_access" | null required
  • trigger object required
  • actions array of object required
  • createdBy string (uuid) | null required
  • lastRunAt string (date-time) | null required
  • lastRunStatus "succeeded" | "failed" | "skipped" | null required
  • nextRunAt string (date-time) | null required
  • createdAt string (date-time) required
  • updatedAt string (date-time) 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)

An automation's runs of the last 30 days, newest first

GET /api/v1/bases/{baseId}/automations/{automationId}/runs

Access: base:read_automations on the base (see ACTIONS for the minimum role); personal access tokens need automations:read.

Parameters

Responses

• 200 Success
  • runs array of object required
    • id string (uuid) required
    • automationId string (uuid) required
    • status "succeeded" | "failed" | "skipped" required
    • mode "live" | "test" | "retry" required
    • skipReason "loop" | "quota" | null required
    • retryOf string (uuid) | null required
    • trigger any required
    • steps array of object required
      • index integer required
      • type "createRecord" | "updateRecord" | "findRecords" | "sendEmail" | "httpRequest" | "slackMessage" | "runScript" required
      • status "succeeded" | "failed" | "skipped" required
      • input any required
      • output any required
      • error string | null required
      • durationMs integer required
    • error string | null required
    • depth integer required
    • triggeredBy string (uuid) | null required
    • durationMs integer required
    • createdAt string (date-time) 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)

Trigger a webhook-received (body) or button-clicked (recordId) automation

POST /api/v1/bases/{baseId}/automations/{automationId}/trigger

Access: base:run_automations on the base (see ACTIONS for the minimum role); personal access tokens need automations:run.

Parameters

Request body

• recordId string (uuid)
• body any

Responses

• 200 Success
  • queued true required
  • triggerId string (uuid) 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)

Bases the caller (and token) can read, with their permission level

GET /api/v1/meta/bases

Access: any signed-in user, for their own data; personal access tokens need schema.bases:read.

Parameters

Responses

• 200 Success
  • bases array of object required
    • id string required
    • name string required
    • permissionLevel "read" | "comment" | "edit" | "create" | "owner" required
• 401 Not signed in
• 422 The request failed validation
• 429 Too many requests: a rate limit was reached (see Retry-After)

A base's tables with their fields (types and options) and views

GET /api/v1/meta/bases/{baseId}/tables

Access: base:read on the base (see ACTIONS for the minimum role); personal access tokens need schema.bases:read.

Parameters

Responses

• 200 Success
  • tables array of object required
    • id string required
    • name string required
    • description string
    • primaryFieldId string required
    • fields array of object required
      • id string required
      • name string required
      • type string required
      • openrowsType string required
      • description string
      • options any
    • views array of object required
      • id string required
      • name string required
      • type string 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)

Create a table with its fields (the first is the primary field)

POST /api/v1/meta/bases/{baseId}/tables

Access: table:create on the base (see ACTIONS for the minimum role); personal access tokens need schema.bases:write.

Parameters

Request body

• name string required
• description string
• fields array of object required
  • name string required
  • type string required
  • description string
  • options object

Responses

• 200 Success
  • id string required
  • name string required
  • description string
  • primaryFieldId string required
  • fields array of object required
    • id string required
    • name string required
    • type string required
    • openrowsType string required
    • description string
    • options any
  • views array of object required
    • id string required
    • name string required
    • type string 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 a field

POST /api/v1/meta/bases/{baseId}/tables/{tableIdOrName}/fields

Access: base:read on the base (see ACTIONS for the minimum role); personal access tokens need schema.bases:write.

Parameters

Request body

• name string required
• type string required
• description string
• options object

Responses

• 200 Success
  • id string required
  • name string required
  • type string required
  • openrowsType string required
  • description string
  • options any
• 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)

Rename a field or change its description

PATCH /api/v1/meta/bases/{baseId}/tables/{tableIdOrName}/fields/{fieldId}

Access: base:read on the base (see ACTIONS for the minimum role); personal access tokens need schema.bases:write.

Parameters

Request body

• name string
• description string | null

Responses

• 200 Success
  • id string required
  • name string required
  • type string required
  • openrowsType string required
  • description string
  • options any
• 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)

List records: pageSize, offset, maxRecords, view, sort, fields, filterByFormula

GET /api/v1/{baseId}/{tableIdOrName}

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

Parameters

Responses

• 200 Success
  • records array of object required
    • id string required
    • createdTime string required
    • fields object required
    • commentCount integer
  • offset string
• 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 10 (records)

POST /api/v1/{baseId}/{tableIdOrName}

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

Parameters

Request body

object

Responses

• 200 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)

Replace up to 10 records: fields left out are cleared

PUT /api/v1/{baseId}/{tableIdOrName}

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

Parameters

Request body

• records array of object required
  • id string (uuid)
  • fields object required
• performUpsert object
  • fieldsToMergeOn array of string required
• typecast boolean
• returnFieldsByFieldId boolean

Responses

• 200 Success
  • records array of object required
    • id string required
    • createdTime string required
    • fields object required
    • commentCount integer
  • createdRecords array of string
  • updatedRecords array of string
• 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)

Update up to 10 records (or upsert with performUpsert)

PATCH /api/v1/{baseId}/{tableIdOrName}

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

Parameters

Request body

• records array of object required
  • id string (uuid)
  • fields object required
• performUpsert object
  • fieldsToMergeOn array of string required
• typecast boolean
• returnFieldsByFieldId boolean

Responses

• 200 Success
  • records array of object required
    • id string required
    • createdTime string required
    • fields object required
    • commentCount integer
  • createdRecords array of string
  • updatedRecords array of string
• 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)

Delete up to 10 records (records[]), to the trash

DELETE /api/v1/{baseId}/{tableIdOrName}

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

Parameters

Responses

• 200 Success
  • records array of object required
    • id string 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)

List records with the parameters in the body (for long formulas)

POST /api/v1/{baseId}/{tableIdOrName}/listRecords

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

Parameters

Request body

• pageSize integer
• offset string
• maxRecords integer
• view string
• fields array of string
• sort array of object
  • field string required
  • direction "asc" | "desc"
• filterByFormula string
• cellFormat "json" | "string"
• timeZone string
• userLocale string
• returnFieldsByFieldId boolean | "0" | "1" | "true" | "false"
• recordMetadata array of "commentCount"

Responses

• 200 Success
  • records array of object required
    • id string required
    • createdTime string required
    • fields object required
    • commentCount integer
  • offset string
• 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)

One record

GET /api/v1/{baseId}/{tableIdOrName}/{recordId}

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

Parameters

Responses

• 200 Success
  • id string required
  • createdTime string required
  • fields object required
  • commentCount integer
• 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)

Replace a record: fields left out are cleared

PUT /api/v1/{baseId}/{tableIdOrName}/{recordId}

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

Parameters

Request body

• fields object required
• typecast boolean
• returnFieldsByFieldId boolean

Responses

• 200 Success
  • id string required
  • createdTime string required
  • fields object required
  • commentCount integer
• 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)

Update a record: only the fields given change

PATCH /api/v1/{baseId}/{tableIdOrName}/{recordId}

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

Parameters

Request body

• fields object required
• typecast boolean
• returnFieldsByFieldId boolean

Responses

• 200 Success
  • id string required
  • createdTime string required
  • fields object required
  • commentCount integer
• 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)

Delete a record (to the trash)

DELETE /api/v1/{baseId}/{tableIdOrName}/{recordId}

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

Parameters

Responses

• 200 Success
  • id string 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
• 429 Too many requests: a rate limit was reached (see Retry-After)

A record's comments, newest first

GET /api/v1/{baseId}/{tableIdOrName}/{recordId}/comments

Access: base:read on the base (see ACTIONS for the minimum role); personal access tokens need data.recordComments:read.

Parameters

Responses

• 200 Success
  • comments array of object required
    • id string required
    • author object required
      • id string required
      • email string
      • name string
    • text string required
    • createdTime string required
    • lastUpdatedTime string | null required
  • offset string | 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)

Comment on a record

POST /api/v1/{baseId}/{tableIdOrName}/{recordId}/comments

Access: base:read on the base (see ACTIONS for the minimum role); personal access tokens need data.recordComments:write.

Parameters

Request body

• text string required

Responses

• 200 Success
  • id string required
  • author object required
    • id string required
    • email string
    • name string
  • text string required
  • createdTime string required
  • lastUpdatedTime string | 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)