# Overview (/docs/reference/api)



API overview [#api-overview]

<LegacyApiFragmentRedirect />

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](/docs/reference/clickhouse-compatibility).

Machine-readable spec:

```text
https://rawtree.com/openapi.json
```

Base URL:

```text
https://api.rawtree.com
```

Most endpoints use bearer authentication:

```text
Authorization: Bearer rt_...
```

See the [error reference](/docs/reference/errors) 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 [#request-conventions]

Read [Authentication](/docs/reference/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](https://rawtree.com/openapi.json) for machine-readable request and response schemas.
The reference also covers native app protocols. Their response formats differ from the service JSON API.

Resources [#resources]

* [Organizations](/docs/reference/api/organizations)
* [Regions](/docs/reference/api/regions)
* [Clusters](/docs/reference/api/clusters)
* [Databases](/docs/reference/api/databases)
* [Tables](/docs/reference/api/tables)
* [Query](/docs/reference/api/query)
* [Handlers](/docs/reference/api/handlers)
* [Logs](/docs/reference/api/logs)
* [Metrics](/docs/reference/api/metrics)
* [Connectors](/docs/reference/api/connectors)
* [Workflows](/docs/reference/api/workflows)
* [API keys](/docs/reference/api/keys)
* [Service accounts](/docs/reference/api/service-accounts)
* [Federation issuers](/docs/reference/api/federation-issuers)
* [Federation rules](/docs/reference/api/federation-rules)
* [Apps](/docs/reference/api/apps)

Paused clusters [#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:

```json
{
  "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 [#health]

GET `/health` [#get-health]

Check service health.

Response:

```json
{ "status": "ok" }
```

No authentication required.

Request:

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

Expected response: **HTTP 200**.

```json
{
  "status": "ok"
}
```

Errors: `503`. See [API errors](/docs/reference/errors).

HTTP errors [#http-errors]

| Status | Meaning                                                        |
| ------ | -------------------------------------------------------------- |
| `400`  | Invalid request or unsupported syntax                          |
| `401`  | Missing, expired, or invalid credential                        |
| `403`  | Credential lacks the required permission                       |
| `404`  | Resource is absent or not visible to the caller                |
| `409`  | Resource conflict, stale revision, or confirmed paused cluster |
| `413`  | Request or result exceeds a size limit                         |
| `422`  | Request fields fail validation                                 |
| `429`  | Request rate limit reached                                     |
| `503`  | Service is disabled or an upstream is unavailable              |

See [API errors](/docs/reference/errors) for error codes and recovery steps.
Native OTLP, Prometheus, Splunk HEC, and handler responses retain their protocol's error format.

Reference scope [#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.