Skip to main content

API

AvailableFreeAvailableIndividualAvailableTeamAvailableCustom Compare plans

The Agent API lets you manage connectors, credentials, and data operations programmatically over HTTP. Use it to integrate Airbyte Agents into any language or framework, or to build custom backend services that interact with third-party data sources.

This section walks through the four operations most apps need: authenticate, add a connector, execute operations, and manage workspaces. Deeper endpoint details (every parameter, response schema, and error code) live in the API reference.

When to use the API​

  • Your backend isn't Python, so the SDK isn't an option.
  • You need direct HTTP control over authentication, connector management, or execution.
  • You're building custom admin flows or embedding the authentication module in your application.
  • You want to call Airbyte Agents from any language or framework that can make HTTP requests.

If you're writing Python, the SDK wraps the same endpoints with a typed interface. If your agent speaks the Model Context Protocol, the MCP server gives you zero-install access. For shell scripts and CI, see the CLI.

Choose your interface​

You can use Airbyte Agents programmatically in several ways:

  • MCP server: a remote, Airbyte-hosted server. Best for AI agents that speak the Model Context Protocol (Claude, ChatGPT, Cursor, VS Code). Zero install.
  • SDK: a typed Python library. Best for Python apps, notebooks, scripts, and AI agents built with frameworks like Pydantic AI or LangChain.
  • CLI: a shell interface with composable JSON output. Best for scripts, CI jobs, and AI-agent harnesses that call command-line tools.
  • API: an HTTP API. Best for non-Python backends, custom admin flows, and languages the SDK doesn't cover.
  • Web app: a browser UI at app.airbyte.ai. Best for no-code exploration and scheduled automations.

All interfaces share the same connectors, credentials, and Context Store. See Choose how to use Airbyte Agents for a detailed comparison.

Base URL​

All API requests use the base URL https://api.airbyte.ai.

If your account belongs to multiple organizations, generate your application token from the organization you want to target. The API resolves the target organization from the token, so you don't need to pass an extra header.

How the pieces fit together​

The four pages in this section are designed to map one-to-one with the SDK section so the same mental model works in either environment.

  1. Authentication: Get an application token (and, when needed, a scoped token). This is how every subsequent call is authorized.

  2. Add a connector: Create a connector from a definition_id plus the credentials for the third-party service.

  3. Execute operations: First introspect the connector (GET /integrations/connectors/<connector_id>/inspect, then GET /skills/docs) to discover its entities, actions, and usage guidance, then call POST /integrations/connectors/<connector_id>/execute to read from or take action on the connected service.

  4. Manage workspaces: Administer workspaces (list, update, delete). These are operations the SDK defers to the API. Most apps use the default workspace and don't need this page.

End-to-end example​

This snippet authenticates, creates a connector, and executes a single operation. It parallels the SDK end-to-end example.

1. Get an application token
curl -X POST https://api.airbyte.ai/api/v1/account/applications/token \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>"
  }'

Make your first request​

Once you have an application token, a good starting point is listing the available source connector definitions. This read-only endpoint returns the catalog of connectors available in Airbyte Agents, so it returns data even if you haven't configured anything yet. It requires the bearer token like every other endpoint.

Request
curl https://api.airbyte.ai/api/v1/integrations/definitions/sources \
  -H 'Authorization: Bearer <application_token>'
Response
{
  "definitions": [
    {
      "sourceDefinitionId": "ef69ef6e-aa7f-4af1-a01d-ef775033524e",
      "name": "GitHub",
      "iconUrl": "https://connectors.airbyte.com/files/metadata/airbyte/source-github/latest/icon.svg",
      "supportLevel": "certified"
    },
    {
      "sourceDefinitionId": "b117307c-14b6-41aa-9571-75e6871e6d44",
      "name": "Salesforce",
      "iconUrl": "https://connectors.airbyte.com/files/metadata/airbyte/source-salesforce/latest/icon.svg",
      "supportLevel": "certified"
    }
  ]
}

You can filter results by name using the name query parameter:

Request
curl 'https://api.airbyte.ai/api/v1/integrations/definitions/sources?name=github' \
  -H 'Authorization: Bearer <application_token>'

Use the API​

Was this page helpful?