Metadata¶

The Airtable API gives you the ability to list all of your bases, tables, fields, and views. pyAirtable allows you to inspect and interact with this metadata in your bases.

There may be parts of the Airtable API which are not supported below; you can always use Api.request to call them directly.

Reading schemas¶

All of the methods below return complex nested data structures, some of which have their own convenience methods for searching their contents, such as TableSchema.field(). You’ll find more detail in the API reference for pyairtable.models.schema.

Api.bases(*, force=False)[source]

Retrieve the base’s schema and return a list of Base instances.

Parameters: force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Usage:

>>> api.bases()
[
    <pyairtable.Base base_id='appSW9...'>,
    <pyairtable.Base base_id='appLkN...'>
]

Return type: List[Base]

Base.schema()[source]

Retrieve the schema of all tables in the base and caches it.

Usage:

>>> base.schema().tables
[TableSchema(...), TableSchema(...), ...]
>>> base.schema().table("tblXXXXXXXXXXXXXX")
TableSchema(id="tblXXXXXXXXXXXXXX", ...)
>>> base.schema().table("My Table")
TableSchema(id="...", name="My Table", ...)

Parameters: force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: BaseSchema

Base.tables(*, force=False)[source]

Retrieve the base’s schema and returns a list of Table instances.

Parameters: force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.

Usage:

>>> base.tables()
[
    <Table base='appLkN...' id='tbltp8DGLhqbUmjK1' name='Apartments'>,
    <Table base='appLkN...' id='tblK6MZHez0ZvBChZ' name='Districts'>
]

Return type: List[Table]

Table.schema(*, force=False)[source]

Retrieve the schema of the current table.

Usage:

>>> table.schema()
TableSchema(
    id='tblslc6jG0XedVMNx',
    name='My Table',
    primary_field_id='fld6jG0XedVMNxFQW',
    fields=[...],
    views=[...]
)

Parameters: force (bool, default: False) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: TableSchema

Enterprise information¶

pyAirtable exposes a number of classes and methods for interacting with enterprise organizations. The following methods are only available on an Enterprise plan. If you call one of them against a base that is not part of an enterprise workspace, Airtable will return a 404 error, and pyAirtable will add a reminder to the exception to check your billing plan.

Api.enterprise(enterprise_account_id)[source]

⚠ This feature is only available on Enterprise billing plans.

Build an object representing an enterprise account.

Return type: Enterprise

Base.collaborators()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve base collaborators.

Parameters: force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: BaseCollaborators

Base.shares()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve base shares.

Parameters: force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: List[Info]

Workspace.collaborators()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve basic information, collaborators, and invite links for the given workspace, caching the result.

See https://airtable.com/developers/web/api/get-workspace-collaborators

Parameters: force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: WorkspaceCollaborators

Enterprise.info()[source]

⚠ This feature is only available on Enterprise billing plans.

Retrieve basic information about the enterprise, caching the result.

Parameters: force (bool) – By default, this method will only fetch information from the API if it has not been cached. If called with force=True it will always call the API, and will overwrite any cached values.
Return type: EnterpriseInfo

Modifying existing schema¶

To modify a table or field, you can modify its schema object directly and call save(), as shown below. You can only change names and descriptions; the Airtable API does not permit changing any other options.

>>> schema = table.schema()
>>> schema.name = "Renamed"
>>> schema.save()
>>> field = schema.field("Name")
>>> field.name = "Label"
>>> field.description = "The primary field on the table"
>>> field.save()

Creating schema elements¶

The following methods allow creating bases, tables, or fields:

Api.create_base(workspace_id, name, tables)[source]

Create a base in the given workspace.

See https://airtable.com/developers/web/api/create-base

Parameters

workspace_id (str) – The ID of the workspace where the new base will live.
name (str) – The name to give to the new base. Does not need to be unique.
tables (Sequence[Dict[str, Any]]) – A list of dict objects that conform to Airtable’s Table model.

Return type

Base

Workspace.create_base(name, tables)[source]

Create a base in the given workspace.

See https://airtable.com/developers/web/api/create-base

Parameters

name (str) – The name to give to the new base. Does not need to be unique.
tables (Sequence[Dict[str, Any]]) – A list of dict objects that conform to Airtable’s Table model.

Return type

Base

Workspace.move_base(base, target, index=None)[source]

⚠ This feature is only available on Enterprise billing plans.

Move the given base to a new workspace.

See https://airtable.com/developers/web/api/move-base

Usage:

>>> ws = api.workspace("wspmhESAta6clCCwF")
>>> base = api.workspace("appCwFmhESAta6clC")
>>> workspace.move_base(base, "wspSomeOtherPlace", index=0)

Return type: None

Base.create_table(name, fields, description=None)[source]

Create a table in the given base.

Parameters

name (str) – The unique table name.
fields (Sequence[Dict[str, Any]]) – A list of dict objects that conform to the Airtable field model.
description (Optional[str], default: None) – The table description. Must be no longer than 20k characters.

Return type

Table

Table.create_field(name, type, description=None, options=None)[source]

Create a field on the table.

Parameters

name (str) – The unique name of the field.
field_type – One of the Airtable field types.
description (Optional[str], default: None) – A long form description of the table.
options (Optional[Dict[str, Any]], default: None) – Only available for some field types. For more information, read about the Airtable field model.

Return type

Union[AITextFieldSchema, AutoNumberFieldSchema, BarcodeFieldSchema, ButtonFieldSchema, CheckboxFieldSchema, CountFieldSchema, CreatedByFieldSchema, CreatedTimeFieldSchema, CurrencyFieldSchema, DateFieldSchema, DateTimeFieldSchema, DurationFieldSchema, EmailFieldSchema, ExternalSyncSourceFieldSchema, FormulaFieldSchema, LastModifiedByFieldSchema, LastModifiedTimeFieldSchema, MultilineTextFieldSchema, MultipleAttachmentsFieldSchema, MultipleCollaboratorsFieldSchema, MultipleLookupValuesFieldSchema, MultipleRecordLinksFieldSchema, MultipleSelectsFieldSchema, NumberFieldSchema, PercentFieldSchema, PhoneNumberFieldSchema, RatingFieldSchema, RichTextFieldSchema, RollupFieldSchema, SingleCollaboratorFieldSchema, SingleLineTextFieldSchema, SingleSelectFieldSchema, UrlFieldSchema, UnknownFieldSchema]

Deleting schema elements¶

⚠ This feature is only available on Enterprise billing plans.

The Airtable API does not allow deleting tables or fields, but it does allow deleting workspaces, bases, and views. pyAirtable supports the following methods:

To delete a Workspace:

>>> ws = api.workspace("wspmhESAta6clCCwF")
>>> ws.delete()

To delete a Base:

>>> base = api.base("appMxESAta6clCCwF")
>>> base.delete()

To delete a view, first retrieve its ViewSchema:

>>> vw = table.schema().view("View Name")
>>> vw.delete()