The official Airtable JavaScript library.

Airtable.js

The Airtable API provides a simple way of accessing your data. Whether it's contacts, sales leads, inventory, applicant information or todo items, the vocabulary of the interactions closely matches your data structure. You will use your table names to address tables, column names to access data stored in those columns. In other words, the Airtable API is your own RESTful API for your base.

Installation

Node.js

To install Airtable.js in a node project:

npm install airtable

Airtable.js is compatible with Node 10 and above.

Browser

To use Airtable.js in the browser, use build/airtable.browser.js.

For a demo, run:

cd test/test_files
python -m SimpleHTTPServer

Edit test/test_files/index.html - put your BASE_ID and API_KEY (Be careful! You are putting your API key on a web page! Create a separate account and share only one base with it.)

Then open http://localhost:8000/ in your browser.

Airtable.js is compatible with browsers supported by the Airtable web app with the exception of Safari 10.0. Airtable.js supports Safari 10.1 and higher. See the technical requirements for more details.

Configuration

There are three configurable options available:

• apiKey - your secret API token. Visit /create/tokens to create a personal access token. OAuth access tokens can also be used.
• endpointUrl - the API endpoint to hit. You might want to override it if you are using an API proxy (e.g. runscope.net) to debug your API calls. (AIRTABLE_ENDPOINT_URL).
• requestTimeout - the timeout in milliseconds for requests. The default is 5 minutes (300000).

You can set the options globally via Airtable.configure:

Airtable.configure({ apiKey: 'YOUR_SECRET_API_TOKEN' })

Globally via process env (e.g. in 12factor setup):

export AIRTABLE_API_KEY=YOUR_SECRET_API_TOKEN

You can also override the settings per connection:

const airtable = new Airtable({endpointUrl: 'https://api-airtable-com-8hw7i1oz63iz.runscope.net/'})

Interactive documentation

Go to https://airtable.com/api to see the interactive API documentation for your Airtable bases. Once you select a base, click the "JavaScript" tab to see code snippets using Airtable.js. It'll have examples for all operations you can perform against your base using this library.

You can also view non-interactive API documentation at https://airtable.com/developers/web/api.

Promises

As of v0.5.0 all of the methods that take a done callback will return a Promise if you don't pass in a done callback.

For example:

table.select().firstPage(result => { ... })

is equivalent to

table.select().firstPage().then(result => { ... })

Tests

Tests are run via npm run test.

We strive for 100% test coverage. Some aspects may not be testable or suitable for test coverage. The tooling supports ignoring specific parts of a file documented here; use that as appropriate.

When you run the tests a coverage report will be generated at ./coverage/lcov-report/index.html which you can access in the browser for line by line reporting.

v0.12.2

• Fix invalid URL error in abort-controller

v0.12.1

• Add recordMetadata param to table.select(params) in order to fetch comment counts, available as record.commentCount.

v0.11.6

• Remove behavior of including AIRTABLE_API_KEY in airtable.browser.js via envify
• Add web worker compatibility

v0.11.5

• Update select() and list() to support to use POST endpoint when GET url length would exceed Airtable's 16k character limit
• Update select() and list() to explicitly choose to use GET or POST endpoint via new 'method' arg

v0.11.4

• Add support for returnFieldsByFieldId param.

v0.11.3

• Add a UMD build to use for browser-targeted builds. This fixes an issue where other apps that use airtable.js as a dependency were bundling code that expects to run in a node environment when building for a browser enviornment.

v0.11.2

• Bump NPM package versions (#276, #281, #293, #296, #297, #298)

v0.11.1

• Bump NPM package versions (#250, #253, #266, #267, #268)

v0.11.0

• Add support for custom headers
• Allow requestTimeout to be configured like other AirtableOptions
• Fix type warnings

v0.10.1

• Fix error handler in updating an array (#223)
• Fix binding fetch to window (#235)
• Update lodash and node-fetch dependencies
• Widen @types/node dependency

v0.10.0

• Convert to TypeScript. The project now comes with .d.ts typescript definition files.

v0.9.0

• Remove Promise polyfill (#195)
• Replace deprecated request library with node-fetch (#191)
• Increase test coverage of library to 100% (#190, #188, #187, #186, #185, #184, #183 #182, #181, #178, #177, #176, #175)
• Enable CI (#173, #190)
• Improve README (#164)
• Remove support for Safari 10.0

v0.8.1

• Require Node 8 or above (down from Node 10)

v0.8.0

• Require Node 10 or above
• Add Promise polyfill (#147)
• Remove allowUnauthorizedSsl option

v0.7.2

• Properly reject unauthorized SSL certificates (#140)
• Minor tweaks to formatting in README (#136)
• Update Lodash to 4.17.15 (#141)

v0.7.1

• Fix a User-Agent bug in Node (#132)
• Stop publishing non-essential files to npm (#128)

v0.7.0

• Remove custom class library, shrinking the file size and improving debugging (#123)
• Improve an error message (#115)
• Update Lodash to 4.17.14 (#124)

v0.6.0

• Add support for beta of batch record operations (#86, #88, #92)
• Add backoff when rate limited (#110)
• Shrink browser build by removing assert module (#101)
• Fix bug when calling some functions with callbacks (#103)

v0.5.10

• Make API key less likely to be logged (#82, #83)

v0.5.9

• Update lodash dependency (#80)

v0.5.8

• Remove async dependency (#76)
• Shrink size of browser build by about half (#76)

v0.5.7

• Support dotenv for loading config (#59)
• Improve error message is select() is called without args (#70)
• Update dependencies (#73)

v0.5.6

• Fix crash when specifying sort direction or cellFormat options

v0.5.5

• Upgrade lodash package from 2.4.1 to 4.17.10

v0.5.4

• Upgrade request package to 2.85.0

v0.5.3

• Fix User-Agent header warnings when running Chrome (#52)
• Fix JSON imports so webpack can bundle

v0.5.2

• Support for the cellFormat, userLocale, and timeZone parameters

v0.5.1

• Improved handling of unexpected server errors
• Exports AirtableError class as Airtable.Error for use in instanceof checks.

v0.5.0

• Optional Promise-based API: if you call any method that takes a callback without providing a callback, it will return a Promise:

   table.find(recordId).then(record => {
       // Process record.
   }).catch(err => {
       // Handle error.
   })

  • Added an all() method for automatically fetching all records across all pages when selecting from a table:

    table.select({view: 'Main View'}).all().then(records => {

       // records array will contain every record in Main View.

    }).catch(err => {

       // Handle error.

    })

v0.4.5

• The default timeout for requests is increased from 30 seconds to 5 minutes. You can set a custom timeout by passing requestTimeout in milliseconds to the Airtable constructor or Airtable.configure:

  Airtable.configure({requestTimeout: 30 * 1000}); // 30 seconds

v0.4.4

• airtable.browser.js no longer implicitly depends on jQuery being available on the page.
• Upgraded dependency: request 2.79.0 (removes tough-cookie vulnerability warning).

v0.4.3

• Fixed issue that prevented callback from being called with error when running in the browser and servers are unreachable.

v0.4.2

• Upgraded dependencies: async 1.5.2, request 2.73.0

v0.4.1

• Fixed a bug that prevented records returned from select queries from being deleted.

• Fixed the demo page (test/test_files/index.html)

v0.4.0

• Added Table.select for querying records in a table. It takes the following optional parameters for sorting and filtering records:

   fields: only include the specified fields in results.
   filterByFormula: only include records that satisfy the formula.
   maxRecords: at most, return this many records in total.
   pageSize: at most, return this many records in each request.
   sort: specify fields to use for sorting the records.
   view: return records from a specific view, using the view order.

• Deprecated Table.list and Table.forEach. Use Table.select instead.

v0.2.0

• Renamed Application to Base. This is a breaking change for the client, no changes in the API.

v0.1.19

• Added ability to listRecords according to view (filters and order) and sort by a field.