API Reference

REST API endpoints for Kalibr observability platform.

Base URL: https://api.kalibr.systems

Authentication

All requests require an API key in the X-API-Key header:

X-API-Key: sk_live_...

Ingestion

POST/api/ingest

Ingest trace events. Supports NDJSON (default) and JSON formats.

Headers

Header	Value
`X-API-Key`	Your API key
`Content-Type`	`application/x-ndjson` or `application/json`

NDJSON Body (Recommended)

{"trace_id":"abc","span_id":"123","provider":"openai","model_id":"gpt-4o","operation":"chat","duration_ms":250,"input_tokens":100,"output_tokens":50,"cost_usd":0.001,"status":"success","tenant_id":"my-tenant","timestamp":"2025-01-15T12:00:00Z","schema_version":"1.0"}
{"trace_id":"def","span_id":"456",...}

JSON Body

{
  "events": [
    {
      "trace_id": "abc",
      "span_id": "123",
      "provider": "openai",
      "model_id": "gpt-4o",
      ...
    }
  ]
}

Event Schema v1.0

Field	Type	Required	Description
`schema_version`	string	Yes	Always "1.0"
`trace_id`	string	Yes	Trace identifier
`span_id`	string	Yes	Span identifier
`parent_span_id`	string	No	Parent span for nesting
`tenant_id`	string	Yes	Tenant identifier
`provider`	string	Yes	LLM provider
`model_id`	string	Yes	Model name
`operation`	string	Yes	Operation type
`duration_ms`	number	Yes	Duration in milliseconds
`input_tokens`	number	Yes	Input token count
`output_tokens`	number	Yes	Output token count
`cost_usd`	number	Yes	Cost in USD
`status`	string	Yes	success, error, timeout
`timestamp`	string	Yes	ISO 8601 timestamp
`environment`	string	No	prod, staging, dev
`service`	string	No	Service name
`workflow_id`	string	No	Workflow identifier
`error_type`	string	No	Error class name
`error_message`	string	No	Error message
`metadata`	object	No	Custom metadata

Traces

GET/api/otel/spans

Query spans with filters.

Query Parameters

Parameter	Type	Description
`vendor`	string	Filter by provider
`model`	string	Filter by model (partial match)
`trace_id`	string	Filter by trace ID
`start_time`	datetime	Start of time range
`end_time`	datetime	End of time range
`min_cost`	number	Minimum cost filter
`max_cost`	number	Maximum cost filter
`status`	string	Filter by status
`limit`	number	Max results (default: 100)
`offset`	number	Pagination offset

GET/api/otel/traces/{trace_id}

Get all spans for a specific trace.

GET/api/otel/metrics

Get aggregated metrics (cost, latency, tokens by provider/model).

GET/api/otel/comparison

Multi-provider comparison data for dashboard.

Intelligence

Base URL: https://kalibr-intelligence.fly.dev/api/v1/intelligence

POST/policy

Get model recommendation for a goal.

{
  "goal": "book_meeting",
  "task_type": "scheduling",    // optional
  "constraints": {              // optional
    "max_cost_usd": 0.05,
    "max_latency_ms": 3000
  },
  "window_hours": 168           // optional, default 1 week
}

POST/report-outcome

Report execution outcome.

{
  "trace_id": "abc123",
  "goal": "book_meeting",
  "success": true,
  "score": 0.9,                 // optional
  "failure_reason": "timeout",  // optional
  "metadata": {}                // optional
}

POST/recommend

Get model recommendation by task type.

{
  "task_type": "summarization",
  "optimize_for": "balanced",   // cost, quality, latency, balanced
  "constraints": {}
}

GET/patterns/{task_type}

Get aggregated patterns for a task type.

POST/compare

Compare specific models.

GET/health

Health check.

Error Responses

Status	Description
400	Bad request (validation error)
401	Unauthorized (invalid API key)
403	Forbidden (tier restriction)
404	Not found
429	Rate limited
500	Server error

Rate Limits

Tier	Limit
Free	100 req/min
Pro	500 req/min
Enterprise	Custom

Next Steps

Python SDK — SDK documentation
System Architecture — How it works