ReferenceBack to Docs

API Reference

REST API for telemetry ingestion, aggregated querying, and real-time event streaming.

Base URL

https://skillstrace.dev

All endpoints accept and return JSON. Authentication is via Bearer token when an API key is configured.

POST

/api/telemetry

Ingest one or more telemetry events. Accepts a single event object or an array of events.

Authentication

Required when SKILLS_TRACE_API_KEY is configured.

Authorization: Bearer sk_trace_...

Request Body

{
  "skillId": "skill://acme/pr-review",
  "version": "1.2.0",
  "detection": "watermark",
  "confidence": 1.0,
  "timestamp": "2026-03-09T10:00:00Z",
  "agentId": "dev-assistant",
  "model": "gpt-4.1",
  "environment": "production",
  "tokensIn": 1420,
  "tokensOut": 310,
  "latencyMs": 2100,
  "team": "platform",
  "project": "agent-v2",
  "tenantId": "acme-corp"
}

Response

201Events ingested successfully
{ "ingested": 1 }
400Invalid payload — missing required fields or malformed JSON
401Unauthorized — missing or invalid API key

curl Example

curl -X POST https://skillstrace.dev/api/telemetry \
  -H "Authorization: Bearer sk_trace_..." \
  -H "Content-Type: application/json" \
  -d '{
    "skillId": "skill://acme/pr-review",
    "version": "1.2.0",
    "detection": "watermark",
    "confidence": 1.0,
    "timestamp": "2026-03-09T10:00:00Z"
  }'
GET

/api/telemetry/query

Query aggregated telemetry metrics. Returns pre-computed summaries for dashboard widgets and reporting.

Query Parameters

ParameterRequiredDescription
typeRequiredQuery type: usage, cost, drift, risk, or overview.
rangeOptionalTime range filter (e.g., 7d, 30d, 90d).
environmentOptionalFilter results by environment (e.g., production, staging).

Response Example (type=overview)

{
  "totalSkills": 42,
  "totalDetections": 12847,
  "topSkill": {
    "skillId": "acme/pr-review",
    "count": 3241
  },
  "avgLatencyMs": 8.3
}

curl Example

curl "https://skillstrace.dev/api/telemetry/query?type=overview&range=7d" \
  -H "Authorization: Bearer sk_trace_..."
GET

/api/telemetry/stream

Real-time Server-Sent Events (SSE) stream of telemetry events. Ideal for live dashboards and monitoring tools.

Response Format

The endpoint returns an SSE stream. Each event is a JSON object prefixed with data:.

data: {"skillId":"skill://acme/pr-review","version":"1.2.0","detection":"watermark","confidence":1.0,"timestamp":"2026-03-09T10:00:01Z"}

data: {"skillId":"skill://acme/code-gen","version":"2.0.0","detection":"frontmatter-hash","confidence":0.9,"timestamp":"2026-03-09T10:00:03Z"}

curl Example

curl -N https://skillstrace.dev/api/telemetry/stream

JavaScript Example

const source = new EventSource('/api/telemetry/stream');

source.onmessage = (event) => {
  const detection = JSON.parse(event.data);
  // Handle real-time detection event
};
Getting StartedBack to Documentation