# Create a connection

Creates a new ClickHouse connection.

[endpoint]
base_url = "https://telemetry.betterstack.com"
path = "/api/v1/connections"
method = "POST"

[[body_param]]
name = "client_type"
description = "Type of client connection. Currently only `clickhouse` is supported."
required = true
type = "string"

[[body_param]]
name = "team_names"
description = "Array of team names to associate with the connection. Connections are organization-wide, but can be scoped to specific teams for data access control. Only one of `team_names` or `team_ids` should be provided."
required = false
type = "array"

[[body_param]]
name = "team_ids"
description = "Array of team IDs to associate with the connection. Connections are organization-wide, but can be scoped to specific teams for data access control. Only one of `team_names` or `team_ids` should be provided."
required = false
type = "array"

[[body_param]]
name = "data_region"
description = """
Data region or private cluster name to create the source in.  \nPermitted values for most plans are: `us_east`, `germany`, `singapore`.
"""
required = false
type = "string"

[[body_param]]
name = "ip_allowlist"
description = "Array of IP addresses or CIDR ranges that are allowed to use this connection."
required = false
type = "array"

[[body_param]]
name = "valid_until"
description = "ISO 8601 timestamp when the connection expires."
required = false
type = "string"

[[body_param]]
name = "note"
description = "A descriptive note for the connection."
required = false
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''The newly created connection, including its password.'''
body = '''
{
  "data": {
    "id": "44498",
    "type": "connection",
    "attributes": {
      "id": 44498,
      "client_type": "clickhouse",
      "note": "Production connection for analytics",
      "created_at": "2025-11-07T13:20:55.652Z",
      "valid_until": "2025-12-02T00:00:00.000Z",
      "host": "eu-nbg-2-connect.betterstackdata.com",
      "port": 443,
      "username": "urKyY9Y1ojWOAjtmAZ3hswsdfvedCRXir",
      "password": "31ctySUgUnSuuppbroGLp66kBdB7ngHzoipm3yEEp6TX8kT77E7EDUsHnDRWoIWC",
      "data_region": "eu-nbg-2",
      "ip_allowlist": [
        "192.168.1.0/24",
        "10.0.0.1"
      ],
      "team_ids": [
        1234
      ],
      "team_names": [
        "My Team"
      ],
      "created_by": null,
      "sample_query": "curl -u urKyY9Y1ojWOAjtmAZ3hswsdfvedCRXir:31ctySUgUnSuuppbroGLp66kBdB7ngHzoipm3yEEp6TX8kT77E7EDUsHnDRWoIWC -H 'Content-type: plain/text' -X POST 'https://eu-nbg-2-connect.betterstackdata.com?output_format_pretty_row_numbers=0' -d \"SELECT query_collection || '_' || type AS named_collection, multiIf( type = 'logs', 'SELECT dt, raw FROM remote(' || query_collection || '_logs) LIMIT 10 UNION ALL SELECT dt, raw FROM s3Cluster(primary, ' || query_collection || '_s3) WHERE _row_type = 1 LIMIT 10', type = 'spans', 'SELECT dt, raw FROM remote(' || query_collection || '_spans) LIMIT 10 UNION ALL SELECT dt, raw FROM s3Cluster(primary, ' || query_collection || '_s3) WHERE _row_type = 3 LIMIT 10', type = 'metrics', 'SELECT toStartOfHour(dt) AS time, countMerge(events_count) FROM remote(' || query_collection || '_metrics) GROUP BY time ORDER BY time DESC LIMIT 10', null ) AS query_with FROM VALUES('query_collection String, type String', ('t1234_application_example_2', 'logs'), ('t1234_application_example_2', 'metrics')) ORDER BY named_collection FORMAT Pretty\"",
      "data_sources": [
        {
          "source_name": "Application example",
          "source_id": 1325114,
          "team_name": "My Team",
          "data_sources": [
            "remote(t1234_application_example_2_logs)",
            "remote(t1234_application_example_2_metrics)",
            "s3Cluster(primary, t1234_application_example_2_s3)"
          ]
        }
      ]
    }
  }
}
'''
[[response]]
status = 422
description = '''Validation failed due to invalid parameters.'''
body = '''
{
  "errors": "Cannot specify both team_names and team_ids"
}
'''
[/responses]

[note]
This API requires a [global API token](https://betterstack.com/docs/logs/api/getting-started/#get-a-global-api-token) for authentication, not a team-specific token. Include the token in the `Authorization` header.
[/note]

[warning]
The **password is only returned in the creation response** and cannot be retrieved later. Store it securely.
[/warning]

#### Example cURL

```shell
[label Example]
curl --request POST \
  --url https://telemetry.betterstack.com/api/v1/connections \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "client_type": "clickhouse",
    "team_names": ["My Team"],
    "data_region": "germany",
    "ip_allowlist": ["192.168.1.0/24", "10.0.0.1"],
    "valid_until": "2025-12-02T00:00:00Z",
    "note": "Production connection for analytics"
  }'
```