Introduction
# Airtable
Access the Airtable API with managed OAuth authentication. Manage bases, tables, and records with full CRUD operations.
## Quick Start
```bash # List records from a table python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/airtable/v0/{baseId}/{tableIdOrName}?maxRecords=100') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## Base URL
``` https://gateway.maton.ai/airtable/{native-api-path} ```
Replace `{native-api-path}` with the actual Airtable API endpoint path. The gateway proxies requests to `api.airtable.com` and automatically injects your OAuth token.
## Authentication
All requests require the Maton API key in the Authorization header:
``` Authorization: Bearer $MATON_API_KEY ```
**Environment Variable:** Set your API key as `MATON_API_KEY`:
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### Getting Your API Key
1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key
## Connection Management
Manage your Airtable OAuth connections at `https://ctrl.maton.ai`.
### List Connections
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=airtable&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Create Connection
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'airtable'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Get Connection
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "airtable", "metadata": {} } } ```
Open the returned `url` in a browser to complete OAuth authorization.
### Delete Connection
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Specifying Connection
If you have multiple Airtable connections, specify which one to use with the `Maton-Connection` header:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/airtable/v0/appXXXXX/TableName') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
If omitted, the gateway uses the default (oldest) active connection.
## API Reference
### List Bases
```bash GET /airtable/v0/meta/bases ```
### Get Base Schema
```bash GET /airtable/v0/meta/bases/{baseId}/tables ```
### List Records
```bash GET /airtable/v0/{baseId}/{tableIdOrName}?maxRecords=100 ```
With view:
```bash GET /airtable/v0/{baseId}/{tableIdOrName}?view=Grid%20view&maxRecords=100 ```
With filter formula:
```bash GET /airtable/v0/{baseId}/{tableIdOrName}?filterByFormula={Status}='Active' ```
With field selection:
```bash GET /airtable/v0/{baseId}/{tableIdOrName}?fields[]=Name&fields[]=Status&fields[]=Email ```
With sorting:
```bash GET /airtable/v0/{baseId}/{tableIdOrName}?sort[0][field]=Created&sort[0][direction]=desc ```
### Get Record
```bash GET /airtable/v0/{baseId}/{tableIdOrName}/{recordId} ```
### Create Records
```bash POST /airtable/v0/{baseId}/{tableIdOrName} Content-Type: application/json
{ "records": [ { "fields": { "Name": "New Record", "Status": "Active", "Email": "[email protected]" } } ] } ```
### Update Records (PATCH - partial update)
```bash PATCH /airtable/v0/{baseId}/{tableIdOrName} Content-Type: application/json
{ "records": [ { "id": "recXXXXXXXXXXXXXX", "fields": { "Status": "Completed" } } ] } ```
### Update Records (PUT - full replace)
```bash PUT /airtable/v0/{baseId}/{tableIdOrName} Content-Type: application/json
{ "records": [ { "id": "recXXXXXXXXXXXXXX", "fields": { "Name": "Updated Name", "Status": "Active" } } ] } ```
### Delete Records
```bash DELETE /airtable/v0/{baseId}/{tableIdOrName}?records[]=recXXXXX&records[]=recYYYYY ```
## Pagination
Use `pageSize` and `offset` for pagination:
```bash GET /airtable/v0/{baseId}/{tableIdOrName}?pageSize=50&offset=itrXXXXXXXXXXX ```
Response includes `offset` when more records exist:
```json { "records": [...], "offset": "itrXXXXXXXXXXX" } ```
## Code Examples
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/airtable/v0/appXXXXX/TableName?maxRecords=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/airtable/v0/appXXXXX/TableName', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'maxRecords': 10} ) ```
## Notes
- Base IDs start with `app` - Table IDs start with `tbl` (can also use table name) - Record IDs start with `rec` - Maximum 100 records per request for create/update - Maximum 10 records per delete request - Filter formulas use Airtable formula syntax - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping.
## Error Handling
| Status | Meaning | |--------|---------| | 400 | Missing Airtable connection | | 401 | Invalid or missing Maton API key | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from Airtable API |
### Troubleshooting: API Key Issues
1. Check that the `MATON_API_KEY` environment variable is set:
```bash echo $MATON_API_KEY ```
2. Verify the API key is valid by listing connections:
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### Troubleshooting: Invalid App Name
1. Ensure your URL path starts with `airtable`. For example:
- Correct: `https://gateway.maton.ai/airtable/v0/{baseId}/{tableIdOrName}` - Incorrect: `https://gateway.maton.ai/v0/{baseId}/{tableIdOrName}`
## Resources
- [Airtable API Overview](https://airtable.com/developers/web/api/introduction) - [List Records](https://airtable.com/developers/web/api/list-records) - [Create Records](https://airtable.com/developers/web/api/create-records) - [Update Records](https://airtable.com/developers/web/api/update-record) - [Delete Records](https://airtable.com/developers/web/api/delete-record) - [Formula Reference](https://support.airtable.com/docs/formula-field-reference) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])