Create Source Connection

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

POST /v1/source-connections

Create Source Connection

cURL

curl --request POST \
  --url https://api.example.com/v1/source-connections \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "short_name": "<string>",
  "readable_collection_id": "<string>",
  "description": "<string>",
  "config": {},
  "authentication": {
    "credentials": {},
    "access_token": "<string>",
    "refresh_token": "<string>",
    "expires_at": "<string>",
    "redirect_uri": "<string>",
    "client_id": "<string>",
    "client_secret": "<string>",
    "provider_readable_id": "<string>",
    "provider_config": {}
  },
  "schedule": {
    "cron": "<string>",
    "continuous": true,
    "cursor_field": "<string>"
  },
  "sync_immediately": true,
  "redirect_url": "<string>"
}
'

200

{
  "id": "<string>",
  "name": "<string>",
  "short_name": "<string>",
  "status": "<string>",
  "auth": {}
}

Overview

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

name · string

Display name for the connection (4-42 characters)

If not provided, defaults to the source name with “Connection” appended

Example: “My GitHub 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

Example: “customer-support-tickets-x7k9m”

description · string

Optional description of what this connection is used for (max 255 characters)

config · object

Source-specific configuration (e.g., repository name, filters)

Show example

{
  "repo_name": "airweave-ai/airweave",
  "branch": "main"
}

authentication · object

Authentication configuration (type auto-detected from provided fields)

Show Direct Auth

credentials · object · required

Authentication credentials (e.g., API key, token)

Example: {"personal_access_token": "ghp_xxxxx"}

Show OAuth Token

access_token · string · required

OAuth access token

refresh_token · string

OAuth refresh token

expires_at · string

Token expiry time (ISO 8601)

Show OAuth Browser

redirect_uri · string

OAuth redirect URI

client_id · string

OAuth2 client ID (for BYOC)

client_secret · string

OAuth2 client secret (for BYOC)

Show Auth Provider

provider_readable_id · string · required

Auth provider readable ID

provider_config · object

Provider-specific configuration

schedule · object

Optional sync schedule configuration

Show properties

cron · string

Cron expression for scheduled syncs

continuous · boolean · default: false

Enable continuous sync mode

cursor_field · string

Field for incremental sync

sync_immediately · boolean

Run initial sync after creation

Defaults to true for direct/token/auth_provider, false for OAuth flows

redirect_url · string

URL to redirect to after OAuth flow completes (only for OAuth flows)

Response

id · string · required

Unique UUID identifier of the created connection

name · string · required

Display name

short_name · string · required

Source type identifier

status · string · required

Current status (e.g., PENDING_AUTH, ACTIVE, SYNCING)

auth · object · required

Authentication details including auth_url for OAuth flows

Example Requests

Direct Auth (GitHub)

curl -X POST https://api.airweave.ai/v1/source-connections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Docs Repo",
    "short_name": "github",
    "readable_collection_id": "documentation-ab123",
    "config": {
      "repo_name": "company/docs",
      "branch": "main"
    },
    "authentication": {
      "credentials": {
        "personal_access_token": "ghp_xxxxxxxxxxxx"
      }
    }
  }'

Example Response (Direct Auth)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "GitHub Docs Repo",
  "short_name": "github",
  "readable_collection_id": "documentation-ab123",
  "status": "SYNCING",
  "auth": {
    "method": "direct",
    "authenticated": true,
    "authenticated_at": "2024-03-15T09:30:00Z"
  },
  "config": {
    "repo_name": "company/docs",
    "branch": "main"
  },
  "created_at": "2024-03-15T09:30:00Z",
  "modified_at": "2024-03-15T09:30:00Z"
}

Example Response (OAuth Browser)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Slack Workspace",
  "short_name": "slack",
  "readable_collection_id": "team-comms-xy789",
  "status": "PENDING_AUTH",
  "auth": {
    "method": "oauth_browser",
    "authenticated": false,
    "auth_url": "https://api.airweave.ai/v1/source-connections/authorize/abc123",
    "auth_url_expires": "2024-03-15T10:00:00Z",
    "redirect_url": "https://app.example.com/connections"
  },
  "created_at": "2024-03-15T09:30:00Z",
  "modified_at": "2024-03-15T09:30:00Z"
}