# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Soda Cloud API v4 Datasources API
  version: 1.0.0
extends: openapi/soda-data-data-sources-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 18
- target: $.paths['/api/v1/datasources'].get
  update:
    x-apievangelist-phrasing:
      intent: List data sources
      effect: read
      questions:
      - Which data sources are connected to my organization?
      - Can I search my data sources by name?
      instructions:
      - text: List all my data sources.
      - text: Search data sources for {search}.
        slots:
          search: query.search
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a data source
      effect: write
      questions:
      - How do I connect a new data source from a YAML configuration?
      - Can I assign a runner when I add a data source?
      instructions:
      - text: 'Create a data source from this configuration: {configurationFileContents}.'
        slots:
          configurationFileContents: requestBody.configurationFileContents
      - text: Add data source {label} on runner {runnerId} with config {configurationFileContents}.
        slots:
          label: requestBody.label
          runnerId: requestBody.runnerId
          configurationFileContents: requestBody.configurationFileContents
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/actions/testConnection'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a data source connection
      effect: read
      questions:
      - Can I check that a data source configuration connects before saving it?
      - Which runner is used when testing a connection?
      instructions:
      - text: Test the connection of {configurationFileContents} using runner {runnerId}.
        slots:
          configurationFileContents: requestBody.configurationFileContents
          runnerId: requestBody.runnerId
      - text: Start a connection test on runner {runnerId} for config {configurationFileContents}.
        slots:
          runnerId: requestBody.runnerId
          configurationFileContents: requestBody.configurationFileContents
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/actions/testConnection/{operationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check connection test result
      effect: read
      questions:
      - Did my data source connection test succeed?
      - What is the state of an asynchronous connection test?
      instructions:
      - text: Get the result of connection test {operationId}.
        slots:
          operationId: path.operationId
      - text: Poll connection test {operationId} until it finishes.
        slots:
          operationId: path.operationId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List data source roles
      effect: read
      questions:
      - What data source-level roles can I assign?
      - Which permission sets exist for individual data sources?
      instructions:
      - text: List the data source roles in my organization.
      - text: Show page {page} of data source roles.
        slots:
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom data source role
      effect: write
      questions:
      - Can I create a data source role that lets people create datasets?
      - How do I define a role limited to viewing a data source?
      instructions:
      - text: Create a data source role named {name}.
        slots:
          name: requestBody.name
      - text: Create data source role {name} with create-datasets {createDatasets} and view-datasource {viewDatasource}.
        slots:
          name: requestBody.name
          createDatasets: requestBody.createDatasets
          viewDatasource: requestBody.viewDatasource
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/roles/{roleId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a data source role
      effect: write
      questions:
      - Can I change what an existing data source role is allowed to do?
      - How do I rename a custom data source role?
      instructions:
      - text: Rename data source role {roleId} to {name}.
        slots:
          roleId: path.roleId
          name: requestBody.name
      - text: Update data source role {roleId} ({name}) so manage-settings is {manageDatasourceSettings}.
        slots:
          roleId: path.roleId
          name: requestBody.name
          manageDatasourceSettings: requestBody.manageDatasourceSettings
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/roles/{roleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a data source role
      effect: destructive
      questions:
      - How do I remove a custom data source role?
      - Can I delete a data source permission role that is no longer used?
      instructions:
      - text: Delete data source role {roleId}.
        slots:
          roleId: path.roleId
      - text: Remove the custom data source role {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/{datasourceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a data source
      effect: read
      questions:
      - What are the details of one data source?
      - Can I fetch a single data source by its ID?
      instructions:
      - text: Get data source {datasourceId}.
        slots:
          datasourceId: path.datasourceId
      - text: Show the configuration details of data source {datasourceId}.
        slots:
          datasourceId: path.datasourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/{datasourceId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a data source
      effect: write
      questions:
      - How do I change the connection configuration of an existing data source?
      - Can I move a data source to a different runner?
      instructions:
      - text: Update data source {datasourceId} with configuration {configurationFileContents}.
        slots:
          datasourceId: path.datasourceId
          configurationFileContents: requestBody.configurationFileContents
      - text: Switch data source {datasourceId} to runner {runnerId}.
        slots:
          datasourceId: path.datasourceId
          runnerId: requestBody.runnerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/{datasourceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a data source
      effect: destructive
      questions:
      - How do I disconnect a data source and everything under it?
      - Is deleting a data source done asynchronously?
      instructions:
      - text: Delete data source {datasourceId}.
        slots:
          datasourceId: path.datasourceId
      - text: Remove data source {datasourceId} and all its associated resources.
        slots:
          datasourceId: path.datasourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/{datasourceId}/diagnosticsWarehouse'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a data source's diagnostics warehouse
      effect: read
      questions:
      - Is a diagnostics warehouse enabled for this data source?
      - Where does a data source store scan results and failed rows?
      instructions:
      - text: Show the diagnostics warehouse configuration of data source {datasourceId}.
        slots:
          datasourceId: path.datasourceId
      - text: Check the diagnostics warehouse setup on data source {datasourceId}.
        slots:
          datasourceId: path.datasourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/{datasourceId}/diagnosticsWarehouse'].post
  update:
    x-apievangelist-phrasing:
      intent: Configure a data source's diagnostics warehouse
      effect: write
      questions:
      - Can I send failed rows and scan results to my own warehouse?
      - How do I choose the table name template for diagnostics data?
      instructions:
      - text: 'Enable the diagnostics warehouse on data source {datasourceId}: {enabled}.'
        slots:
          datasourceId: path.datasourceId
          enabled: requestBody.enabled
      - text: Set the diagnostics table name template for data source {datasourceId} to {tableNameTemplate}.
        slots:
          datasourceId: path.datasourceId
          tableNameTemplate: requestBody.tableNameTemplate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/{datasourceId}/discover'].post
  update:
    x-apievangelist-phrasing:
      intent: Run discovery on a data source
      effect: write
      questions:
      - Can I detect new tables in a data source without waiting for the schedule?
      - How do I trigger an on-demand discovery scan?
      instructions:
      - text: Run discovery on data source {datasourceId}.
        slots:
          datasourceId: path.datasourceId
      - text: Scan data source {datasourceId} for new tables and schemas now.
        slots:
          datasourceId: path.datasourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/{datasourceId}/onboardDatasets'].post
  update:
    x-apievangelist-phrasing:
      intent: Onboard discovered datasets
      effect: write
      questions:
      - How do I turn discovered tables into monitored datasets?
      - Can I onboard several discovered datasets from a data source at once?
      instructions:
      - text: Onboard discovered datasets {discoveredDatasetIds} in data source {datasourceId}.
        slots:
          discoveredDatasetIds: requestBody.discoveredDatasetIds
          datasourceId: path.datasourceId
      - text: Start onboarding {discoveredDatasetIds} as datasets on data source {datasourceId}.
        slots:
          discoveredDatasetIds: requestBody.discoveredDatasetIds
          datasourceId: path.datasourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/{datasourceId}/onboardDatasets/{operationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check dataset onboarding status
      effect: read
      questions:
      - Has onboarding of my discovered datasets finished?
      - What state is an onboarding operation in?
      instructions:
      - text: Get the status of onboarding {operationId} on data source {datasourceId}.
        slots:
          operationId: path.operationId
          datasourceId: path.datasourceId
      - text: Poll dataset onboarding {operationId} for data source {datasourceId}.
        slots:
          operationId: path.operationId
          datasourceId: path.datasourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/{datasourceId}/responsibilities'].get
  update:
    x-apievangelist-phrasing:
      intent: List who has access to a data source
      effect: read
      questions:
      - Which users and groups hold roles on a data source?
      - Who is responsible for this data source?
      instructions:
      - text: List responsibilities on data source {datasourceId}.
        slots:
          datasourceId: path.datasourceId
      - text: Show which users and groups have roles on data source {datasourceId}.
        slots:
          datasourceId: path.datasourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/datasources/{datasourceId}/responsibilities'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace data source access assignments
      effect: write
      questions:
      - How do I give a group a role on a data source?
      - Does updating data source responsibilities overwrite the existing list?
      instructions:
      - text: Set responsibilities on data source {datasourceId} to {responsibilities}.
        slots:
          datasourceId: path.datasourceId
          responsibilities: requestBody.responsibilities
      - text: Replace who can access data source {datasourceId} with {responsibilities}.
        slots:
          datasourceId: path.datasourceId
          responsibilities: requestBody.responsibilities
      method: generated
      generated: '2026-10-01'