API reference

The Rootprint API is the HTTP surface of your self-hosted instance: send logs and spans, query them from other tools, and automate administration. If you are setting up log collection for the first time, start with Send logs.

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 or traces (NDJSON, OTLP)	Ingest API key (bearer, prefix `rp_`)	Settings → API keys
Read logs from an external tool	Query API key (bearer, prefix `rpk_`)	Profile (user menu) or Settings → Service accounts
Check health	None	`GET /api/health` is public

Bearer-token endpoints use the standard Authorization header.

Authorization: Bearer <token>

An ingest API key writes logs to the one index it is scoped to. Spans always go to the span store; see Traces. Query API keys are read-only and read every index; see Query logs with API keys.

Common tasks

Task	Endpoints	Credential
Check health	`GET /api/health`	None
Send logs	`POST /api/ingest/ndjson`, `POST /v1/logs`	Ingest API key
Send traces	`POST /v1/traces`	Ingest API key
Search logs	`GET /api/indexes`, `GET /api/indexes/{indexId}/logs`, `…/logs/histogram`, `…/fields/values`	Query API key or session
Read traces	`GET /api/traces/{traceId}`, `GET /api/traces/explore/spans`, `GET /api/traces/explore/overview`	Query API key or session
Read service health	`GET /api/services`, `GET /api/services/errors`	Query API key or session
Export logs	`GET /api/indexes/{indexId}/logs/export`	Session
Manage indexes, keys, and users	`/api/indexes`, `/api/api-keys`, `/api/service-accounts`, `/api/users`	Admin session
Configure sign-in	Google, GitHub, and OpenID Connect credentials and allow-lists under `/api/settings/auth`, and the password sign-in toggle, `PUT /api/settings/auth/password`	Admin session

Query logs with API keys lists every endpoint that accepts a query API key. The sidebar has the full endpoint reference.

Timestamps

Request timestamps are Unix epoch seconds: startTs and endTs in query strings, and startTime/endTime in share and saved-view bodies.

Common content types

Content type	Use for
`application/json`	Most app and admin endpoints
`application/x-ndjson`	The NDJSON gateway (`POST /api/ingest/ndjson`)
`application/x-protobuf`	OTLP logs and traces

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. Retryable — honor `Retry-After`.

OTLP endpoints follow OTLP-style error responses instead of the app JSON error shape. Rootprint rate-limits auth and read routes; see Rate limiting. It does not rate-limit ingest endpoints, so apply a limit at your reverse proxy or load balancer if your deployment needs one.

Overview

Log ingest API

Log explorer API

Traces API

Service health API

Saved views

Share links

Index management API

Index sources API

API key administration

Service accounts

Personal API keys

User and invite API

Authentication API

Auth settings API

System monitoring API

Base URL

Authentication

Common tasks

Timestamps

Common content types

Error responses

​Base URL

​Authentication

​Common tasks

​Timestamps

​Common content types

​Error responses

Base URL

Authentication

Common tasks

Timestamps

Common content types

Error responses