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_...

Health

GET /health

Check service health.

Response:

{"status":"ok"}

Projects

GET /v1/projects

List projects available to the authenticated user.

POST /v1/projects

Create a project.

{"name":"analytics"}

If name is omitted, RawTree generates one.

PATCH /v1/projects/{project}

Rename a project.

{"name":"analytics_v2"}

DELETE /v1/projects/{project}

Delete a project and its data.

Query

POST /v1/query

Execute a read-only SQL query.

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

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 insert and query logs.

Query parameters:

Search filters:

type:select
type:insert
type:describe
type:explain
status:success
status:error
table:events,audit

Example:

type:insert status:error table:events

OpenTelemetry

RawTree accepts native OpenTelemetry Protocol ingest over OTLP/HTTP and OTLP/gRPC. 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. The API key selects the project, and the table header selects the destination table.

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/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 project API key:

Authorization: Bearer rt_...

Tables

GET /v1/tables

List tables in the current project.

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 project.

POST /v1/keys

Create an API key.

{"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.