API Overview

The SideSeat REST API provides programmatic access to run data (traces), session management, and real-time streaming.

Base URL

All API endpoints are prefixed with /api/v1/project/{project_id}/otel.

http://localhost:5388/api/v1/project/default/otel

The default project ID is default.

Authentication

When authentication is enabled, include a Bearer token in requests:

curl -H "Authorization: Bearer your-token" \
  http://localhost:5388/api/v1/project/default/otel/traces

See Authentication for details on obtaining tokens.

Pagination

List endpoints use page-based pagination.

Query Parameters:

page - Page number (default: 1)
limit - Items per page (default: 50)

Response Fields:

data - Array of results
meta - Pagination metadata (page, limit, total_items, total_pages)

# First page
curl "http://localhost:5388/api/v1/project/default/otel/traces?page=1&limit=20"

# Next page
curl "http://localhost:5388/api/v1/project/default/otel/traces?page=2&limit=20"

Error Responses

All errors follow a consistent format:

{
  "error": "error_type",
  "code": "ERROR_CODE",
  "message": "Human-readable error message"
}

Common Error Codes:

Code	HTTP Status	Description
`TRACE_NOT_FOUND`	404	Trace does not exist
`SPAN_NOT_FOUND`	404	Span does not exist
`SESSION_NOT_FOUND`	404	Session does not exist
`STORAGE_ERROR`	500	Database error
`AUTH_REQUIRED`	401	Authentication required
`TOKEN_EXPIRED`	401	Token has expired

Endpoints

Endpoint	Description	Docs
`GET /traces`	List traces	Traces
`GET /traces/{id}`	Get trace	Traces
`GET /traces/{id}/messages`	Get trace messages	Traces
`GET /spans`	List spans	Spans
`GET /traces/{trace_id}/spans/{span_id}`	Get span	Spans
`GET /sessions`	List sessions	Sessions
`GET /sessions/{id}`	Get session	Sessions
`GET /sse`	Real-time stream	SSE

Health Check

GET /api/v1/health

Returns server health status:

{
  "status": "ok",
  "version": "1.0.5"
}

OTLP Ingestion

Traces are ingested via OTLP endpoints:

POST /otel/{project_id}/v1/traces
POST /otel/{project_id}/v1/metrics
POST /otel/{project_id}/v1/logs

See OpenTelemetry Reference for ingestion details.