---
title: "Create Source Connection"
method: POST
path: "/source-connections"
tags: ["source-connections"]
---

# Create Source Connection

`POST /source-connections`

## Request

- Base URL: `https://api.airweave.ai`
- URL: `https://api.airweave.ai/source-connections`
- Auth: API key in header `x-api-key`

Create a new source connection to sync data from an external source.

The authentication method determines the creation flow:

- **Direct**: Provide credentials (API key, token) directly. Connection is created immediately.
- **OAuth Browser**: Returns a connection with an `auth_url` to redirect users for authentication.
- **OAuth Token**: Provide an existing OAuth token. Connection is created immediately.
- **Auth Provider**: Use a pre-configured auth provider (e.g., Composio, Pipedream).

After successful authentication, data sync can begin automatically or on-demand.

## Request body

- SourceConnectionCreate: Create a source connection with authentication configuration. Source connections link a data source (e.g., GitHub, Slack) to a collection. The authentication method determines how credentials are provided and whether the connection is created immediately or requires an OAuth flow.
  - `name` string, nullable: Display name for the connection. If not provided, defaults to '{Source Name} Connection'.
  - `short_name` string, required: Source type identifier (e.g., 'slack', 'github', 'notion')
  - `readable_collection_id` string, required: The readable ID of the collection to add this connection to
  - `description` string, nullable: Optional description of what this connection is used for
  - `config` object, nullable: Source-specific configuration (e.g., repository name, filters)
  - `schedule` ScheduleConfig: Schedule configuration for syncs.
    - `cron` string, nullable: Cron expression for scheduled syncs
    - `continuous` boolean: Enable continuous sync mode
    - `cursor_field` string, nullable: Field for incremental sync
  - `sync_immediately` boolean, nullable: Run initial sync after creation. Defaults to True for direct/token/auth_provider, False for OAuth browser/BYOC flows (which sync after authentication)
  - `authentication` union: Authentication configuration. Type is auto-detected from provided fields.
    - DirectAuthentication: Direct authentication with API keys or passwords.
      - `credentials` object, required: Authentication credentials
    - OAuthTokenAuthentication: OAuth authentication with pre-obtained token.
      - `access_token` string, required: OAuth access token
      - `refresh_token` string, nullable: OAuth refresh token
      - `expires_at` string, date-time, nullable: Token expiry time
    - OAuthBrowserAuthentication: OAuth authentication via browser flow. Supports both OAuth2 and OAuth1 BYOC (Bring Your Own Client): - OAuth2 BYOC: Provide client_id + client_secret - OAuth1 BYOC: Provide consumer_key + consumer_secret
      - `redirect_uri` string, nullable: OAuth redirect URI
      - `client_id` string, nullable: OAuth2 client ID (for custom apps)
      - `client_secret` string, nullable: OAuth2 client secret (for custom apps)
      - `consumer_key` string, nullable: OAuth1 consumer key (for custom apps)
      - `consumer_secret` string, nullable: OAuth1 consumer secret (for custom apps)
    - AuthProviderAuthentication: Authentication via external provider.
      - `provider_readable_id` string, required: Auth provider readable ID
      - `provider_config` object, nullable: Provider-specific configuration
  - `redirect_url` string, nullable: URL to redirect to after OAuth flow completes (only used for OAuth flows)

## Response `200`

Created source connection

- SourceConnection: Complete source connection details including auth, config, sync status, and entities. This schema provides full information about a source connection, suitable for detail views and monitoring sync progress.
  - `id` string, uuid, required: Unique identifier of the source connection
  - `organization_id` string, uuid, required: Organization this connection belongs to
  - `name` string, required: Display name of the connection
  - `description` string, nullable: Optional description of the connection's purpose
  - `short_name` string, required: Source type identifier
  - `readable_collection_id` string, required: Collection this connection belongs to
  - `status` 'active' | 'pending_auth' | 'syncing' | 'error' | 'inactive' | 'pending_sync', required: Source connection status enum - represents overall connection state.
  - `created_at` string, date-time, required: When the connection was created (ISO 8601)
  - `modified_at` string, date-time, required: When the connection was last modified (ISO 8601)
  - `auth` AuthenticationDetails, required: Authentication information.
    - `method` 'direct' | 'oauth_browser' | 'oauth_token' | 'oauth_byoc' | 'auth_provider', required: Authentication methods for source connections.
    - `authenticated` boolean, required
    - `authenticated_at` string, date-time, nullable
    - `expires_at` string, date-time, nullable
    - `auth_url` string, nullable: For pending OAuth flows
    - `auth_url_expires` string, date-time, nullable
    - `redirect_url` string, nullable
    - `claim_token` string, nullable: One-time token to verify OAuth flow ownership. Only returned when creating an OAuth browser connection.
    - `provider_readable_id` string, nullable
    - `provider_id` string, nullable
  - `config` object, nullable: Source-specific configuration values
  - `schedule` ScheduleDetails: Schedule information.
    - `cron` string, nullable
    - `next_run` string, date-time, nullable
    - `continuous` boolean
    - `cursor_field` string, nullable
    - `cursor_value` unknown
  - `sync` SyncDetails: Sync execution details.
    - `total_runs` integer
    - `successful_runs` integer
    - `failed_runs` integer
    - `last_job` SyncJobDetails: Sync job details.
      - `id` string, uuid, required
      - `status` 'created' | 'pending' | 'running' | 'completed' | 'failed' | 'cancelling' | 'cancelled', required: Sync job status enum.
      - `started_at` string, date-time, nullable
      - `completed_at` string, date-time, nullable
      - `duration_seconds` number, nullable
      - `entities_inserted` integer
      - `entities_updated` integer
      - `entities_deleted` integer
      - `entities_failed` integer
      - `error` string, nullable
  - `sync_id` string, uuid, nullable: ID of the associated sync (internal use)
  - `entities` EntitySummary: Entity state summary.
    - `total_entities` integer
    - `by_type` object
  - `federated_search` boolean: Whether this source uses federated (real-time) search instead of syncing

## Other responses

- `422`: Validation Error
- `429`: Rate Limit Exceeded

## Changes

> 63 revisions in range; 2 not diffed.

- **2026-03-22** `a8105b372b4d`: 1 info
  - added the optional property `auth/claim_token` to the response with the `200` status
- **2026-02-14** `dcef44679b67`: 1 info
  - added the required property `organization_id` to the response with the `200` status
- **2026-02-04** `9c8b36d8fcaa`: 1 breaking, 3 info
  - the response property `description` became optional for the status `200`
  - added the non-success response with the status `429`
  - the response property `detail` became required for the status `422`
  - response property `detail/items/loc/items/` list-of-types was narrowed by removing types `integer` from media type `application/json` of response `422`
- **2025-10-09** `c25c4670614e`: 2 info
  - added the optional property `federated_search` to the response with the `200` status
  - added the optional property `sync_id` to the response with the `200` status
- **2025-10-04** `fff3c4b10970`: 1 info
  - added the new optional request property `redirect_url`

[Operation history](https://skmtc.dev/airweave-ai/apis/airweave/changes/source-connections/post.md)

---

[API](https://skmtc.dev/airweave-ai/apis/airweave.md) - [All operations](https://skmtc.dev/airweave-ai/apis/airweave/llms.txt) - [OpenAPI document](https://skmtc.dev/airweave-ai/apis/airweave/revisions/bf410c28c0c6?raw)