Web API

Press shift + S to search API reference.

Guide

Changelog

This page lists changes made to the Web API and its documentation.

Also see our deprecation guidelines for our policy on breaking changes.

Please refer to our metadata and enterprise documentation pages for changes made before 2022-11-15. Note that in order to view these pages you must already be an enterprise customer, as all documentation before this date was restricted to enterprise customers.

2024-11-25

We've improved the OAuth integration experience

  • Multiple OAuth token refresh requests now only invalidate access if the number of requests exceeds 10 per second

2024-11-11

We’ve released several new API capabilities to support the Enterprise Hub feature, including:

  • New API endpoint: Create descendant enterprise - Now you can create descendant enterprise accounts in an organization.
  • New API endpoint: Move workspaces - Now you can bulk move workspaces between enterprise accounts belonging to the same organization.
  • New API endpoint: Move user groups - Now you can bulk move user groups between enterprise accounts belonging to the same organization.
  • Added new enterprise.account:write scope that allows creating descendant enterprises.
  • Added new enterprise.groups:manage scope that allows moving user groups.
  • Get enterprise - Now supports retrieving info across the enterprise and its descendants by populating the new include query parameter with the value of aggregated or descendants. Enterprise endpoints get user by id and get users by id or email have also been updated with this new functionality.
  • Remove user from enterprise - Now supports removing a user's access from the enterprise and its descendants by populating the new removeFromDescendants request field.

2024-07-31

  • New API endpoint: Upload attachment - Now you can upload an attachment to an attachment cell via the file bytes directly.

2024-04-10

  • New API endpoint: Grant admin access - Now you can bulk grant admin access to enterprise users.
  • New API endpoint: Revoke admin access - Now you can bulk revoke admin access from enterprise users.

2024-04-08

2024-02-01

2023-11-27

  • Added Billing plans reference guide
  • Updated the billing plan availability on endpoints to distinguish between the additional tiers:
    • Newly added: "Business"
    • Renamed: "Enterprise" -> "Enterprise (pre-2023.08 legacy plan)"
    • Unchanged: "Enterprise Scale"

2023-11-14

  • Updated Rate limits with details about the per-user rate limit for requests made using personal access tokens

Update on API Key-based webhook deprecation

  • It was previously announced that webhooks created by API keys would start to have an expiry time (like webhooks created by personal access tokens or OAuth access tokens) after February 1st 2024. In order to support a smoother migration experience, we have decided to change this: legacy webhooks created by user API keys will not ever expire.
  • As a reminder, to continue using webhooks after API keys are deprecated, the new authentication methods must be used.

2023-10-03

2023-09-13

2023-08-30

  • Get base schema - Now returns the executing formula text as a part of the schema for formula column types.
  • Added new user.email:read scope that allows reading the user's email address
  • Renamed "Get user ID & scopes" endpoint to "Get user info" and updated documentation. It now returns the user's email if the token has user.email:read scope

2023-07-24

  • Updated Errors documentation with an example of a retriable 503 error.

2023-06-12

  • OAuth integrations should see a reduced number of invalidations due to refresh tokens. We've added a short grace period during which duplicate requests will result in a 409 response rather than an invalidation. We'll be monitoring this to see if it addresses issues or whether further work is needed.

2023-04-05

  • Added ability to use field id's when using filterByFormula in list records - Now you can use a formula to filter records and not be susceptible to field name changes!

2023-03-22

  • New API endpoint: Manage user membership - Now you can bulk manage and unmanage enterprise users in "claim" mode organizations!

2023-03-15

  • Fixed bug related to returnFieldsByFieldId parameter for list records and get record endpoints. A value of false would previously return fields by their ID. Now, passing returnFieldsByFieldId=false will return fields by their name, not their ID.

2023-03-08

  • Updated Errors documentation with more examples of 403 errors.
  • Message for INVALID_PERMISSIONS_OR_MODEL_NOT_FOUND error updated to mention checking your user's permissions.
  • Updated OAuth reference with details about the expected success status code when requesting tokens.

2023-02-15

More information about the deprecation of user API keys, including intermediate deprecation milestones and a FAQ, can now be found here.

2023-02-08

2023-01-18

We're excited to announce the graduation of our announced features from last November's beta launch!

New authentication methods, now in general availability

  • For general background, please see those prior notes
  • Errata: User ID & Scopes is only available for the new authentication methods, now fixed

New: Sync CSV data endpoint

Sync CSV data endpoint is a new sync integration that accepts CSV-formatted data through our Web API.

We hope this makes it easier to plug in data sources that Airtable does not yet natively support!

API Key deprecation period start

With the graduation of personal access tokens and OAuth integrations, we're also starting the deprecation period for the previous method of user API keys.

We'll turn off API key access entirely after February 1, 2024. In the coming weeks, we'll share intermediate deprecation milestones, and more actionable details.

API Key-based webhook deprecation

As a reminder, the webhooks now in general availability require one of the new authentication methods. They have expiry times and require refreshes to continue to function.

As part of the user API key deprecation, we'll also phase out of previous features that relied on those keys. For example, enterprise users had access to create webhooks using API keys.

  • We'll phase out the ability for user API keys to create new webhooks; we'll share deprecation milestones and more details in the coming weeks
  • After February 1, 2024, any existing API key-created webhooks will also expire. These may be refreshed using the new authentication methods [Note: as of November 2023, webhooks created using API key will no longer expire in the future - see here for more info]

2022-12-12

2022-11-15

We’re excited to announce a number of updates to our developer tools and APIs, including:

  • New API authentication methods (now available in beta)
  • New API capabilities
  • New API docs

New authentication methods, now available in beta

We've released several new API authentication features in beta to provide even more security and control for developers. These include:

  • Personal access tokens for individual use: All users will be able to use personal access tokens for individual development.
  • OAuth for Integrations: Developers looking to build integrations will be able to use OAuth for a secure and seamless integration setup.
  • Service accounts (Enterprise only): Enterprise admins will be able to set up service accounts as non-user accounts for integrations and other uses.
  • Granular scopes and resources: All users will gain access to more granular control over scopes and resources, such as limiting a personal access token to read only access or limiting access to specific bases. Enterprise admins can also grant access to all workspaces and bases owned by their enterprise

For more information, please refer to the authentication reference page, as well as our detailed guides for personal access tokens and OAuth integrations.

Note: After personal access tokens and OAuth are no longer in beta, a deprecation timeline for Airtable API keys will be announced. There will be a notice period of at least 12 months before the deprecation is enforced, per our deprecation guidelines.

New API capabilities

We’ve released a number of new API capabilities, including new endpoints and updates to existing endpoints:

New API endpoints

Updates to existing endpoints

New API docs

We’ve updated our API docs to make them easier to use and navigate for developers. But rest assured, our existing per-base documentation remains as is!