> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.airweave.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airweave.ai/_mcp/server. # Create Source Connection POST https://api.airweave.ai/source-connections Content-Type: application/json 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. Reference: https://docs.airweave.ai/api-reference/source-connections/create-source-connections-post ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /source-connections: post: operationId: create-source-connections-post summary: Create Source Connection description: >- 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. tags: - source-connections parameters: - name: x-api-key in: header required: true schema: type: string responses: '200': description: Created source connection content: application/json: schema: $ref: '#/components/schemas/SourceConnection' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '429': description: Rate Limit Exceeded content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/SourceConnectionCreate' servers: - url: https://api.airweave.ai description: Production - url: http://localhost:8001 description: Local components: schemas: ScheduleConfig: type: object properties: cron: type: - string - 'null' description: Cron expression for scheduled syncs continuous: type: boolean default: false description: Enable continuous sync mode cursor_field: type: - string - 'null' description: Field for incremental sync description: Schedule configuration for syncs. title: ScheduleConfig DirectAuthentication: type: object properties: credentials: type: object additionalProperties: description: Any type description: Authentication credentials required: - credentials description: Direct authentication with API keys or passwords. title: DirectAuthentication OAuthTokenAuthentication: type: object properties: access_token: type: string description: OAuth access token refresh_token: type: - string - 'null' description: OAuth refresh token expires_at: type: - string - 'null' format: date-time description: Token expiry time required: - access_token description: OAuth authentication with pre-obtained token. title: OAuthTokenAuthentication OAuthBrowserAuthentication: type: object properties: redirect_uri: type: - string - 'null' description: OAuth redirect URI client_id: type: - string - 'null' description: OAuth2 client ID (for custom apps) client_secret: type: - string - 'null' description: OAuth2 client secret (for custom apps) consumer_key: type: - string - 'null' description: OAuth1 consumer key (for custom apps) consumer_secret: type: - string - 'null' description: OAuth1 consumer secret (for custom apps) description: |- 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 title: OAuthBrowserAuthentication AuthProviderAuthentication: type: object properties: provider_readable_id: type: string description: Auth provider readable ID provider_config: type: - object - 'null' additionalProperties: description: Any type description: Provider-specific configuration required: - provider_readable_id description: Authentication via external provider. title: AuthProviderAuthentication SourceConnectionCreateAuthentication: oneOf: - $ref: '#/components/schemas/DirectAuthentication' - $ref: '#/components/schemas/OAuthTokenAuthentication' - $ref: '#/components/schemas/OAuthBrowserAuthentication' - $ref: '#/components/schemas/AuthProviderAuthentication' description: >- Authentication configuration. Type is auto-detected from provided fields. title: SourceConnectionCreateAuthentication SourceConnectionCreate: type: object properties: name: type: - string - 'null' description: >- Display name for the connection. If not provided, defaults to '{Source Name} Connection'. short_name: type: string description: Source type identifier (e.g., 'slack', 'github', 'notion') readable_collection_id: type: string description: The readable ID of the collection to add this connection to description: type: - string - 'null' description: Optional description of what this connection is used for config: type: - object - 'null' additionalProperties: description: Any type description: Source-specific configuration (e.g., repository name, filters) schedule: oneOf: - $ref: '#/components/schemas/ScheduleConfig' - type: 'null' description: Optional sync schedule configuration sync_immediately: type: - boolean - 'null' description: >- Run initial sync after creation. Defaults to True for direct/token/auth_provider, False for OAuth browser/BYOC flows (which sync after authentication) authentication: oneOf: - $ref: '#/components/schemas/SourceConnectionCreateAuthentication' - type: 'null' description: >- Authentication configuration. Type is auto-detected from provided fields. redirect_url: type: - string - 'null' description: >- URL to redirect to after OAuth flow completes (only used for OAuth flows) required: - short_name - readable_collection_id description: >- 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. title: SourceConnectionCreate SourceConnectionStatus: type: string enum: - active - pending_auth - syncing - error - needs_reauth - inactive - pending_sync description: Source connection status enum - represents overall connection state. title: SourceConnectionStatus AuthenticationMethod: type: string enum: - direct - oauth_browser - oauth_token - oauth_byoc - auth_provider description: Authentication methods for source connections. title: AuthenticationMethod AuthenticationDetails: type: object properties: method: $ref: '#/components/schemas/AuthenticationMethod' authenticated: type: boolean authenticated_at: type: - string - 'null' format: date-time expires_at: type: - string - 'null' format: date-time auth_url: type: - string - 'null' description: For pending OAuth flows auth_url_expires: type: - string - 'null' format: date-time redirect_url: type: - string - 'null' claim_token: type: - string - 'null' description: >- One-time token to verify OAuth flow ownership. Only returned when creating an OAuth browser connection. provider_readable_id: type: - string - 'null' provider_id: type: - string - 'null' required: - method - authenticated description: Authentication information. title: AuthenticationDetails ScheduleDetails: type: object properties: cron: type: - string - 'null' next_run: type: - string - 'null' format: date-time continuous: type: boolean default: false cursor_field: type: - string - 'null' description: Schedule information. title: ScheduleDetails SyncJobStatus: type: string enum: - created - pending - running - completed - failed - cancelling - cancelled description: Sync job status enum. title: SyncJobStatus SourceConnectionErrorCategory: type: string enum: - oauth_credentials_expired - api_key_invalid - auth_provider_account_gone - auth_provider_credentials_invalid - usage_limit_exceeded - rate_limited description: Error categories for credential/auth failures on source connections. title: SourceConnectionErrorCategory SyncJobDetails: type: object properties: id: type: string format: uuid status: $ref: '#/components/schemas/SyncJobStatus' started_at: type: - string - 'null' format: date-time completed_at: type: - string - 'null' format: date-time duration_seconds: type: - number - 'null' format: double entities_inserted: type: integer default: 0 entities_updated: type: integer default: 0 entities_deleted: type: integer default: 0 entities_failed: type: integer default: 0 error: type: - string - 'null' error_category: oneOf: - $ref: '#/components/schemas/SourceConnectionErrorCategory' - type: 'null' required: - id - status description: Sync job details. title: SyncJobDetails SyncDetails: type: object properties: total_runs: type: integer default: 0 successful_runs: type: integer default: 0 failed_runs: type: integer default: 0 last_job: oneOf: - $ref: '#/components/schemas/SyncJobDetails' - type: 'null' description: Sync execution details. title: SyncDetails EntityTypeStats: type: object properties: count: type: integer last_updated: type: - string - 'null' format: date-time required: - count description: Statistics for a specific entity type. title: EntityTypeStats EntitySummary: type: object properties: total_entities: type: integer default: 0 by_type: type: object additionalProperties: $ref: '#/components/schemas/EntityTypeStats' entity_id: type: string name: type: string entity_type: type: string source_name: type: string relevance_score: type: - number - 'null' format: double description: Entity state summary. title: EntitySummary SourceConnection: type: object properties: id: type: string format: uuid description: Unique identifier of the source connection organization_id: type: string format: uuid description: Organization this connection belongs to name: type: string description: Display name of the connection description: type: - string - 'null' description: Optional description of the connection's purpose short_name: type: string description: Source type identifier readable_collection_id: type: string description: Collection this connection belongs to status: $ref: '#/components/schemas/SourceConnectionStatus' description: Current operational status of the connection created_at: type: string format: date-time description: When the connection was created (ISO 8601) modified_at: type: string format: date-time description: When the connection was last modified (ISO 8601) auth: $ref: '#/components/schemas/AuthenticationDetails' description: Authentication status and details config: type: - object - 'null' additionalProperties: description: Any type description: Source-specific configuration values schedule: oneOf: - $ref: '#/components/schemas/ScheduleDetails' - type: 'null' description: Sync schedule configuration sync: oneOf: - $ref: '#/components/schemas/SyncDetails' - type: 'null' description: Sync execution history and statistics sync_id: type: - string - 'null' format: uuid description: ID of the associated sync (internal use) entities: oneOf: - $ref: '#/components/schemas/EntitySummary' - type: 'null' description: Summary of synced entities by type error_category: oneOf: - $ref: '#/components/schemas/SourceConnectionErrorCategory' - type: 'null' description: >- Error category when status is needs_reauth (e.g. oauth_credentials_expired) error_message: type: - string - 'null' description: Human-readable error message when status is needs_reauth provider_settings_url: type: - string - 'null' description: >- URL to the auth provider's settings dashboard (for auth_provider errors) provider_short_name: type: - string - 'null' description: Auth provider short_name (e.g. 'composio', 'pipedream') for display federated_search: type: boolean default: false description: >- Whether this source uses federated (real-time) search instead of syncing required: - id - organization_id - name - short_name - readable_collection_id - status - created_at - modified_at - auth description: >- 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. title: SourceConnection ValidationErrorDetail: type: object properties: loc: type: array items: type: string description: Location of the error (e.g., ['body', 'url']) msg: type: string description: Human-readable error message type: type: string description: Error type identifier required: - loc - msg - type description: Details about a validation error for a specific field. title: ValidationErrorDetail ValidationErrorResponse: type: object properties: detail: type: array items: $ref: '#/components/schemas/ValidationErrorDetail' description: List of validation errors required: - detail description: |- Response returned when request validation fails (HTTP 422). This occurs when the request body contains invalid data, such as malformed URLs, invalid event types, or missing required fields. title: ValidationErrorResponse RateLimitErrorResponse: type: object properties: detail: type: string description: Error message explaining the rate limit required: - detail description: >- Response returned when rate limit is exceeded (HTTP 429). The API enforces rate limits to ensure fair usage. When exceeded, wait for the duration specified in the Retry-After header before retrying. title: RateLimitErrorResponse securitySchemes: default: type: apiKey in: header name: x-api-key ``` ## Examples **Request** ```json { "short_name": "github", "readable_collection_id": "customer-support-tickets-x7k9m" } ``` **Response** ```json { "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": "active", "created_at": "2024-03-15T09:30:00Z", "modified_at": "2024-03-15T14:22:15Z", "auth": { "method": "direct", "authenticated": true, "authenticated_at": "2024-03-15T09:30:00Z" }, "description": "Main documentation repository", "config": { "branch": "main", "repo_name": "company/docs" }, "schedule": { "cron": "0 */6 * * *", "next_run": "2024-03-15T18:00:00Z" }, "sync": { "total_runs": 15, "successful_runs": 14, "failed_runs": 1, "last_job": { "id": "770e8400-e29b-41d4-a716-446655440002", "status": "created", "started_at": "2024-03-15T12:00:00Z", "completed_at": "2024-03-15T12:05:32Z", "duration_seconds": 332, "entities_inserted": 45, "entities_updated": 12 } }, "entities": { "total_entities": 1250, "by_type": { "file": { "count": 1250 } } }, "federated_search": false } ``` **SDK Code** ```python import requests url = "https://api.airweave.ai/source-connections" payload = { "short_name": "github", "readable_collection_id": "customer-support-tickets-x7k9m" } headers = { "x-api-key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```typescript import { AirweaveSDKClient } from "@airweave/sdk"; const client = new AirweaveSDKClient({ apiKey: "YOUR_API_KEY" }); await client.sourceConnections.create({ short_name: "github", readable_collection_id: "customer-support-tickets-x7k9m" }); ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.airweave.ai/source-connections" payload := strings.NewReader("{\n \"short_name\": \"github\",\n \"readable_collection_id\": \"customer-support-tickets-x7k9m\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("x-api-key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.airweave.ai/source-connections") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["x-api-key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"short_name\": \"github\",\n \"readable_collection_id\": \"customer-support-tickets-x7k9m\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.airweave.ai/source-connections") .header("x-api-key", "") .header("Content-Type", "application/json") .body("{\n \"short_name\": \"github\",\n \"readable_collection_id\": \"customer-support-tickets-x7k9m\"\n}") .asString(); ``` ```php request('POST', 'https://api.airweave.ai/source-connections', [ 'body' => '{ "short_name": "github", "readable_collection_id": "customer-support-tickets-x7k9m" }', 'headers' => [ 'Content-Type' => 'application/json', 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.airweave.ai/source-connections"); var request = new RestRequest(Method.POST); request.AddHeader("x-api-key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"short_name\": \"github\",\n \"readable_collection_id\": \"customer-support-tickets-x7k9m\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "x-api-key": "", "Content-Type": "application/json" ] let parameters = [ "short_name": "github", "readable_collection_id": "customer-support-tickets-x7k9m" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.airweave.ai/source-connections")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```