Airweave source-connections API

openapi: 3.2.0
info:
  title: Reference collections Source Connections API
  version: 1.0.0
servers:
- url: https://api.airweave.ai
  description: Production
- url: http://localhost:8001
  description: Local
tags:
- name: source-connections
paths:
  /source-connections:
    get:
      operationId: list-source-connections-get
      summary: List Source Connections
      description: 'Retrieve all source connections for your organization.


        Returns a lightweight list of source connections with essential fields for

        display and navigation. Use the collection filter to see connections within

        a specific collection.


        For full connection details including sync history, use the GET /{id} endpoint.'
      tags:
      - source-connections
      parameters:
      - name: collection
        in: query
        description: Filter by collection readable ID
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: skip
        in: query
        description: Number of connections to skip for pagination
        required: false
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Maximum number of connections to return (1-1000)
        required: false
        schema:
          type: integer
          default: 100
      - name: x-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of source connections
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SourceConnectionListItem'
        '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'
    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'
  /source-connections/{source_connection_id}:
    get:
      operationId: get-source-connections-source-connection-id-get
      summary: Get Source Connection
      description: 'Retrieve details of a specific source connection.


        Returns complete information about the connection including:

        - Configuration settings

        - Authentication status

        - Sync schedule and history

        - Entity statistics'
      tags:
      - source-connections
      parameters:
      - name: source_connection_id
        in: path
        description: Unique identifier of the source connection (UUID)
        required: true
        schema:
          type: string
          format: uuid
      - name: x-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Source connection details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnection'
        '404':
          description: Source Connection Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
    patch:
      operationId: update-source-connections-source-connection-id-patch
      summary: Update Source Connection
      description: 'Update an existing source connection''s configuration.


        You can modify:

        - **Name and description**: Display information

        - **Configuration**: Source-specific settings (e.g., repository name, filters)

        - **Schedule**: Cron expression for automatic syncs

        - **Authentication**: Update credentials (direct auth only)


        Only include the fields you want to change; omitted fields retain their current values.'
      tags:
      - source-connections
      parameters:
      - name: source_connection_id
        in: path
        description: Unique identifier of the source connection to update (UUID)
        required: true
        schema:
          type: string
          format: uuid
      - name: x-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Updated source connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnection'
        '404':
          description: Source Connection Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '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/SourceConnectionUpdate'
    delete:
      operationId: delete-source-connections-source-connection-id-delete
      summary: Delete Source Connection
      description: "Permanently delete a source connection and all its synced data.\n\n**What happens when you delete:**\n\n1. Any running sync is cancelled and the API waits (up to 15 s) for the\n   worker to stop writing.\n2. The source connection, sync configuration, job history, and entity\n   metadata are cascade-deleted from the database.\n3. A background cleanup workflow is scheduled to remove data from the\n   vector database (Vespa) and raw data storage (ARF). This may take\n   several minutes for large datasets but does **not** block the response.\n\nThe API returns immediately after step 2. Vector database cleanup happens\nasynchronously -- the data becomes unsearchable as soon as the database\nrecords are deleted.\n\n**Warning**: This action cannot be undone."
      tags:
      - source-connections
      parameters:
      - name: source_connection_id
        in: path
        description: Unique identifier of the source connection to delete (UUID)
        required: true
        schema:
          type: string
          format: uuid
      - name: x-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted source connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnection'
        '404':
          description: Source Connection Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
  /source-connections/{source_connection_id}/jobs:
    get:
      operationId: get-source-connection-jobs-source-connections-source-connection-id-jobs-get
      summary: List Sync Jobs
      description: "Retrieve the sync job history for a source connection.\n\nReturns a list of sync jobs ordered by creation time (newest first). Each job\nincludes status, timing information, and entity counts.\n\nJob statuses:\n- **PENDING**: Job is queued, waiting for the worker to pick it up\n- **RUNNING**: Sync is actively pulling and processing data\n- **COMPLETED**: Sync finished successfully\n- **FAILED**: Sync encountered an unrecoverable error\n- **CANCELLING**: Cancellation has been requested. The worker is\n  gracefully stopping the pipeline and cleaning up destination data.\n- **CANCELLED**: Sync was cancelled. The worker has fully stopped\n  and destination data cleanup has been scheduled."
      tags:
      - source-connections
      parameters:
      - name: source_connection_id
        in: path
        description: Unique identifier of the source connection (UUID)
        required: true
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        description: Maximum number of jobs to return (1-1000)
        required: false
        schema:
          type: integer
          default: 100
      - name: x-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of sync jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SourceConnectionJob'
        '404':
          description: Source Connection Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
  /source-connections/{source_connection_id}/run:
    post:
      operationId: run-source-connections-source-connection-id-run-post
      summary: Run Sync
      description: 'Trigger a data synchronization job for a source connection.


        Starts an asynchronous sync job that pulls the latest data from the connected

        source. The job runs in the background and you can monitor its progress using

        the jobs endpoint.


        For continuous sync connections, this performs an incremental sync by default.

        Use `force_full_sync=true` to perform a complete re-sync of all data.'
      tags:
      - source-connections
      parameters:
      - name: source_connection_id
        in: path
        description: Unique identifier of the source connection to sync (UUID)
        required: true
        schema:
          type: string
          format: uuid
      - name: force_full_sync
        in: query
        description: Force a full sync ignoring cursor data. Only applies to continuous sync connections. Non-continuous connections always perform full syncs.
        required: false
        schema:
          type: boolean
          default: false
      - name: x-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Created sync job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnectionJob'
        '404':
          description: Source Connection Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '409':
          description: Sync Already Running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
  /source-connections/{source_connection_id}/jobs/{job_id}/cancel:
    post:
      operationId: cancel-job-source-connections-source-connection-id-jobs-job-id-cancel-post
      summary: Cancel Sync Job
      description: "Request cancellation of a running sync job.\n\n**State lifecycle**: `PENDING` / `RUNNING` → `CANCELLING` → `CANCELLED`\n\n1. The API immediately marks the job as **CANCELLING** in the database.\n2. A cancellation signal is sent to the Temporal workflow.\n3. The worker receives the signal, gracefully stops the sync pipeline\n   (cancels worker pool, source stream), and marks the job as **CANCELLED**.\n\nAlready-processed entities are retained in the vector database.\nIf the worker is unresponsive, a background cleanup job will force the\ntransition to CANCELLED after 3 minutes.\n\n**Note**: Only jobs in `PENDING` or `RUNNING` state can be cancelled.\nAttempting to cancel a `COMPLETED`, `FAILED`, or `CANCELLED` job returns 400."
      tags:
      - source-connections
      parameters:
      - name: source_connection_id
        in: path
        description: Unique identifier of the source connection (UUID)
        required: true
        schema:
          type: string
          format: uuid
      - name: job_id
        in: path
        description: Unique identifier of the sync job to cancel (UUID)
        required: true
        schema:
          type: string
          format: uuid
      - name: x-api-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Job with cancellation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnectionJob'
        '404':
          description: Job Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '409':
          description: Job Cannot Be Cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
components:
  schemas:
    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
    SourceConnectionJob:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the sync job
        source_connection_id:
          type: string
          format: uuid
          description: ID of the source connection this job belongs to
        status:
          $ref: '#/components/schemas/SyncJobStatus'
          description: 'Current status: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED, or CANCELLING'
        started_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the job started execution (ISO 8601)
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the job finished (ISO 8601). Null if still running.
        duration_seconds:
          type:
          - number
          - 'null'
          format: double
          description: Total execution time in seconds. Null if still running.
        entities_inserted:
          type: integer
          default: 0
          description: Number of new entities created during this sync
        entities_updated:
          type: integer
          default: 0
          description: Number of existing entities updated during this sync
        entities_deleted:
          type: integer
          default: 0
          description: Number of entities removed during this sync
        entities_failed:
          type: integer
          default: 0
          description: Number of entities that failed to process
        error:
          type:
          - string
          - 'null'
          description: Error message if the job failed
        error_category:
          oneOf:
          - $ref: '#/components/schemas/SourceConnectionErrorCategory'
          - type: 'null'
          description: Error category for credential errors (e.g. oauth_credentials_expired)
        error_details:
          type:
          - object
          - 'null'
          additionalProperties:
            description: Any type
          description: Additional error context for debugging
      required:
      - id
      - source_connection_id
      - status
      description: 'A sync job representing a single synchronization run.


        Sync jobs track the execution of data synchronization from a source connection.

        Each job includes timing information, entity counts, and error details if applicable.'
      title: SourceConnectionJob
    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
    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
    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
    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
    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
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      title: HTTPValidationError
    ValidationErrorLocItems:
      oneOf:
      - type: string
      - type: integer
      title: ValidationErrorLocItems
    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
    ConflictErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing the conflict
      required:
      - detail
      description: 'Response returned when a resource conflict occurs (HTTP 409).


        This typically occurs when attempting to create a resource that already exists,

        or when an operation cannot be completed due to the current state of a resource.'
      title: ConflictErrorResponse
    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
    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
    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
    ValidationError:
      type: object
      properties:
        loc:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorLocItems'
        msg:
          type: string
        type:
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SourceConnectionUpdateAuthentication:
      oneOf:
      - $ref: '#/components/schemas/DirectAuthentication'
      - $ref: '#/components/schemas/OAuthTokenAuthentication'
      - $ref: '#/components/schemas/OAuthBrowserAuthentication'
      - $ref: '#/components/schemas/AuthProviderAuthentication'
      description: Updated authentication credentials (direct auth only)
      title: SourceConnectionUpdateAuthentication
    NotFoundErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what was not found
      required:
      - detail
      description: Response returned when a resource is not found (HTTP 404).
      title: NotFoundErrorResponse
    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
    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
    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:
        

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/airweave/refs/heads/main/openapi/airweave-source-connections-api-openapi.yml