Skip to main content
The LightShip REST API is the machine-facing interface to trace query, access model, users, and audit. Browser requests use a session cookie obtained through POST /login; automation uses personal API keys of the form lsk_... in an Authorization: Bearer header. Roles and user attributes are resolved on every request, so a permission change takes effect without rotating credentials.

​
Base URL

Examples throughout the API reference use this local Docker Compose URL. For a hosted installation, replace it with your LightShip deployment URL, such as https://your-lightship.example. Terminate TLS in front of LightShip for production.

​
Authentication

​
Request and response format

All requests and responses use JSON. Send Content-Type: application/json on requests with a body. Errors are returned with a non-2xx status code and a JSON body describing the failure.
LightShip fails closed. Missing configuration, an unauthorized caller, or an unreachable trace source produces an error or an empty result set instead of leaking data.

​
Where to next

Query traces

Fetch authorized traces with filters and cursor pagination.

Filter reference

See the operator matrix and JSON filter shape.

Access model

Discover ClickHouse schema and manage bindings and marked fields.

Audit log

Read authentication, query, and configuration activity.