API reference - Rootprint

The Rootprint API is the HTTP surface behind your self-hosted instance. Start with the external APIs when you need to send logs from a shipper or query logs from another tool. Use the session-based APIs when you need to automate web-app workflows such as index management, user administration, or monitoring. If you are setting up log collection for the first time, start with Send logs. If you already know the endpoint you need, use the generated endpoint reference in the sidebar.

Base URL

All API requests go to your Rootprint instance. Replace the host below with your Rootprint host, including the port if it does not serve on the default one.

https://<your-rootprint>

Authentication

Rootprint uses these authentication modes, depending on the endpoint.

Use case	Auth method	Where to get it
Send logs over NDJSON or OTLP	Ingest API key (bearer, prefix `rp_`)	Settings → API keys
Send traces over OTLP	Ingest API key (bearer, prefix `rp_`)	Settings → API keys
Read logs from an external tool	Query API key (bearer, prefix `rpk_`)	Settings → Profile or Settings → Service accounts
Check health	None	`GET /api/health` is public

Bearer-token endpoints use the standard Authorization header.

Authorization: Bearer <token>

Ingest API keys are scoped to one index; that index is fixed by the key and cannot be changed per request. Spans are the exception: POST /v1/traces always writes to the span store named by TRACE_INDEX_ID, whatever index the key is scoped to. See Traces. Query API keys are read-only and not index-scoped. A personal API key, also called a personal access token (PAT), authenticates as the user who created it. A service account API key authenticates as the service account.

Endpoint groups

The generated endpoint reference is arranged around the audience for each endpoint.

Group	What it contains
Log ingest API	NDJSON and OTLP endpoints for log producers
Log explorer API	Search, histograms, field values, and exports. Query API keys work on search, histogram, field-value, and field-discovery endpoints.
Traces API	OTLP span ingest and single-trace lookup
Service health API	Service health computed from spans: request rate, errors, latency, top endpoints, downstream calls, and the failing spans themselves
Saved views	Create, list, update, and delete saved searches scoped to an index
Share links	Create and resolve public share links for log views
Index management API	Index metadata, field discovery, preferences, and stats
Index sources API	Configure the log sources feeding an index, including enable state and checkpoints
API key administration	Create and delete ingest API keys and service account API keys
Service accounts	Create and delete non-human accounts for shared integrations
Personal API keys	Self-service create, list, and revoke for personal query keys
User and invite API	Users, roles, password resets, invites, and invite acceptance
Authentication API	Setup, sign-in, sessions, sign-out, and password changes
Auth settings API	Google and GitHub OAuth credentials, allowed domains, and allowed organizations
System monitoring API	Health, cluster overview, activity, and metrics

Timestamps

Every timestamp the API takes is Unix epoch seconds — startTs and endTs on search, histogram, field-value, export, monitoring, and stats requests, and startTime/endTime in a share or saved-view body. Log documents keep their own nanosecond fields; that is document data, not a request parameter.

GET /api/indexes/{indexId}/stats ignores from and to rather than rejecting them. A caller sending those instead of startTs and endTs gets an unbounded query: the oldest snapshots up to limit (5,000 by default), not the window it asked for.

Common content types

Use application/json for most app and admin endpoints. Use application/x-ndjson for the HTTP endpoint.

Content-Type: application/x-ndjson

Use application/x-protobuf for OTLP logs and traces.

Content-Type: application/x-protobuf

Good first requests

Goal	Endpoint	Notes
Health check	`GET /api/health`	No authentication required
Send NDJSON logs	`POST /api/ingest/ndjson`	Requires an ingest API key
Send OTLP logs	`POST /v1/logs`	Requires an ingest API key and protobuf body
Send OTLP traces	`POST /v1/traces`	Requires an ingest API key and protobuf body
Read a trace	`GET /api/traces/{traceId}`	Accepts a session cookie or a query API key
List indexes	`GET /api/indexes`	Accepts a session cookie or a query API key
Search logs	`GET /api/indexes/{indexId}/logs`	Accepts a session cookie or a query API key

Error responses

Most app-level endpoints return JSON errors with a stable error object.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "statusCode": 400,
    "requestId": "req_abc123"
  }
}

Status	Meaning
`400`	Invalid query string, path parameter, or JSON body
`401`	Missing session or bearer token
`403`	Authenticated, but not allowed
`404`	Unknown route or resource
`409`	Conflict, such as first-admin setup already done
`413`	Payload too large
`415`	Unsupported media type
`422`	Unprocessable entity, such as a share payload over 64KB
`429`	Rate limit exceeded — Rootprint’s own (`TOO_MANY_REQUESTS`) or Quickwit’s, passed through (`UPSTREAM_RATE_LIMIT`). Honor `Retry-After`.
`500`	Internal server error
`503`	Quickwit or another upstream dependency is down

OTLP endpoints follow OTLP-style error responses instead of the app JSON error shape.

Rootprint rate-limits unauthenticated auth routes per client IP and read routes (search, histogram, field values, traces, service health, share resolution) per signed-in user. Ingest endpoints are not limited by Rootprint — apply rate limiting at your reverse proxy or load balancer if your deployment needs it. See Rate limiting for the tunables.

​Base URL

​Authentication

​Endpoint groups

​Timestamps

​Common content types

​Good first requests

​Error responses

Base URL

Authentication

Endpoint groups

Timestamps

Common content types

Good first requests

Error responses