# Connectors (/docs/reference/api/connectors)



Connectors [#connectors]

These methods require an organization administrator. Pass organization and cluster names on every request.

Use `/v1/connectors` to manage connectors for an organization and cluster. See
the [Kafka connector guide](/docs/guides/ingest/kafka-connector) for setup.

Connector types [#connector-types]

Kafka connectors read topics with consumer groups. Postgres connectors capture changes from logical replication.
The method examples below use Kafka. For Postgres, set `type` to `postgres` and use `postgres_tables` in each destination.
Its settings require `host`, `database`, `user`, `publication`, and `slot`. The port defaults to `5432`. The password is optional.
The source publication must already exist. `create_slot_if_missing` controls whether the service creates the replication slot.
The service deletes slots that it owns when you delete the connector or change its slot. It preserves slots that already existed.
Responses hide secret values. A PATCH request preserves omitted settings and credentials.
Use `status: "paused"` to pause a connector and `status: "active"` to resume it.

GET `/v1/connectors` [#get-v1connectors]

Read connectors.

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      | Organization name |
| `cluster`      | query    | string | Yes      | Cluster name      |

Request:

```bash
# Read connectors.
curl -X GET "https://api.rawtree.com/v1/connectors?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
{
  "connectors": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "kafka-events",
      "type": "kafka",
      "destinations": [
        {
          "id": "11111111-1111-4111-8111-111111111111",
          "topics": [
            "events"
          ],
          "group_id": "rawtree-events",
          "database": "analytics",
          "table": "events"
        }
      ],
      "settings": {
        "bootstrap_servers": "broker.example.com:9092",
        "auto_offset_reset": "earliest"
      },
      "status": "active",
      "credentials_configured": false,
      "revision": 1,
      "created_at": "2026-11-09T10:00:00Z",
      "updated_at": "2026-11-09T10:00:00Z"
    }
  ]
}
```

Errors: `400`, `401`, `403`, `503`. See [API errors](/docs/reference/errors).

POST `/v1/connectors` [#post-v1connectors]

Create connectors.

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      | Organization name |
| `cluster`      | query    | string                               | Yes      | Cluster name      |
| `name`         | body     | string                               | Yes      | —                 |
| `type`         | body     | ConnectorType                        | Yes      | —                 |
| `destinations` | body     | array of ConnectorDestinationRequest | Yes      | —                 |
| `settings`     | body     | object                               | Yes      | —                 |

Request:

```bash
# Create connectors.
curl -X POST "https://api.rawtree.com/v1/connectors?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "kafka-events",
  "type": "kafka",
  "destinations": [
    {
      "topics": [
        "events"
      ],
      "database": "analytics",
      "table": "events"
    }
  ],
  "settings": {
    "bootstrap_servers": "broker.example.com:9092",
    "auto_offset_reset": "earliest"
  }
}'
```

Expected response: **HTTP 201**.

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "kafka-events",
  "type": "kafka",
  "destinations": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "topics": [
        "events"
      ],
      "group_id": "rawtree-events",
      "database": "analytics",
      "table": "events"
    }
  ],
  "settings": {
    "bootstrap_servers": "broker.example.com:9092",
    "auto_offset_reset": "earliest"
  },
  "status": "active",
  "credentials_configured": false,
  "revision": 1,
  "created_at": "2026-11-09T10:00:00Z",
  "updated_at": "2026-11-09T10:00:00Z"
}
```

Errors: `400`, `401`, `403`, `409`, `503`. See [API errors](/docs/reference/errors).

GET `/v1/connectors/{connector_id}` [#get-v1connectorsconnector_id]

Read connectors.

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      | Organization name |
| `cluster`      | query    | string | Yes      | Cluster name      |

Request:

```bash
# Read connectors.
curl -X GET "https://api.rawtree.com/v1/connectors/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "kafka-events",
  "type": "kafka",
  "destinations": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "topics": [
        "events"
      ],
      "group_id": "rawtree-events",
      "database": "analytics",
      "table": "events"
    }
  ],
  "settings": {
    "bootstrap_servers": "broker.example.com:9092",
    "auto_offset_reset": "earliest"
  },
  "status": "active",
  "credentials_configured": false,
  "revision": 1,
  "created_at": "2026-11-09T10:00:00Z",
  "updated_at": "2026-11-09T10:00:00Z"
}
```

Errors: `404`, `503`. See [API errors](/docs/reference/errors).

DELETE `/v1/connectors/{connector_id}` [#delete-v1connectorsconnector_id]

Delete connectors.

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

Request:

```bash
# Delete connectors.
curl -X DELETE "https://api.rawtree.com/v1/connectors/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"
```

Expected response: **HTTP 200**.

```json
{
  "deleted": true
}
```

Errors: `403`, `404`, `503`. See [API errors](/docs/reference/errors).

PATCH `/v1/connectors/{connector_id}` [#patch-v1connectorsconnector_id]

Update connectors.

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 |
| -------------- | -------- | ----------------------- | -------- | ----- |
| `name`         | body     | string or null          | No       | —     |
| `destinations` | body     | array or null           | No       | —     |
| `settings`     | body     | object or null          | No       | —     |
| `status`       | body     | null or ConnectorStatus | No       | —     |

Request:

```bash
# Update connectors.
curl -X PATCH "https://api.rawtree.com/v1/connectors/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "paused"
}'
```

Expected response: **HTTP 200**.

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "kafka-events",
  "type": "kafka",
  "destinations": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "topics": [
        "events"
      ],
      "group_id": "rawtree-events",
      "database": "analytics",
      "table": "events"
    }
  ],
  "settings": {
    "bootstrap_servers": "broker.example.com:9092",
    "auto_offset_reset": "earliest"
  },
  "status": "paused",
  "credentials_configured": false,
  "revision": 1,
  "created_at": "2026-11-09T10:00:00Z",
  "updated_at": "2026-11-09T10:00:00Z"
}
```

Errors: `400`, `403`, `404`, `409`, `503`. See [API errors](/docs/reference/errors).

POST `/v1/connectors/preview` [#post-v1connectorspreview]

Preview an unsaved Kafka connector.

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

Requires an organization administrator. `list_topics` accepts no parameters. `preview_topic` requires `parameters.topic` and accepts `parameters.limit` from 1 to 100. Previews do not commit consumer offsets. Saved previews use stored credentials and reject settings overrides. Postgres previews are not supported.

Request:

```bash
# Preview an unsaved Kafka connector.
curl -X POST "https://api.rawtree.com/v1/connectors/preview?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "list_topics",
  "type": "kafka",
  "settings": {
    "bootstrap_servers": "broker.example.com:9092",
    "auto_offset_reset": "earliest"
  }
}'
```

Expected response: **HTTP 200**.

```json
{
  "type": "kafka",
  "observed_at": "2026-11-09T10:00:00Z",
  "operation": "list_topics",
  "data": {
    "topics": [
      {
        "name": "events",
        "partitions": 3
      }
    ]
  }
}
```

POST `/v1/connectors/{connector_id}/preview` [#post-v1connectorsconnector_idpreview]

Preview a saved Kafka connector.

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

Requires an organization administrator. `list_topics` accepts no parameters. `preview_topic` requires `parameters.topic` and accepts `parameters.limit` from 1 to 100. Previews do not commit consumer offsets. Saved previews use stored credentials and reject settings overrides. Postgres previews are not supported.

Request:

```bash
# Preview a saved Kafka connector.
curl -X POST "https://api.rawtree.com/v1/connectors/11111111-1111-4111-8111-111111111111/preview?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "list_topics"
}'
```

Expected response: **HTTP 200**.

```json
{
  "type": "kafka",
  "observed_at": "2026-11-09T10:00:00Z",
  "operation": "list_topics",
  "data": {
    "topics": [
      {
        "name": "events",
        "partitions": 3
      }
    ]
  }
}
```