0
# Core API Operations
1

2
Fundamental Airtable API access through the Api, Base, and Table classes. These provide the foundation for all pyAirtable operations including authentication, connection management, and basic CRUD operations.
3

4
## Capabilities
5

6
### API Connection Management
7

8
The Api class manages authentication, HTTP connections, retry strategies, and provides factory methods for accessing bases and tables.
9

10
```python { .api }
11
class Api:
12
    def __init__(self, api_key: str, *, 
13
                 timeout: Optional[tuple[int, int]] = None,
14
                 retry_strategy: Optional[Union[bool, object]] = True,
15
                 endpoint_url: str = "https://api.airtable.com",
16
                 use_field_ids: bool = False):
17
        """
18
        Initialize API connection.
19
        
20
        Parameters:
21
        - api_key: Airtable API key or personal access token
22
        - timeout: (connect_timeout, read_timeout) in seconds
23
        - retry_strategy: Retry configuration (True for default, False to disable)
24
        - endpoint_url: API endpoint URL (for debugging/proxy)
25
        - use_field_ids: Use field IDs instead of names in responses
26
        """
27

28
    def whoami(self) -> dict:
29
        """
30
        Get current user ID and scopes.
31
        
32
        Returns:
33
        dict with 'id' and optional 'scopes' keys
34
        """
35

36
    def base(self, base_id: str, *, validate: bool = False, force: bool = False) -> Base:
37
        """
38
        Get Base instance.
39
        
40
        Parameters:
41
        - base_id: Airtable base ID (starts with 'app')
42
        - validate: Validate base exists via API call
43
        - force: Force refresh of cached metadata
44
        
45
        Returns:
46
        Base instance
47
        """
48

49
    def table(self, base_id: str, table_name: str, *, 
50
              validate: bool = False, force: bool = False) -> Table:
51
        """
52
        Get Table instance directly.
53
        
54
        Parameters:
55
        - base_id: Airtable base ID (starts with 'app')
56
        - table_name: Table name or ID (starts with 'tbl')
57
        - validate: Validate table exists via API call
58
        - force: Force refresh of cached metadata
59
        
60
        Returns:
61
        Table instance
62
        """
63

64
    def bases(self, *, force: bool = False) -> list[Base]:
65
        """
66
        List all accessible bases.
67
        
68
        Parameters:
69
        - force: Force refresh of cached base list
70
        
71
        Returns:
72
        List of Base instances
73
        """
74

75
    def create_base(self, workspace_id: str, name: str, tables: list[dict]) -> Base:
76
        """
77
        Create a new base.
78
        
79
        Parameters:
80
        - workspace_id: Workspace ID where base will be created
81
        - name: Base name
82
        - tables: List of table schema dictionaries
83
        
84
        Returns:
85
        Base instance for the created base
86
        """
87

88
    def workspace(self, workspace_id: str) -> Workspace:
89
        """
90
        Get Workspace instance.
91
        
92
        Parameters:
93
        - workspace_id: Workspace ID (starts with 'wsp')
94
        
95
        Returns:
96
        Workspace instance
97
        """
98

99
    def enterprise(self, enterprise_account_id: str) -> Enterprise:
100
        """
101
        Get Enterprise instance (Enterprise plans only).
102
        
103
        Parameters:
104
        - enterprise_account_id: Enterprise account ID
105
        
106
        Returns:
107
        Enterprise instance
108
        """
109

110
    @property
111
    def api_key(self) -> str:
112
        """Current API key or access token."""
113

114
    # HTTP methods
115
    def request(self, method: str, url: str, **kwargs) -> dict:
116
        """Make authenticated API request."""
117

118
    def get(self, url: str, **kwargs) -> dict:
119
        """Make GET request."""
120

121
    def post(self, url: str, **kwargs) -> dict:
122
        """Make POST request."""
123

124
    def patch(self, url: str, **kwargs) -> dict:
125
        """Make PATCH request."""
126

127
    def delete(self, url: str, **kwargs) -> dict:
128
        """Make DELETE request."""
129
```
130

131
### Base Management
132

133
Base class represents an Airtable base and provides access to tables, metadata, webhooks, and collaboration features.
134

135
```python { .api }
136
class Base:
137
    def __init__(self, api: Api, base_id: str, *, 
138
                 name: Optional[str] = None,
139
                 permission_level: Optional[str] = None):
140
        """
141
        Initialize Base instance.
142
        
143
        Parameters:
144
        - api: Api instance
145
        - base_id: Base ID (starts with 'app')
146
        - name: Base name (if known)
147
        - permission_level: User's permission level on base
148
        """
149

150
    @property
151
    def id(self) -> str:
152
        """Base ID."""
153

154
    @property
155
    def name(self) -> Optional[str]:
156
        """Base name (if available)."""
157

158
    def table(self, id_or_name: str, *, 
159
              validate: bool = False, force: bool = False) -> Table:
160
        """
161
        Get Table instance.
162
        
163
        Parameters:
164
        - id_or_name: Table name or ID
165
        - validate: Validate table exists
166
        - force: Force refresh metadata
167
        
168
        Returns:
169
        Table instance
170
        """
171

172
    def tables(self, *, force: bool = False) -> list[Table]:
173
        """
174
        Get all tables in base.
175
        
176
        Parameters:
177
        - force: Force refresh base schema
178
        
179
        Returns:
180
        List of Table instances
181
        """
182

183
    def create_table(self, name: str, fields: list[dict], 
184
                     description: Optional[str] = None) -> Table:
185
        """
186
        Create new table in base.
187
        
188
        Parameters:
189
        - name: Table name (must be unique)
190
        - fields: List of field schema dictionaries
191
        - description: Table description (max 20k characters)
192
        
193
        Returns:
194
        Table instance for created table
195
        """
196

197
    def schema(self, *, force: bool = False) -> object:
198
        """
199
        Get base schema with all tables and fields.
200
        
201
        Parameters:
202
        - force: Force refresh cached schema
203
        
204
        Returns:
205
        BaseSchema object with tables and field information
206
        """
207

208
    def webhooks(self) -> list[object]:
209
        """
210
        Get all webhooks configured for this base.
211
        
212
        Returns:
213
        List of Webhook objects
214
        """
215

216
    def webhook(self, webhook_id: str) -> object:
217
        """
218
        Get specific webhook by ID.
219
        
220
        Parameters:
221
        - webhook_id: Webhook ID
222
        
223
        Returns:
224
        Webhook object
225
        """
226

227
    def add_webhook(self, notify_url: str, spec: Union[dict, object]) -> object:
228
        """
229
        Create webhook for base.
230
        
231
        Parameters:
232
        - notify_url: URL to receive webhook notifications
233
        - spec: Webhook specification dict or WebhookSpecification object
234
        
235
        Returns:
236
        CreateWebhookResponse with webhook ID and secret
237
        """
238

239
    def delete(self) -> None:
240
        """Delete base (Enterprise only)."""
241
```
242

243
### Table Operations
244

245
Table class provides direct access to records and table-level operations including CRUD operations, schema management, and field creation.
246

247
```python { .api }
248
class Table:
249
    def __init__(self, api_key: Optional[str], base: Union[Base, str], 
250
                 table_name: Union[str, object]):
251
        """
252
        Initialize Table instance.
253
        
254
        Parameters:
255
        - api_key: API key (deprecated, use Api.table() instead)
256
        - base: Base instance or base ID
257
        - table_name: Table name, ID, or TableSchema object
258
        """
259

260
    @property
261
    def id(self) -> str:
262
        """Table ID (fetched from API if needed)."""
263

264
    @property
265
    def name(self) -> str:
266
        """Table name."""
267

268
    @property
269
    def base(self) -> Base:
270
        """Base instance containing this table."""
271

272
    @property
273
    def api(self) -> Api:
274
        """API instance used by this table."""
275

276
    def schema(self, *, force: bool = False) -> object:
277
        """
278
        Get table schema with field definitions.
279
        
280
        Parameters:
281
        - force: Force refresh cached schema
282
        
283
        Returns:
284
        TableSchema object with field information
285
        """
286

287
    def create_field(self, name: str, field_type: str, 
288
                     description: Optional[str] = None,
289
                     options: Optional[dict] = None) -> object:
290
        """
291
        Create new field in table.
292
        
293
        Parameters:
294
        - name: Field name (must be unique in table)
295
        - field_type: Airtable field type (e.g., 'singleLineText', 'number')
296
        - description: Field description
297
        - options: Field-specific options dict
298
        
299
        Returns:
300
        FieldSchema object for created field
301
        """
302
```
303

304
### Usage Examples
305

306
#### Basic API Setup
307

308
```python
309
from pyairtable import Api
310

311
# Initialize with API key
312
api = Api('your_personal_access_token')
313

314
# Check authentication
315
user_info = api.whoami()
316
print(f"Connected as user: {user_info['id']}")
317

318
# List available bases
319
bases = api.bases()
320
for base in bases:
321
    print(f"Base: {base.name} ({base.id})")
322
```
323

324
#### Working with Bases and Tables
325

326
```python
327
# Get base instance
328
base = api.base('app1234567890abcde')
329

330
# Get base schema
331
schema = base.schema()
332
print(f"Base has {len(schema.tables)} tables")
333

334
# List all tables
335
tables = base.tables()
336
for table in tables:
337
    print(f"Table: {table.name} ({table.id})")
338

339
# Get specific table
340
table = base.table('My Table Name')
341
# or by table ID
342
table = base.table('tbl1234567890abcde')
343
```
344

345
#### Table Schema and Field Management
346

347
```python
348
# Get table schema
349
schema = table.schema()
350
print(f"Table has {len(schema.fields)} fields")
351

352
# Create new field
353
new_field = table.create_field(
354
    name='Priority',
355
    field_type='singleSelect',
356
    options={
357
        'choices': [
358
            {'name': 'High', 'color': 'redBright'},
359
            {'name': 'Medium', 'color': 'yellowBright'},
360
            {'name': 'Low', 'color': 'greenBright'}
361
        ]
362
    }
363
)
364
print(f"Created field: {new_field.name}")
365
```
366

367
#### Connection Configuration
368

369
```python
370
from pyairtable import Api
371
from pyairtable.api.retrying import retry_strategy
372

373
# Custom timeout and retry configuration
374
api = Api(
375
    'your_token',
376
    timeout=(5, 30),  # 5s connect, 30s read timeout
377
    retry_strategy=retry_strategy(
378
        total=5,  # max retries
379
        backoff_factor=1.0  # exponential backoff
380
    )
381
)
382

383
# Disable retries
384
api = Api('your_token', retry_strategy=False)
385

386
# Use field IDs instead of names
387
api = Api('your_token', use_field_ids=True)
388
```