Schema API

The schema endpoints let administrators inspect ClickHouse, bind a trace table, and mark the columns and map keys that filters and policies may reference. All endpoints require the admin role and use session cookies or Authorization: Bearer lsk_....

POST /schema/discover

Discover ClickHouse tables, columns, maps, and sampled map keys. LightShip ranks likely trace tables to speed up binding. For map-key sampling, provide table, timestamp, maps, and optional RFC 3339 from and to bounds. When bounds are omitted, the last 24 hours are sampled. The older window duration remains accepted for API compatibility.

curl -X POST http://localhost:8080/schema/discover \
  -H "Authorization: Bearer lsk_xxxxxxxx"

GET /schema

Export the stored access model, including the current binding, marked fields, and user attributes.

curl http://localhost:8080/schema \
  -H "Authorization: Bearer lsk_xxxxxxxx"

PUT /schema/binding

Set the trace table and confirm the five required structural columns.

string

required

Fully qualified ClickHouse table name (must contain a ., for example otel.otel_traces).

string

required

Column containing the trace identifier.

string

required

Column containing the span timestamp.

string

required

Column containing the span identifier.

string

required

Column containing the parent span identifier.

string

required

Column containing the span name.

curl -X PUT http://localhost:8080/schema/binding \
  -H "Authorization: Bearer lsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "table": "otel.otel_traces",
    "trace_id": "TraceId",
    "timestamp": "Timestamp",
    "span_id": "SpanId",
    "parent_span_id": "ParentSpanId",
    "name": "SpanName"
  }'

PUT /schema/fields

Replace the entire set of marked trace fields. Fields omitted from the request are removed. User attribute keys are registered automatically when they are added to a user.

array

required

Array of field descriptors with map, name, filterable, policy, and logical_type.

curl -X PUT http://localhost:8080/schema/fields \
  -H "Authorization: Bearer lsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {"map": "SpanAttributes", "name": "gen_ai.agent.name", "filterable": true, "policy": true, "logical_type": "string"},
      {"map": "SpanArrayAttributes", "name": "langfuse.trace.tags", "filterable": true, "policy": true, "logical_type": "string_array"}
    ]
  }'

Removing a field that a stored policy still references is rejected. Update or delete the affected role first.

GET /schema/optimizations

Report missing indexes and suggested DDL for the bound table.

curl http://localhost:8080/schema/optimizations \
  -H "Authorization: Bearer lsk_xxxxxxxx"

LightShip never applies DDL automatically. Review the suggestions and run them against ClickHouse yourself.

Overview

Identity

Traces

Access Model

Observability & MCP

POST /schema/discover

GET /schema

PUT /schema/binding

PUT /schema/fields

GET /schema/optimizations

​POST /schema/discover

​GET /schema

​PUT /schema/binding

​PUT /schema/fields

​GET /schema/optimizations

POST /schema/discover

GET /schema

PUT /schema/binding

PUT /schema/fields

GET /schema/optimizations