> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Connectors

> Retrieve a list of connector records with advanced filtering, sorting, and include capabilities. This endpoint supports:

**Default behavior**: Returns all connectors associated with the workspace_id and organization extracted from the authentication token.

**Include functionality**: Use the `include` parameter to get full details of related resources in the response.

**Date filtering**: Filter by creation or update date ranges using `created_at_from/to` and `updated_at_from/to`.

**Relationship filtering**: Filter by related entities using `workspace_id`, `published_by`, etc.

**Category filtering**: Filter by connector categories like `crm`, `api`, `database`, etc.

**Status filtering**: Filter by connector status and data synchronization state.

**Sorting**: Sort results by `created_at`, `updated_at`, `name`, or `category` in ascending or descending order.

## Filtering & sorting on related objects

Filter and sort on a **related (included) object** by nesting into the relationship — the same relationships you pass to `include`.

* **To-one** relations nest directly: `{ "issuer": { "name": { "_eq": "Acme" } } }`, and sort by a dot-path: `"orderBy": { "field": "issuer.name", "direction": "asc" }`.
* **To-many** relations must be quantified with `_some`, `_every`, or `_none`: `{ "items": { "_some": { "quantity": { "_gt": 1 } } } }`. They are **not** directly sortable (a to-many sort needs an aggregate proxy).
* **Composite** `composite_*` columns are virtual — filter and sort on their underlying source fields, not on the composite.

Workspace row-level security applies at every hop, so a related-object filter never widens your tenant scope. Full operator set, deep-nesting rules, and pagination notes: [Filtering & sorting](/api-reference/filtering-and-sorting).

This resource's related objects (the ones you can `include`) and how to filter or sort on each:

| Relationship           | Cardinality                  | Filter on a field                                                         | Sort by a field                              |
| ---------------------- | ---------------------------- | ------------------------------------------------------------------------- | -------------------------------------------- |
| `workspace_connectors` | to-many (WorkspaceConnector) | `{ "workspace_connectors": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️                      |
| `connector_filters`    | to-many (ConnectorFilter)    | `{ "connector_filters": { "_some": { "field_name": { "_eq": … } } } }`    | aggregate proxy only ⚠️                      |
| `provider_connector`   | to-one (ProviderConnector)   | `{ "provider_connector": { "field_name": { "_eq": … } } }`                | `"field": "provider_connector.field_name"` ✅ |

Replace `field_name` with any field of the related object. See its object-reference page for the full field list.

**Filter by a to-one relation** (and sort by it):

```json theme={null}
{
  "root": "connectors",
  "whereClause": { "provider_connector": { "field_name": { "_ilike": "%acme%" } } },
  "orderBy": { "field": "provider_connector.field_name", "direction": "asc" }
}
```

**Filter by a to-many relation** (quantified — bare nesting is invalid):

```json theme={null}
{
  "root": "connectors",
  "whereClause": { "workspace_connectors": { "_some": { "field_name": { "_gt": 0 } } } }
}
```


## OpenAPI

````yaml GET /v1/connectors
openapi: 3.1.0
info:
  title: Well Document API
  version: 1.0.0
  description: API for uploading and managing financial documents in the Well platform
servers:
  - url: https://api.wellapp.ai
security: []
paths:
  /v1/connectors:
    get:
      tags:
        - Connectors
      summary: List connectors
      description: >-
        Retrieve a list of connector records with advanced filtering, sorting,
        and include capabilities. This endpoint supports:


        **Default behavior**: Returns all connectors associated with the
        workspace_id and organization extracted from the authentication token.


        **Include functionality**: Use the `include` parameter to get full
        details of related resources in the response.


        **Date filtering**: Filter by creation or update date ranges using
        `created_at_from/to` and `updated_at_from/to`.


        **Relationship filtering**: Filter by related entities using
        `workspace_id`, `published_by`, etc.


        **Category filtering**: Filter by connector categories like `crm`,
        `api`, `database`, etc.


        **Status filtering**: Filter by connector status and data
        synchronization state.


        **Sorting**: Sort results by `created_at`, `updated_at`, `name`, or
        `category` in ascending or descending order.
      operationId: listConnectors
      parameters:
        - $ref: '#/components/parameters/AuthorizationHeader'
        - name: include
          in: query
          required: false
          schema:
            type: string
          description: >-
            Comma-separated list of related resources to include. Available
            options: published_by, logo, category
          example: published_by,logo
        - name: created_at_from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter connectors created from this date (ISO 8601 format)
          example: '2025-01-01T00:00:00Z'
        - name: created_at_to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter connectors created until this date (ISO 8601 format)
          example: '2025-12-31T23:59:59Z'
        - name: updated_at_from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter connectors updated from this date (ISO 8601 format)
          example: '2025-01-01T00:00:00Z'
        - name: updated_at_to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter connectors updated until this date (ISO 8601 format)
          example: '2025-12-31T23:59:59Z'
        - name: workspace_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter by workspace ID that published the connector
          example: 550e8400-e29b-41d4-a716-446655440000
        - name: published_by
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter by workspace that published the connector
          example: 550e8400-e29b-41d4-a716-446655440000
        - name: category
          in: query
          required: false
          schema:
            type: string
            enum:
              - database
              - data_warehouse
              - other
          description: >-
            Filter by connector category. See [all available
            categories](/enums/category-connector) for complete list.
          example: crm
        - name: direction
          in: query
          required: false
          schema:
            type: string
            enum:
              - import
              - export
              - both
          description: Filter by data flow direction capability
          example: import
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - active
              - inactive
              - pending
              - deprecated
          description: Filter by connector status
          example: active
        - name: name
          in: query
          required: false
          schema:
            type: string
          description: Filter by connector name (partial match, case-insensitive)
          example: Salesforce
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - created_at
              - '-created_at'
              - updated_at
              - '-updated_at'
              - name
              - '-name'
              - category
              - '-category'
          description: >-
            Sort by field. Use '-' prefix for descending order (e.g.,
            '-created_at' for newest first)
          example: '-created_at'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: Number of results to return per page
          example: 25
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number for pagination
          example: 1
      responses:
        '200':
          description: Connectors retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorListResponse'
              example:
                data:
                  - type: connector
                    id: f47ac10b-58cc-4372-a567-0e02b2c3d479
                    attributes:
                      slug: salesforce
                      name: Salesforce
                      description: Connects to Salesforce CRM for sync.
                      category: crm
                      direction: import
                      tags:
                        - crm
                        - cloud
                        - sync
                      status: active
                      version: 2.1.0
                      data_quality:
                        imported_fields:
                          - invoice
                          - company
                          - people
                        last_synced: '2025-06-20T09:00:00Z'
                      redirect_url: https://app.well.com/connectors/salesforce/success
                      state: active
                      created_at: '2025-10-07T14:30:00.000Z'
                      updated_at: '2025-10-07T14:30:00.000Z'
                    relationships:
                      published_by:
                        data:
                          type: organization
                          id: 550e8400-e29b-41d4-a716-446655440001
                      logo:
                        data:
                          type: media
                          id: 550e8400-e29b-41d4-a716-446655440002
                  - type: connector
                    id: a1b2c3d4-58cc-4372-a567-0e02b2c3d480
                    attributes:
                      slug: github
                      name: GitHub
                      description: Connects to GitHub for repository management and CI/CD.
                      category: ci_cd
                      direction: both
                      tags:
                        - git
                        - version-control
                        - ci-cd
                      status: active
                      version: 1.5.2
                      data_quality:
                        imported_fields:
                          - company
                          - people
                        last_synced: '2025-06-19T15:30:00Z'
                      redirect_url: https://app.well.com/connectors/github/success
                      state: active
                      created_at: '2025-09-15T08:00:00.000Z'
                      updated_at: '2025-10-01T12:00:00.000Z'
                    relationships:
                      published_by:
                        data:
                          type: organization
                          id: 550e8400-e29b-41d4-a716-446655440001
                      logo:
                        data:
                          type: media
                          id: 550e8400-e29b-41d4-a716-446655440003
                included:
                  - type: organization
                    id: 550e8400-e29b-41d4-a716-446655440001
                    attributes:
                      name: Well Technologies
                      description: >-
                        Open-source data integration and financial technology
                        platform
                      website: https://well.com
                      external_id: well_org_001
                  - type: media
                    id: 550e8400-e29b-41d4-a716-446655440002
                    attributes:
                      file_name: salesforce_logo.png
                      content_type: image/png
                      file_size: 15420
                      media_type: logo
                      upload_url: https://storage.well.com/media/salesforce_logo.png
                  - type: media
                    id: 550e8400-e29b-41d4-a716-446655440003
                    attributes:
                      file_name: github_logo.png
                      content_type: image/png
                      file_size: 18750
                      media_type: logo
                      upload_url: https://storage.well.com/media/github_logo.png
                meta:
                  page: 1
                  limit: 25
                  total: 2
                  total_pages: 1
        '401':
          description: Unauthorized - invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
components:
  parameters:
    AuthorizationHeader:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
      description: Bearer token for authentication
  schemas:
    ConnectorListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                const: connector
              id:
                type: string
                format: uuid
                description: UUID of the connector
                example: 550e8400-e29b-41d4-a716-446655440000
              attributes:
                $ref: '#/components/schemas/ConnectorAttributesPostResponse'
              relationships:
                $ref: '#/components/schemas/ConnectorRelationshipsPostResponse'
              included:
                $ref: '#/components/schemas/ConnectorIncludedPostResponse'
        meta:
          type: object
          properties:
            page:
              type: integer
              description: Current page number
              example: 1
            limit:
              type: integer
              description: Number of items per page
              example: 25
            total:
              type: integer
              description: Total number of items
              example: 100
            total_pages:
              type: integer
              description: Total number of pages
              example: 4
    UnauthorizedError:
      type: object
      properties:
        code:
          type: string
          example: UNAUTHORIZED
          description: Error code identifier
        status:
          type: integer
          example: 401
          description: HTTP status code
        title:
          type: string
          example: Unauthorized
          description: Error title
        message:
          type: string
          example: You are not authorized to access this resource
          description: Detailed error message
        meta:
          type: object
          properties:
            log_id:
              type: string
              format: uuid
              example: 65c669d4-679c-4a8b-b8c0-fbe37699bb5b
              description: Unique identifier for tracking this error in logs
          required:
            - log_id
      required:
        - code
        - status
        - title
        - message
        - meta
    ConnectorAttributesPostResponse:
      type: object
      properties:
        slug:
          type: string
          maxLength: 255
          pattern: ^[a-z0-9_-]+$
          description: Connector slug used in URLs (system generated if not provided)
          example: salesforce
        name:
          type: string
          maxLength: 255
          description: Connector name
          example: Salesforce
        description:
          type: string
          maxLength: 1000
          description: Description of the connector
          example: Connects to Salesforce CRM for sync.
        category:
          type: string
          enum:
            - database
            - ...
          description: >-
            Integration category. See [all available
            categories](/enums/category-connector) for complete list.
          example: api
        direction:
          type: string
          enum:
            - import
            - export
            - both
          description: Data flow direction capability
          example: import
        tags:
          type: array
          items:
            type: string
          description: Grouping/search tags
          example:
            - crm
            - cloud
            - sync
        data_quality:
          type: object
          properties:
            imported_fields:
              type: array
              items:
                type: string
                enum:
                  - invoice
                  - company
                  - people
              description: >-
                Category connector. See [all available
                categories](/enums/category-connector) for complete list.
              example:
                - invoice
                - company
                - people
            last_synced:
              type: string
              format: date-time
              description: Timestamp of last sync
              example: '2025-06-20T09:00:00Z'
        redirect_url:
          type: string
          format: uri
          description: URL to redirect customers after onboarding flow
          example: https://app.well.com/connectors/salesforce/success
        state:
          type: string
          description: State included in the redirect URL
          example: active
        status:
          type: string
          enum:
            - active
            - beta
            - deprecated
          description: Lifecycle status (system managed)
          example: active
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
          example: '2025-10-07T14:30:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2025-10-07T14:30:00.000Z'
    ConnectorRelationshipsPostResponse:
      type: object
      properties:
        published_by:
          type: object
          properties:
            data:
              type: object
              properties:
                type:
                  type: string
                  const: workspace
                id:
                  type: string
                  format: uuid
                  description: UUID of the workspace that published this connector
                  example: 550e8400-e29b-41d4-a716-446655440001
        logo:
          type: object
          properties:
            data:
              type: object
              properties:
                type:
                  type: string
                  const: media
                id:
                  type: string
                  format: uuid
                  description: UUID of the logo media
                  example: 550e8400-e29b-41d4-a716-446655440010
    ConnectorIncludedPostResponse:
      type: object
      description: >-
        Object containing included resources referenced in relationships,
        organized by resource type. These are the actual created/linked
        resources with real UUIDs.
      properties:
        published_by:
          type: object
          description: Workspaces associated with this company
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    const: workspace
                  id:
                    type: string
                    format: uuid
                    description: UUID of the workspace
                  attributes:
                    $ref: '#/components/schemas/WorkspaceCreateAttributes'
        media:
          type: object
          description: Media files associated with this company
          properties:
            data:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    const: media
                  id:
                    type: string
                    format: uuid
                    description: UUID of the media
                  attributes:
                    $ref: '#/components/schemas/MediaAttributes'
    WorkspaceCreateAttributes:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Workspace name
        description:
          type: string
          maxLength: 1000
          description: Workspace description
        avatar_color:
          type: string
          pattern: ^#[A-Fa-f0-9]{6}$
          description: 'Avatar color in hexadecimal format (e.g., #FF5733)'
        external_workspace_id:
          type: string
          minLength: 1
          maxLength: 255
          description: External workspace identifier
      required:
        - name
    MediaAttributes:
      type: object
      properties:
        media_type:
          type: string
          enum:
            - avatar
            - logo
            - banner
        url:
          type: string
          format: uri
          description: URL to the media file
        is_primary:
          type: boolean
          description: Whether this is the primary media
        processed_at:
          type:
            - string
          format: date-time
          description: Timestamp when media processing completed
        uploaded_at:
          type: string
          format: date-time

````