> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootprint.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Use the Rootprint HTTP API to ingest logs, query logs from external tools, and automate administration against your own Rootprint deployment.

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](/send-logs/overview). 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.

```http theme={"theme":"github-light"}
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.

```http theme={"theme":"github-light"}
Content-Type: application/x-ndjson
```

Use `application/x-protobuf` for OTLP logs.

```http theme={"theme":"github-light"}
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.

```json theme={"theme":"github-light"}
{
  "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.

<Note>
  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.
</Note>