Felt Sources API

openapi: 3.0.0
info:
  description: Felt REST API v2.0
  title: Felt Comments Sources API
  version: '2.0'
servers:
- url: https://felt.com
  variables: {}
security: []
tags:
- description: 'Sources connect your databases to Felt.


    With these APIs, you can configure data source connections, credentials, and sync settings to create live maps.

    '
  name: Sources
  x-page-description: APIs to connect your data
  x-page-icon: database
paths:
  /api/v2/sources/{source_id}/update:
    post:
      callbacks: {}
      description: 'Update data source connection settings, access permissions, or configuration details.


        Connecting the Source and inspecting its datasets will happen asynchronously after the API response is returned. To determine when the inspection process has completed, poll the Show Source endpoint and check for `sync_status: completed`.

        '
      operationId: update_source
      parameters:
      - description: The ID of the source to update
        in: path
        name: source_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceUpdateParams'
        description: Source update params
        required: false
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceReference'
          description: Source reference
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Update source
      tags:
      - Sources
  /api/v2/sources:
    get:
      callbacks: {}
      description: Retrieve all data sources accessible to the authenticated user within the workspace.
      operationId: list_sources
      parameters:
      - description: Only needed when using the API as part of a plugin
        in: query
        name: workspace_id
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceReferenceList'
          description: Source references
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: List sources
      tags:
      - Sources
      x-sort-order: 0
    post:
      callbacks: {}
      description: 'Create a new data source connection with authentication credentials and access permissions.


        Connecting the Source and inspecting its datasets will happen asynchronously after the API response is returned. To determine when the inspection process has completed, poll the Show Source endpoint and check for `sync_status: completed`.

        '
      operationId: create_source
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceCreateParams'
        description: Source create params
        required: false
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceReference'
          description: Source reference
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Create source
      tags:
      - Sources
  /api/v2/sources/{source_id}/sync:
    post:
      callbacks: {}
      description: 'Trigger a full data synchronization from the source to update all connected layers with latest data.


        Syncing will happen asynchronously after the API response is returned. To determine when the inspection process has completed, poll the Show Source endpoint and check for `sync_status: completed`.

        '
      operationId: sync_source
      parameters:
      - description: The ID of the source to sync
        in: path
        name: source_id
        required: true
        schema:
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceReference'
          description: Source reference
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Sync source
      tags:
      - Sources
  /api/v2/sources/{source_id}:
    delete:
      callbacks: {}
      description: 'Permanently delete a data source connection and all its associated layers and data.


        {% hint style="warning" %}

        Any layers created from the Source will remain after it is deleted, but they will no longer be refreshed.

        {% endhint %}

        '
      operationId: delete_source
      parameters:
      - description: The ID of the source to delete
        in: path
        name: source_id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Delete source
      tags:
      - Sources
    get:
      callbacks: {}
      description: Retrieve detailed configuration and connection information for a specific data source.
      operationId: show_source
      parameters:
      - description: The ID of the source to show
        in: path
        name: source_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Source'
          description: Source
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Get source
      tags:
      - Sources
  /api/v2/sources/{source_id}/credentials:
    post:
      callbacks: {}
      description: 'Add authentication credentials to an existing data source for secure access.


        Some sources may need to be configured with additional credentials to work with Felt. Access to S3 Buckets, for example, may be protected by IAM policies. Adding a `SourceCredential-AwsAssumeRole` credential to your S3 Bucket source allows Felt to connect to a private source.


        Sensitive fields in credentials, like `SourceCredential-KeyPair.private_key`, will be returned as `felt:redacted`.

        '
      operationId: create_source_credential
      parameters:
      - description: The ID of the source to attach the credential
        in: path
        name: source_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceCredentialCreateParams'
        description: Source create credential params
        required: false
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceCredential'
          description: Source credential created
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Create source credential
      tags:
      - Sources
  /api/v2/sources/{source_id}/credentials/{credential_id}/update:
    post:
      callbacks: {}
      description: 'Update existing authentication credentials for a data source connection.


        Sensitive fields in credentials, like `SourceCredential-KeyPair.private_key`, will be returned as `felt:redacted`.

        '
      operationId: update_source_credential
      parameters:
      - description: The ID of the source that the credential belongs to
        in: path
        name: source_id
        required: true
        schema:
          type: string
      - description: The ID of the credential
        in: path
        name: credential_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SourceCredentialUpdateParams'
        description: Source credential update params
        required: false
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceCredential'
          description: Source credential updated
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Update source credential
      tags:
      - Sources
  /api/v2/sources/{source_id}/credentials/{credential_id}:
    delete:
      callbacks: {}
      description: Remove authentication credentials from a data source connection.
      operationId: delete_source_credential
      parameters:
      - description: The ID of the source that the credential belongs to
        in: path
        name: source_id
        required: true
        schema:
          type: string
      - description: The ID of the credential to delete
        in: path
        name: credential_id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Delete source credential
      tags:
      - Sources
components:
  schemas:
    SourceConnection-ABSBucket:
      additionalProperties: false
      description: Microsoft Azure Blob Storage
      properties:
        blob_storage_url:
          type: string
        credentials:
          items:
            properties:
              created_at:
                nullable: true
                type: integer
              credential:
                oneOf:
                - $ref: '#/components/schemas/SourceCredential-AzureStorageString'
                type: object
              id:
                $ref: '#/components/schemas/FeltID'
              name:
                type: string
              source_id:
                $ref: '#/components/schemas/FeltID'
              updated_at:
                nullable: true
                type: integer
              use_case:
                enum:
                - source_authentication
                type: string
            type: object
          type: array
        type:
          enum:
          - abs_bucket
          type: string
      title: SourceConnection-ABSBucket
      type: object
    SourceCredentialUpdate-SnowflakePAT:
      additionalProperties: false
      description: Authenticate to Snowflake with a programmatic access token (PAT)
      properties:
        token:
          type: string
        type:
          enum:
          - snowflake_pat
          type: string
      required:
      - type
      title: SourceCredentialUpdate-SnowflakePAT
      type: object
    SourceConnection-STAC:
      additionalProperties: false
      description: SpatioTemporal Asset Catalogs
      properties:
        credentials:
          items:
            properties:
              created_at:
                nullable: true
                type: integer
              credential:
                oneOf:
                - $ref: '#/components/schemas/SourceCredential-GcpServiceAccountJson'
                - $ref: '#/components/schemas/SourceCredential-AzureStorageString'
                - $ref: '#/components/schemas/SourceCredential-AwsAssumeRole'
                - $ref: '#/components/schemas/SourceCredential-CustomHeaders'
                type: object
              id:
                $ref: '#/components/schemas/FeltID'
              name:
                type: string
              source_id:
                $ref: '#/components/schemas/FeltID'
              updated_at:
                nullable: true
                type: integer
              use_case:
                enum:
                - stac_api_authentication
                - stac_asset_fetching
                type: string
            type: object
          type: array
        type:
          enum:
          - stac
          type: string
        url:
          type: string
      title: SourceConnection-STAC
      type: object
    FeltID:
      example: luCHyMruTQ6ozGk3gPJfEB
      format: felt_id
      nullable: false
      title: FeltID
      type: string
    SourceCredential-CustomHeaders:
      additionalProperties: false
      description: Authenticate to an API using headers
      properties:
        headers:
          items:
            properties:
              name:
                description: The header name
                type: string
              sensitive:
                description: Whether or not the header is sensitive. If it is marked as sensitive, then `felt:redacted` will be returned when viewing this header
                type: boolean
              value:
                description: The header value
                type: string
            required:
            - name
            - value
            - sensitive
            type: object
          type: array
        type:
          enum:
          - custom_headers
          type: string
      required:
      - type
      - headers
      title: SourceCredential-CustomHeaders
      type: object
    SourceConnection-Postgres:
      additionalProperties: false
      description: Postgres / PostGIS
      properties:
        database:
          type: string
        host:
          type: string
        port:
          nullable: true
          type: integer
        schema:
          nullable: true
          type: string
        type:
          enum:
          - postgresql
          type: string
        user:
          type: string
      title: SourceConnection-Postgres
      type: object
    SourceCredential-SnowflakePAT:
      additionalProperties: false
      description: Authenticate to Snowflake with a programmatic access token (PAT)
      properties:
        token:
          type: string
        type:
          enum:
          - snowflake_pat
          type: string
      required:
      - type
      - token
      title: SourceCredential-SnowflakePAT
      type: object
    SourceConnection-Databricks:
      additionalProperties: false
      properties:
        catalog:
          nullable: true
          type: string
        credentials:
          items:
            properties:
              created_at:
                nullable: true
                type: integer
              credential:
                oneOf:
                - $ref: '#/components/schemas/SourceCredential-OAuthM2M'
                - $ref: '#/components/schemas/SourceCredential-DatabricksPAT'
                type: object
              id:
                $ref: '#/components/schemas/FeltID'
              name:
                type: string
              source_id:
                $ref: '#/components/schemas/FeltID'
              updated_at:
                nullable: true
                type: integer
              use_case:
                enum:
                - source_authentication
                type: string
            type: object
          type: array
        http_path:
          type: string
        schema:
          nullable: true
          type: string
        server_hostname:
          type: string
        type:
          enum:
          - databricks
          type: string
      title: SourceConnection-Databricks
      type: object
    SourceCreateParams:
      additionalProperties: false
      properties:
        connection:
          $ref: '#/components/schemas/SourceCreateConnectionParams'
        name:
          type: string
        permissions:
          $ref: '#/components/schemas/SourcePermissions'
      required:
      - name
      - connection
      title: SourceCreateParams
      type: object
    SourceConnection-GCSBucket:
      additionalProperties: false
      description: Google Cloud Storage
      properties:
        credentials:
          items:
            properties:
              created_at:
                nullable: true
                type: integer
              credential:
                oneOf:
                - $ref: '#/components/schemas/SourceCredential-GcpServiceAccountJson'
                type: object
              id:
                $ref: '#/components/schemas/FeltID'
              name:
                type: string
              source_id:
                $ref: '#/components/schemas/FeltID'
              updated_at:
                nullable: true
                type: integer
              use_case:
                enum:
                - source_authentication
                type: string
            type: object
          type: array
        gs_uri:
          type: string
        type:
          enum:
          - gcs_bucket
          type: string
      title: SourceConnection-GCSBucket
      type: object
    Source:
      additionalProperties: false
      properties:
        automatic_sync:
          enum:
          - enabled
          - paused
          type: string
        connection:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/SourceConnection-ABSBucket'
          - $ref: '#/components/schemas/SourceConnection-Google-BigQuery'
          - $ref: '#/components/schemas/SourceConnection-Databricks'
          - $ref: '#/components/schemas/SourceConnection-ESRI-FeatureServer'
          - $ref: '#/components/schemas/SourceConnection-GCSBucket'
          - $ref: '#/components/schemas/SourceConnection-Microsoft-SQL'
          - $ref: '#/components/schemas/SourceConnection-Postgres'
          - $ref: '#/components/schemas/SourceConnection-Amazon-Redshift'
          - $ref: '#/components/schemas/SourceConnection-S3Bucket'
          - $ref: '#/components/schemas/SourceConnection-Snowflake'
          - $ref: '#/components/schemas/SourceConnection-STAC'
          - $ref: '#/components/schemas/SourceConnection-WFS'
          - $ref: '#/components/schemas/SourceConnection-WMS-WMTS'
        created_at:
          nullable: true
          type: integer
        datasets:
          items:
            $ref: '#/components/schemas/SourceDataset'
          type: array
        id:
          $ref: '#/components/schemas/FeltID'
        last_synced_at:
          nullable: true
          type: integer
        name:
          type: string
        owner_id:
          $ref: '#/components/schemas/FeltID'
        permissions:
          $ref: '#/components/schemas/SourcePermissions'
        sync_status:
          enum:
          - syncing
          - completed
          - failed
          type: string
        type:
          enum:
          - source
          type: string
        updated_at:
          nullable: true
          type: integer
        workspace_id:
          $ref: '#/components/schemas/FeltID'
      title: Source
      type: object
    SourceCredential-AzureStorageString:
      additionalProperties: false
      description: Authenticate to Azure Blob Storage
      properties:
        connection_string:
          type: string
        type:
          enum:
          - azure_storage_connection_string
          type: string
      required:
      - type
      - connection_string
      title: SourceCredential-AzureStorageString
      type: object
    InternalServerError:
      properties:
        errors:
          items:
            properties:
              detail:
                type: string
              source:
                properties:
                  parameter:
                    type: string
                type: object
              title:
                type: string
            type: object
          type: array
      title: InternalServerError
      type: object
    UnauthorizedError:
      properties:
        errors:
          items:
            properties:
              detail:
                type: string
              source:
                properties:
                  header:
                    enum:
                    - authorization
                    type: string
                type: object
              title:
                type: string
            type: object
          type: array
      title: UnauthorizedError
      type: object
    SourceCredentialUpdateParams:
      additionalProperties: false
      properties:
        credential:
          oneOf:
          - $ref: '#/components/schemas/SourceCredentialUpdate-AwsAssumeRole'
          - $ref: '#/components/schemas/SourceCredentialUpdate-AzureStorageString'
          - $ref: '#/components/schemas/SourceCredentialUpdate-CustomHeaders'
          - $ref: '#/components/schemas/SourceCredentialUpdate-GcpServiceAccountJson'
          - $ref: '#/components/schemas/SourceCredentialUpdate-KeyPair'
          - $ref: '#/components/schemas/SourceCredentialUpdate-SnowflakePAT'
          type: object
        name:
          type: string
        use_case:
          enum:
          - stac_api_authentication
          - stac_asset_fetching
          - source_authentication
          type: string
      title: SourceCredentialUpdateParams
      type: object
    SourceConnection-Amazon-Redshift:
      additionalProperties: false
      properties:
        database:
          type: string
        host:
          type: string
        port:
          nullable: true
          type: integer
        type:
          enum:
          - redshift
          type: string
        user:
          type: string
      title: SourceConnection-Amazon-Redshift
      type: object
    SourceCredentialCreateParams:
      additionalProperties: false
      properties:
        credential:
          oneOf:
          - $ref: '#/components/schemas/SourceCredential-AwsAssumeRole'
          - $ref: '#/components/schemas/SourceCredential-AzureStorageString'
          - $ref: '#/components/schemas/SourceCredential-CustomHeaders'
          - $ref: '#/components/schemas/SourceCredential-GcpServiceAccountJson'
          - $ref: '#/components/schemas/SourceCredential-KeyPair'
          - $ref: '#/components/schemas/SourceCredential-SnowflakePAT'
          type: object
        name:
          type: string
        use_case:
          enum:
          - stac_api_authentication
          - stac_asset_fetching
          - source_authentication
          type: string
      required:
      - name
      - use_case
      - credential
      title: SourceCredentialCreateParams
      type: object
    SourceUpdateConnectionParams:
      oneOf:
      - additionalProperties: false
        properties:
          blob_storage_url:
            description: ABS blob storage URL
            type: string
          type:
            enum:
            - abs_bucket
            type: string
        required:
        - type
        title: SourceUpdateConnectionParams-ABS
        type: object
      - additionalProperties: false
        properties:
          base64_encoded_service_account:
            description: BigQuery credentials - Base 64 encoded Service account JSON
            nu

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