Connectors API methods, requests, and responses for RawTree Cloud and RawTree BYOC.

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 for setup.

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`

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:

# 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.

{
  "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.

POST `/v1/connectors`

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:

# 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.

{
  "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.

GET `/v1/connectors/{connector_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:

# 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.

{
  "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.

DELETE `/v1/connectors/{connector_id}`

Delete connectors.

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

Request:

# 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.

{
  "deleted": true
}

Errors: 403, 404, 503. See API errors.

PATCH `/v1/connectors/{connector_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:

# 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.

{
  "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.

POST `/v1/connectors/preview`

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:

# 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.

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

POST `/v1/connectors/{connector_id}/preview`

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.

Request:

# 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.

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

Connectors

On this page