KalmiaKalmia
Back to docs

API Reference

REST API

All endpoints are served from your Kalmia instance. Replace localhost:3000 with your deployed URL in production.

Proxy Endpoints

Forward LLM requests through Kalmia to automatically capture traces.

POST/api/v1/chat/completions

OpenAI-compatible proxy. Forwards to api.openai.com and captures a trace for each request.

POST/api/v1/messages

Anthropic-compatible proxy. Forwards to api.anthropic.com and captures a trace for each request.

Trace Endpoints

Ingest, list, and search traces.

POST/api/v1/traces/ingest

Ingest pre-built trace objects. Accepts a single trace or an array of traces.

GET/api/v1/traces

List captured traces. Supports ?project= and ?provider= query filters.

POST/api/traces/search

Full-text search across trace content. Returns matching traces with relevance scores.

Experiment Endpoints

Register experiments and fetch aggregated trace data.

POST/api/experiments

Register a new experiment. Pass a name and an array of correlationIds to group traces.

GET/api/experiments

List all experiments in the current workspace.

GET/api/experiments/:batchId

Fetch a single experiment with live trace data from Braintrust. Includes preprocessed metrics.

POST/api/experiments/:batchId/analysis

Run AI-powered analysis on experiment traces. Returns insights about agent behavior.

Braintrust Trace Endpoints

Fetch traces directly from your Braintrust project.

GET/api/braintrust/traces

List recent traces from Braintrust. Supports pagination and project filters.

GET/api/braintrust/traces/:id

Fetch a single trace by ID with full span data.

Annotations & Behaviors

Create behavior definitions and annotate traces.

GET/api/behaviors

List all behavior definitions for the current workspace.

POST/api/behaviors

Create a new behavior definition with a label and plain-language description.

GET/api/annotations

List annotations. Supports ?trace_id= and ?label= filters.

POST/api/annotations

Create an annotation on a trace. Includes label, confidence, and optional notes.

POST/api/behaviors/detect

Run AI-powered behavior detection on a set of traces. Auto-creates annotations on matches.

Example: Register an Experiment

curl -X POST https://your-kalmia.app/api/experiments \
  -H "Content-Type: application/json" \
  -d '{
    "name": "RAG vs no-RAG",
    "correlationIds": [
      "run-abc-123",
      "run-def-456"
    ]
  }'
{
  "id": "exp-uuid-789",
  "name": "RAG vs no-RAG",
  "correlationIds": ["run-abc-123", "run-def-456"],
  "createdAt": "2026-03-01T..."
}