Create Connection

POST/api/v2/connections

Creates a new ClickHouse connection

Authorizations

AuthorizationBearer API Keyheaderrequired
`Authorization: Bearer <token>`

Request bodyJSON

namestringrequired
Display name for the connection.

Example: "Production ClickHouse"
hoststringrequired
ClickHouse HTTP endpoint URL.

Example: "https://clickhouse.example.com:8443"
usernamestringrequired
ClickHouse username.

Example: "default"
passwordoptionalstring
ClickHouse password. Never returned by the API.

Example: "my-secret-password"
hyperdxSettingPrefixoptionalstringor null
Optional prefix for HyperDX-specific ClickHouse settings. Must only contain alphanumeric characters and underscores.

Example: "hyperdx_"
isPrometheusEndpointoptionalboolean
Optional. When true, host is treated as a Prometheus-compatible API endpoint (e.g. Prometheus or Thanos) and PromQL queries are proxied to it. When false or omitted, host is a ClickHouse HTTP endpoint.

Example: false

Response

JSON

200

Successfully created connection

JSON

dataoptionalobject
The connection object.
8 properties
- idstringrequired
  Unique connection ID.
  
  Example: "507f1f77bcf86cd799439012"
- namestringrequired
  Display name for the connection.
  
  Example: "Production ClickHouse"
- hoststringrequired
  ClickHouse HTTP endpoint URL.
  
  Example: "https://clickhouse.example.com:8443"
- usernamestringrequired
  ClickHouse username.
  
  Example: "default"
- hyperdxSettingPrefixoptionalstringor null
  Optional prefix for HyperDX-specific ClickHouse settings. Must only contain alphanumeric characters and underscores.
  
  Example: "hyperdx_"
- isPrometheusEndpointoptionalboolean
  Optional. When true, host is treated as a Prometheus-compatible API endpoint (e.g. Prometheus or Thanos) and PromQL queries are proxied to it. When false or omitted, host is a ClickHouse HTTP endpoint.
  
  Example: false
- createdAtoptionalstring
  Creation timestamp
  
  format: date-time
  Example: "2025-01-01T00:00:00.000Z"
- updatedAtoptionalstring
  Last update timestamp
  
  format: date-time
  Example: "2025-06-15T10:30:00.000Z"

Create Connection

curl --request POST \
  --url /api/v2/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production ClickHouse",
  "host": "https://clickhouse.example.com:8443",
  "username": "default",
  "password": "my-secret-password",
  "hyperdxSettingPrefix": "hyperdx_",
  "isPrometheusEndpoint": false
}
'

const url = '/api/v2/connections';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    name: 'Production ClickHouse',
    host: 'https://clickhouse.example.com:8443',
    username: 'default',
    password: 'my-secret-password',
    hyperdxSettingPrefix: 'hyperdx_',
    isPrometheusEndpoint: false
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "/api/v2/connections"

payload = {
    "name": "Production ClickHouse",
    "host": "https://clickhouse.example.com:8443",
    "username": "default",
    "password": "my-secret-password",
    "hyperdxSettingPrefix": "hyperdx_",
    "isPrometheusEndpoint": False
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "data": {
    "id": "507f1f77bcf86cd799439012",
    "name": "Production ClickHouse",
    "host": "https://clickhouse.example.com:8443",
    "username": "default",
    "hyperdxSettingPrefix": "hyperdx_",
    "isPrometheusEndpoint": false,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-06-15T10:30:00.000Z"
  }
}

{
  "message": "Body validation failed: name: Required"
}

{
  "message": "Unauthorized access. API key is missing or invalid."
}

Authorizations

Request bodyJSON

Response

200

400

401