API overview

This page covers the service API for RawTree Cloud and RawTree BYOC. Examples use https://api.rawtree.com for RawTree Cloud and RawTree BYOC across regions. Available routes depend on the deployed service version.

RawTree is the database behind these interfaces. Query API syntax restrictions, request limits, and service permissions are separate from engine capabilities. See ClickHouse compatibility and API scope.

Machine-readable spec:

https://rawtree.com/openapi.json

Base URL:

https://api.rawtree.com

Most endpoints use bearer authentication:

Authorization: Bearer rt_...

See the error reference for response fields and error codes.

API keys are scoped to an organization and cluster, not to one database. For data endpoints, pass database=<name> in the query string or use the x-rawtree-database header. Omitting both uses the API key's stored default database. A key created without a database selector stores the logical default database.

Request conventions

Read Authentication first. Examples use RAWTREE_API_KEY for data requests and RAWTREE_USER_TOKEN for user requests. A user token is a session token or an OAuth access token with full_access. Use RAWTREE_SESSION_TOKEN where a method requires a first-party session.

Replace the example organization, cluster, UUIDs, and resource names with your own values. IDs and timestamps in responses are illustrative. Empty lists show a valid response when no data matches. Response examples describe the wire format, not a live deployment snapshot.

For user requests, pass the organization and cluster names. For data requests, select the database with database or x-rawtree-database. API keys and workload tokens already select an organization and cluster. Some management APIs still require explicit names. Path parameters use UUIDs where shown. URL-encode names and other path values.

Use the OpenAPI specification for machine-readable request and response schemas. The reference also covers native app protocols. Their response formats differ from the service JSON API.

Resources

• Organizations
• Regions
• Clusters
• Databases
• Tables
• Query
• Handlers
• Logs
• Metrics
• Connectors
• Workflows
• API keys
• Service accounts
• Federation issuers
• Federation rules
• Apps

Paused clusters

Data requests to a paused cluster return HTTP 409 with the standard error shape when the service has a recent, confirmed paused status:

{
  "error": "cluster_paused",
  "message": "Cluster is paused.",
  "hint": "Resume the cluster before sending data requests."
}

Resume the cluster and wait until it is ready before retrying. Cluster management endpoints, including resume, remain available. API request logs also remain available because they use the service's internal logs cluster. If the data plane has no healthy upstream but paused status cannot be confirmed, the API returns HTTP 503 with error: "upstream_unavailable" instead. Splunk HEC endpoints retain their native response format and report code 9 (Server is busy) while the cluster is paused. OTLP gRPC exports return FAILED_PRECONDITION for a confirmed pause and UNAVAILABLE for an unconfirmed upstream outage.

Health

GET /health

Check service health.

Response:

{ "status": "ok" }

No authentication required.

Request:

# Check regional database readiness.
curl -X GET "https://api.rawtree.com/health"

Expected response: HTTP 200.

{
  "status": "ok"
}

Errors: 503. See API errors.

HTTP errors

See API errors for error codes and recovery steps. Native OTLP, Prometheus, Splunk HEC, and handler responses retain their protocol's error format.

Reference scope

This reference covers the public service methods and native app protocols. Dashboard sign-in, billing checkout, staff administration, internal database proxy routes, and private organization integrations are separate service interfaces. Use the dashboard for billing and Slack authorization. Use the supported OAuth flow for external applications.