Datasources | Documentation

List datasources

get

/api/v1/datasources

This endpoint allows you to list datasources in your organization.

This GET is a paginated API that uses the following parameters to request specific details:

size: Supply an integer value between 10 and 1000, inclusive. The default value is 10.
page: Supply an integer value. The default value is 0.
search: Supply a string value to filter datasources by name (case-insensitive partial match).

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Datasources

Rate limiting

60 requests/60 seconds

Authorizations

AuthorizationstringRequired

Query parameters

pageinteger · int32Optional

searchstringOptional

sizeinteger · int32Optional

Responses

200

Successful response

application/json

firstbooleanRequired

lastbooleanRequired

numberinteger · int32Required

sizeinteger · int32Required

totalElementsinteger · int32Required

totalPagesinteger · int32Required

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/api/v1/datasources

GET /api/v1/datasources HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "content": [
    {
      "createdAt": "text",
      "id": "text",
      "label": "text",
      "name": "text",
      "type": "bigquery",
      "updatedAt": "text"
    }
  ],
  "first": true,
  "last": true,
  "number": 1,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1
}

Create a datasource

post

/api/v1/datasources

Creates a new V4 datasource with the provided configuration.

The datasource type is extracted from the YAML configuration file contents.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Datasources

Rate limiting

10 requests/60 seconds

Authorizations

AuthorizationstringRequired

Body

configurationFileContentsstringRequired

labelstringOptional

runnerIdstringRequired

Responses

200

Successful response

application/json

discoveryScanIdstringOptional

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/datasources

POST /api/v1/datasources HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "configurationFileContents": "text",
  "label": "text",
  "runnerId": "text"
}

{
  "datasource": {
    "createdAt": "text",
    "id": "text",
    "label": "text",
    "name": "text",
    "type": "bigquery",
    "updatedAt": "text"
  },
  "discoveryScanId": "text"
}

Test datasource connection

post

/api/v1/datasources/actions/testConnection

This endpoint triggers an asynchronous connection test for a datasource configuration.

The response includes an operation ID that you can use to poll the status of the connection test.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Datasources

Rate limiting

10 requests/60 seconds

Authorizations

AuthorizationstringRequired

Body

configurationFileContentsstringRequired

runnerIdstringRequired

Responses

202

Accepted

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/datasources/actions/testConnection

POST /api/v1/datasources/actions/testConnection HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "configurationFileContents": "text",
  "runnerId": "text"
}

No content

Get status for async connection test

get

/api/v1/datasources/actions/testConnection/{operationId}

This endpoint allows you to check the status of an asynchronous connection test operation.

Use the operation ID returned by the test connection endpoint to poll for its current state.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Datasources

Rate limiting

60 requests/60 seconds

Authorizations

AuthorizationstringRequired

Path parameters

operationIdstringRequired

Responses

200

Successful response

application/json

idstringRequired

messagestringOptional

startedstringOptional

stateobject · enumRequiredPossible values:

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/api/v1/datasources/actions/testConnection/{operationId}

GET /api/v1/datasources/actions/testConnection/{operationId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "id": "text",
  "message": "text",
  "started": "text",
  "state": "queued"
}

Get a datasource

get

/api/v1/datasources/{datasourceId}

This endpoint allows you to retrieve a specific datasource by its ID.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Datasources

Rate limiting

1000 requests/60 seconds

Authorizations

AuthorizationstringRequired

Path parameters

datasourceIdstringRequired

Responses

200

Successful response

application/json

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/api/v1/datasources/{datasourceId}

GET /api/v1/datasources/{datasourceId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "datasource": {
    "createdAt": "text",
    "id": "text",
    "label": "text",
    "name": "text",
    "type": "bigquery",
    "updatedAt": "text"
  }
}

Update a datasource

post

/api/v1/datasources/{datasourceId}

Updates the configuration of an existing contract (V4) datasource.

Only the fields provided in the request body will be updated.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Datasources

Rate limiting

100 requests/60 seconds

Authorizations

AuthorizationstringRequired

Path parameters

datasourceIdstringRequired

Body

configurationFileContentsstringOptional

labelstringOptional

runnerIdstringOptional

Responses

200

Successful response

application/json

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/datasources/{datasourceId}

POST /api/v1/datasources/{datasourceId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "configurationFileContents": "text",
  "label": "text",
  "runnerId": "text"
}

{
  "datasource": {
    "createdAt": "text",
    "id": "text",
    "label": "text",
    "name": "text",
    "type": "bigquery",
    "updatedAt": "text"
  }
}

Delete a datasource

delete

/api/v1/datasources/{datasourceId}

Deletes an existing datasource and all its associated resources.

The deletion is performed asynchronously.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Datasources

Rate limiting

10 requests/60 seconds

Authorizations

AuthorizationstringRequired

Path parameters

datasourceIdstringRequired

Responses

200

Successful response

application/json

messagestringOptional

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

delete

/api/v1/datasources/{datasourceId}

DELETE /api/v1/datasources/{datasourceId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "message": "text"
}

Get datasource diagnostics warehouse configuration

get

/api/v1/datasources/{datasourceId}/diagnosticsWarehouse

This endpoint allows you to retrieve the diagnostics warehouse configuration for a specific datasource in your organization's Soda Cloud account. The diagnostics warehouse collects scan-related data and securely forwards it to the customer's warehouse for storage and analysis.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Datasources

Rate limiting

1000 requests/60 seconds

Authorizations

AuthorizationstringRequired

Path parameters

datasourceIdstringRequired

Responses

200

Successful response

application/json

enabledbooleanOptional

reuseDatasourcebooleanOptional

tableNameTemplatestringOptional

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/api/v1/datasources/{datasourceId}/diagnosticsWarehouse

GET /api/v1/datasources/{datasourceId}/diagnosticsWarehouse HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "enabled": true,
  "failedRowsConfiguration": {
    "actionButton": {
      "enabled": true,
      "title": "text",
      "url": "text"
    },
    "enabled": true,
    "exposeQueries": true,
    "failedRowsCollectionStrategy": {
      "maxRowCountOverride": 1,
      "threshold": 1,
      "thresholdCondition": "greaterThan",
      "type": "useDefaultMaxRowCount"
    },
    "locationMessage": "text",
    "maxRowCount": 1
  },
  "reuseDatasource": true,
  "scanAndResultsConfiguration": {
    "enabled": true
  },
  "tableNameTemplate": "text"
}

Update datasource diagnostics warehouse configuration

post

/api/v1/datasources/{datasourceId}/diagnosticsWarehouse

This endpoint allows you to update the diagnostics warehouse configuration for a specific datasource in your organization's Soda Cloud account. The diagnostics warehouse collects scan-related data and securely stores it in your warehouse for storage and analysis.

Table name template

The tableNameTemplate field controls how diagnostic tables are named in the warehouse. Use the {dataset_name} placeholder to include the source dataset name. For example, dwh_{dataset_name}_failed produces table names like dwh_orders_failed.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Datasources

Rate limiting

100 requests/60 seconds

Authorizations

AuthorizationstringRequired

Path parameters

datasourceIdstringRequired

Body

configurationFileContentsstringOptional

enabledbooleanOptional

reuseDatasourcebooleanOptional

tableNameTemplatestringOptional

Responses

200

Successful response

application/json

enabledbooleanOptional

reuseDatasourcebooleanOptional

tableNameTemplatestringOptional

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/datasources/{datasourceId}/diagnosticsWarehouse

POST /api/v1/datasources/{datasourceId}/diagnosticsWarehouse HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 450

{
  "configurationFileContents": "text",
  "enabled": true,
  "failedRowsConfiguration": {
    "actionButton": {
      "enabled": true,
      "title": "text",
      "url": "text"
    },
    "enabled": true,
    "exposeQueries": true,
    "failedRowsCollectionStrategy": {
      "maxRowCountOverride": 1,
      "threshold": 1,
      "thresholdCondition": "greaterThan",
      "type": "useDefaultMaxRowCount"
    },
    "locationMessage": "text",
    "maxRowCount": 1
  },
  "reuseDatasource": true,
  "scanAndResultsConfiguration": {
    "enabled": true
  },
  "tableNameTemplate": "text"
}

{
  "enabled": true,
  "failedRowsConfiguration": {
    "actionButton": {
      "enabled": true,
      "title": "text",
      "url": "text"
    },
    "enabled": true,
    "exposeQueries": true,
    "failedRowsCollectionStrategy": {
      "maxRowCountOverride": 1,
      "threshold": 1,
      "thresholdCondition": "greaterThan",
      "type": "useDefaultMaxRowCount"
    },
    "locationMessage": "text",
    "maxRowCount": 1
  },
  "reuseDatasource": true,
  "scanAndResultsConfiguration": {
    "enabled": true
  },
  "tableNameTemplate": "text"
}

Trigger datasource discovery

post

/api/v1/datasources/{datasourceId}/discover

This endpoint triggers a discovery scan on the specified datasource.

Discovery scans detect new tables and schemas in the datasource. Use this to run discovery on-demand instead of waiting for the scheduled cron.

The response includes a Location header and X-Soda-Scan-Id header identifying the triggered scan. Use the scan ID with the Get scan status endpoint to poll for completion.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.

Tags

Datasources

Rate limiting

10 requests/60 seconds

Authorizations

AuthorizationstringRequired

Path parameters

datasourceIdstringRequired

Responses

201

Created

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/datasources/{datasourceId}/discover

POST /api/v1/datasources/{datasourceId}/discover HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

No content

Onboard discovered datasets

post

/api/v1/datasources/{datasourceId}/onboardDatasets

This endpoint triggers the asynchronous onboarding of discovered datasets for a datasource.

Supply a list of discovered dataset IDs in the request body to onboard them as datasets.

The response includes an onboarding ID that you can use to poll the status of the onboarding process.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Users must have global role permission CREATE_NEW_DATASOURCES_AND_DATASETS to execute this call.

Tags

Datasources

Rate limiting

10 requests/60 seconds

Authorizations

AuthorizationstringRequired

Path parameters

datasourceIdstringRequired

Body

discoveredDatasetIdsstring[]Required

Responses

202

Accepted

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/datasources/{datasourceId}/onboardDatasets

POST /api/v1/datasources/{datasourceId}/onboardDatasets HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "discoveredDatasetIds": [
    "text"
  ]
}

No content

Get status for async dataset onboarding process

get

/api/v1/datasources/{datasourceId}/onboardDatasets/{operationId}

This endpoint allows you to check the status of an asynchronous dataset onboarding operation.

Use the operation ID returned by the onboard datasets endpoint to poll for its current state.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Authorization

Any Soda Cloud user in your organization may execute this query.

Tags

Datasources

Rate limiting

60 requests/60 seconds

Authorizations

AuthorizationstringRequired

Path parameters

datasourceIdstringRequired

operationIdstringRequired

Responses

200

Successful response

application/json

endedstringOptional

idstringRequired

messagestringOptional

startedstringOptional

stateobject · enumRequiredPossible values:

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/api/v1/datasources/{datasourceId}/onboardDatasets/{operationId}

GET /api/v1/datasources/{datasourceId}/onboardDatasets/{operationId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "ended": "text",
  "id": "text",
  "message": "text",
  "started": "text",
  "state": "queued"
}

hashtagList datasources

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagCreate a datasource

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagTest datasource connection

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagGet status for async connection test

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagGet a datasource

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagUpdate a datasource

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagDelete a datasource

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagGet datasource diagnostics warehouse configuration

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagUpdate datasource diagnostics warehouse configuration

hashtagTable name template

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagTrigger datasource discovery

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagOnboard discovered datasets

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

hashtagGet status for async dataset onboarding process

hashtagAuthentication

hashtagAuthorization

hashtagTags

hashtagRate limiting

List datasources

Authentication

Authorization

Tags

Rate limiting

Create a datasource

Authentication

Authorization

Tags

Rate limiting

Test datasource connection

Authentication

Authorization

Tags

Rate limiting

Get status for async connection test

Authentication

Authorization

Tags

Rate limiting

Get a datasource

Authentication

Authorization

Tags

Rate limiting

Update a datasource

Authentication

Authorization

Tags

Rate limiting

Delete a datasource

Authentication

Authorization

Tags

Rate limiting

Get datasource diagnostics warehouse configuration

Authentication

Authorization

Tags

Rate limiting

Update datasource diagnostics warehouse configuration

Table name template

Authentication

Authorization

Tags

Rate limiting

Trigger datasource discovery

Authentication

Authorization

Tags

Rate limiting

Onboard discovered datasets

Authentication

Authorization

Tags

Rate limiting

Get status for async dataset onboarding process

Authentication

Authorization

Tags

Rate limiting