API reference

This page covers the public RawTree API surface from the OpenAPI spec.

Machine-readable spec:

https://api.rawtree.com/v1/openapi.json

Base URL:

https://api.rawtree.com

Most endpoints use bearer authentication:

Authorization: Bearer rt_...

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.

Health

GET /health

Check service health.

Response:

{ "status": "ok" }

Databases

GET /v1/databases

List databases available in the API key's cluster. Requires a readable API key (admin, read_write, or read_only) or an authenticated organization member.

POST /v1/databases

Create a database. API-key authentication requires admin permission.

{ "name": "analytics" }

DELETE /v1/databases/{database}

Delete a database and its data. Requires admin permission. Deleting a database does not revoke the cluster-wide API keys that could access it. The managed default database cannot be deleted.

Query

POST /v1/query

Execute a read-only SQL query.

{ "sql": "SELECT * FROM events LIMIT 10" }

The optional format field selects the ClickHouse response format. It defaults to JSON, and supports JSONEachRow, JSONEachRowWithProgress, JSONCompact, CSV, CSVWithNames, TSV, TSVWithNames, and TabSeparated. For formats other than JSON, the response body is returned in the requested raw format. For example:

{
  "sql": "EXPLAIN SELECT 1",
  "format": "JSONEachRowWithProgress"
}

JSONEachRowWithProgress returns newline-delimited JSON records, including progress, metadata, and row records.

Default JSON response shape:

{
  "meta": [{ "name": "action", "type": "String" }],
  "data": [{ "action": "click" }],
  "rows": 1,
  "statistics": { "elapsed": 0.001, "rows_read": 1, "bytes_read": 128 },
  "hints": []
}

Logs

GET /v1/logs

List platform API requests captured by RawTree's internal request spans. Query execution history belongs to the Queries screen; this endpoint focuses on HTTP request activity.

Query parameters:

Each log includes its span-based log ID, creation time, method, URL path, matched API route, status code, source, duration, user agent, client version, request size, trace ID, database, and structured error details when the request failed. A bounded textual request body may be included for supported requests (up to 8 KiB); response body content is not recorded.

OpenTelemetry

RawTree accepts native OpenTelemetry Protocol ingest over OTLP/HTTP and OTLP/gRPC. For setup instructions, SDK environment variables, Collector config, and a smoke test, see the OpenTelemetry guide.

The OpenTelemetry app must be installed on the target cluster before these native endpoints can be used. The generic table insert transforms, such as POST /v1/tables/traces?transform=otlp-traces, do not require the app.

Both paths apply the built-in OpenTelemetry transforms and write to the default signal tables.

Native OTLP endpoints write to the default traces, logs, and metrics tables unless you provide a signal-specific destination header: x-rawtree-traces-table, x-rawtree-logs-table, or x-rawtree-metrics-table. For OTLP/HTTP, select the database with the database query parameter. For OTLP/gRPC, use the x-rawtree-database metadata header. If the request omits a selector, RawTree uses the API key's stored default database.

POST /otlp/v1/traces

Ingest OTLP/HTTP traces into the traces table, or into the table named by x-rawtree-traces-table.

POST /otlp/v1/logs

Ingest OTLP/HTTP logs into the logs table, or into the table named by x-rawtree-logs-table.

POST /otlp/v1/metrics

Ingest OTLP/HTTP metrics into the metrics table, or into the table named by x-rawtree-metrics-table.

These endpoints accept application/json and application/x-protobuf OTLP export payloads. Successful requests normally return an empty OTLP export response: {} for JSON requests or an empty protobuf message for protobuf requests. If RawTree accepts the export but drops invalid signal records, the response uses the OTLP partialSuccess shape with rejectedSpans, rejectedLogRecords, or rejectedDataPoints plus an errorMessage.

OTLP/HTTP request bodies can be gzip-compressed with Content-Encoding: gzip. Request bodies are limited to 100 MiB after decompression; larger exports return 413.

OTLP/gRPC

Send OTLP/gRPC export requests to the standard collector services:

Use https://api.rawtree.com as the OTLP endpoint, or http://localhost:4317 with the local Docker Compose stack.

Use bearer authentication with a cluster API key:

Authorization: Bearer rt_...

Prometheus

RawTree exposes Prometheus remote write and query-compatible endpoints under /prometheus/api/v1. The Prometheus app must be installed on the target cluster before any endpoint in this group can be used. See the Prometheus guide for configuration and supported endpoints.

Splunk and SPL search

The Splunk app enables both the Splunk HEC-compatible ingestion endpoints and RawTree's platform-native SPL search API for a cluster. SPL searches run inside RawTree against the selected database's splunk_events table; they do not install or require a Splunk search provider, command, or add-on.

POST /v1/spl/search

Execute a supported, read-only SPL search. A readable cluster API key uses its bound organization, cluster, and database when those selectors are omitted. With a user or OAuth token, pass the organization, cluster, and database. As on other data endpoints, x-rawtree-database can select the database instead of the database query parameter.

POST /v1/spl/search?organization=acme&cluster=production&database=logs
Authorization: Bearer rt_...

{
  "spl": "index=bot_traffic endpoint=\"/api/login\" action=blocked | sort - _time",
  "earliest": "-30m",
  "latest": "now",
  "query_id": "optional-client-query-id"
}

Time bounds accept non-negative epoch seconds, now, or a negative relative value such as -30m, -24h, or -7d. RawTree applies the same read-only query safeguards and cancellation ownership rules as the SQL query API. Cancel a running request with POST /v1/query/cancel using the same query_id, organization, and database scope.

The supported SPL subset covers base searches and search/where boolean filters; positive fields/table; rename; bounded eval; stats with count, dc, sum, avg, and values plus optional BY; sort; head; multi-field dedup; and timechart with a bounded span and an optional split field. Unsupported or ambiguous commands return 400 instead of being passed through as SQL.

The JSON response includes the standard query meta, data, rows, and statistics fields, plus the original spl, a bounded, chronologically ordered timeline, a result_kind of events or statistics, a truncated flag, and an entry for every pipeline segment in source order. Timeline buckets are zero-filled across the requested window (or the recent default window when no time bounds are supplied), with granularity selected to keep the series bounded. Each stage has command, expression, output_rows, and truncated fields. output_rows is the row count after that stage. It is capped at 10,000; truncated: true means a 10,001st row proved that the real count is larger, while exactly 10,000 rows remain exact with truncated: false.

RawTree measures cardinality-changing stages and carries exact counts across row-preserving stages. Measurement is limited to the first 12 stages and to the generated-query size budget, so output_rows is null when a stage cannot be measured safely. Clients should calculate percentages only for consecutive stages whose counts are non-null and untruncated, where the previous count is positive and the current count does not exceed it. In that case, kept percent is current / previous * 100, affected rows is previous - current, and affected percent is 100 - kept percent; percentage values use the 0–100 range.

Search execution is synchronous: the response is returned after both the main result and the single bounded analysis query for timeline and stage feedback complete. Both queries use the same authorization, database scope, read-only validation, execution limits, and cancellation ownership.

Saved searches

Saved searches are scoped to an organization and cluster and are available to authenticated organization members while the Splunk app is installed:

Pass organization and cluster on every saved-search request. List requests also accept search, created_by, and database filters. The list returns metadata for at most 200 searches and sets truncated when additional matches exist; fetch one search to read its SPL and time window. Uninstalling the Splunk app disables HEC, SPL execution, and saved-search access but preserves saved-search records and ingested data. Reinstalling the app makes them available again; SQL access is unaffected.

Apps

Apps are installed per cluster, and clusters start with no apps installed. App management requires an authenticated user session or OAuth access token; cluster API keys cannot manage apps.

GET /v1/apps

List the available apps and their installation state. Any member of the organization can list apps. Pass the organization and cluster names in the query string:

GET /v1/apps?organization=acme&cluster=production

{
  "cluster": {
    "id": "9f30c31c-74a7-4a08-aab0-494689ab5b31",
    "name": "production"
  },
  "apps": [
    { "id": "opentelemetry", "name": "OpenTelemetry", "installed": true },
    { "id": "prometheus", "name": "Prometheus", "installed": false }
  ]
}

This endpoint reads platform metadata only, so it remains available while the cluster is provisioning, paused, stopped, or otherwise unavailable.

PUT /v1/apps/{app_id}

Install an app. Organization admin access is required. The request has no body and is idempotent:

PUT /v1/apps/prometheus?organization=acme&cluster=production

{ "id": "prometheus", "name": "Prometheus", "installed": true }

Installation enables the app's native endpoints; it does not change the cluster lifecycle state or guarantee that the cluster is ready.

DELETE /v1/apps/{app_id}

Uninstall an app. Organization admin access is required. The request has no body and is idempotent:

DELETE /v1/apps/prometheus?organization=acme&cluster=production

{ "id": "prometheus", "name": "Prometheus", "installed": false }

Uninstallation disables the app's native endpoints; it does not change the cluster lifecycle state. The Apps catalog remains available while the cluster is stopped.

Tables

GET /v1/tables

List tables in the selected database.

GET /v1/tables/{table}

Describe a table.

POST /v1/tables/{table}

Insert data. Send one JSON object or an array of JSON objects.

[{ "action": "click", "user": "alice" }]

Optional transform for JSON body inserts:

POST /v1/tables/traces?transform=otlp-traces

Transforms flatten known source formats before insert.

See Transforms for supported input shapes and emitted rows.

Supported transforms:

• otlp-traces
• otlp-logs
• otlp-metrics
• cloudwatch-logs
• cloudtrail
• firehose

For AWS Firehose HTTP endpoint delivery, use:

POST /v1/tables/events?transform=firehose
X-Amz-Firehose-Access-Key: <rawtree-api-key>

Firehose records must contain base64-encoded data in records[].data. If the decoded value is a JSON object, RawTree inserts it as one row. If it is an array of JSON objects, RawTree inserts one row per object. If it is UTF-8 TSV text and columns is present, RawTree inserts one row per TSV line using those column names. If it is UTF-8 TSV text without columns, RawTree inserts one row with the decoded text in data. Other decoded formats return 400. Successful Firehose inserts return {requestId,timestamp}.

URL ingest uses query parameters:

POST /v1/tables/events?url=https%3A%2F%2Fexample.com%2Fevents.jsonl

Transforms are not supported with URL inserts. If you use ?url=, transform the data before hosting it.

DELETE /v1/tables/{table}

Delete a table. Requires admin permission.

API keys

GET /v1/keys

List API keys for the current cluster. Requires an admin API key or JWT.

POST /v1/keys

Create a cluster-wide API key. Requires an admin API key or JWT. The database selected on this request is stored as the key's default for later requests that omit a database selector; if none is selected, RawTree stores default.

{ "name": "my-agent", "permission": "read_write" }

Valid permissions:

• admin
• read_write
• write_only
• read_only

DELETE /v1/keys/{id_or_token}

Delete an API key by UUID or full rt_... token.