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 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.

Base URL​

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

If your account belongs to a single organization, the API resolves the target organization from your credentials and you don't need to pass an extra header. If your account belongs to multiple organizations, you must add an X-Organization-Id: <organization_id> header when you request an application token, or the API returns a 400 asking you to specify the organization. To find the ID, run airbyte-agent organizations list with the CLI, or copy it from the /organizations/<organization_id> URL after you select the organization in app.airbyte.ai.

How the pieces fit together​

The pages in this section follow the same order as 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?