Skip to content

HTTP Query API

Each cluster runs the Hydrolix HTTP query API. The API endpoint is https://{myhost}.hydrolix.live/query.

We recommend the POST endpoint, although there is also a GET endpoint.

Clients may authenticate with credentials or present an authorization token.

Present an authorization token⚓︎

The HTTP query API supports auth tokens and authentication via local user credentials.

Get the bearer token, which is good for the next 24 hours, to authenticate future API calls. This command assumes you've set the $HDX_HOSTNAME, $HDX_USER and $HDX_PASSWORD environment variables:

1
2
3
4
5
6
7
8
export HDX_TOKEN=$(
  curl -v -X POST -H "Content-Type: application/json" \
  https://$HDX_HOSTNAME/config/v1/login/ \
  -d "{
    \"username\":\"$HDX_USER\",
    \"password\":\"$HDX_PASSWORD\"  
  }" | jq -r ".auth_token.access_token"
)

If the token is valid, the HTTP Query API returns an HTTP 200 and the response.

1
2
3
4
5
curl -X POST \
  --header "Authorization: Bearer ${HDX_TOKEN}" \
  --url https://{myhost}.hydrolix.live/query \
  --data "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;" \
2354732

If the token is invalid, the HTTP Query API returns an HTTP 400 and the following error.

1
2
3
4
{
    "error": "Code: 516. DB::Exception: username@example.com: Authentication failed: password is incorrect, or there is no user with such name. (AUTHENTICATION_FAILED)",
    "query": "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;"
}

If the token is empty, the HTTP Query API returns an HTTP 400 and the following error.

1
2
3
4
{
    "error": "std::exception. Code: 1001, type: h::db::ContextError, e.what() = <ContextError no authentication token provided> (version 24.8.6.1)",
    "query": "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;"
}

Authenticate with credentials⚓︎

If the credentials are valid, the HTTP Query API returns an HTTP 200 and the response.

1
2
3
4
5
curl -X POST \
  --user "${HDX_USERNAME}:${HDX_PASSWORD}" \
  --url https://{myhost}.hydrolix.live/query \
  --data "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;" \
2354732

If the credentials are invalid, the HTTP Query API returns an HTTP 400 and the following error.

1
2
3
{
    "error": "<TurbineApiAuthenticatorError api login failed with provided username/password 'username@example.com'. <HttpPermanentResponseError error=request_failed status_code=401 path=/config/v1/login {\"detail\":\"Could not login\"}>>",
    "query": "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;"

Learn more on the Enable Query Authentication, User Authentication, and Configure IP Access pages.