> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/data-sources/access-data-sources.md).
# Access Data Sources and Manage Requests
{% hint style="info" %}
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
{% endhint %}
## Endpoints and methods
| Method | Endpoint | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **POST** | [`/dataSource/subscribe`](#post-datasource-subscribe) | Subscribe to a data source. |
| **POST** | [`/dataSource/{dataSourceId}/access`](#post-datasource-datasourceid-access) | Add a user to a specific data source. |
| **GET** | [`/dataSource/tasks/pending`](#get-datasource-tasks-pending) | Get all pending tasks for this user and pending tasks this user has created. |
| **GET** | [`/dataSource/{dataSourceId}/tasks`](#get-datasource-datasourceid-tasks) | Returns all tasks the user has made, can approve or deny, or validate for this data source. |
| **PUT** | [`/dataSource/{dataSourceId}/access/{subscriptionId}`](#put-datasource-datasourceid-access-subscriptionid) | Change user status for a specific data source. |
| **DELETE** | [`/dataSource/{dataSourceId}/unsubscribe`](#delete-datasourcedatasourceidunsubscribe) | Unsubscribe from a data source. |
| **DELETE** | [`/dataSource/tasks/{taskId}`](#delete-datasourcetaskstaskid) | Delete the specified task. |
## `POST` `/dataSource/subscribe`
Subscribe to a data source.
```bash
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://your-immuta-url.com/dataSource/subscribe?dataSourceId=22
```
**Payload example**
```json
{
"dataSourceIds": [
22
],
"metadata": {},
"approvals": [
{
"requiredPermission": "Owner",
"specificApproverRequired": false,
"specificApprover": 2,
"ownerModelId": 23
}
],
"groupId": 12
}
```
### Query parameters
| Attribute | Description | Required |
| ------------ | -------------------------------- | -------- |
| dataSourceId | `integer` Data source ID number. | **Yes** |
### Payload parameters
| Attribute | Description | Required |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| dataSourceIds | `array` The ID of the data source the user is subscribing to. | No |
| approvals | `array` Includes details about the subscription policy on the data source: `requiredPermissions`, `specificApproverRequired`, `specificApprover`, and `ownerModelId`. | No |
### Response
Returns subscription results for the requested data source.
| Attribute | Description |
| --------- | --------------------------------------------- |
| inError | `array` Subscription requests that failed. |
| success | `array` Subscription requests that succeeded. |
```json
{
"inError": [],
"success": [{
"id": 64,
"modelId": "22",
"modelType": "datasource",
"state": "subscribed",
"metadata": {},
"admin": null,
"denialReasoning": null,
"profile": 2,
"group": null,
"expiration": null,
"acknowledgeRequired": false,
"createdAt": "2021-08-26T16:36:09.587Z",
"updatedAt": "2021-08-26T16:36:09.587Z",
"approved": true
}]
}
```
## `POST` `/dataSource/{dataSourceId}/access`
Add a user to a specific data source. Requestors cannot add themselves to a data source. To request access to a data source, [use the `/dataSource/subscribe` endpoint](#post-datasource-subscribe).
**Required**: The global `GOVERNANCE` permission or be the data source owner
```bash
curl \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://your-immuta-url.com/dataSource/22/access
```
**Payload example**
```json
{
"profileId": 3,
"state": "subscribed"
}
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ----------------------------- | -------- |
| dataSourceId | `integer` The data source ID. | **Yes** |
### Payload parameters
| Attribute | Description | Required |
| ---------- | -------------------------------------------------------------------------------------------------------------------------- | -------- |
| state | `string` The status of the user: `subscribed`, `owner`, `expert`, or `ingest`. | **Yes** |
| profileId | `integer` The profile ID of the user being added to the data source. | **Yes** |
| groupId | `integer` The ID of the group being added to the data source. | No |
| approvals | `array` Details about the user approving access: `requiredPermission`, `specificApproverRequired`, and `specificApprover`. | No |
| expiration | `date` The date the user's data source subscription ends. | No |
### Response
Returns the subscription record for the added user.
| Attribute | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | `integer` The user's subscription ID. |
| modelId | `integer` The model ID. |
| modelType | `string` The Immuta component to add the user to: `datasource` or `project`. |
| state | `string` The user's data source role, such as `subscribed`. |
| denialReasoning | `string` If the user was denied access, the reason for denial. |
| profile | `integer` The user's profile ID. |
| group | `integer` If a group was added, the group ID. |
| expiration | `date` The date the user's subscription to the data source will expire. |
| acknowledgeRequired | `boolean` If the data source is associated with a project, this value will be `true` if the user needs to confirm they have read the project acknowledgement. |
| createdAt | `timestamp` The date and time of creation. |
| updatedAt | `timestamp` The date and time of update. |
| approved | `boolean` When `true`, the user's request has been approved. |
```json
{
"id": 19,
"modelId": "1",
"modelType": "datasource",
"state": "subscribed",
"metadata": null,
"admin": 2,
"denialReasoning": null,
"profile": 3,
"group": null,
"expiration": null,
"acknowledgeRequired": false,
"createdAt": "2021-09-21T14:24:12.528Z",
"updatedAt": "2021-09-21T14:24:12.528Z",
"approved": true
}
```
## `GET` `/dataSource/tasks/pending`
Get all pending tasks for this user and pending tasks this user has created.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/tasks/pending
```
### Query parameters
| Attribute | Description | Required |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| searchText | `string` If specified, will filter results using the specified string. | No |
| searchModel | `string` Will filter the results by model type: `dataSource` or `schemaEvolution`. | No |
| offset | `integer` The number of results to skip (for paging). | No |
| size | `integer` The number of results to return per page. | No |
| schemaEvolutionConnectionString | `string` The schema evolution connection string to filter by. | No |
| countBySchemaEvolution | `boolean` If`true`, will only return the number of tasks, grouped by schema evolution. | No |
| countByDataSource | `boolean` If`true`, will only return the number of tasks, grouped by data source. | No |
| countOnly | `boolean` When `true`, will only return a count of the pending tasks. | No |
| groupByDataSource | `boolean` If `true`, will return the results as an array of `{ dataSourceId: , rows: }`. | No |
| types | `Array[string]` Filters the results by the type of task: `dataSourceCreated`, `columnAdded`, `columnDeleted`, or `columnTypeChanged`. The `dataSourceCreated`, `columnAdded`, `columnDeleted`, and `columnTypeChanged` tasks are only created if a policy that contains the `New` tag is active and [schema monitoring](/saas/configuration/integrations/data-and-integrations/registering-metadata/schema-monitoring/reference-guides/schema-monitoring.md#data-source-requests) or [object sync](/saas/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/connections-overview.md#data-source-requests) identifies a change in the remote platform. | No |
### Response
Returns incoming and outgoing pending tasks.
| Attribute | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------- |
| outgoing | `array` Includes details of the tasks or requests created by the user, such as the `count`, `type`, and `targetEmails`. |
| incoming | `array` Includes details about the tasks received by the user, such as the `count`, `type`, and `targetEmails`. |
```json
{
"outgoing": [],
"incoming": [{
"fullCount": 1,
"dataSource": {
"id": 11,
"name": "Public Customer"
},
"isOutgoing": false,
"rows": [{
"id": 1,
"state": "pending",
"type": "columnAdded",
"reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Customer\"",
"targetNames": [
"Katie"
],
"targetEmails": [
"katie@immuta.com"
],
"requester": {
"name": "Immuta System Account",
"id": 1,
"email": null
},
"dataSource": {
"id": 11,
"name": "Public Customer"
},
"createdAt": "2024-08-06T14:37:09.279+00:00",
"metadata": {
"colName": "org",
"colType": "VARCHAR(16777216)"
},
"isOutgoing": false
}]
}]
}
```
## `GET` `/dataSource/{dataSourceId}/tasks`
Returns all tasks the user has made, can approve or deny, or validate for this data source.
```bash
curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/23/tasks?sortOrder=desc
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ----------------------------- | -------- |
| dataSourceId | `integer` The data source ID. | **Yes** |
### Query parameters
| Attribute | Description | Required |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| states | `Array[string]` The state of the tasks: `pending` or `completed`. | No |
| targetProfileId | `integer` Only returns tasks where the target user has this profile ID. | No |
| requestingUserProfileId | `integer` Only returns tasks where the requesting user has this profile ID. | No |
| profileId | `integer` Returns tasks where either the target or requesting user has this profile ID. | No |
| searchText | `string` A string used to filter returned users. The query is executed with a wildcard prefix and suffix. | No |
| searchModel | `string` A string used to determine how results should be filtered using searchText. | No |
| types | `Array[string]` The type of task: `dataSourceCreated`, `columnAdded`, `columnDeleted`, or `columnTypeChanged`. The `dataSourceCreated`, `columnAdded`, `columnDeleted`, and `columnTypeChanged` tasks are only created if a policy that contains the `New` tag is active and [schema monitoring](/saas/configuration/integrations/data-and-integrations/registering-metadata/schema-monitoring/reference-guides/schema-monitoring.md#data-source-requests) or a [object sync](/saas/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/connections-overview.md#data-source-requests) identifies a change in the remote platform. | No |
| size | `integer` The number of results to return. | No |
| offset | `integer` The number of results to skip (for paging). | No |
| sortField | `string` The field by which to sort the result set. | No |
| sortOrder | `string` The order in which to sort the results. **The default is `desc`.** | No |
| countOnly | `boolean` If `true`, will only return the number of tasks. | No |
### Response
Returns matching tasks for the specified data source.
| Attribute | Description |
| --------- | --------------------------------------------------------------------------------------------- |
| hits | `array` Includes details about each task, such as the `id`, `state`, `type`, and `requestor`. |
| count | `integer` The total number of tasks. |
```json
{
"hits": [
{
"fullCount": 2,
"id": 6,
"state": "completed",
"type": "columnAdded",
"reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Customer\"",
"targetNames": [
"John"
],
"targetEmails": [
"john@example.com"
],
"requester": {
"name": "Immuta System Account",
"id": 1
},
"dataSource": {
"id": 11,
"name": "Public Customer"
},
"createdAt": "2021-10-12T15:48:23.095Z"
},
{
"fullCount": 2,
"id": 7,
"state": "completed",
"type": "columnAdded",
"reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Fake Medical Claims 2017\"",
"targetNames": [
"John"
],
"targetEmails": [
"john@example.com"
],
"requester": {
"name": "Immuta System Account",
"id": 1
},
"dataSource": {
"id": 3,
"name": "Public Fake Medical Claims 2017"
},
"createdAt": "2021-10-12T18:56:22.954Z"
}
],
"count": 2
}
```
## `PUT` `/dataSource/{dataSourceId}/access/{subscriptionId}`
{% hint style="info" %}
The `/dataSource/{dataSourceId}/access/{subscriptionId}` endpoint cannot be used for connection-backed data sources when updating a user to an owner. To complete this action on any connection-backed data sources, use the [`/data`](/saas/developer-guides/api-intro/connections-api/how-to-guides/manage-a-connection.md) endpoint to update the `dataOwners`.
{% endhint %}
Change user status for a specific data source. Requestors cannot update their own status for a data source.
**Required**: The global `GOVERNANCE` permission or be the data source owner
```bash
curl \
--request PUT \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
--data @example-payload.json \
https://your-immuta-url.com/dataSource/23/access/95
```
**Payload example**
```json
{
"state": "subscribed"
}
```
### Path parameters
| Attribute | Description | Required |
| -------------- | --------------------------------------------------- | -------- |
| dataSourceId | `Integer` The data source ID. | **Yes** |
| subscriptionId | `Integer` The data source member's subscription ID. | **Yes** |
### Payload parameters
| Attribute | Description | Required |
| --------- | ---------------------------------------------------------------------------------- | -------- |
| state | `string` The new status for the user: `subscribed`, `owner`, `expert` or `ingest`. | **Yes** |
### Response
Returns the updated subscription record for the data source member.
| Attribute | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| id | `integer` The data source member's subscription ID. |
| modelId | `integer` The model ID. |
| modelType | `array` The Immuta component the user's subscription is updated for: `datasource` or `project`. |
| state | `array` The current state of the user's role: `subscribed`, `owner`, `expert`, or `ingest`. |
| profile | `integer` The profile ID. |
| group | `integer` If a group's status is being updated, this is the group ID. |
| expiration | `timestamp` The date the user will no longer have access to the data source. |
| acknowledgeRequired | `boolean` This attribute is specific to projects. When `true` the user needs to confirm they have read the project acknowledgement statement. |
| createdAt | `timestamp` The date and time created. |
| updatedAt | `timestamp` The date and time updated. |
| originalState | `array` The user's previous status for the data source. |
| approved | `boolean` If `true`, the status is approved. |
```json
{
"id": 95,
"modelId": "3",
"modelType": "datasource",
"state": "subscribed",
"metadata": {},
"admin": 2,
"profile": 3,
"group": null,
"expiration": null,
"acknowledgeRequired": false,
"createdAt": "2021-10-12T15:40:13.878Z",
"updatedAt": "2021-10-12T16:10:46.801Z",
"originalState": "expert",
"approved": true
}
```
## `DELETE` `/dataSource/{dataSourceId}/unsubscribe`
Unsubscribe from a data source.
```bash
curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/23/unsubscribe
```
### Path parameters
| Attribute | Description | Required |
| ------------ | ----------------------------- | -------- |
| dataSourceId | `integer` The data source ID. | **Yes** |
### Response
Returns subscription status for the requesting user.
| Attribute | Description |
| --------- | ------------------------------------------------------------------------------ |
| success | `boolean` If `true`, the requesting user is unsubscribed from the data source. |
```json
{
"success": true
}
```
## `DELETE` `/dataSource/tasks/{taskId}`
Delete the specified task.
```bash
curl \
--request DELETE \
--header "Content-Type: application/json" \
--header "Authorization: Bearer dea464c07bd07300095caa8" \
https://your-immuta-url.com/dataSource/tasks/8
```
### Path parameters
| Attribute | Description | Required |
| --------- | ------------------------- | -------- |
| taskId | `integer` Target task ID. | **Yes** |
### Response
Returns details for the deleted task.
| Attribute | Description |
| ------------ | ------------------------------------------------------------- |
| id | `integer` The deleted task ID. |
| state | `string` The state of the deleted task, such as `pending`. |
| type | `string` The type of deleted task, such as `columnAdded`. |
| targetNames | `array[string]` The names of users who received the request. |
| targetEmails | `array[string]` The emails of users who received the request. |
| requester | `metadata` Details regarding the requesting profile. |
| dataSource | `metadata` details regarding the data source. |
| metadata | `array` Details about the deleted task. |
```json
{
"fullCount": 1,
"id": 8,
"state": "pending",
"type": "columnAdded",
"reason": "Immuta has detected a new column \"org\" in the remote table and has added it to \"Public Customer\"",
"targetNames": ["Katie"],
"targetEmails": ["katie@example.com"],
"requester": {
"name": "Immuta System Account",
"id": 1
},
"dataSource": {
"id": 11,
"name": "Public Customer"
},
"createdAt": "2021-10-12T19:28:04.999Z"
}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/data-sources/access-data-sources.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.