Overhaul

api-reference/datasets/datapoints.mdx

@@ -0,0 +1,9 @@
+---
+title: "List dataset datapoints"
+method: GET
+path: /v1/datasets/datapoints
+openapi: "GET /v1/datasets/datapoints"
+description: List datapoints from a dataset.
+---
+
+List datapoints with filters: `datasetId` or `datasetName`, plus `limit` and `offset`.

api-reference/datasets/list.mdx

@@ -0,0 +1,9 @@
+---
+title: "List datasets"
+method: GET
+path: /v1/datasets
+openapi: "GET /v1/datasets"
+description: List datasets by id or name.
+---
+
+List datasets with optional filters: `id` and/or `name`.

api-reference/datasets/parquet.mdx

@@ -0,0 +1,9 @@
+---
+title: "Download dataset parquet"
+method: GET
+path: /v1/datasets/{datasetId}/parquets/{idx}
+openapi: "GET /v1/datasets/{datasetId}/parquets/{idx}"
+description: Stream a parquet export for a dataset.
+---
+
+Streams a parquet file from the export bucket for the given dataset and index.

api-reference/datasets/upsert.mdx

@@ -0,0 +1,10 @@
+---
+title: "Create datapoints"
+method: POST
+path: /v1/datasets/datapoints
+openapi: "POST /v1/datasets/datapoints"
+description: Insert datapoints and optionally create a dataset.
+---
+
+Body: `{"dataset": {"datasetName"|"datasetId"}, "datapoints":[{id?,data,target?,metadata?}], "createDataset"?: bool}`.  
+Creates the dataset if requested; returns `201` if created.

api-reference/evals/init_eval.mdx

@@ -1,8 +1,9 @@
 ---
-title: 'Initialize Evaluation'
-openapi: 'POST /v1/evals'
+title: "Create evaluation"
+method: POST
+path: /v1/evals
+openapi: "POST /v1/evals"
+description: Create an evaluation.
 ---
 
-### Description
-
-Create a new evaluation with an optional name and group. If no name is provided, a random name will be generated automatically. 
+Create an evaluation. If no name is provided, Laminar generates one automatically.

api-reference/evals/save_eval_datapoints.mdx

@@ -1,12 +1,9 @@
 ---
-title: 'Save Evaluation Datapoints'
-openapi: 'POST /v1/evals/{eval_id}/datapoints'
+title: "Add evaluation datapoints"
+method: POST
+path: /v1/evals/{eval_id}/datapoints
+openapi: "POST /v1/evals/{eval_id}/datapoints"
+description: Add datapoints to an existing evaluation.
 ---
 
-### Description
-
-Save multiple evaluation datapoints to an existing evaluation. Each datapoint can include input, output, expected output, executor output, scores, and metadata.
-
-<Note>
-The actual datapoints are not saved until you call the [Update Evaluation Datapoint](/api-reference/evals/update_eval_datapoint) endpoint.
-</Note>
+Add multiple evaluation datapoints to an existing evaluation. Each datapoint can include input, output, expected output, executor output, scores, and metadata. Datapoints are stored immediately; the update endpoint is only for changing a specific datapoint later.

api-reference/evals/update_eval_datapoint.mdx

@@ -1,8 +1,9 @@
 ---
-title: 'Update Evaluation Datapoint'
-openapi: 'POST /v1/evals/{eval_id}/datapoints/{datapoint_id}'
+title: "Update evaluation datapoint"
+method: POST
+path: /v1/evals/{eval_id}/datapoints/{datapoint_id}
+openapi: "POST /v1/evals/{eval_id}/datapoints/{datapoint_id}"
+description: Update a specific datapoint with new output or scores.
 ---
 
-### Description
-
-Update a specific evaluation datapoint with new executor output and scores.
+Update a specific evaluation datapoint with new executor output, scores, or metadata.

api-reference/evaluators/create-evaluator-score.mdx

@@ -5,4 +5,4 @@ openapi: 'POST /v1/evaluators/score'
 
 ### Description
 
-Create a score for a span using either a trace ID or span ID. When using a trace ID, the score will be attached to the root span of that trace. 
+Create a score for a span using either a trace ID or span ID. When using a trace ID, the score is attached to the root span of that trace. This endpoint records the provided score; it does not run evaluator logic server-side.

api-reference/evaluators/score.mdx

@@ -0,0 +1,9 @@
+---
+title: "Score via evaluator"
+method: POST
+path: /v1/evaluators/score
+openapi: "POST /v1/evaluators/score"
+description: Create a manual evaluator score attached to a span.
+---
+
+Create a score for a span using either a trace ID or span ID. When a trace ID is provided, the score is attached to the root span. This endpoint writes the score you supply; it does not execute or look up evaluator definitions.

api-reference/health/health.mdx

@@ -0,0 +1,9 @@
+---
+title: "Health probe"
+method: GET
+path: /health
+openapi: "GET /health"
+description: Health check (RabbitMQ connectivity).
+---
+
+Checks RabbitMQ connectivity. Consumer /health also validates worker counts.

api-reference/health/ready.mdx

@@ -0,0 +1,9 @@
+---
+title: "Readiness probe"
+method: GET
+path: /ready
+openapi: "GET /ready"
+description: Readiness check.
+---
+
+Readiness check; returns 500 if dependencies are unavailable.

api-reference/ingestion/browser-sessions.mdx

@@ -0,0 +1,10 @@
+---
+title: "Ingest browser session events"
+method: POST
+path: /v1/browser-sessions/events
+openapi: "POST /v1/browser-sessions/events"
+description: Send browser session events (ingest or default key).
+---
+
+Body: `{"events":[{type,timestamp,data(base64|bytes)}], "sessionId", "traceId", "source"?, "sdkVersion"?}`.  
+`400` if `traceId` is nil UUID. `403` on data limit. Publishes to MQ.

api-reference/ingestion/metrics.mdx

@@ -0,0 +1,9 @@
+---
+title: "Ingest metrics"
+method: POST
+path: /v1/metrics
+openapi: "POST /v1/metrics"
+description: Placeholder OTLP metrics ingestion.
+---
+
+Accepts OTLP metrics posts and returns `200 OK`. Placeholder endpoint.

api-reference/ingestion/otlp-grpc.mdx

@@ -0,0 +1,8 @@
+---
+title: "OTLP gRPC ingest"
+method: POST
+path: TraceService/Export (gRPC)
+description: Ingest traces over OTLP gRPC (ingest or default key).
+---
+
+This is a gRPC method, not an HTTP endpoint. Send OTLP TraceService/Export requests to the gRPC port (default 8001) with `Authorization: Bearer <api-key>` (ingest or default key). Enforces usage-limit checks.

api-reference/ingestion/traces.mdx

@@ -0,0 +1,9 @@
+---
+title: "Ingest traces"
+method: POST
+path: /v1/traces
+openapi: "POST /v1/traces"
+description: OTLP trace ingestion (ingest or default key).
+---
+
+Send OTLP `ExportTraceServiceRequest` bytes to enqueue spans. Returns `403` when workspace data limit is hit. Supports keep-alive.

api-reference/introduction.mdx

@@ -1,15 +1,66 @@
 ---
-title: 'Overview'
-description: 'General guidelines on using our API'
+title: API reference
+description: HTTP endpoints for ingesting traces, sessions, datasets, evals, and querying data.
 ---
 
-## General
+Use the REST API to ingest traces/browser sessions, manage datasets/evals, and query your Laminar data. Authentication depends on the endpoint (ingest or default project key). See the left sidebar for all routes.
 
-Use the following base URL: `https://api.lmnr.ai/v1`
+## Base URL
 
-For example, `POST https://api.lmnr.ai/v1/sql/query`
+```
+https://api.lmnr.ai/v1
+```
 
-For more detailed information about each endpoint or schema, check our OpenAPI specification.
+## Auth notes
+
+- `/v1/traces`, `/v1/metrics`, `/v1/browser-sessions/events` allow ingest-only **or** default API keys.
+- Other `/v1/*` routes require default project API keys.
+- `/api/v1/projects/{project_id}/...` assume auth is handled upstream (frontend middleware).
+
+## Ingestion (/v1, ingest or default key)
+
+- `POST /v1/traces` — OTLP `ExportTraceServiceRequest` bytes; enqueues spans; `403` when workspace data limit hit; keep-alive supported.
+- `POST /v1/browser-sessions/events` — JSON `{events:[{type,timestamp,data(base64|bytes)}], sessionId, traceId, source?, sdkVersion?}`; `400` if `traceId` is nil UUID, `403` on data limit; publishes to MQ.
+- `POST /v1/metrics` — placeholder; returns `200 OK` for OTLP metrics posts.
+
+## Tracing / datasets / evals (/v1, default keys)
+
+- Tags: `POST /v1/tag` with `{"names":[...],"traceId":UUID}` or `{"names":[...],"spanId":UUID}`; resolves top span if only traceId given; returns `{id, spanId}` list.
+- Datasets:
+  - `GET /v1/datasets?id?&name?` — list datasets
+  - `GET /v1/datasets/datapoints?...` — paginated datapoints
+  - `POST /v1/datasets/datapoints` — create dataset (optional) and insert datapoints
+  - `GET /v1/datasets/{datasetId}/parquets/{idx}` — stream parquet from export bucket
+- Evals:
+  - `POST /v1/evals` — create evaluation (name?, groupName?, metadata?)
+  - `POST /v1/evals/{evalId}/datapoints` — bulk save datapoints
+  - `POST /v1/evals/{evalId}/datapoints/{datapointId}` — update one datapoint
+- Evaluator scores: `POST /v1/evaluators/score` with `{"name","score","source","metadata?","traceId"|"spanId"}`; resolves span and writes score.
+- SQL & payloads:
+  - `POST /v1/sql/query` — body `{query}`; returns `{data:[...]}`
+  - `GET /v1/payloads/{payloadId}?payloadType=image|raw` — stream stored payload
+
+## Project-scoped (`/api/v1/projects/{project_id}`)
+
+- Spans: `POST .../spans` to enqueue a span; `POST .../spans/search` to query spans (Quickwit).
+- SQL helpers: `POST .../sql/query|validate|to-json|from-json` for query execution/translation.
+- Evaluation analytics: `GET .../evaluation-score-stats` and `GET .../evaluation-score-distribution` for score summaries.
+- Realtime SSE: `GET .../realtime?key=traces|trace_{traceId}` opens a project SSE stream.
+
+## Health and gRPC
+
+- `GET /health` and `GET /ready` check RabbitMQ (consumer health checks worker counts).
+- OTLP gRPC trace ingestion: `TraceService/Export` on gRPC port (default 8001) with Bearer API key (ingest or default); enforces usage limits.
+
+## Reference endpoints
+
+- [Trigger or update an evaluation run](/api-reference/evals/init_eval) — `POST /v1/evals`
+- [Add evaluation datapoints](/api-reference/evals/save_eval_datapoints) — `POST /v1/evals/{eval_id}/datapoints`
+- [Update a specific datapoint](/api-reference/evals/update_eval_datapoint) — `POST /v1/evals/{eval_id}/datapoints/{datapoint_id}`
+- [Score via evaluator](/api-reference/evaluators/score) — `POST /v1/evaluators/score`
+- [Run a SQL query against Laminar data](/api-reference/sql/sql_query) — `POST /v1/sql/query`
+
+See the OpenAPI spec for full schemas.
 
 <Card
   title="Laminar OpenAPI specification"
@@ -19,16 +70,17 @@ For more detailed information about each endpoint or schema, check our OpenAPI s
   Full OpenAPI specification file
 </Card>
 
-Each endpoint's page in OpenAPI specification specifies the method, path and parameters to be used. Additionally, you can try sending the request from there.
-
 ## Authentication
 
-All API endpoints are authenticated using Project API key as Bearer token.
-
-To get the token, go to "settings" page and move to "Project API keys" section. Then get a token from there or generate a new one.
+Send your `LMNR_PROJECT_API_KEY` as a Bearer token.
 
-Note that each project has different Project API keys. For switching between projects, press "Laminar" icon at the top-left of the dashboard.
+```bash
+curl -X POST https://api.lmnr.ai/v1/sql/query \
+  -H "Authorization: Bearer $LMNR_PROJECT_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"SELECT * FROM spans LIMIT 1"}'
+```
 
-<Frame caption="Press settings on the navbar and go to Project API Keys section">
-<img width="1000" src="/images/api-reference/project-api-key.png" alt="Project API key bearer tokens" />
+<Frame caption="Project API keys">
+  <img width="1000" src="/images/api-reference/project-api-key.png" alt="Project API key bearer tokens" />
 </Frame>

api-reference/openapi.json

@@ -22,7 +22,7 @@
     "/v1/queues/push": {
       "post": {
         "tags": [
-          "api::queues"
+          "Queues"
         ],
         "operationId": "push_to_queue",
         "requestBody": {
@@ -75,7 +75,7 @@
     "/v1/evals": {
       "post": {
         "tags": [
-          "api::evaluations"
+          "Evals"
         ],
         "operationId": "init_eval",
         "requestBody": {
@@ -127,7 +127,7 @@
     "/v1/evals/{eval_id}/datapoints": {
       "post": {
         "tags": [
-          "api::evaluations"
+          "Evals"
         ],
         "operationId": "save_eval_datapoints",
         "parameters": [
@@ -204,7 +204,7 @@
     "/v1/evals/{eval_id}/datapoints/{datapoint_id}": {
       "post": {
         "tags": [
-          "api::evaluations"
+          "Evals"
         ],
         "operationId": "update_eval_datapoint",
         "parameters": [
@@ -291,7 +291,7 @@
     "/v1/evaluators/score": {
       "post": {
         "tags": [
-          "api::evaluators"
+          "Evaluators"
         ],
         "operationId": "create_evaluator_score",
         "requestBody": {
@@ -339,7 +339,7 @@
     "/v1/sql/query": {
       "post": {
         "tags": [
-          "api::sql"
+          "SQL"
         ],
         "operationId": "sql_query",
         "requestBody": {

api-reference/payloads/get_payload.mdx

@@ -0,0 +1,9 @@
+---
+title: "Get payload"
+method: GET
+path: /v1/payloads/{payloadId}
+openapi: "GET /v1/payloads/{payloadId}"
+description: Stream a stored payload (image or raw).
+---
+
+Retrieve a stored payload. Use `payloadType=image|raw` query param to control content type.

api-reference/projects/eval_score_distribution.mdx

@@ -0,0 +1,9 @@
+---
+title: "Evaluation score distribution"
+method: GET
+path: /api/v1/projects/{project_id}/evaluation-score-distribution
+openapi: "GET /api/v1/projects/{project_id}/evaluation-score-distribution"
+description: Score distribution across buckets.
+---
+
+Get score distribution for one or more evaluations. Query params: `evaluationIds` (comma-separated UUIDs), `scoreName`.

api-reference/projects/eval_score_stats.mdx

@@ -0,0 +1,9 @@
+---
+title: "Evaluation score stats"
+method: GET
+path: /api/v1/projects/{project_id}/evaluation-score-stats
+openapi: "GET /api/v1/projects/{project_id}/evaluation-score-stats"
+description: Average score for an evaluation.
+---
+
+Get average score value for an evaluation. Query params: `evaluationId`, `scoreName`.

api-reference/projects/realtime.mdx

@@ -0,0 +1,9 @@
+---
+title: "Realtime SSE"
+method: GET
+path: /api/v1/projects/{project_id}/realtime
+openapi: "GET /api/v1/projects/{project_id}/realtime"
+description: Open a project SSE stream.
+---
+
+Open a server-sent events stream. Query param `key=traces|trace_{traceId}` selects the stream.

api-reference/projects/spans.mdx

@@ -0,0 +1,10 @@
+---
+title: "Project spans"
+method: POST
+path: /api/v1/projects/{project_id}/spans
+openapi: "POST /api/v1/projects/{project_id}/spans"
+description: Enqueue a span for a project.
+---
+
+Body: `{name, spanType?, startTime, endTime, attributes?, traceId?, parentSpanId?}`.  
+Returns `{spanId, traceId}`.

api-reference/projects/spans_search.mdx

@@ -0,0 +1,10 @@
+---
+title: "Search spans"
+method: POST
+path: /api/v1/projects/{project_id}/spans/search
+openapi: "POST /api/v1/projects/{project_id}/spans/search"
+description: Search spans for a project.
+---
+
+Body: `{traceId?, searchQuery, startTime?, endTime?, searchIn?, limit, offset}`.  
+Returns hits `{trace_id, span_id}` from Quickwit.

api-reference/projects/sql_from_json.mdx

@@ -0,0 +1,9 @@
+---
+title: "SQL from JSON"
+method: POST
+path: /api/v1/projects/{project_id}/sql/from-json
+openapi: "POST /api/v1/projects/{project_id}/sql/from-json"
+description: Convert a JSON query structure to SQL.
+---
+
+Body: `{queryStructure}`. Returns `{success, sql?, error?}`.