This is page 2 of 3. Use http://codebase.md/felores/airtable-mcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .gitignore
├── .npmignore
├── docs
│ ├── Airtable API Documentation.md
│ ├── Airtable API field types and cell values.md
│ ├── Airtable_MCP_server_guide_for_LLMs.md
│ ├── mcp-llm-guide.md
│ └── MCP-llms-full.md
├── LICENSE
├── package-lock.json
├── package.json
├── prompts
│ ├── project-knowledge.md
│ └── system-prompt.md
├── README.md
├── scripts
│ └── post-build.js
├── src
│ ├── index.ts
│ └── types.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/docs/Airtable API Documentation.md:
--------------------------------------------------------------------------------
```markdown
1 | # Airtable API Documentation
2 |
3 | Guide
4 |
5 | # Authentication
6 |
7 | ## [§](/developers/web/api/authentication\#basics) Basics
8 |
9 | Airtable's API uses token-based authentication, allowing users to authenticate API requests by inputting their tokens
10 | into the HTTP authorization bearer token header.
11 |
12 | Example:
13 |
14 | ```
15 |
16 | curl https://api.airtable.com/v0/YOUR_BASE_ID/YOUR_TABLE_ID_OR_NAME -H \
17 | "Authorization: Bearer YOUR_TOKEN"
18 | ```
19 |
20 | All API requests must be authenticated and made through HTTPS.
21 |
22 | Passing personal access tokens and OAuth access tokens via the legacy `api_key` URL parameter is not supported.
23 |
24 | ## [§](/developers/web/api/authentication\#types-of-token) Types of token
25 |
26 | > As of February 1st 2024, the deprecation period for Airtable API keys has ended. Users of Airtable API keys must
27 | > migrate to the new authentication methods to continue using Airtable's API. See [this article](https://support.airtable.com/docs/airtable-api-key-deprecation-notice)
28 | > for more details.
29 |
30 | We currently support using personal access tokens and OAuth access tokens during the authentication process.
31 |
32 | [Personal access tokens](/developers/web/guides/personal-access-tokens) are for personal development, like building an integration for
33 | yourself, your client, or your company. They can be created and managed at [/create/tokens](/../../create/tokens) or
34 | from the enterprise admin panel for [service accounts](https://support.airtable.com/docs/service-accounts-overview). Personal access tokens act as your user account, and should not
35 | be shared with third-party services or integrations.
36 |
37 | [OAuth access tokens](/developers/web/guides/oauth-integrations) are recommended for building an integration where other users grant your
38 | service access to Airtable’s API on their behalf. In this case, your integration is a third-party service with respect to Airtable.
39 | After registering your integration with Airtable at [/create/oauth](/../../create/oauth), tokens are available
40 | via the [OAuth grant flow](https://oauth.net/2/).
41 |
42 | Any integrations that allow other users to grant access to Airtable should use OAuth.
43 |
44 | ## [§](/developers/web/api/authentication\#scopes-and-resources-access) Scopes and resources/access
45 |
46 | Personal access and Oauth tokens serve as the account of the user who grants access, with the following limitations:
47 |
48 | - [Scopes](/developers/web/api/scopes): What actions the token can perform.
49 | - Resources/access: What bases and workspace the token can access. Tokens can be granted access to individual—or all—bases/workspaces. These can be listed using the [list bases](/developers/web/api/list-bases) endpoint.
50 |
51 | For example, to update a record in a base via API, the user who granted the token must have editor access to the base.
52 | Additionally, the token must have both the correct scope ( `data.records:write`) and the base added to it as a resource.
53 |
54 | For personal access tokens, scopes and resources/access are individually configured from [/create/tokens](/../../create/tokens).
55 | And for OAuth access tokens, developers choose the requested scopes from [/create/oauth](/../../create/oauth),
56 | while end-users decide what resources to grant access to.
57 |
58 | 
59 |
60 | Guide
61 |
62 | # Scopes
63 |
64 | Scopes control what actions a token can perform.
65 |
66 | [Personal access tokens](https://airtable.com/developers/web/guides/personal-access-tokens) and [OAuth access tokens](https://airtable.com/developers/web/guides/oauth-integrations) can only access API endpoints covered by the scopes granted to them. A full reference of available scopes is below.
67 |
68 | **Note**: By default, OAuth integrations can only request basic scopes. See [here](https://airtable.com/developers/web/guides/oauth-integrations#making-api-requests) for more information about requesting enterprise scopes.
69 |
70 | On top of requesting the correct scope, the user and token must also have the required resources and permissions to perform the action.
71 |
72 | Example 1: a personal access token with the scope `data.records:read` and a base added to it would be able to use the "Read records" endpoint on that base, but would not be allowed to use the "Write records" endpoint for that base. Similarly, it would not be able to use the "Read records" endpoint to access other bases that have not been added to the token.
73 |
74 | Example 2: a personal access token with the scope `schema.bases:read` and multiple bases added to it would only be able to create fields in bases where the user has Creator permissions (required to customize fields).
75 |
76 | For more information on how tokens work, refer to the [Authentication](https://airtable.com/developers/web/api/authentication) reference.
77 |
78 | ## Basic scopes
79 |
80 | The following scopes are available to all users:
81 |
82 | [§](/developers/web/api/scopes#data-records-read)`data.records:read`
83 |
84 | See the data in records
85 |
86 | - [List records](https://airtable.com/developers/web/api/list-records)
87 | - [Get record](https://airtable.com/developers/web/api/get-record)
88 |
89 | [§](/developers/web/api/scopes#data-records-write)`data.records:write`
90 |
91 | Create, edit, and delete records
92 |
93 | - [Delete multiple records](https://airtable.com/developers/web/api/delete-multiple-records)
94 | - [Update multiple records](https://airtable.com/developers/web/api/update-multiple-records)
95 | - [Create records](https://airtable.com/developers/web/api/create-records)
96 | - [Sync CSV data](https://airtable.com/developers/web/api/post-sync-api-endpoint)
97 | - [Delete record](https://airtable.com/developers/web/api/delete-record)
98 | - [Update record](https://airtable.com/developers/web/api/update-record)
99 |
100 | [§](/developers/web/api/scopes#data-record-comments-read)`data.recordComments:read`
101 |
102 | See comments in records
103 |
104 | - [List comments](https://airtable.com/developers/web/api/list-comments)
105 |
106 | [§](/developers/web/api/scopes#data-record-comments-write)`data.recordComments:write`
107 |
108 | Create, edit, and delete record comments
109 |
110 | - [Create comment](https://airtable.com/developers/web/api/create-comment)
111 | - [Delete comment](https://airtable.com/developers/web/api/delete-comment)
112 | - [Update comment](https://airtable.com/developers/web/api/update-comment)
113 |
114 | [§](/developers/web/api/scopes#schema-bases-read)`schema.bases:read`
115 |
116 | See the structure of a base, like table names or field types
117 |
118 | - [List bases](https://airtable.com/developers/web/api/list-bases)
119 | - [Get base schema](https://airtable.com/developers/web/api/get-base-schema)
120 |
121 | [§](/developers/web/api/scopes#schema-bases-write)`schema.bases:write`
122 |
123 | Edit the structure of a base, like adding new fields or tables
124 |
125 | - [Create base](https://airtable.com/developers/web/api/create-base)
126 | - [Create table](https://airtable.com/developers/web/api/create-table)
127 | - [Update table](https://airtable.com/developers/web/api/update-table)
128 | - [Create field](https://airtable.com/developers/web/api/create-field)
129 | - [Update field](https://airtable.com/developers/web/api/update-field)
130 | - [Sync CSV data](https://airtable.com/developers/web/api/post-sync-api-endpoint)
131 |
132 | [§](/developers/web/api/scopes#webhook-manage)`webhook:manage`
133 |
134 | View, create, delete webhooks for a base, as well as fetch webhook payloads.
135 |
136 | - [List webhooks](https://airtable.com/developers/web/api/list-webhooks)
137 | - [Create a webhook](https://airtable.com/developers/web/api/create-a-webhook)
138 | - [Delete a webhook](https://airtable.com/developers/web/api/delete-a-webhook)
139 | - [Enable/disable webhook notifications](https://airtable.com/developers/web/api/enable-disable-webhook-notifications)
140 | - [Refresh a webhook](https://airtable.com/developers/web/api/refresh-a-webhook)
141 |
142 | [§](/developers/web/api/scopes#block-manage)`block:manage`
143 |
144 | Create new releases and submissions for custom extensions via the Blocks CLI.
145 |
146 | [§](/developers/web/api/scopes#user-email-read)`user.email:read`
147 |
148 | See the user's email address
149 |
150 | ## Enterprise member scopes
151 |
152 | The following scopes are only available to users on an enterprise account:
153 |
154 | [§](/developers/web/api/scopes#enterprise-groups-read)`enterprise.groups:read`
155 |
156 | View information about user groups under the enterprise, their access, and their members
157 |
158 | - [Get user group](https://airtable.com/developers/web/api/get-user-group)
159 |
160 | [§](/developers/web/api/scopes#workspaces-and-bases-read)`workspacesAndBases:read`
161 |
162 | View metadata about workspaces, bases, and views including collaborators
163 |
164 | - [Get base collaborators](https://airtable.com/developers/web/api/get-base-collaborators)
165 | - [List block installations](https://airtable.com/developers/web/api/list-block-installations)
166 | - [Get interface](https://airtable.com/developers/web/api/get-interface)
167 | - [List views](https://airtable.com/developers/web/api/list-views)
168 | - [Get view metadata](https://airtable.com/developers/web/api/get-view-metadata)
169 | - [Get workspace collaborators](https://airtable.com/developers/web/api/get-workspace-collaborators)
170 |
171 | [§](/developers/web/api/scopes#workspaces-and-bases-write)`workspacesAndBases:write`
172 |
173 | Edit metadata of workspaces and bases, including collaborators, invites, views, and extensions
174 |
175 | - [Delete block installation](https://airtable.com/developers/web/api/delete-block-installation)
176 | - [Manage block installation](https://airtable.com/developers/web/api/manage-block-installation)
177 | - [Add base collaborator](https://airtable.com/developers/web/api/add-base-collaborator)
178 | - [Delete base collaborator](https://airtable.com/developers/web/api/delete-base-collaborator)
179 | - [Update collaborator base permission](https://airtable.com/developers/web/api/update-collaborator-base-permission)
180 | - [Add interface collaborator](https://airtable.com/developers/web/api/add-interface-collaborator)
181 | - [Delete interface collaborator](https://airtable.com/developers/web/api/delete-interface-collaborator)
182 | - [Update interface collaborator](https://airtable.com/developers/web/api/update-interface-collaborator)
183 | - [Delete interface invite](https://airtable.com/developers/web/api/delete-interface-invite)
184 | - [Delete base invite](https://airtable.com/developers/web/api/delete-base-invite)
185 | - [Delete view](https://airtable.com/developers/web/api/delete-view)
186 | - [Add workspace collaborator](https://airtable.com/developers/web/api/add-workspace-collaborator)
187 | - [Delete workspace collaborator](https://airtable.com/developers/web/api/delete-workspace-collaborator)
188 | - [Update workspace collaborator](https://airtable.com/developers/web/api/update-workspace-collaborator)
189 | - [Delete workspace invite](https://airtable.com/developers/web/api/delete-workspace-invite)
190 | - [Update workspace restrictions](https://airtable.com/developers/web/api/update-workspace-restrictions)
191 |
192 | [§](/developers/web/api/scopes#workspaces-and-bases-shares-manage)`workspacesAndBases.shares:manage`
193 |
194 | View, enable, disable and delete share links for bases. Note: Share links can be used to view the data in the base.
195 |
196 | - [List shares](https://airtable.com/developers/web/api/list-shares)
197 | - [Delete share](https://airtable.com/developers/web/api/delete-share)
198 | - [Manage share](https://airtable.com/developers/web/api/manage-share)
199 |
200 | ## Enterprise admin scopes
201 |
202 | The following scopes are only available to enterprise admins:
203 |
204 | [§](/developers/web/api/scopes#enterprise-scim-users-and-groups-manage)`enterprise.scim.usersAndGroups:manage`
205 |
206 | Manage the organization's users and groups via SCIM APIs, including provisioning and deprovisioning them.
207 |
208 | - [List groups](https://airtable.com/developers/web/api/list-scim-groups)
209 | - [Create group](https://airtable.com/developers/web/api/create-scim-group)
210 | - [Delete group](https://airtable.com/developers/web/api/delete-scim-group)
211 | - [Get group](https://airtable.com/developers/web/api/get-scim-group)
212 | - [Patch group](https://airtable.com/developers/web/api/patch-scim-group)
213 | - [Put group](https://airtable.com/developers/web/api/put-scim-group)
214 | - [List users](https://airtable.com/developers/web/api/list-scim-users)
215 | - [Create user](https://airtable.com/developers/web/api/create-scim-user)
216 | - [Delete user](https://airtable.com/developers/web/api/delete-scim-user)
217 | - [Get user](https://airtable.com/developers/web/api/get-scim-user)
218 | - [Patch user](https://airtable.com/developers/web/api/patch-scim-user)
219 | - [Put user](https://airtable.com/developers/web/api/put-scim-user)
220 |
221 | [§](/developers/web/api/scopes#enterprise-audit-logs-read)`enterprise.auditLogs:read`
222 |
223 | View the organization's audit logs
224 |
225 | - [Audit log events](https://airtable.com/developers/web/api/audit-log-events)
226 | - [List audit log requests](https://airtable.com/developers/web/api/list-audit-log-requests)
227 | - [Create audit log request](https://airtable.com/developers/web/api/create-audit-log-request)
228 | - [Get audit log request](https://airtable.com/developers/web/api/get-audit-log-request)
229 |
230 | [§](/developers/web/api/scopes#enterprise-change-events-read)`enterprise.changeEvents:read`
231 |
232 | View the organization's change events
233 |
234 | - [Change events](https://airtable.com/developers/web/api/change-events)
235 |
236 | [§](/developers/web/api/scopes#enterprise-exports-manage)`enterprise.exports:manage`
237 |
238 | Manage the organization's data exports, including eDiscovery exports
239 |
240 | - [List eDiscovery exports](https://airtable.com/developers/web/api/list-ediscovery-export)
241 | - [Create eDiscovery export](https://airtable.com/developers/web/api/create-ediscovery-export)
242 | - [Get eDiscovery export](https://airtable.com/developers/web/api/get-ediscovery-export)
243 |
244 | [§](/developers/web/api/scopes#enterprise-account-read)`enterprise.account:read`
245 |
246 | View data about the enterprise account, including workspaces ids, users, groups and email domains
247 |
248 | - [Get enterprise](https://airtable.com/developers/web/api/get-enterprise)
249 |
250 | [§](/developers/web/api/scopes#enterprise-account-write)`enterprise.account:write`
251 |
252 | Edit data about the enterprise account, including creating descendant enterprise accounts
253 |
254 | - [Create descendant enterprise](https://airtable.com/developers/web/api/create-descendant-enterprise)
255 |
256 | [§](/developers/web/api/scopes#enterprise-user-read)`enterprise.user:read`
257 |
258 | View account information of users under the enterprise, including user id, name, email and bases user has access to
259 |
260 | - [Get users by id or email](https://airtable.com/developers/web/api/get-users-by-id-or-email)
261 | - [Get user by id](https://airtable.com/developers/web/api/get-user-by-id)
262 |
263 | [§](/developers/web/api/scopes#enterprise-user-write)`enterprise.user:write`
264 |
265 | Manage users under the enterprise account, including provisioning, deactivating and deleting users
266 |
267 | - [Delete users by email](https://airtable.com/developers/web/api/delete-users-by-email)
268 | - [Manage user batched](https://airtable.com/developers/web/api/manage-user-batched)
269 | - [Manage user membership](https://airtable.com/developers/web/api/manage-user-membership)
270 | - [Grant admin access](https://airtable.com/developers/web/api/grant-admin-access)
271 | - [Revoke admin access](https://airtable.com/developers/web/api/revoke-admin-access)
272 | - [Delete user by id](https://airtable.com/developers/web/api/delete-user-by-id)
273 | - [Manage user](https://airtable.com/developers/web/api/manage-user)
274 | - [Logout user](https://airtable.com/developers/web/api/logout-user)
275 | - [Remove user from enterprise](https://airtable.com/developers/web/api/remove-user-from-enterprise)
276 |
277 | [§](/developers/web/api/scopes#enterprise-groups-manage)`enterprise.groups:manage`
278 |
279 | Manage user groups under the enterprise, including moving them
280 |
281 | - [Move user groups](https://airtable.com/developers/web/api/move-user-groups)
282 |
283 | [§](/developers/web/api/scopes#workspaces-and-bases-manage)`workspacesAndBases:manage`
284 |
285 | Manage workspaces and bases under the enterprise, including moving them
286 |
287 | - [Delete base](https://airtable.com/developers/web/api/delete-base)
288 | - [Move workspaces](https://airtable.com/developers/web/api/move-workspaces)
289 | - [Delete workspace](https://airtable.com/developers/web/api/delete-workspace)
290 | - [Move base](https://airtable.com/developers/web/api/move-base)
291 |
292 | 
293 |
294 |
295 | # Errors
296 |
297 | The Airtable Web API follows HTTP status code semantics.
298 |
299 | 2xx codes signify success, 4xx mostly represent user error, 5xx generally correspond to a server error. The error messages will return a JSON-encoded body that contains **error** and **message** fields. Those will provide specific error condition and human-readable message to identify what caused the error.
300 |
301 | ## [§](/developers/web/api/errors\#success-code) Success code
302 |
303 | ### [§](/developers/web/api/errors\#anchor-200-ok)`200 OK`
304 |
305 | Request completed successfully.
306 |
307 | ## [§](/developers/web/api/errors\#user-error-codes) User error codes
308 |
309 | These errors generally indicate a problem on the client side. If you are getting one of these, check your code and the request details.
310 |
311 | ### [§](/developers/web/api/errors\#anchor-400-bad-request)`400 Bad Request`
312 |
313 | The request encoding is invalid; the request can't be parsed as a valid JSON.
314 |
315 | ### [§](/developers/web/api/errors\#anchor-401-unauthorized)`401 Unauthorized`
316 |
317 | Accessing a protected resource without authorization or with invalid credentials.
318 |
319 | ### [§](/developers/web/api/errors\#anchor-403-forbidden)`403 Forbidden`
320 |
321 | Accessing a protected resource with API credentials that don't have access to that resource.
322 |
323 | See [below](/developers/web/api/errors#anchor-403) for examples and suggested debugging steps.
324 |
325 | ### [§](/developers/web/api/errors\#anchor-404-not-found)`404 Not Found`
326 |
327 | Route or resource is not found. This error is returned when the request hits an undefined route, or if the resource doesn't exist (e.g. has been deleted).
328 |
329 | ### [§](/developers/web/api/errors\#anchor-413-request-entity-too-large)`413 Request Entity Too Large`
330 |
331 | The request exceeded the maximum allowed payload size. You shouldn't encounter this under normal use.
332 |
333 | ### [§](/developers/web/api/errors\#anchor-422-invalid-request)`422 Invalid Request`
334 |
335 | The request data is invalid. This includes most of the base-specific validations. You will receive a detailed error message and code pointing to the exact issue.
336 |
337 | ### [§](/developers/web/api/errors\#anchor-429-too-many-requests)`429 Too Many Requests`
338 |
339 | The API is limited to 5 requests per second per base. You will receive a 429 status code and a message "Rate limit exceeded. Please try again later" and will need to wait 30 seconds before subsequent requests will succeed. To learn more about rate limits, please visit our [Rate Limits](/developers/web/api/rate-limits) guide.
340 |
341 | ## [§](/developers/web/api/errors\#server-error-codes) Server error codes
342 |
343 | These errors generally represent an error on our side. In the event of a 5xx error code, detailed information about the error will be automatically recorded, and Airtable's developers will be notified.
344 |
345 | ### [§](/developers/web/api/errors\#anchor-500-internal-server-error)`500 Internal Server Error`
346 |
347 | The server encountered an unexpected condition.
348 |
349 | ### [§](/developers/web/api/errors\#anchor-502-bad-gateway)`502 Bad Gateway`
350 |
351 | Airtable's servers are restarting or an unexpected outage is in progress. You should generally not receive this error, and requests are safe to retry.
352 |
353 | ### [§](/developers/web/api/errors\#anchor-503-service-unavailable)`503 Service Unavailable`
354 |
355 | The server could not process your request in time. The server could be temporarily unavailable, or it could have timed out processing your request. You should retry the request with backoffs.
356 |
357 | ## [§](/developers/web/api/errors\#example-error-responses) Example error responses
358 |
359 | ### [§](/developers/web/api/errors\#anchor-404)`404`
360 |
361 | The path is not valid.
362 |
363 | ```
364 |
365 | 404 Not Found
366 | {
367 | "error": "NOT_FOUND"
368 | }
369 | ```
370 |
371 | ```
372 |
373 | 404 Not Found
374 | {
375 | "error": {
376 | "type": "NOT_FOUND"
377 | }
378 | }
379 | ```
380 |
381 | ### [§](/developers/web/api/errors\#anchor-403)`403`
382 |
383 | You don't have the right permission for the resource, or the resource was not found.
384 |
385 | Check that both you and the token have access to the resource. For example, to access a base using a personal access token,
386 | your user must be a collaborator _and_ the token must also have access to the base. See [this guide](/developers/web/api/authentication#scopes-and-resources-access) for more details.
387 |
388 | ```
389 |
390 | 403 Forbidden
391 | {
392 | "error": {
393 | "type": "INVALID_PERMISSIONS_OR_MODEL_NOT_FOUND",
394 | "message": "Invalid permissions, or the requested model was not found. Check that both your user and your token have the required permissions, and that the model names and/or ids are correct."
395 | }
396 | }
397 | ```
398 |
399 | You don't have permission to create records in the given table. This is returned both when creating records directly,
400 | and when creating linked records while updating cell values.
401 |
402 | Check whether the table or any fields you are setting values for have [editing permissions](https://support.airtable.com/docs/using-field-and-table-editing-permissions) limited.
403 |
404 | ```
405 |
406 | 403 Forbidden
407 | {
408 | "error": {
409 | "type": "INVALID_PERMISSIONS",
410 | "message": "You are not permitted to create records in table TABLE_NAME (TABLE_ID)"
411 | }
412 | }
413 | ```
414 |
415 | You don't have permission to update cell values in the given field. Check whether the field has [editing permissions](https://support.airtable.com/docs/using-field-and-table-editing-permissions) limited.
416 |
417 | ```
418 |
419 | 403 Forbidden
420 | {
421 | "error": {
422 | "type": "INVALID_PERMISSIONS",
423 | "message": "You are not permitted to write cell values in field FIELD_NAME (FIELD_ID)"
424 | }
425 | }
426 | ```
427 |
428 | You don't have the right permission for the action.
429 |
430 | ```
431 |
432 | 403 Forbidden
433 | {
434 | "error": {
435 | "type": "INVALID_PERMISSIONS",
436 | "message": "You are not permitted to perform this operation"
437 | }
438 | }
439 | ```
440 |
441 | ### [§](/developers/web/api/errors\#anchor-422)`422`
442 |
443 | The path is correct, however the body is either not understood or not permitted.
444 |
445 | ```
446 |
447 | 422 Unprocessable Entity
448 | {
449 | "error": {
450 | "type": "INVALID_REQUEST_UNKNOWN",
451 | "message": "Invalid request: parameter validation failed. Check your request data."
452 | }
453 | }
454 | ```
455 |
456 | ### [§](/developers/web/api/errors\#anchor-429)`429`
457 |
458 | The request has been rate limited.
459 |
460 | ```
461 |
462 | 429 Too Many Requests
463 | {
464 | "error": {
465 | "type": "RATE_LIMIT_REACHED",
466 | "message": "Rate limit exceeded. Please try again later"
467 | }
468 | }
469 | ```
470 |
471 | ### [§](/developers/web/api/errors\#anchor-503)`503`
472 |
473 | The server is temporarily unavailable and the request should be retried. The `Retry-After` header may be provided.
474 |
475 | ```
476 |
477 | 503 Service Unavailable
478 | {
479 | "error": {
480 | "type": "RETRIABLE_ERROR",
481 | "message": "Server encountered an error while processing your request, and it is safe to retry the request"
482 | }
483 | }
484 | ```
485 |
486 | Records
487 |
488 | # List records
489 |
490 | get `https://api.airtable.com/v0/{baseId}/{tableIdOrName}`
491 |
492 | List records in a table. Note that table names and table ids can be used interchangeably.
493 | We recommend using table IDs so you don't need to modify your API request when your table name changes.
494 |
495 | The server returns one page of records at a time. Each page will contain **pageSize** records, which is 100 by default.
496 | If there are more records, the response will contain an **offset**. To fetch the next page of records, include **offset** in the next request's parameters.
497 | Pagination will stop when you've reached the end of your table. If the **maxRecords** parameter is passed, pagination will stop once you've reached this maximum.
498 |
499 | Returned records do not include any fields with "empty" values, e.g. **""**, **\[\]**, or **false**.
500 |
501 | You can filter, sort, and format the results with query parameters. Note that these parameters need to be URL encoded.
502 | You can use our [API URL encoder tool](https://codepen.io/airtable/pen/MeXqOg) to help with this.
503 | If you are using a helper library like [Airtable.js](https://github.com/Airtable/airtable.js), these parameters will be automatically encoded.
504 |
505 | **Note** Airtable's API only accepts request with a URL shorter than 16,000 characters. Encoded formulas may cause your requests to exceed this limit.
506 | To fix this issue you can instead make a POST request to `/v0/{baseId}/{tableIdOrName}/listRecords` while passing the parameters within the body of
507 | the request instead of the query parameters.
508 |
509 | [§](/developers/web/api/list-records#requirements)
510 |
511 | ### Requirements
512 |
513 | | | |
514 | | --- | --- |
515 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
516 | | Scope | [`data.records:read`](https://airtable.com/developers/web/api/scopes#data-records-read) |
517 | | User role | Base read-only |
518 | | Billing plans | All plans |
519 |
520 | [§](/developers/web/api/list-records#path)
521 |
522 | ### Path parameters
523 |
524 | ``
525 |
526 | | | |
527 | | --- | --- |
528 | | [§](/developers/web/api/list-records#path-baseid)`baseId` | `string` |
529 | | [§](/developers/web/api/list-records#path-tableidorname)`tableIdOrName` | `string` |
530 |
531 | [§](/developers/web/api/list-records#query)
532 |
533 | ### Query parameters
534 |
535 | ``
536 |
537 | | | |
538 | | --- | --- |
539 | | [§](/developers/web/api/list-records#query-timezone)`timeZone` | `optional<` [`Timezone`](https://airtable.com/developers/web/api/model/timezone) `>` <br>The [time zone](https://support.airtable.com/docs/supported-timezones-for-set-timezone)<br>that should be used to format dates when using `string` as the `cellFormat`. This parameter is<br>required when using `string` as the `cellFormat`. |
540 | | [§](/developers/web/api/list-records#query-userlocale)`userLocale` | `optional<` `string` `>` <br>The [user locale](https://support.airtable.com/docs/supported-locale-modifiers-for-set-locale)<br>that should be used to format dates when using `string` as the `cellFormat`. This parameter is<br>required when using `string` as the `cellFormat`. |
541 | | [§](/developers/web/api/list-records#query-pagesize)`pageSize` | `optional<` `number` `>` <br>The number of records returned in each request. Must be less than or equal to 100. Default is 100. |
542 | | [§](/developers/web/api/list-records#query-maxrecords)`maxRecords` | `optional<` `number` `>` <br>The maximum total number of records that will be returned in your requests.<br>If this value is larger than **pageSize** (which is 100 by default), you may have to load multiple pages to reach this total. |
543 | | [§](/developers/web/api/list-records#query-offset)`offset` | `optional<` `string` `>` <br>To fetch the next page of records, include offset from the previous request in the next request's parameters. |
544 | | [§](/developers/web/api/list-records#query-view)`view` | `optional<` `string` `>` <br>The name or ID of a view in the table. If set, only the records in that view will be returned.<br>The records will be sorted according to the order of the view unless the **sort** parameter is included, which overrides that order.<br>Fields hidden in this view will be returned in the results. To only return a subset of fields, use the **fields** parameter. |
545 | | [§](/developers/web/api/list-records#query-sort)`sort` | `optional<` `array of the below object` `>`
546 |
547 | A list of sort objects that specifies how the records will be ordered.
548 | Each sort object must have a **field** key specifying the name of the field to sort on,
549 | and an optional **direction** key that is either **"asc"** or **"desc"**. The default direction is **"asc"**.
550 |
551 | The **sort** parameter overrides the sorting of the view specified in the **view** parameter.
552 | If neither the **sort** nor the **view** parameter is included, the order of records is arbitrary.
553 |
554 | ``
555 |
556 | | | |
557 | | --- | --- |
558 | | [§](/developers/web/api/list-records#query-sort-field)`field` | `string` |
559 | | [§](/developers/web/api/list-records#query-sort-direction)`direction` | `optional<``"asc" | "desc"` `>` | |
560 | | [§](/developers/web/api/list-records#query-filterbyformula)`filterByFormula` | `optional<` `string` `>` <br>A [formula](https://support.airtable.com/docs/formula-field-reference) used to filter records.<br>The formula will be evaluated for each record, and if the result is not **0**, **false**, **""**, **NaN**, **\[\]**,<br>or **#Error!** the record will be included in the response. We recommend testing your formula in the Formula field UI<br>before using it in your API request.<br>If combined with the **view** parameter, only records in that view which satisfy the formula will be returned.<br>The formula must be encoded first before passing it as a value.<br>You can use [this tool](https://codepen.io/airtable/full/MeXqOg) to not only encode the formula but also create the entire url you need.<br>Formulas can use field names, or field id's inside of the formula.<br>**Note** Airtable's API only accepts request with a URL shorter than 16,000 characters.<br>Encoded formulas may cause your requests to exceed this limit. To fix this issue you can instead make a<br>POST request to `/v0/{baseId}/{tableIdOrName}/listRecords` while passing the<br>parameters within the body of the request instead of the query parameters. |
561 | | [§](/developers/web/api/list-records#query-cellformat)`cellFormat` | `optional<``"json" | "string"` `>` <br>The format that should be used for cell values. Supported values are:<br>- **json**: cells will be formatted as JSON, depending on the field type.<br>- **string**: cells will be formatted as user-facing strings, regardless of the field type.<br>The **timeZone** and **userLocale** parameters are required when using **string** as the **cellFormat**.<br>**Note**: You should not rely on the format of these strings, as it is subject to change.<br>The default is **json**. |
562 | | [§](/developers/web/api/list-records#query-fields)`fields` | `optional<` `array of strings` `>` <br>Only data for fields whose names or IDs are in this list will be included in the result.<br>If you don't need every field, you can use this parameter to reduce the amount of data transferred.<br>**Note** Airtable's API only accepts request with a URL shorter than 16,000 characters.<br>Encoded formulas may cause your requests to exceed this limit. To fix this issue you can instead make a<br>POST request to `/v0/{baseId}/{tableIdOrName}/listRecords` while passing the<br>parameters within the body of the request instead of the query parameters. |
563 | | [§](/developers/web/api/list-records#query-returnfieldsbyfieldid)`returnFieldsByFieldId` | `optional<` `boolean` `>` <br>An optional boolean value that lets you return field objects where the key is the field id.<br>This defaults to **false**, which returns field objects where the key is the field name. |
564 | | [§](/developers/web/api/list-records#query-recordmetadata)`recordMetadata` | `optional<` `array of "commentCount"` `>` <br>An optional field that, if specified, includes **commentCount** on each record returned. |
565 |
566 | [§](/developers/web/api/list-records#response)
567 |
568 | ### Response format
569 |
570 | ``
571 |
572 | List of records with fields and cell values
573 |
574 | | | |
575 | | --- | --- |
576 | | [§](/developers/web/api/list-records#response-offset)`offset` | `optional<` `string` `>` <br>If there are more records, the response will contain an offset. Pass this offset into the<br>next request to fetch the next page of records. |
577 | | [§](/developers/web/api/list-records#response-records)`records` | `array of the below object` ``
578 |
579 | A single record with field and cell values
580 |
581 | | | |
582 | | --- | --- |
583 | | [§](/developers/web/api/list-records#response-records-id)`id` | `string` <br>Record ID |
584 | | [§](/developers/web/api/list-records#response-records-createdtime)`createdTime` | `string` <br>A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z" |
585 | | [§](/developers/web/api/list-records#response-records-fields)`fields` | `object`
586 |
587 | Cell values are keyed by either field name or field ID (conditioned on `returnFieldsByFieldId`).
588 |
589 | See [Cell Values](/developers/web/api/field-model) for more information on cell value response types.
590 |
591 | | | |
592 | | --- | --- |
593 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | |
594 | | [§](/developers/web/api/list-records#response-records-commentcount)`commentCount` | `optional<` `number` `>` <br>The number of comments (if there are any) on the record.<br>The `recordMetadata` query parameter must include `"commentCount"` in order to receive this. | |
595 |
596 | ### Error responses
597 |
598 | Iteration timeout (422)
599 |
600 | Iteration may timeout due to client inactivity or server restarts. It may then restart iteration from the beginning.
601 |
602 | ```
603 |
604 | {
605 | "error": {
606 | "type": "LIST_RECORDS_ITERATOR_NOT_AVAILABLE"
607 | }
608 | }
609 | ```
610 |
611 | Request (example)
612 |
613 | Copy
614 |
615 | ```
616 |
617 | $
618 | curl "https://api.airtable.com/v0/{baseId}/{tableIdOrName}" \
619 | -H "Authorization: Bearer YOUR_TOKEN"
620 | ```
621 |
622 | 200 – Response (example)
623 |
624 | ```
625 |
626 | {
627 | "records": [\
628 | {\
629 | "createdTime": "2022-09-12T21:03:48.000Z",\
630 | "fields": {\
631 | "Address": "333 Post St",\
632 | "Name": "Union Square",\
633 | "Visited": true\
634 | },\
635 | "id": "rec560UJdUtocSouk"\
636 | },\
637 | {\
638 | "createdTime": "2022-09-12T21:03:48.000Z",\
639 | "fields": {\
640 | "Address": "1 Ferry Building",\
641 | "Name": "Ferry Building"\
642 | },\
643 | "id": "rec3lbPRG4aVqkeOQ"\
644 | }\
645 | ]
646 | }
647 | ```
648 |
649 | Records
650 |
651 | # Get record
652 |
653 | get `https://api.airtable.com/v0/{baseId}/{tableIdOrName}/{recordId}`
654 |
655 | Retrieve a single record. Any "empty" fields (e.g. **""**, **\[\]**, or **false**) in the record will not be returned.
656 |
657 | [§](/developers/web/api/get-record#requirements)
658 |
659 | ### Requirements
660 |
661 | | | |
662 | | --- | --- |
663 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
664 | | Scope | [`data.records:read`](https://airtable.com/developers/web/api/scopes#data-records-read) |
665 | | User role | Base read-only |
666 | | Billing plans | All plans |
667 |
668 | [§](/developers/web/api/get-record#path)
669 |
670 | ### Path parameters
671 |
672 | ``
673 |
674 | | | |
675 | | --- | --- |
676 | | [§](/developers/web/api/get-record#path-baseid)`baseId` | `string` |
677 | | [§](/developers/web/api/get-record#path-tableidorname)`tableIdOrName` | `string` |
678 | | [§](/developers/web/api/get-record#path-recordid)`recordId` | `string` |
679 |
680 | [§](/developers/web/api/get-record#query)
681 |
682 | ### Query parameters
683 |
684 | ``
685 |
686 | | | |
687 | | --- | --- |
688 | | [§](/developers/web/api/get-record#query-cellformat)`cellFormat` | `optional<``"json" | "string"` `>` <br>The format that should be used for cell values. Supported values are:<br>- `json:` cells will be formatted as JSON, depending on the field type.<br>- `string:` cells will be formatted as user-facing strings, regardless of the field type. The `timeZone` and `userLocale` parameters are required when using `string` as the `cellFormat`.<br>**Note:** You should not rely on the format of these strings, as it is subject to change.<br>The default is `json`. |
689 | | [§](/developers/web/api/get-record#query-returnfieldsbyfieldid)`returnFieldsByFieldId` | `optional<` `boolean` `>` <br>An optional boolean value that lets you return field objects where the key is the field id.<br>This defaults to `false`, which returns field objects where the key is the field name. |
690 |
691 | [§](/developers/web/api/get-record#response)
692 |
693 | ### Response format
694 |
695 | ``
696 |
697 | | | |
698 | | --- | --- |
699 | | [§](/developers/web/api/get-record#response-id)`id` | `string` <br>Record ID |
700 | | [§](/developers/web/api/get-record#response-createdtime)`createdTime` | `string` <br>A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z" |
701 | | [§](/developers/web/api/get-record#response-fields)`fields` | `object`
702 |
703 | Cell values are keyed by either field name or field ID (conditioned on `returnFieldsByFieldId`).
704 |
705 | See [Cell Values](/developers/web/api/field-model) for more information on cell value response types.
706 |
707 | | | |
708 | | --- | --- |
709 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | |
710 |
711 | Request (example)
712 |
713 | Copy
714 |
715 | ```
716 |
717 | $
718 | curl "https://api.airtable.com/v0/{baseId}/{tableIdOrName}/{recordId}" \
719 | -H "Authorization: Bearer YOUR_TOKEN"
720 | ```
721 |
722 | 200 – Response (example)
723 |
724 | ```
725 |
726 | {
727 | "createdTime": "2022-09-12T21:03:48.000Z",
728 | "fields": {
729 | "Address": "333 Post St",
730 | "Name": "Union Square",
731 | "Visited": true
732 | },
733 | "id": "rec560UJdUtocSouk"
734 | }
735 | ```
736 |
737 | Records
738 |
739 | # Update multiple records
740 |
741 | patchput `https://api.airtable.com/v0/{baseId}/{tableIdOrName}`
742 |
743 | Updates up to 10 records, or upserts them when `performUpsert` is set (see below).
744 |
745 | The URL path accepts both table names and table IDs. We recommend using table IDs so you don't need to modify
746 | your API request when your table name changes.
747 |
748 | A `PATCH` request will only update the fields included in the request. Fields not included in the request will be unchanged.
749 | A `PUT` request will perform a destructive update and clear all unincluded cell values.
750 |
751 | ### [§](/developers/web/api/update-multiple-records\#upserts) Upserts
752 |
753 | Set the `performUpsert` property in your request to enable upsert behavior. When upserting is enabled, the `id` property
754 | of records becomes optional. Records that do not include `id` will use the fields chosen by [`fieldsToMergeOn`](/developers/web/api/update-multiple-records#request-performupsert-fieldstomergeon)
755 | as an external ID to match with existing records.
756 |
757 | - If zero matches are found, a new record will be created.
758 | - If one match is found, that record will be updated.
759 | - If multiple matches are found, the request will fail.
760 |
761 | Records that include `id` will ignore `fieldsToMergeOn` and behave as normal updates. If no record with the given `id` exists,
762 | the request will fail and will not create a new record.
763 | The API response for upsert requests will additionally include `updatedRecords` and `createdRecords` arrays, indicating which records
764 | in the `records` array already existed and were updated, or did not exist and were created, respectively.
765 |
766 | Airtable reserves the right to throttle upsert requests differently from the [standard rate limit throttling policy](https://airtable.com/developers/web/api/rate-limits).
767 |
768 | ### [§](/developers/web/api/update-multiple-records\#typecasting) Typecasting
769 |
770 | Set the `typecast` parameter to `true` to enable typecasting. When typecasting is enabled, Airtable will try to convert string values
771 | in a record's `fields` object to the appropriate cell value. This conversion is only performed on a best-effort basis.
772 | Typecasting is disabled by default to ensure your data's integrity, but it may be helpful when integrating with third-party services.
773 |
774 | [§](/developers/web/api/update-multiple-records#requirements)
775 |
776 | ### Requirements
777 |
778 | | | |
779 | | --- | --- |
780 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
781 | | Scope | [`data.records:write`](https://airtable.com/developers/web/api/scopes#data-records-write) |
782 | | User role | Base editor |
783 | | Billing plans | All plans |
784 |
785 | [§](/developers/web/api/update-multiple-records#path)
786 |
787 | ### Path parameters
788 |
789 | ``
790 |
791 | | | |
792 | | --- | --- |
793 | | [§](/developers/web/api/update-multiple-records#path-baseid)`baseId` | `string` |
794 | | [§](/developers/web/api/update-multiple-records#path-tableidorname)`tableIdOrName` | `string` |
795 |
796 | [§](/developers/web/api/update-multiple-records#request)
797 |
798 | ### Request body
799 |
800 | ``
801 |
802 | | | |
803 | | --- | --- |
804 | | [§](/developers/web/api/update-multiple-records#request-performupsert)`performUpsert` | `optional<` `the below object` `>`
805 |
806 | Enables upsert behavior when set.
807 |
808 | **fieldsToMergeOn** will be used as an external ID to match records for updates. For records
809 | where no match is found, a new Airtable record will be created.
810 |
811 | ``
812 |
813 | | | |
814 | | --- | --- |
815 | | [§](/developers/web/api/update-multiple-records#request-performupsert-fieldstomergeon)`fieldsToMergeOn` | `array of strings` <br>An array with at least one and at most three field names or IDs. IDs must uniquely identify<br>a single record. These cannot be computed fields (formulas, lookups, rollups), and must be<br>one of the following types: number, text, long text, single select, multiple select, date. | |
816 | | [§](/developers/web/api/update-multiple-records#request-returnfieldsbyfieldid)`returnFieldsByFieldId` | `optional<` `boolean` `>` <br>If set to `true`, records in the API response will key the **fields** object by field ID.<br>Defaults to `false` when unset, which returns **fields** objects keyed by field name. |
817 | | [§](/developers/web/api/update-multiple-records#request-typecast)`typecast` | `optional<` `boolean` `>` <br>If set to `true`, Airtable will try to convert string values into the appropriate<br>cell value. This conversion is only performed on a best-effort basis. To ensure your data's<br>integrity, this should only be used when necessary.<br>Defaults to `false` when unset. |
818 | | [§](/developers/web/api/update-multiple-records#request-records)`records` | `array of the below object` ``
819 |
820 | | | |
821 | | --- | --- |
822 | | [§](/developers/web/api/update-multiple-records#request-records-id)`id` | `optional<` `string` `>` <br>The ID of the record to update. Required when **performUpsert** is undefined. |
823 | | [§](/developers/web/api/update-multiple-records#request-records-fields)`fields` | `object`
824 |
825 | | | |
826 | | --- | --- |
827 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | | |
828 |
829 | [§](/developers/web/api/update-multiple-records#response)
830 |
831 | ### Response format
832 |
833 | `any of the below objects`
834 |
835 | * * *
836 |
837 | ``
838 |
839 | | | |
840 | | --- | --- |
841 | | [§](/developers/web/api/update-multiple-records#response-multiple-0-records)`records` | `array of the below object` ``
842 |
843 | | | |
844 | | --- | --- |
845 | | [§](/developers/web/api/update-multiple-records#response-multiple-0-records-id)`id` | `string` <br>Record ID |
846 | | [§](/developers/web/api/update-multiple-records#response-multiple-0-records-createdtime)`createdTime` | `string` <br>A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z" |
847 | | [§](/developers/web/api/update-multiple-records#response-multiple-0-records-fields)`fields` | `object`
848 |
849 | Cell values are keyed by either field name or field ID (conditioned on `returnFieldsByFieldId`).
850 |
851 | See [Cell Values](/developers/web/api/field-model) for more information on cell value response types.
852 |
853 | | | |
854 | | --- | --- |
855 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | | |
856 |
857 | * * *
858 |
859 | ``
860 |
861 | | | |
862 | | --- | --- |
863 | | [§](/developers/web/api/update-multiple-records#response-multiple-1-createdrecords)`createdRecords` | `array of strings` <br>Record IDs of records created by the upsert request. |
864 | | [§](/developers/web/api/update-multiple-records#response-multiple-1-updatedrecords)`updatedRecords` | `array of strings` <br>Record IDs of existing records modified by the upsert request. |
865 | | [§](/developers/web/api/update-multiple-records#response-multiple-1-records)`records` | `array of the below object` ``
866 |
867 | | | |
868 | | --- | --- |
869 | | [§](/developers/web/api/update-multiple-records#response-multiple-1-records-id)`id` | `string` <br>Record ID |
870 | | [§](/developers/web/api/update-multiple-records#response-multiple-1-records-createdtime)`createdTime` | `string` <br>A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z" |
871 | | [§](/developers/web/api/update-multiple-records#response-multiple-1-records-fields)`fields` | `object`
872 |
873 | Cell values are keyed by either field name or field ID (conditioned on `returnFieldsByFieldId`).
874 |
875 | See [Cell Values](/developers/web/api/field-model) for more information on cell value response types.
876 |
877 | | | |
878 | | --- | --- |
879 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | | |
880 |
881 | Request (example)
882 |
883 | Copy
884 |
885 | ```
886 |
887 | $
888 | curl -X PATCH "https://api.airtable.com/v0/{baseId}/{tableIdOrName}" \
889 | -H "Authorization: Bearer YOUR_TOKEN" \
890 | -H "Content-Type: application/json" \
891 | --data '{
892 | "records": [\
893 | {\
894 | "fields": {\
895 | "Address": "501 Twin Peaks Blvd",\
896 | "Name": "Twin Peaks",\
897 | "Visited": true\
898 | },\
899 | "id": "rec560UJdUtocSouk"\
900 | },\
901 | {\
902 | "fields": {\
903 | "Visited": true\
904 | },\
905 | "id": "rec3lbPRG4aVqkeOQ"\
906 | }\
907 | ]
908 | }'
909 | ```
910 |
911 | 200 – Response (example)
912 |
913 | ```
914 |
915 | {
916 | "records": [\
917 | {\
918 | "createdTime": "2022-09-12T21:03:48.000Z",\
919 | "fields": {\
920 | "Address": "501 Twin Peaks Blvd",\
921 | "Name": "Twin Peaks",\
922 | "Visited": true\
923 | },\
924 | "id": "rec560UJdUtocSouk"\
925 | },\
926 | {\
927 | "createdTime": "2022-09-12T21:03:48.000Z",\
928 | "fields": {\
929 | "Address": "1 Ferry Building",\
930 | "Name": "Ferry Building",\
931 | "Visited": true\
932 | },\
933 | "id": "rec3lbPRG4aVqkeOQ"\
934 | }\
935 | ]
936 | }
937 | ```
938 |
939 | Request (example)
940 |
941 | Copy
942 |
943 | ```
944 |
945 | $
946 | curl -X PATCH "https://api.airtable.com/v0/{baseId}/{tableIdOrName}" \
947 | -H "Authorization: Bearer YOUR_TOKEN" \
948 | -H "Content-Type: application/json" \
949 | --data '{
950 | "performUpsert": {
951 | "fieldsToMergeOn": [\
952 | "Name"\
953 | ]
954 | },
955 | "records": [\
956 | {\
957 | "fields": {\
958 | "Address": "501 Twin Peaks Blvd",\
959 | "Name": "Twin Peaks",\
960 | "Visited": true\
961 | }\
962 | },\
963 | {\
964 | "fields": {\
965 | "Name": "New Park",\
966 | "Visited": true\
967 | }\
968 | }\
969 | ]
970 | }'
971 | ```
972 |
973 | 200 – Response (example)
974 |
975 | ```
976 |
977 | {
978 | "createdRecords": [\
979 | "recsHMqsp3GEm3lEi"\
980 | ],
981 | "records": [\
982 | {\
983 | "createdTime": "2022-09-12T21:03:48.000Z",\
984 | "fields": {\
985 | "Address": "501 Twin Peaks Blvd",\
986 | "Name": "Twin Peaks",\
987 | "Visited": true\
988 | },\
989 | "id": "rec560UJdUtocSouk"\
990 | },\
991 | {\
992 | "createdTime": "2022-11-15T01:02:04.400Z",\
993 | "fields": {\
994 | "Name": "New Park",\
995 | "Visited": true\
996 | },\
997 | "id": "recsHMqsp3GEm3lEi"\
998 | }\
999 | ],
1000 | "updatedRecords": [\
1001 | "rec560UJdUtocSouk"\
1002 | ]
1003 | }
1004 | ```
1005 |
1006 | Records
1007 |
1008 | # Update record
1009 |
1010 | patchput `https://api.airtable.com/v0/{baseId}/{tableIdOrName}/{recordId}`
1011 |
1012 | Updates a single record. Table names and table ids can be used interchangeably.
1013 | We recommend using table IDs so you don't need to modify your API request when your table name changes.
1014 | A **PATCH** request will only update the fields you specify, leaving the rest as they were.
1015 | A **PUT** request will perform a destructive update and clear all unspecified cell values.
1016 |
1017 | Your request body should include a **fields** property whose value is an object containing your record's cell values, keyed by either field name or field id.
1018 |
1019 | Automatic data conversion for update actions can be enabled via **typecast** parameter. The Airtable API will perform best-effort automatic data conversion
1020 | from string values if the **typecast** parameter is passed in. Automatic conversion is disabled by default to ensure data integrity,
1021 | but it may be helpful for integrating with 3rd party data sources.
1022 |
1023 | [§](/developers/web/api/update-record#requirements)
1024 |
1025 | ### Requirements
1026 |
1027 | | | |
1028 | | --- | --- |
1029 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
1030 | | Scope | [`data.records:write`](https://airtable.com/developers/web/api/scopes#data-records-write) |
1031 | | User role | Base editor |
1032 | | Billing plans | All plans |
1033 |
1034 | [§](/developers/web/api/update-record#path)
1035 |
1036 | ### Path parameters
1037 |
1038 | ``
1039 |
1040 | | | |
1041 | | --- | --- |
1042 | | [§](/developers/web/api/update-record#path-baseid)`baseId` | `string` |
1043 | | [§](/developers/web/api/update-record#path-tableidorname)`tableIdOrName` | `string` |
1044 | | [§](/developers/web/api/update-record#path-recordid)`recordId` | `string` |
1045 |
1046 | [§](/developers/web/api/update-record#request)
1047 |
1048 | ### Request body
1049 |
1050 | ``
1051 |
1052 | | | |
1053 | | --- | --- |
1054 | | [§](/developers/web/api/update-record#request-returnfieldsbyfieldid)`returnFieldsByFieldId` | `optional<` `boolean` `>` <br>An optional boolean value that lets you return field objects keyed by the field id.<br>This defaults to `false`, which returns field objects where the key is the field name. |
1055 | | [§](/developers/web/api/update-record#request-typecast)`typecast` | `optional<` `boolean` `>` <br>The Airtable API will perform best-effort automatic data conversion from string values<br>if the typecast parameter is passed in. Automatic conversion is disabled by default to<br>ensure data integrity, but it may be helpful for integrating with 3rd party data sources. |
1056 | | [§](/developers/web/api/update-record#request-fields)`fields` | `object`
1057 |
1058 | | | |
1059 | | --- | --- |
1060 | | `key: string` | `any` | |
1061 |
1062 | [§](/developers/web/api/update-record#response)
1063 |
1064 | ### Response format
1065 |
1066 | ``
1067 |
1068 | | | |
1069 | | --- | --- |
1070 | | [§](/developers/web/api/update-record#response-id)`id` | `string` <br>Record ID |
1071 | | [§](/developers/web/api/update-record#response-createdtime)`createdTime` | `string` <br>A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z" |
1072 | | [§](/developers/web/api/update-record#response-fields)`fields` | `object`
1073 |
1074 | Cell values are keyed by either field name or field ID (conditioned on `returnFieldsByFieldId`).
1075 |
1076 | See [Cell Values](/developers/web/api/field-model) for more information on cell value response types.
1077 |
1078 | | | |
1079 | | --- | --- |
1080 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | |
1081 |
1082 | Request (example)
1083 |
1084 | Copy
1085 |
1086 | ```
1087 |
1088 | $
1089 | curl -X PATCH "https://api.airtable.com/v0/{baseId}/{tableIdOrName}/{recordId}" \
1090 | -H "Authorization: Bearer YOUR_TOKEN" \
1091 | -H "Content-Type: application/json" \
1092 | --data '{
1093 | "fields": {
1094 | "Address": "1 Ferry Building",
1095 | "Name": "Ferry Building",
1096 | "Visited": true
1097 | }
1098 | }'
1099 | ```
1100 |
1101 | 200 – Response (example)
1102 |
1103 | ```
1104 |
1105 | {
1106 | "createdTime": "2022-09-12T21:03:48.000Z",
1107 | "fields": {
1108 | "Address": "1 Ferry Building",
1109 | "Name": "Ferry Building",
1110 | "Visited": true
1111 | },
1112 | "id": "rec3lbPRG4aVqkeOQ"
1113 | }
1114 | ```
1115 |
1116 | Records
1117 |
1118 | # Create records
1119 |
1120 | post `https://api.airtable.com/v0/{baseId}/{tableIdOrName}`
1121 |
1122 | Creates multiple records. Note that table names and table ids can be used interchangeably.
1123 | We recommend using table IDs so you don't need to modify your API request when your table name changes.
1124 |
1125 | Your request body should include an array of up to 10 record objects. Each of these objects should have one key
1126 | whose value is an inner object containing your record's cell values, keyed by either field name or field id.
1127 |
1128 | Returns a unique array of the newly created record ids if the call succeeds.
1129 |
1130 | You can also include a single record object at the top level.
1131 |
1132 | [§](/developers/web/api/create-records#requirements)
1133 |
1134 | ### Requirements
1135 |
1136 | | | |
1137 | | --- | --- |
1138 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
1139 | | Scope | [`data.records:write`](https://airtable.com/developers/web/api/scopes#data-records-write) |
1140 | | User role | Base editor |
1141 | | Billing plans | All plans |
1142 |
1143 | [§](/developers/web/api/create-records#path)
1144 |
1145 | ### Path parameters
1146 |
1147 | ``
1148 |
1149 | | | |
1150 | | --- | --- |
1151 | | [§](/developers/web/api/create-records#path-baseid)`baseId` | `string` |
1152 | | [§](/developers/web/api/create-records#path-tableidorname)`tableIdOrName` | `string` |
1153 |
1154 | [§](/developers/web/api/create-records#request)
1155 |
1156 | ### Request body
1157 |
1158 | ``
1159 |
1160 | | | |
1161 | | --- | --- |
1162 | | [§](/developers/web/api/create-records#request-fields)`fields` | `optional<` `the below object` `>`
1163 |
1164 | Create **a single** record
1165 |
1166 | ``
1167 |
1168 | | | |
1169 | | --- | --- |
1170 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | |
1171 | | [§](/developers/web/api/create-records#request-records)`records` | `optional<` `array of the below object` `>`
1172 |
1173 | Create **multiple** records
1174 |
1175 | Pass in multiple records to create multiple in one request
1176 |
1177 | ``
1178 |
1179 | | | |
1180 | | --- | --- |
1181 | | [§](/developers/web/api/create-records#request-records-fields)`fields` | `object`
1182 |
1183 | | | |
1184 | | --- | --- |
1185 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | | |
1186 | | [§](/developers/web/api/create-records#request-returnfieldsbyfieldid)`returnFieldsByFieldId` | `optional<` `boolean` `>` <br>An optional boolean value that lets you return field objects keyed by the field id.<br>This defaults to `false`, which returns field objects where the key is the field name. |
1187 | | [§](/developers/web/api/create-records#request-typecast)`typecast` | `optional<` `boolean` `>` <br>The Airtable API will perform best-effort automatic data conversion from string values<br>if the typecast parameter is passed in. Automatic conversion is disabled by default to<br>ensure data integrity, but it may be helpful for integrating with 3rd party data sources. |
1188 |
1189 | [§](/developers/web/api/create-records#response)
1190 |
1191 | ### Response format
1192 |
1193 | `any of the below objects`
1194 |
1195 | * * *
1196 |
1197 | ``
1198 |
1199 | | | |
1200 | | --- | --- |
1201 | | [§](/developers/web/api/create-records#response-multiple-0-records)`records` | `array of the below object` ``
1202 |
1203 | | | |
1204 | | --- | --- |
1205 | | [§](/developers/web/api/create-records#response-multiple-0-records-id)`id` | `string` <br>Record ID |
1206 | | [§](/developers/web/api/create-records#response-multiple-0-records-createdtime)`createdTime` | `string` <br>A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z" |
1207 | | [§](/developers/web/api/create-records#response-multiple-0-records-fields)`fields` | `object`
1208 |
1209 | Cell values are keyed by either field name or field ID (conditioned on `returnFieldsByFieldId`).
1210 |
1211 | See [Cell Values](/developers/web/api/field-model) for more information on cell value response types.
1212 |
1213 | | | |
1214 | | --- | --- |
1215 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | | |
1216 |
1217 | * * *
1218 |
1219 | ``
1220 |
1221 | | | |
1222 | | --- | --- |
1223 | | [§](/developers/web/api/create-records#response-multiple-1-id)`id` | `string` <br>Record ID |
1224 | | [§](/developers/web/api/create-records#response-multiple-1-createdtime)`createdTime` | `string` <br>A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z" |
1225 | | [§](/developers/web/api/create-records#response-multiple-1-fields)`fields` | `object`
1226 |
1227 | Cell values are keyed by either field name or field ID (conditioned on `returnFieldsByFieldId`).
1228 |
1229 | See [Cell Values](/developers/web/api/field-model) for more information on cell value response types.
1230 |
1231 | | | |
1232 | | --- | --- |
1233 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | |
1234 |
1235 | Request (example)
1236 |
1237 | Copy
1238 |
1239 | ```
1240 |
1241 | $
1242 | curl -X POST "https://api.airtable.com/v0/{baseId}/{tableIdOrName}" \
1243 | -H "Authorization: Bearer YOUR_TOKEN" \
1244 | -H "Content-Type: application/json" \
1245 | --data '{
1246 | "records": [\
1247 | {\
1248 | "fields": {\
1249 | "Address": "333 Post St",\
1250 | "Name": "Union Square",\
1251 | "Visited": true\
1252 | }\
1253 | },\
1254 | {\
1255 | "fields": {\
1256 | "Address": "1 Ferry Building",\
1257 | "Name": "Ferry Building"\
1258 | }\
1259 | }\
1260 | ]
1261 | }'
1262 | ```
1263 |
1264 | 200 – Response (example)
1265 |
1266 | ```
1267 |
1268 | {
1269 | "records": [\
1270 | {\
1271 | "createdTime": "2022-09-12T21:03:48.000Z",\
1272 | "fields": {\
1273 | "Address": "333 Post St",\
1274 | "Name": "Union Square",\
1275 | "Visited": true\
1276 | },\
1277 | "id": "rec560UJdUtocSouk"\
1278 | },\
1279 | {\
1280 | "createdTime": "2022-09-12T21:03:48.000Z",\
1281 | "fields": {\
1282 | "Address": "1 Ferry Building",\
1283 | "Name": "Ferry Building"\
1284 | },\
1285 | "id": "rec3lbPRG4aVqkeOQ"\
1286 | }\
1287 | ]
1288 | }
1289 | ```
1290 |
1291 | Request (example)
1292 |
1293 | Copy
1294 |
1295 | ```
1296 |
1297 | $
1298 | curl -X POST "https://api.airtable.com/v0/{baseId}/{tableIdOrName}" \
1299 | -H "Authorization: Bearer YOUR_TOKEN" \
1300 | -H "Content-Type: application/json" \
1301 | --data '{
1302 | "fields": {
1303 | "Address": "333 Post St",
1304 | "Name": "Union Square",
1305 | "Visited": true
1306 | }
1307 | }'
1308 | ```
1309 |
1310 | 200 – Response (example)
1311 |
1312 | ```
1313 |
1314 | {
1315 | "createdTime": "2022-09-12T21:03:48.000Z",
1316 | "fields": {
1317 | "Address": "333 Post St",
1318 | "Name": "Union Square",
1319 | "Visited": true
1320 | },
1321 | "id": "rec560UJdUtocSouk"
1322 | }
1323 | ```
1324 |
1325 | Records
1326 |
1327 | # Delete multiple records
1328 |
1329 | delete `https://api.airtable.com/v0/{baseId}/{tableIdOrName}`
1330 |
1331 | Deletes records given an array of record ids
1332 |
1333 | [§](/developers/web/api/delete-multiple-records#requirements)
1334 |
1335 | ### Requirements
1336 |
1337 | | | |
1338 | | --- | --- |
1339 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
1340 | | Scope | [`data.records:write`](https://airtable.com/developers/web/api/scopes#data-records-write) |
1341 | | User role | Base editor |
1342 | | Billing plans | All plans |
1343 |
1344 | [§](/developers/web/api/delete-multiple-records#path)
1345 |
1346 | ### Path parameters
1347 |
1348 | ``
1349 |
1350 | | | |
1351 | | --- | --- |
1352 | | [§](/developers/web/api/delete-multiple-records#path-baseid)`baseId` | `string` |
1353 | | [§](/developers/web/api/delete-multiple-records#path-tableidorname)`tableIdOrName` | `string` |
1354 |
1355 | [§](/developers/web/api/delete-multiple-records#query)
1356 |
1357 | ### Query parameters
1358 |
1359 | ``
1360 |
1361 | | | |
1362 | | --- | --- |
1363 | | [§](/developers/web/api/delete-multiple-records#query-records)`records` | `optional<` `array of strings` `>` <br>The recordIds of each record to be deleted. Up to 10 recordIds can be provided. |
1364 |
1365 | [§](/developers/web/api/delete-multiple-records#response)
1366 |
1367 | ### Response format
1368 |
1369 | ``
1370 |
1371 | | | |
1372 | | --- | --- |
1373 | | [§](/developers/web/api/delete-multiple-records#response-records)`records` | `array of the below object` ``
1374 |
1375 | | | |
1376 | | --- | --- |
1377 | | [§](/developers/web/api/delete-multiple-records#response-records-id)`id` | `string` <br>Record ID |
1378 | | [§](/developers/web/api/delete-multiple-records#response-records-deleted)`deleted` | `true` | |
1379 |
1380 | Request (example)
1381 |
1382 | Copy
1383 |
1384 | ```
1385 |
1386 | $
1387 | curl -X DELETE "https://api.airtable.com/v0/{baseId}/{tableIdOrName}\
1388 | ?records[]=rec560UJdUtocSouk&records[]=rec3lbPRG4aVqkeOQ" \
1389 | -H "Authorization: Bearer YOUR_TOKEN"
1390 | ```
1391 |
1392 | 200 – Response (example)
1393 |
1394 | ```
1395 |
1396 | {
1397 | "records": [\
1398 | {\
1399 | "deleted": true,\
1400 | "id": "rec560UJdUtocSouk"\
1401 | },\
1402 | {\
1403 | "deleted": true,\
1404 | "id": "rec3lbPRG4aVqkeOQ"\
1405 | }\
1406 | ]
1407 | }
1408 | ```
1409 |
1410 | Records
1411 |
1412 | # Delete record
1413 |
1414 | delete `https://api.airtable.com/v0/{baseId}/{tableIdOrName}/{recordId}`
1415 |
1416 | Deletes a single record
1417 |
1418 | [§](/developers/web/api/delete-record#requirements)
1419 |
1420 | ### Requirements
1421 |
1422 | | | |
1423 | | --- | --- |
1424 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
1425 | | Scope | [`data.records:write`](https://airtable.com/developers/web/api/scopes#data-records-write) |
1426 | | User role | Base editor |
1427 | | Billing plans | All plans |
1428 |
1429 | [§](/developers/web/api/delete-record#path)
1430 |
1431 | ### Path parameters
1432 |
1433 | ``
1434 |
1435 | | | |
1436 | | --- | --- |
1437 | | [§](/developers/web/api/delete-record#path-baseid)`baseId` | `string` |
1438 | | [§](/developers/web/api/delete-record#path-tableidorname)`tableIdOrName` | `string` |
1439 | | [§](/developers/web/api/delete-record#path-recordid)`recordId` | `string` |
1440 |
1441 | [§](/developers/web/api/delete-record#response)
1442 |
1443 | ### Response format
1444 |
1445 | ``
1446 |
1447 | | | |
1448 | | --- | --- |
1449 | | [§](/developers/web/api/delete-record#response-id)`id` | `string` <br>Record ID |
1450 | | [§](/developers/web/api/delete-record#response-deleted)`deleted` | `true` |
1451 |
1452 | Request (example)
1453 |
1454 | Copy
1455 |
1456 | ```
1457 |
1458 | $
1459 | curl -X DELETE "https://api.airtable.com/v0/{baseId}/{tableIdOrName}/{recordId}" \
1460 | -H "Authorization: Bearer YOUR_TOKEN"
1461 | ```
1462 |
1463 | 200 – Response (example)
1464 |
1465 | ```
1466 |
1467 | {
1468 | "deleted": true,
1469 | "id": "rec560UJdUtocSouk"
1470 | }
1471 | ```
1472 |
1473 | Records
1474 |
1475 | # Sync CSV data
1476 |
1477 | post `https://api.airtable.com/v0/{baseId}/{tableIdOrName}/sync/{apiEndpointSyncId}`
1478 |
1479 | Syncs raw CSV data into a Sync API table.
1480 | You must first set up a sync from a base (instructions in this [support article](https://support.airtable.com/docs/airtable-sync-integration-api-endpoint)).
1481 | The **apiEndpointSyncId** in the path parameters can be found in the setup flow when
1482 | creating a new Sync API table, or from the synced table settings.
1483 |
1484 | The CSV data can contain up to 10k rows, 500 columns, and the HTTP request's size is limited to 2 MB.
1485 |
1486 | There is a rate limit of 20 requests, per 5 minutes, per base for this endpoint.
1487 |
1488 | [§](/developers/web/api/post-sync-api-endpoint#requirements)
1489 |
1490 | ### Requirements
1491 |
1492 | | | |
1493 | | --- | --- |
1494 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token) |
1495 | | Scopes | [`data.records:write`](https://airtable.com/developers/web/api/scopes#data-records-write), [`schema.bases:write`](https://airtable.com/developers/web/api/scopes#schema-bases-write) |
1496 | | User role | Base creator |
1497 | | Billing plans | Pro, Enterprise (pre-2023.08 legacy plan), Enterprise Scale |
1498 |
1499 | [§](/developers/web/api/post-sync-api-endpoint#path)
1500 |
1501 | ### Path parameters
1502 |
1503 | ``
1504 |
1505 | | | |
1506 | | --- | --- |
1507 | | [§](/developers/web/api/post-sync-api-endpoint#path-baseid)`baseId` | `string` |
1508 | | [§](/developers/web/api/post-sync-api-endpoint#path-tableidorname)`tableIdOrName` | `string` |
1509 | | [§](/developers/web/api/post-sync-api-endpoint#path-apiendpointsyncid)`apiEndpointSyncId` | `string` |
1510 |
1511 | [§](/developers/web/api/post-sync-api-endpoint#response)
1512 |
1513 | ### Response format
1514 |
1515 | ``
1516 |
1517 | | | |
1518 | | --- | --- |
1519 | | [§](/developers/web/api/post-sync-api-endpoint#response-success)`success` | `true` |
1520 |
1521 | Request (example)
1522 |
1523 | Copy
1524 |
1525 | ```
1526 |
1527 | $
1528 | curl -X POST "https://api.airtable.com/v0/{baseId}/{tableIdOrName}/sync/{apiEndpointSyncId}" \
1529 | -H "Authorization: Bearer YOUR_TOKEN" \
1530 | -H "Content-Type: text/csv" \
1531 | --data 'column1,column2
1532 | row1-column1,row1-column2
1533 | row2-column1,row2-column2'
1534 | ```
1535 |
1536 | Records
1537 |
1538 | # Upload attachment
1539 |
1540 | post `https://content.airtable.com/v0/{baseId}/{recordId}/{attachmentFieldIdOrName}/uploadAttachment`
1541 |
1542 | Upload an attachment up to 5 MB to an attachment cell via the file bytes directly.
1543 |
1544 | To upload attachments above this size that are accessible by a public URL, they can be added using [https://airtable.com/developers/web/api/field-model#multipleattachment](https://airtable.com/developers/web/api/field-model#multipleattachment)
1545 |
1546 | [§](/developers/web/api/upload-attachment#requirements)
1547 |
1548 | ### Requirements
1549 |
1550 | | | |
1551 | | --- | --- |
1552 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
1553 | | Scope | [data.records:write](/developers/web/api/scopes#data-records-write) |
1554 | | User role | Base editor |
1555 | | Billing plans | All plans |
1556 |
1557 | [§](/developers/web/api/upload-attachment#path)
1558 |
1559 | ### Path parameters
1560 |
1561 | ``
1562 |
1563 | | | |
1564 | | --- | --- |
1565 | | [§](/developers/web/api/upload-attachment#path-baseid)`baseId` | `string` |
1566 | | [§](/developers/web/api/upload-attachment#path-recordid)`recordId` | `string` |
1567 | | [§](/developers/web/api/upload-attachment#path-attachmentfieldidorname)`attachmentFieldIdOrName` | `string` |
1568 |
1569 | [§](/developers/web/api/upload-attachment#request)
1570 |
1571 | ### Request body
1572 |
1573 | ``
1574 |
1575 | | | |
1576 | | --- | --- |
1577 | | [§](/developers/web/api/upload-attachment#request-contenttype)`contentType` | `string` <br>Content type, e.g. "image/jpeg" |
1578 | | [§](/developers/web/api/upload-attachment#request-file)`file` | `string` <br>The base64 encoded string of the file to be uploaded. |
1579 | | [§](/developers/web/api/upload-attachment#request-filename)`filename` | `string` <br>Filename, e.g. "foo.jpg" |
1580 |
1581 | [§](/developers/web/api/upload-attachment#response)
1582 |
1583 | ### Response format
1584 |
1585 | ``
1586 |
1587 | | | |
1588 | | --- | --- |
1589 | | [§](/developers/web/api/upload-attachment#response-id)`id` | `string` <br>Record ID |
1590 | | [§](/developers/web/api/upload-attachment#response-createdtime)`createdTime` | `string` <br>A date timestamp in the ISO format, eg:"2018-01-01T00:00:00.000Z" |
1591 | | [§](/developers/web/api/upload-attachment#response-fields)`fields` | `object`
1592 |
1593 | Cell values are keyed by field ID.
1594 |
1595 | See [Cell Values](/developers/web/api/field-model) for more information on cell value response types.
1596 |
1597 | | | |
1598 | | --- | --- |
1599 | | `key: string` | [`Cell value`](https://airtable.com/developers/web/api/field-model) | |
1600 |
1601 | Request (example)
1602 |
1603 | Copy
1604 |
1605 | ```
1606 |
1607 | $
1608 | curl -X POST "https://content.airtable.com/v0/{baseId}/{recordId}/{attachmentFieldIdOrName}/uploadAttachment" \
1609 | -H "Authorization: Bearer YOUR_TOKEN" \
1610 | -H "Content-Type: application/json" \
1611 | --data '{
1612 | "contentType": "text/plain",
1613 | "file": "SGVsbG8gd29ybGQ=",
1614 | "filename": "sample.txt"
1615 | }'
1616 | ```
1617 |
1618 | 200 – Response (example)
1619 |
1620 | ```
1621 |
1622 | {
1623 | "createdTime": "2022-02-01T21:25:05.663Z",
1624 | "fields": {
1625 | "fld00000000000000": [\
1626 | {\
1627 | "filename": "sample.txt",\
1628 | "id": "att00000000000000",\
1629 | "size": 11,\
1630 | "type": "text/plain",\
1631 | "url": "https://v5.airtableusercontent.com/v3/u/29/29/1716940800000/ffhiecnieIwxisnIBDSAln/foDeknw_G5CdkdPW1j-U0yUCX9YSaE1EJft3wvXb85pnTY1sKZdYeFvKpsM-fqOa6Bnu5MQVPA_ApINEUXL_E3SAZn6z01VN9Pn9SluhSy4NoakZGapcvl4tuN3jktO2Dt7Ck_gh4oMdsrcV8J-t_A/53m17XmDDHsNtIqzM1PQVnRKutK6damFgNNS5WCaTbI"\
1632 | }\
1633 | ]
1634 | },
1635 | "id": "rec00000000000000"
1636 | }
1637 | ```
1638 |
1639 | Bases
1640 |
1641 | # List bases
1642 |
1643 | get `https://api.airtable.com/v0/meta/bases`
1644 |
1645 | Returns the list of bases the token can access, 1000 bases at a time.
1646 | If there is another page to request, pass the offset as a URL query parameter.
1647 | (e.g. `?offset=itr23sEjsdfEr3282/appSW9R5uCNmRmfl6`)
1648 |
1649 | [§](https://airtable.com/developers/web/api/list-bases#requirements)
1650 |
1651 | ### Requirements
1652 |
1653 | | | |
1654 | | --- | --- |
1655 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
1656 | | Scope | [`schema.bases:read`](https://airtable.com/developers/web/api/scopes#schema-bases-read) |
1657 | | User role | Base read-only |
1658 | | Billing plans | All plans |
1659 |
1660 | [§](https://airtable.com/developers/web/api/list-bases#query)
1661 |
1662 | ### Query parameters
1663 |
1664 | ``
1665 |
1666 | | | |
1667 | | --- | --- |
1668 | | [§](https://airtable.com/developers/web/api/list-bases#query-offset)`offset` | `optional<` `string` `>` |
1669 |
1670 | [§](https://airtable.com/developers/web/api/list-bases#response)
1671 |
1672 | ### Response format
1673 |
1674 | ``
1675 |
1676 | | | |
1677 | | --- | --- |
1678 | | [§](https://airtable.com/developers/web/api/list-bases#response-offset)`offset` | `optional<` `string` `>` |
1679 | | [§](https://airtable.com/developers/web/api/list-bases#response-bases)`bases` | `array of the below object` ``
1680 |
1681 | | | |
1682 | | --- | --- |
1683 | | [§](https://airtable.com/developers/web/api/list-bases#response-bases-id)`id` | `string` <br>Base ID, a unique identifier for a base. |
1684 | | [§](https://airtable.com/developers/web/api/list-bases#response-bases-name)`name` | `string` |
1685 | | [§](https://airtable.com/developers/web/api/list-bases#response-bases-permissionlevel)`permissionLevel` | `"none" | "read" | "comment" | "edit" | "create"` | |
1686 |
1687 | Request (example)
1688 |
1689 | Copy
1690 |
1691 | ```
1692 |
1693 | $
1694 | curl "https://api.airtable.com/v0/meta/bases" \
1695 | -H "Authorization: Bearer YOUR_TOKEN"
1696 | ```
1697 |
1698 | 200 – Response (example)
1699 |
1700 | ```
1701 |
1702 | {
1703 | "bases": [\
1704 | {\
1705 | "id": "appLkNDICXNqxSDhG",\
1706 | "name": "Apartment Hunting",\
1707 | "permissionLevel": "create"\
1708 | },\
1709 | {\
1710 | "id": "appSW9R5uCNmRmfl6",\
1711 | "name": "Project Tracker",\
1712 | "permissionLevel": "edit"\
1713 | }\
1714 | ],
1715 | "offset": "itr23sEjsdfEr3282/appSW9R5uCNmRmfl6"
1716 | }
1717 | ```
1718 |
1719 | Bases
1720 |
1721 | # Get base schema
1722 |
1723 | get `https://api.airtable.com/v0/meta/bases/{baseId}/tables`
1724 |
1725 | Returns the schema of the tables in the specified base.
1726 |
1727 | [§](https://airtable.com/developers/web/api/get-base-schema#requirements)
1728 |
1729 | ### Requirements
1730 |
1731 | | | |
1732 | | --- | --- |
1733 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
1734 | | Scope | [`schema.bases:read`](https://airtable.com/developers/web/api/scopes#schema-bases-read) |
1735 | | User role | Base read-only |
1736 | | Billing plans | All plans |
1737 |
1738 | [§](https://airtable.com/developers/web/api/get-base-schema#path)
1739 |
1740 | ### Path parameters
1741 |
1742 | ``
1743 |
1744 | | | |
1745 | | --- | --- |
1746 | | [§](https://airtable.com/developers/web/api/get-base-schema#path-baseid)`baseId` | `string` |
1747 |
1748 | [§](https://airtable.com/developers/web/api/get-base-schema#query)
1749 |
1750 | ### Query parameters
1751 |
1752 | ``
1753 |
1754 | | | |
1755 | | --- | --- |
1756 | | [§](https://airtable.com/developers/web/api/get-base-schema#query-include)`include` | `optional<` `array of "visibleFieldIds"` `>` <br>If specified, additional fields to include in the `views` object response; currently, this list only allows a single literal value `visibleFieldIds` (for views of type `grid` only) |
1757 |
1758 | [§](https://airtable.com/developers/web/api/get-base-schema#response)
1759 |
1760 | ### Response format
1761 |
1762 | ``
1763 |
1764 | | | |
1765 | | --- | --- |
1766 | | [§](https://airtable.com/developers/web/api/get-base-schema#response-tables)`tables` | `array of Table models` |
1767 |
1768 | Request (example)
1769 |
1770 | Copy
1771 |
1772 | ```
1773 |
1774 | $
1775 | curl "https://api.airtable.com/v0/meta/bases/{baseId}/tables" \
1776 | -H "Authorization: Bearer YOUR_TOKEN"
1777 | ```
1778 |
1779 | 200 – Response (example)
1780 |
1781 | ```
1782 |
1783 | {
1784 | "tables": [\
1785 | {\
1786 | "description": "Apartments to track.",\
1787 | "fields": [\
1788 | {\
1789 | "description": "Name of the apartment",\
1790 | "id": "fld1VnoyuotSTyxW1",\
1791 | "name": "Name",\
1792 | "type": "singleLineText"\
1793 | },\
1794 | {\
1795 | "id": "fldoaIqdn5szURHpw",\
1796 | "name": "Pictures",\
1797 | "options": {\
1798 | "isReversed": false\
1799 | },\
1800 | "type": "multipleAttachments"\
1801 | },\
1802 | {\
1803 | "id": "fldumZe00w09RYTW6",\
1804 | "name": "District",\
1805 | "options": {\
1806 | "inverseLinkFieldId": "fldWnCJlo2z6ttT8Y",\
1807 | "isReversed": false,\
1808 | "linkedTableId": "tblK6MZHez0ZvBChZ",\
1809 | "prefersSingleRecordLink": true\
1810 | },\
1811 | "type": "multipleRecordLinks"\
1812 | }\
1813 | ],\
1814 | "id": "tbltp8DGLhqbUmjK1",\
1815 | "name": "Apartments",\
1816 | "primaryFieldId": "fld1VnoyuotSTyxW1",\
1817 | "views": [\
1818 | {\
1819 | "id": "viwQpsuEDqHFqegkp",\
1820 | "name": "Grid view",\
1821 | "type": "grid"\
1822 | }\
1823 | ]\
1824 | },\
1825 | {\
1826 | "fields": [\
1827 | {\
1828 | "id": "fldEVzvQOoULO38yl",\
1829 | "name": "Name",\
1830 | "type": "singleLineText"\
1831 | },\
1832 | {\
1833 | "description": "Apartments that belong to this district",\
1834 | "id": "fldWnCJlo2z6ttT8Y",\
1835 | "name": "Apartments",\
1836 | "options": {\
1837 | "inverseLinkFieldId": "fldumZe00w09RYTW6",\
1838 | "isReversed": false,\
1839 | "linkedTableId": "tbltp8DGLhqbUmjK1",\
1840 | "prefersSingleRecordLink": false\
1841 | },\
1842 | "type": "multipleRecordLinks"\
1843 | }\
1844 | ],\
1845 | "id": "tblK6MZHez0ZvBChZ",\
1846 | "name": "Districts",\
1847 | "primaryFieldId": "fldEVzvQOoULO38yl",\
1848 | "views": [\
1849 | {\
1850 | "id": "viwi3KXvrKug2mIBS",\
1851 | "name": "Grid view",\
1852 | "type": "grid"\
1853 | }\
1854 | ]\
1855 | }\
1856 | ]
1857 | }
1858 | ```
1859 |
1860 | # Update field
1861 |
1862 | patch `https://api.airtable.com/v0/meta/bases/{baseId}/tables/{tableId}/fields/{columnId}`
1863 |
1864 | Updates the name and/or description of a field. At least one of name or description must be specified.
1865 |
1866 | [§](https://airtable.com/developers/web/api/update-field#requirements)
1867 |
1868 | ### Requirements
1869 |
1870 | | | |
1871 | | --- | --- |
1872 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
1873 | | Scope | [`schema.bases:write`](https://airtable.com/developers/web/api/scopes#schema-bases-write) |
1874 | | User role | Base creator |
1875 | | Billing plans | All plans |
1876 |
1877 | [§](https://airtable.com/developers/web/api/update-field#path)
1878 |
1879 | ### Path parameters
1880 |
1881 | ``
1882 |
1883 | | | |
1884 | | --- | --- |
1885 | | [§](https://airtable.com/developers/web/api/update-field#path-baseid)`baseId` | `string` |
1886 | | [§](https://airtable.com/developers/web/api/update-field#path-tableid)`tableId` | `string` |
1887 | | [§](https://airtable.com/developers/web/api/update-field#path-columnid)`columnId` | `string` |
1888 |
1889 | [§](https://airtable.com/developers/web/api/update-field#request)
1890 |
1891 | ### Request body
1892 |
1893 | ``
1894 |
1895 | | | |
1896 | | --- | --- |
1897 | | [§](https://airtable.com/developers/web/api/update-field#request-description)`description` | `optional<` `string` `>` <br>The new description for the field (optional). If present, must be a string no longer than 20,000 characters. |
1898 | | [§](https://airtable.com/developers/web/api/update-field#request-name)`name` | `optional<` `string` `>` <br>The new name for the field (optional). |
1899 |
1900 | [§](https://airtable.com/developers/web/api/update-field#response)
1901 |
1902 | ### Response format
1903 |
1904 | ``
1905 |
1906 | | | |
1907 | | --- | --- |
1908 | | [§](https://airtable.com/developers/web/api/update-field#response-id)`id` | `string` |
1909 | | [§](https://airtable.com/developers/web/api/update-field#response-type)`type` | `optional<` [`Field Type`](https://airtable.com/developers/web/api/model/field-type) `>` |
1910 | | [§](https://airtable.com/developers/web/api/update-field#response-name)`name` | `string` |
1911 | | [§](https://airtable.com/developers/web/api/update-field#response-description)`description` | `optional<` `string` `>` |
1912 | | [§](https://airtable.com/developers/web/api/update-field#response-options)`options` | `optional<` [`Field options`](https://airtable.com/developers/web/api/field-model) `>` |
1913 |
1914 | Request (example)
1915 |
1916 | Copy
1917 |
1918 | ```
1919 |
1920 | $
1921 | curl -X PATCH "https://api.airtable.com/v0/meta/bases/{baseId}/tables/{tableId}/fields/{columnId}" \
1922 | -H "Authorization: Bearer YOUR_TOKEN" \
1923 | -H "Content-Type: application/json" \
1924 | --data '{
1925 | "description": "I was changed!",
1926 | "name": "Apartments (revised)"
1927 | }'
1928 | ```
1929 |
1930 | 200 – Response (example)
1931 |
1932 | ```
1933 |
1934 | {
1935 | "description": "I was changed!",
1936 | "id": "fldoi0c3GaRQJ3xnI",
1937 | "name": "Name (revised)",
1938 | "type": "singleLineText"
1939 | }
1940 | ```
1941 |
1942 |
1943 | # Create field
1944 |
1945 | post `https://api.airtable.com/v0/meta/bases/{baseId}/tables/{tableId}/fields`
1946 |
1947 | Creates a new column and returns the schema for the newly created column.
1948 |
1949 | Refer to field types for supported [field types](https://airtable.com/developers/web/api/model/field-type), the write format for field options, and other specifics for certain field types. Supported field types have a write format shown.
1950 |
1951 | [§](https://airtable.com/developers/web/api/create-field#requirements)
1952 |
1953 | ### Requirements
1954 |
1955 | | | |
1956 | | --- | --- |
1957 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
1958 | | Scope | [`schema.bases:write`](https://airtable.com/developers/web/api/scopes#schema-bases-write) |
1959 | | User role | Base creator |
1960 | | Billing plans | All plans |
1961 |
1962 | [§](https://airtable.com/developers/web/api/create-field#path)
1963 |
1964 | ### Path parameters
1965 |
1966 | ``
1967 |
1968 | | | |
1969 | | --- | --- |
1970 | | [§](https://airtable.com/developers/web/api/create-field#path-baseid)`baseId` | `string` |
1971 | | [§](https://airtable.com/developers/web/api/create-field#path-tableid)`tableId` | `string` |
1972 |
1973 | [§](https://airtable.com/developers/web/api/create-field#request)
1974 |
1975 | ### Request body
1976 |
1977 | [`Field model with name`](https://airtable.com/developers/web/api/field-model)
1978 |
1979 | This identical to Field type and options, with
1980 | an additional `name` and `description` property on all types
1981 |
1982 | [§](https://airtable.com/developers/web/api/create-field#response)
1983 |
1984 | ### Response format
1985 |
1986 | ``
1987 |
1988 | | | |
1989 | | --- | --- |
1990 | | [§](https://airtable.com/developers/web/api/create-field#response-id)`id` | `string` |
1991 | | [§](https://airtable.com/developers/web/api/create-field#response-type)`type` | `optional<` [`Field Type`](https://airtable.com/developers/web/api/model/field-type) `>` |
1992 | | [§](https://airtable.com/developers/web/api/create-field#response-name)`name` | `string` |
1993 | | [§](https://airtable.com/developers/web/api/create-field#response-description)`description` | `optional<` `string` `>` |
1994 | | [§](https://airtable.com/developers/web/api/create-field#response-options)`options` | `optional<` [`Field options`](https://airtable.com/developers/web/api/field-model) `>` |
1995 |
1996 | Request (example)
1997 |
1998 | Copy
1999 |
2000 | ```
2001 |
2002 | $
2003 | curl -X POST "https://api.airtable.com/v0/meta/bases/{baseId}/tables/{tableId}/fields" \
2004 | -H "Authorization: Bearer YOUR_TOKEN" \
2005 | -H "Content-Type: application/json" \
2006 | --data '{
2007 | "description": "Whether I have visited this apartment yet.",
2008 | "name": "Visited",
2009 | "options": {
2010 | "color": "greenBright",
2011 | "icon": "check"
2012 | },
2013 | "type": "checkbox"
2014 | }'
2015 | ```
2016 |
2017 | 200 – Response (example)
2018 |
2019 | ```
2020 |
2021 | {
2022 | "description": "Whether I have visited this apartment yet.",
2023 | "id": "fldumZe00w09RYTW6",
2024 | "name": "Visited",
2025 | "options": {
2026 | "color": "redBright",
2027 | "icon": "star"
2028 | },
2029 | "type": "checkbox"
2030 | }
2031 | ```
2032 |
2033 |
2034 | # List bases
2035 |
2036 | get `https://api.airtable.com/v0/meta/bases`
2037 |
2038 | Returns the list of bases the token can access, 1000 bases at a time.
2039 | If there is another page to request, pass the offset as a URL query parameter.
2040 | (e.g. `?offset=itr23sEjsdfEr3282/appSW9R5uCNmRmfl6`)
2041 |
2042 | [§](https://airtable.com/developers/web/api/list-bases#requirements)
2043 |
2044 | ### Requirements
2045 |
2046 | | | |
2047 | | --- | --- |
2048 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
2049 | | Scope | [`schema.bases:read`](https://airtable.com/developers/web/api/scopes#schema-bases-read) |
2050 | | User role | Base read-only |
2051 | | Billing plans | All plans |
2052 |
2053 | [§](https://airtable.com/developers/web/api/list-bases#query)
2054 |
2055 | ### Query parameters
2056 |
2057 | ``
2058 |
2059 | | | |
2060 | | --- | --- |
2061 | | [§](https://airtable.com/developers/web/api/list-bases#query-offset)`offset` | `optional<` `string` `>` |
2062 |
2063 | [§](https://airtable.com/developers/web/api/list-bases#response)
2064 |
2065 | ### Response format
2066 |
2067 | ``
2068 |
2069 | | | |
2070 | | --- | --- |
2071 | | [§](https://airtable.com/developers/web/api/list-bases#response-offset)`offset` | `optional<` `string` `>` |
2072 | | [§](https://airtable.com/developers/web/api/list-bases#response-bases)`bases` | `array of the below object` ``
2073 |
2074 | | | |
2075 | | --- | --- |
2076 | | [§](https://airtable.com/developers/web/api/list-bases#response-bases-id)`id` | `string` <br>Base ID, a unique identifier for a base. |
2077 | | [§](https://airtable.com/developers/web/api/list-bases#response-bases-name)`name` | `string` |
2078 | | [§](https://airtable.com/developers/web/api/list-bases#response-bases-permissionlevel)`permissionLevel` | `"none" | "read" | "comment" | "edit" | "create"` | |
2079 |
2080 | Request (example)
2081 |
2082 | Copy
2083 |
2084 | ```
2085 |
2086 | $
2087 | curl "https://api.airtable.com/v0/meta/bases" \
2088 | -H "Authorization: Bearer YOUR_TOKEN"
2089 | ```
2090 |
2091 | 200 – Response (example)
2092 |
2093 | ```
2094 |
2095 | {
2096 | "bases": [\
2097 | {\
2098 | "id": "appLkNDICXNqxSDhG",\
2099 | "name": "Apartment Hunting",\
2100 | "permissionLevel": "create"\
2101 | },\
2102 | {\
2103 | "id": "appSW9R5uCNmRmfl6",\
2104 | "name": "Project Tracker",\
2105 | "permissionLevel": "edit"\
2106 | }\
2107 | ],
2108 | "offset": "itr23sEjsdfEr3282/appSW9R5uCNmRmfl6"
2109 | }
2110 | ```
2111 |
2112 | # Get base schema
2113 |
2114 | get `https://api.airtable.com/v0/meta/bases/{baseId}/tables`
2115 |
2116 | Returns the schema of the tables in the specified base.
2117 |
2118 | [§](https://airtable.com/developers/web/api/get-base-schema#requirements)
2119 |
2120 | ### Requirements
2121 |
2122 | | | |
2123 | | --- | --- |
2124 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
2125 | | Scope | [`schema.bases:read`](https://airtable.com/developers/web/api/scopes#schema-bases-read) |
2126 | | User role | Base read-only |
2127 | | Billing plans | All plans |
2128 |
2129 | [§](https://airtable.com/developers/web/api/get-base-schema#path)
2130 |
2131 | ### Path parameters
2132 |
2133 | ``
2134 |
2135 | | | |
2136 | | --- | --- |
2137 | | [§](https://airtable.com/developers/web/api/get-base-schema#path-baseid)`baseId` | `string` |
2138 |
2139 | [§](https://airtable.com/developers/web/api/get-base-schema#query)
2140 |
2141 | ### Query parameters
2142 |
2143 | ``
2144 |
2145 | | | |
2146 | | --- | --- |
2147 | | [§](https://airtable.com/developers/web/api/get-base-schema#query-include)`include` | `optional<` `array of "visibleFieldIds"` `>` <br>If specified, additional fields to include in the `views` object response; currently, this list only allows a single literal value `visibleFieldIds` (for views of type `grid` only) |
2148 |
2149 | [§](https://airtable.com/developers/web/api/get-base-schema#response)
2150 |
2151 | ### Response format
2152 |
2153 | ``
2154 |
2155 | | | |
2156 | | --- | --- |
2157 | | [§](https://airtable.com/developers/web/api/get-base-schema#response-tables)`tables` | `array of Table models` |
2158 |
2159 | Request (example)
2160 |
2161 | Copy
2162 |
2163 | ```
2164 |
2165 | $
2166 | curl "https://api.airtable.com/v0/meta/bases/{baseId}/tables" \
2167 | -H "Authorization: Bearer YOUR_TOKEN"
2168 | ```
2169 |
2170 | 200 – Response (example)
2171 |
2172 | ```
2173 |
2174 | {
2175 | "tables": [\
2176 | {\
2177 | "description": "Apartments to track.",\
2178 | "fields": [\
2179 | {\
2180 | "description": "Name of the apartment",\
2181 | "id": "fld1VnoyuotSTyxW1",\
2182 | "name": "Name",\
2183 | "type": "singleLineText"\
2184 | },\
2185 | {\
2186 | "id": "fldoaIqdn5szURHpw",\
2187 | "name": "Pictures",\
2188 | "options": {\
2189 | "isReversed": false\
2190 | },\
2191 | "type": "multipleAttachments"\
2192 | },\
2193 | {\
2194 | "id": "fldumZe00w09RYTW6",\
2195 | "name": "District",\
2196 | "options": {\
2197 | "inverseLinkFieldId": "fldWnCJlo2z6ttT8Y",\
2198 | "isReversed": false,\
2199 | "linkedTableId": "tblK6MZHez0ZvBChZ",\
2200 | "prefersSingleRecordLink": true\
2201 | },\
2202 | "type": "multipleRecordLinks"\
2203 | }\
2204 | ],\
2205 | "id": "tbltp8DGLhqbUmjK1",\
2206 | "name": "Apartments",\
2207 | "primaryFieldId": "fld1VnoyuotSTyxW1",\
2208 | "views": [\
2209 | {\
2210 | "id": "viwQpsuEDqHFqegkp",\
2211 | "name": "Grid view",\
2212 | "type": "grid"\
2213 | }\
2214 | ]\
2215 | },\
2216 | {\
2217 | "fields": [\
2218 | {\
2219 | "id": "fldEVzvQOoULO38yl",\
2220 | "name": "Name",\
2221 | "type": "singleLineText"\
2222 | },\
2223 | {\
2224 | "description": "Apartments that belong to this district",\
2225 | "id": "fldWnCJlo2z6ttT8Y",\
2226 | "name": "Apartments",\
2227 | "options": {\
2228 | "inverseLinkFieldId": "fldumZe00w09RYTW6",\
2229 | "isReversed": false,\
2230 | "linkedTableId": "tbltp8DGLhqbUmjK1",\
2231 | "prefersSingleRecordLink": false\
2232 | },\
2233 | "type": "multipleRecordLinks"\
2234 | }\
2235 | ],\
2236 | "id": "tblK6MZHez0ZvBChZ",\
2237 | "name": "Districts",\
2238 | "primaryFieldId": "fldEVzvQOoULO38yl",\
2239 | "views": [\
2240 | {\
2241 | "id": "viwi3KXvrKug2mIBS",\
2242 | "name": "Grid view",\
2243 | "type": "grid"\
2244 | }\
2245 | ]\
2246 | }\
2247 | ]
2248 | }
2249 | ```
2250 |
2251 |
2252 | # Create base
2253 |
2254 | post `https://api.airtable.com/v0/meta/bases`
2255 |
2256 | Creates a new base with the provided tables and returns the schema for the newly created base.
2257 |
2258 | Refer to field types for supported field types, the write format for field options, and other specifics for certain field types. Supported field types have a write format shown.
2259 |
2260 | At least one table and field must be specified. The first field in the fields array will be used as the table's primary field and must be a supported primary field type. Fields must have case-insensitive unique names within the table.
2261 |
2262 | A default grid view will be created with all fields visible for each provided table.
2263 |
2264 | [§](https://airtable.com/developers/web/api/create-base#requirements)
2265 |
2266 | ### Requirements
2267 |
2268 | | | |
2269 | | --- | --- |
2270 | | Authentication | [Personal access token](https://airtable.com/developers/web/api/authentication#types-of-token), [OAuth integration](https://airtable.com/developers/web/api/authentication#types-of-token) |
2271 | | Scope | [`schema.bases:write`](https://airtable.com/developers/web/api/scopes#schema-bases-write) |
2272 | | User role | Workspace creator |
2273 | | Billing plans | All plans |
2274 |
2275 | [§](https://airtable.com/developers/web/api/create-base#request)
2276 |
2277 | ### Request body
2278 |
2279 | ``
2280 |
2281 | | | |
2282 | | --- | --- |
2283 | | [§](https://airtable.com/developers/web/api/create-base#request-name)`name` | `string` <br>The name for the new base. |
2284 | | [§](https://airtable.com/developers/web/api/create-base#request-workspaceid)`workspaceId` | `string` <br>The workspace where the base will be created. |
2285 | | [§](https://airtable.com/developers/web/api/create-base#request-tables)`tables` | `array of Table Configs` <br>A list of JSON objects representing<br>the tables that will be created along with the base. |
2286 |
2287 | [§](https://airtable.com/developers/web/api/create-base#response)
2288 |
2289 | ### Response format
2290 |
2291 | ``
2292 |
2293 | | | |
2294 | | --- | --- |
2295 | | [§](https://airtable.com/developers/web/api/create-base#response-id)`id` | `string` <br>Base ID, a unique identifier for a base. |
2296 | | [§](https://airtable.com/developers/web/api/create-base#response-tables)`tables` | `array of Table models` |
2297 |
2298 | Request (example)
2299 |
2300 | Copy
2301 |
2302 | ```
2303 |
2304 | $
2305 | curl -X POST "https://api.airtable.com/v0/meta/bases" \
2306 | -H "Authorization: Bearer YOUR_TOKEN" \
2307 | -H "Content-Type: application/json" \
2308 | --data '{
2309 | "name": "Apartment Hunting",
2310 | "tables": [\
2311 | {\
2312 | "description": "A to-do list of places to visit",\
2313 | "fields": [\
2314 | {\
2315 | "description": "Name of the apartment",\
2316 | "name": "Name",\
2317 | "type": "singleLineText"\
2318 | },\
2319 | {\
2320 | "name": "Address",\
2321 | "type": "singleLineText"\
2322 | },\
2323 | {\
2324 | "name": "Visited",\
2325 | "options": {\
2326 | "color": "greenBright",\
2327 | "icon": "check"\
2328 | },\
2329 | "type": "checkbox"\
2330 | }\
2331 | ],\
2332 | "name": "Apartments"\
2333 | }\
2334 | ],
2335 | "workspaceId": "wspmhESAta6clCCwF"
2336 | }'
2337 | ```
2338 |
2339 | 200 – Response (example)
2340 |
2341 | ```
2342 |
2343 | {
2344 | "id": "appLkNDICXNqxSDhG",
2345 | "tables": [\
2346 | {\
2347 | "description": "A to-do list of places to visit",\
2348 | "fields": [\
2349 | {\
2350 | "description": "Name of the apartment",\
2351 | "id": "fld1VnoyuotSTyxW1",\
2352 | "name": "Name",\
2353 | "type": "singleLineText"\
2354 | },\
2355 | {\
2356 | "id": "fldoi0c3GaRQJ3xnI",\
2357 | "name": "Address",\
2358 | "type": "singleLineText"\
2359 | },\
2360 | {\
2361 | "id": "fldumZe00w09RYTW6",\
2362 | "name": "Visited",\
2363 | "options": {\
2364 | "color": "redBright",\
2365 | "icon": "star"\
2366 | },\
2367 | "type": "checkbox"\
2368 | }\
2369 | ],\
2370 | "id": "tbltp8DGLhqbUmjK1",\
2371 | "name": "Apartments",\
2372 | "primaryFieldId": "fld1VnoyuotSTyxW1",\
2373 | "views": [\
2374 | {\
2375 | "id": "viwQpsuEDqHFqegkp",\
2376 | "name": "Grid view",\
2377 | "type": "grid"\
2378 | }\
2379 | ]\
2380 | }\
2381 | ]
2382 | }
2383 | ```
2384 |
2385 |
```