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 deployment URL.

https://your-rootprint-host

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 `lwit_`)	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. 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.
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

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.

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
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`	Upstream rate limit
`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 does not apply an application-level rate limit to ingest endpoints. Apply rate limiting at your reverse proxy or load balancer if your deployment needs it.

​Base URL

​Authentication

​Endpoint groups

​Common content types

​Good first requests

​Error responses

Base URL

Authentication

Endpoint groups

Common content types

Good first requests

Error responses