A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Airbyte API is how an app or AI agent works with an Airbyte workspace: connecting a source to a destination, triggering a sync, checking a job, or listing the connectors already set up. Access is granted through an access token created from an Application, and that token represents one Airbyte user and carries exactly the permissions that user has across their workspaces and organization. Airbyte serves a single path-based version of its public API and pushes dated changes through release notes, and it can notify a webhook when a sync finishes.
How an app or AI agent connects to Airbyte determines what it can reach. There is a route for making calls and a hosted server that exposes Airbyte tools to agents, and each is governed by the access token behind it and the Airbyte user that token represents.
The public REST API takes JSON request bodies, returns JSON, and pages lists with limit and offset. On Airbyte Cloud it lives at https://api.airbyte.com/v1; a self-managed instance serves it under
Airbyte hosts a first-party, remote Model Context Protocol server so an AI agent can manage Airbyte through MCP rather than raw REST calls. It is hosted and managed by Airbyte, so there is nothing to install, and it exposes Airbyte actions to MCP-compatible clients. Airbyte also publishes a separate knowledge MCP server for documentation context.
Airbyte can push a notification to a webhook set on a workspace when a sync succeeds, when a sync fails, or when a source schema changes. The webhook is configured against the workspace rather than subscribed to per event through the API, and the payload carries a pointer to the connection and the records and bytes moved.
An Application created in the Airbyte UI yields a client_id and client_secret. These are exchanged at the token endpoint, with grant-type client_credentials, for a Bearer access token valid for 15 minutes. The token is sent as an Authorization header and represents the Airbyte user who owns the Application, carrying that user's permissions.
The Airbyte API is split into areas an agent can act on, like sources, destinations, connections, and sync jobs. Each area has its own methods, and a write to a connection or a triggered sync moves real data between systems.
Methods for working with sources, the systems Airbyte reads data from.
Methods for working with destinations, the systems Airbyte writes data to.
Methods for working with connections, which join a source to a destination.
Methods for triggering and managing sync jobs against a connection.
Methods for inspecting the streams a source and destination pair can move.
Methods for working with workspaces, which contain sources, destinations, and connections.
Methods for working with tags used to label and organize connections.
Methods for listing the organizations a user belongs to.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SourcesMethods for working with sources, the systems Airbyte reads data from.5 | ||||||
| POST | /v1/sources | Create a source from a name, workspaceId, and a configuration matching a connector definition. | write | Sources: write | Current | |
No per-endpoint scope; needs a token for a user who can write in the target workspace. Acts onsource Permission (capability) Sources: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/sources | List the sources in a workspace. | read | Sources: read | Current | |
Read-only; returns sources the user can see. Acts onsource Permission (capability) Sources: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/sources/{sourceId} | Retrieve a single source by its ID. | read | Sources: read | Current | |
Read-only. Acts onsource Permission (capability) Sources: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/sources/{sourceId} | Update part of a source's configuration. | write | Sources: write | Current | |
A partial update; PUT replaces the source entirely. Acts onsource Permission (capability) Sources: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/sources/{sourceId} | Delete a source. | write | Sources: write | Current | |
Removes the source and breaks connections that use it. Acts onsource Permission (capability) Sources: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DestinationsMethods for working with destinations, the systems Airbyte writes data to.5 | ||||||
| POST | /v1/destinations | Create a destination from a name, workspaceId, and a configuration matching a connector definition. | write | Destinations: write | Current | |
No per-endpoint scope; needs a token for a user who can write in the target workspace. Acts ondestination Permission (capability) Destinations: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/destinations | List the destinations in a workspace. | read | Destinations: read | Current | |
Read-only. Acts ondestination Permission (capability) Destinations: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/destinations/{destinationId} | Retrieve a single destination by its ID. | read | Destinations: read | Current | |
Read-only. Acts ondestination Permission (capability) Destinations: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/destinations/{destinationId} | Update part of a destination's configuration. | write | Destinations: write | Current | |
A partial update; PUT replaces the destination entirely. Acts ondestination Permission (capability) Destinations: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/destinations/{destinationId} | Delete a destination. | write | Destinations: write | Current | |
Removes the destination and breaks connections that use it. Acts ondestination Permission (capability) Destinations: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ConnectionsMethods for working with connections, which join a source to a destination.5 | ||||||
| POST | /v1/connections | Create a connection joining a source and a destination for syncing. | write | Connections: write | Current | |
Requires a sourceId and a destinationId; defines what data moves and on what schedule. Acts onconnection Permission (capability) Connections: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/connections | List the connections in a workspace. | read | Connections: read | Current | |
Read-only. Acts onconnection Permission (capability) Connections: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/connections/{connectionId} | Retrieve a single connection by its ID. | read | Connections: read | Current | |
Read-only. Acts onconnection Permission (capability) Connections: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/connections/{connectionId} | Update a connection's settings, like its streams, schedule, or status. | write | Connections: write | Current | |
Changes what data moves and how often. Acts onconnection Permission (capability) Connections: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/connections/{connectionId} | Delete a connection. | write | Connections: write | Current | |
Stops future syncs between the source and destination. Acts onconnection Permission (capability) Connections: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Jobs (syncs)Methods for triggering and managing sync jobs against a connection.4 | ||||||
| POST | /v1/jobs | Start a job for a connection, with a jobType of sync or reset, to move data. | write | Jobs: write | Current | |
Triggers a real sync against the connectionId; returns a jobId to poll. Acts onjob Permission (capability) Jobs: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/jobs | List jobs, filterable by connectionId, jobType, status, workspace, and date range. | read | Jobs: read | Current | |
Read-only; paginated with limit and offset. Acts onjob Permission (capability) Jobs: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/jobs/{jobId} | Retrieve a job's status and details by its ID. | read | Jobs: read | Current | |
Read-only; the way to poll a triggered sync to completion. Acts onjob Permission (capability) Jobs: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/jobs/{jobId} | Cancel a running job. | write | Jobs: write | Current | |
Stops an in-progress sync. Acts onjob Permission (capability) Jobs: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
StreamsMethods for inspecting the streams a source and destination pair can move.1 | ||||||
| GET | /v1/streams | Get the available stream properties for a source and destination pair. | read | Streams: read | Current | |
Read-only; takes a sourceId, an optional destinationId, and an optional ignoreCache flag. Acts onstream Permission (capability) Streams: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WorkspacesMethods for working with workspaces, which contain sources, destinations, and connections.4 | ||||||
| POST | /v1/workspaces | Create a workspace. | write | Workspaces: write | Current | |
Needs a token for a user who can create workspaces in the organization. Acts onworkspace Permission (capability) Workspaces: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/workspaces | List the workspaces the user can access. | read | Workspaces: read | Current | |
Read-only. Acts onworkspace Permission (capability) Workspaces: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/workspaces/{workspaceId} | Retrieve a single workspace by its ID. | read | Workspaces: read | Current | |
Read-only. Acts onworkspace Permission (capability) Workspaces: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/workspaces/{workspaceId} | Delete a workspace. | write | Workspaces: write | Current | |
Removes the workspace and the sources, destinations, and connections scoped to it. Acts onworkspace Permission (capability) Workspaces: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsMethods for working with tags used to label and organize connections.2 | ||||||
| POST | /v1/tags | Create a tag from a name, color, and workspaceId, used to label connections. | write | Tags: write | Current | |
Scoped to a workspace. Acts ontag Permission (capability) Tags: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/tags | List all tags. | read | Tags: read | Current | |
Read-only. Acts ontag Permission (capability) Tags: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationsMethods for listing the organizations a user belongs to.1 | ||||||
| GET | /v1/organizations | List the organizations the user belongs to. | read | Organizations: read | Current | |
Read-only; reflects the user's organization membership. Acts onorganization Permission (capability) Organizations: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Airbyte can notify an app when a sync finishes or a source schema changes by pushing a message to a webhook set on a workspace. The webhook is configured against the workspace rather than subscribed to per event, and it carries a pointer to the connection plus the records and bytes moved.
| Event | What it signals | Triggered by |
|---|
Airbyte pages long lists with a limit and an offset, and the public API does not publish a fixed per-method request ceiling, so an integration should back off when a response signals it is sending requests too quickly.
Airbyte's public API does not publish a fixed per-method request limit. An integration should treat the API as rate-limited in practice: send requests at a steady pace, watch for a response that signals it is going too fast, and retry with exponential backoff rather than hammering an endpoint. Triggering a sync starts a background job, so polling the job at a sensible interval, rather than in a tight loop, is the intended pattern.
List endpoints page with a limit and an offset query parameter. limit sets the page size and offset skips a number of records, so a client walks a list by increasing offset by the page size until fewer than a full page is returned. The job list also accepts filters such as connectionId, jobType, status, and a date range.
A list page is bounded by the limit parameter. A Bearer access token is valid for 15 minutes, after which a new one must be requested from the token endpoint.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad request | The request was malformed or missing a required field, like a connection created without a sourceId and destinationId. | Fix the request body or parameters against the endpoint reference and resend. The request is not retryable as-is. |
| 401 | Unauthorized | No valid access token was provided, or the token has expired. Tokens last 15 minutes. | Request a fresh Bearer token from the token endpoint with the client credentials, then retry the call. |
| 403 | Forbidden | The Airbyte user behind the token does not have permission for this resource, for example a workspace they cannot access. | Confirm the user's role grants access to the organization and workspace involved, or use a token for a user that has it. |
| 404 | Not found | The requested object does not exist, or is not visible to this user, such as a jobId or connectionId that cannot be found. | Verify the resource ID and that it belongs to a workspace the user can see. |
| 422 | Unprocessable entity | The request was well-formed but failed validation, for example a configuration that does not match the connector definition's schema. | Correct the values against the connector's required configuration and resend. |
Airbyte serves a single path-based version of its public API and ships dated changes through its release notes and deprecation notices rather than minting a new version string per change.
Airbyte serves a single path-based version of its public API for managing sources, destinations, connections, and jobs. It is not pinned per request; notable changes ship through dated release notes and deprecation notices rather than a new version string.
API keys generated from the older portal.airbyte.com stopped working. Programmatic access moved to access tokens created from an Application (client_id and client_secret).
The standalone airbyte-api-server service was retired and its routes were moved into the Airbyte server, changing the self-managed public API path. Calls migrated to the /api/public/v1 path.
Airbyte announced it was deprecating the standalone API server and folding its routes into the Airbyte server, ahead of the July removal.
Airbyte set out to deprecate the older Configuration API, an internal API not intended for managing a deployment, and gathered feedback on the public API to cover the same needs.
Track the release notes and deprecation notices, since changes ship against the same path-based version.
Airbyte release notes ↗Bollard AI sits between a team's AI agents and Airbyte. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.