airbyte-api-python-sdk

airbyte-api is the official Speakeasy-generated Python SDK for programmatically controlling Airbyte Cloud, OSS, and Enterprise. It wraps every resource in Airbyte’s public API — connections, sources, destinations, source/destination definitions, jobs, permissions, organizations, tags, streams, users, and workspaces — behind a single typed AirbyteAPI client, so teams can manage data-pipeline infrastructure as code instead of clicking through the UI.

Every operation ships in matching sync and async variants (e.g. create_connection / create_connection_async) built on httpx, with request and response bodies modeled as Pydantic classes for compile-time-checkable inputs and IDE autocomplete. Configurable retry with exponential backoff and jitter, a before/after request hook system, basic-auth and OAuth2 client-credentials security schemes, and typed SDK error classes round out the client, making it a drop-in building block for CI/CD pipelines, internal platform tooling, and automated Airbyte connection provisioning.

What You Get

• A single AirbyteAPI client class exposing resource namespaces — connections, sources, destinations, jobs, permissions, organizations, tags, streams, users, workspaces, and definition management — each lazily imported to keep startup fast
• Matching synchronous and asynchronous methods for every operation (e.g. list_connections and list_connections_async), so the same SDK works in scripts, async web services, or background workers
• Pydantic-modeled request and response types with a py.typed marker, giving IDEs and type checkers (mypy, pyright) full visibility into request shapes and API responses
• Configurable retry with exponential backoff and jitter, custom HTTP client injection, per-request timeouts, and a before-request/after-success/after-error hook system for cross-cutting concerns like logging or auth refresh
• Support for basic auth and OAuth2 client-credentials security schemes, matching how Airbyte Cloud and self-hosted deployments authenticate API calls

Common Use Cases

• Provisioning and tearing down Airbyte sources, destinations, and connections from infrastructure-as-code or CI/CD pipelines instead of the web UI
• Triggering and monitoring sync or reset jobs programmatically as part of a broader data-orchestration workflow (e.g. from Airflow or Dagster)
• Building internal admin tooling that manages workspaces, user permissions, and organization-level OAuth credentials at scale across many Airbyte tenants
• Automating creation of declarative (low-code) source definitions and rolling them out across environments without manual configuration

Under The Hood

Architecture A thin AirbyteAPI entry point in sdk.py lazily imports resource sub-clients (Connections, Sources, Destinations, Jobs, Permissions, Workspaces, and more) through a __getattr__/_sub_sdk_map pattern, so importing the package doesn’t pay the cost of loading every resource module up front. Every sub-client extends a shared BaseSDK (basesdk.py) whose _build_request/_build_request_with_client methods centralize URL templating, query-parameter and security-header assembly, and request-body serialization, while do_request/do_request_async wrap the actual httpx call in a hook chain (before_request, after_success, after_error) and an optional retry policy. A weakref.finalize on the SDK instance guarantees underlying HTTP clients get closed even if callers never use it as a context manager. The design cleanly separates transport concerns (base SDK) from per-resource API surface (generated resource files), so a change to retry or auth logic touches one file rather than hundreds of endpoint methods.

Tech Stack The SDK targets Python 3.10+ and is built on httpx (>=0.28.1) for both sync and async HTTP, pydantic (>=2.11.2) for request/response modeling, and httpcore as the underlying transport. Packaging uses hatchling with uv-dynamic-versioning to derive the version from git tags, and the project supports installation via uv, pip, or poetry. Development tooling (mypy, pyright, ruff, pylint, poethepoet task runner) is declared as a uv dependency group, and the entire src/airbyte_api tree — client, models, hooks, utils, errors — is machine-generated by Speakeasy from an OpenAPI spec, with CI enforcing a zero-diff check between committed code and freshly regenerated output.

Code Quality No hand-written unit test suite ships in the repository; instead, correctness is enforced by the Speakeasy generation pipeline’s dry-run and zero-diff CI check, which fails a PR if regenerating from the OpenAPI spec produces any drift from committed code. Typing is comprehensive and strict: a py.typed marker, mypy and pyright configuration with explicit_package_bases, and consistent naming conventions mirroring the API’s operation IDs across hundreds of generated model files. Error handling is explicit and typed (SDKError, ResponseValidationError, NoResponseError) rather than relying on bare exceptions, and ruff/pylint enforce style consistency across the generated surface.

API Design The SDK’s ergonomics come from consistent generation rather than hand-tuned design: every operation is exposed twice (sync and async) with matching signatures, resource namespaces map directly onto the API’s logical groupings (connections, sources, destinations, jobs…), and optional parameters use an explicit OptionalNullable/UNSET sentinel type to distinguish “not provided” from “explicitly null” — a common pain point in generated clients. Getting started requires minimal boilerplate: instantiate AirbyteAPI with a security object and call a resource method, with retry, timeout, and custom HTTP client injection available as constructor overrides rather than per-call ceremony.