# DataHub (/docs/reference/api/apps/datahub)



DataHub [#datahub]

Configuration, connection checks, sync, and pause require an organization administrator. Read access requires organization membership.

Publish RawTree table and column metadata to DataHub. Install the DataHub app before you configure it. Record values remain private unless you enable sample values.

Configuration and sync state [#configuration-and-sync-state]

`GET` returns the saved configuration and sync status. It never returns the saved DataHub token.
For the first configuration, omit `revision`. For later changes, send the latest revision from `GET`.
A stale or missing revision returns `409`. Omit `token` to keep the saved token.
The platform instance and environment cannot change after the first configuration.

`POST /sync` returns `202` when the service accepts the request. It does not confirm that metadata reached DataHub.
Read the configuration endpoint again to inspect sync state, counts, timestamps, and errors.
`POST /pause` disables future automatic syncs. The app remains installed.

GET `/v1/apps/datahub/configuration` [#get-v1appsdatahubconfiguration]

Read DataHub configuration and sync status.

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field          | Location | Type   | Required | Notes |
| -------------- | -------- | ------ | -------- | ----- |
| `organization` | query    | string | Yes      | —     |
| `cluster`      | query    | string | Yes      | —     |

Request:

```bash
# Read DataHub configuration and sync status.
curl -X GET "https://api.rawtree.com/v1/apps/datahub/configuration?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
{
  "configuration": {
    "settings": {
      "gms_url": "https://datahub.example.com",
      "platform_instance": "rawtree-production",
      "environment": "PROD",
      "databases": [
        "analytics"
      ],
      "interval_minutes": 60
    },
    "enabled": true,
    "has_token": true,
    "revision": "11111111-1111-4111-8111-111111111111"
  },
  "sync": {
    "state": "idle",
    "tables_synced": 0,
    "columns_synced": 0
  }
}
```

PUT `/v1/apps/datahub/configuration` [#put-v1appsdatahubconfiguration]

Save DataHub configuration.

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field          | Location | Type           | Required | Notes                                                                            |
| -------------- | -------- | -------------- | -------- | -------------------------------------------------------------------------------- |
| `organization` | query    | string         | Yes      | —                                                                                |
| `cluster`      | query    | string         | Yes      | —                                                                                |
| `settings`     | body     | Settings       | Yes      | —                                                                                |
| `enabled`      | body     | boolean        | Yes      | —                                                                                |
| `token`        | body     | string or null | No       | Omit to retain the saved token. Empty clears it (operator-allowed origins only). |
| `revision`     | body     | string or null | No       | Optimistic concurrency token from GET. Omit for the first configuration.         |

Request:

```bash
# Save DataHub configuration.
curl -X PUT "https://api.rawtree.com/v1/apps/datahub/configuration?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {
    "gms_url": "https://datahub.example.com",
    "platform_instance": "rawtree-production",
    "environment": "PROD",
    "databases": [
      "analytics"
    ],
    "interval_minutes": 60
  },
  "enabled": true,
  "token": "REPLACE_WITH_DATAHUB_TOKEN"
}'
```

Expected response: **HTTP 200**.

```json
{
  "configuration": {
    "settings": {
      "gms_url": "https://datahub.example.com",
      "platform_instance": "rawtree-production",
      "environment": "PROD",
      "databases": [
        "analytics"
      ],
      "interval_minutes": 60
    },
    "enabled": true,
    "has_token": true,
    "revision": "11111111-1111-4111-8111-111111111111"
  },
  "sync": {
    "state": "idle",
    "tables_synced": 0,
    "columns_synced": 0
  }
}
```

POST `/v1/apps/datahub/pause` [#post-v1appsdatahubpause]

Pause automatic DataHub syncs.

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field          | Location | Type   | Required | Notes |
| -------------- | -------- | ------ | -------- | ----- |
| `organization` | query    | string | Yes      | —     |
| `cluster`      | query    | string | Yes      | —     |

Request:

```bash
# Pause automatic DataHub syncs.
curl -X POST "https://api.rawtree.com/v1/apps/datahub/pause?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
{
  "configuration": {
    "settings": {
      "gms_url": "https://datahub.example.com",
      "platform_instance": "rawtree-production",
      "environment": "PROD",
      "databases": [
        "analytics"
      ],
      "interval_minutes": 60
    },
    "enabled": false,
    "has_token": true,
    "revision": "11111111-1111-4111-8111-111111111111"
  },
  "sync": {
    "state": "idle",
    "tables_synced": 0,
    "columns_synced": 0
  }
}
```

POST `/v1/apps/datahub/preview` [#post-v1appsdatahubpreview]

Preview tables for DataHub.

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field          | Location | Type                | Required | Notes |
| -------------- | -------- | ------------------- | -------- | ----- |
| `organization` | query    | string              | Yes      | —     |
| `cluster`      | query    | string              | Yes      | —     |
| `databases`    | body     | array of string     | Yes      | —     |
| `table_filter` | body     | null or TableFilter | No       | —     |

Request:

```bash
# Preview tables for DataHub.
curl -X POST "https://api.rawtree.com/v1/apps/datahub/preview?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "databases": [
    "analytics"
  ],
  "table_filter": {
    "mode": "all",
    "exclude": []
  }
}'
```

Expected response: **HTTP 200**.

```json
{
  "tables": []
}
```

POST `/v1/apps/datahub/sync` [#post-v1appsdatahubsync]

Queue a DataHub sync.

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field          | Location | Type   | Required | Notes |
| -------------- | -------- | ------ | -------- | ----- |
| `organization` | query    | string | Yes      | —     |
| `cluster`      | query    | string | Yes      | —     |

Request:

```bash
# Queue a DataHub sync.
curl -X POST "https://api.rawtree.com/v1/apps/datahub/sync?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 202**.

```json
{
  "configuration": {
    "settings": {
      "gms_url": "https://datahub.example.com",
      "platform_instance": "rawtree-production",
      "environment": "PROD",
      "databases": [
        "analytics"
      ],
      "interval_minutes": 60
    },
    "enabled": true,
    "has_token": true,
    "revision": "11111111-1111-4111-8111-111111111111"
  },
  "sync": {
    "state": "queued",
    "tables_synced": 0,
    "columns_synced": 0
  }
}
```

POST `/v1/apps/datahub/test-connection` [#post-v1appsdatahubtest-connection]

Test the DataHub connection.

Use a user session or user OAuth token with `full_access`. API keys and workload tokens cannot use this method.

Parameters:

| Field          | Location | Type           | Required | Notes                                                                            |
| -------------- | -------- | -------------- | -------- | -------------------------------------------------------------------------------- |
| `organization` | query    | string         | Yes      | —                                                                                |
| `cluster`      | query    | string         | Yes      | —                                                                                |
| `settings`     | body     | Settings       | Yes      | —                                                                                |
| `enabled`      | body     | boolean        | Yes      | —                                                                                |
| `token`        | body     | string or null | No       | Omit to retain the saved token. Empty clears it (operator-allowed origins only). |
| `revision`     | body     | string or null | No       | Optimistic concurrency token from GET. Omit for the first configuration.         |

Request:

```bash
# Test the DataHub connection.
curl -X POST "https://api.rawtree.com/v1/apps/datahub/test-connection?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {
    "gms_url": "https://datahub.example.com",
    "platform_instance": "rawtree-production",
    "environment": "PROD",
    "databases": [
      "analytics"
    ],
    "interval_minutes": 60
  },
  "enabled": true,
  "token": "REPLACE_WITH_DATAHUB_TOKEN"
}'
```

Expected response: **HTTP 200**.

```json
{
  "connected": true
}
```