REST API

# Canonical (used by the SDKs)
curl -H "Authorization: Bearer rsk-..."
 
# Alternative (for legacy / non-RFC-7235 clients)
curl -H "X-API-Key: rsk-..."

GET /api/v1/traces

GET /api/v1/traces/{trace_id}

DELETE /api/v1/traces/{trace_id}

GET /api/v1/sessions

GET /api/v1/sessions/{session_id}

DELETE /api/v1/sessions/{session_id}

GET /api/v1/agents

GET /api/v1/agents/{agent_id}

GET /api/v1/diagnoses

GET /api/v1/diagnoses/{diagnosis_id}

POST /api/v1/diagnoses
Content-Type: application/json
 
{
  "trace_id": "trace-abc123",
  "span_id": "span-def456"
}

GET /api/v1/fixes

GET /api/v1/fixes/{fix_id}

GET /api/v1/fixes/active

POST /api/v1/fixes
Content-Type: application/json
 
{
  "title": "Retry on tool timeout",
  "description": "Add exponential backoff retry for TOOL.EXECUTION.TIMEOUT errors",
  "fix_type": "retry",
  "error_code": "TOOL.EXECUTION.TIMEOUT",
  "fix_config": {
    "max_retries": 3,
    "initial_delay_ms": 1000,
    "exponential_base": 2.0,
    "max_delay_ms": 30000,
    "jitter": true
  },
  "confidence": 0.8
}

PATCH /api/v1/fixes/{fix_id}
Content-Type: application/json
 
{
  "status": "active"
}

POST /api/v1/fixes/{fix_id}/promote
Content-Type: application/json
 
{
  "traffic_percentage": 5.0
}

GET /api/v1/deployments

GET /api/v1/deployments/{deployment_id}

POST /api/v1/deployments
Content-Type: application/json
 
{
  "fix_id": "fix-abc123",
  "initial_traffic_percentage": 5.0
}

DELETE /api/v1/deployments/{deployment_id}?reason=Manual+rollback

GET /api/v1/projects

PATCH /api/v1/projects
Content-Type: application/json
 
{
  "settings": {
    "retention_days": 30
  }
}

GET /api/v1/api-keys

POST /api/v1/api-keys
Content-Type: application/json
 
{
  "name": "production-sdk"
}

POST /api/v1/api-keys
Content-Type: application/json
 
{
  "name": "staging-sdk",
  "projectId": "your-project-uuid"
}

DELETE /api/v1/api-keys/{key_id}

GET /api/v1/evaluations

GET /api/v1/evaluations/{evaluation_id}

POST /api/v1/evaluations
Content-Type: application/json
 
{
  "name": "Quality check v2",
  "evaluation_type": "llm_judge",
  "trace_ids": ["trace-abc123", "trace-def456"],
  "criteria": ["faithfulness", "toxicity"],
  "config": {}
}

GET /api/v1/datasets

GET /api/v1/datasets/{dataset_id}

POST /api/v1/datasets
Content-Type: application/json
 
{
  "name": "evaluation-set-v1",
  "description": "Golden test cases",
  "tags": ["production", "v1"]
}

PATCH /api/v1/datasets/{dataset_id}
Content-Type: application/json
 
{
  "description": "Updated description",
  "tags": ["production", "v2"]
}

DELETE /api/v1/datasets/{dataset_id}

GET /api/v1/alerts

POST /api/v1/alerts
Content-Type: application/json
 
{
  "name": "High Error Rate",
  "metric": "error_rate",
  "operator": "gt",
  "threshold": 0.1,
  "window_minutes": 5,
  "severity": "warning",
  "channels": ["slack"]
}

GET /api/v1/alerts/{rule_id}

PATCH /api/v1/alerts/{rule_id}
Content-Type: application/json
 
{
  "enabled": false
}

DELETE /api/v1/alerts/{rule_id}

POST /api/v1/scores
Content-Type: application/json
 
{
  "trace_id": "abc123def456789012345678abcdef01",
  "name": "accuracy",
  "score": 0.95,
  "comment": "Response matched expected output",
  "source": "api"
}

GET /api/v1/scores?trace_id={trace_id}

GET /api/v1/webhooks

GET /api/v1/webhooks/{webhook_id}

POST /api/v1/webhooks
Content-Type: application/json
 
{
  "name": "Production alerts",
  "url": "https://your-server.com/risicare-webhook",
  "events": ["trace.completed", "trace.error", "diagnosis.completed"],
  "secret": "your-webhook-secret",
  "retry_count": 3,
  "timeout_seconds": 30
}

PATCH /api/v1/webhooks/{webhook_id}
Content-Type: application/json
 
{
  "enabled": false
}

DELETE /api/v1/webhooks/{webhook_id}

GET /api/v1/agents/topology

{
  "agents": [
    {"id": "orchestrator", "role": "orchestrator", "traces": 1000},
    {"id": "researcher", "role": "worker", "traces": 2500}
  ],
  "edges": [
    {"from": "orchestrator", "to": "researcher", "count": 500, "type": "delegate"}
  ]
}

POST /api/v1/data/delete-by-subject
Content-Type: application/json
 
{
  "session_id": "user-session-abc",
  "agent_id": "support-agent",
  "trace_ids": ["trace-id-1", "trace-id-2"]
}

{
  "spans_deleted": 42,
  "sessions_deleted": 1,
  "traces_affected": 3,
  "redis_entries_purged": 0,
  "warnings": [],
  "complete": true,
  "erasure_job_id": "6f1c…",
  "stores_outstanding": []
}

HTTP/1.1 202 Accepted
Location: /v1/data/erasure-jobs/{job_id}

{
  "job_id": "6f1c…",
  "erasure_job_id": "6f1c…",
  "location": "/v1/data/erasure-jobs/6f1c…",
  "status": "running",
  "stores_outstanding": ["spans", "sessions"]
}

GET {Location}
Authorization: Bearer rsk-...

POST /v1/spans
Content-Type: application/json
Authorization: Bearer rsk-...
 
{
  "trace_id": "abc123",
  "span_id": "def456",
  "name": "llm.call",
  "start_time": "2024-01-15T10:00:00Z",
  "end_time": "2024-01-15T10:00:01Z",
  "attributes": {...}
}

POST /v1/spans/batch
Content-Type: application/json
Authorization: Bearer rsk-...
 
{
  "spans": [
    {"trace_id": "abc", "span_id": "001", ...},
    {"trace_id": "abc", "span_id": "002", ...}
  ]
}

POST /v1/traces
Content-Type: application/json
Authorization: Bearer rsk-...
 
{
  "trace_id": "abc123",
  "spans": [...],
  "metadata": {...}
}

POST /v1/events
Content-Type: application/json
Authorization: Bearer rsk-...
 
{
  "trace_id": "abc123",
  "span_id": "def456",
  "name": "user.feedback",
  "timestamp": "2024-01-15T10:00:00Z",
  "attributes": {"rating": 5}
}

POST /v1/otlp/v1/traces
Content-Type: application/json
Authorization: Bearer rsk-...
 
{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "my-agent"}}
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "traceId": "5b8efff798038103d269b633813fc60c",
              "spanId": "eee19b7ec3c1b174",
              "name": "llm.call",
              "startTimeUnixNano": "1544712660000000000",
              "endTimeUnixNano": "1544712661000000000"
            }
          ]
        }
      ]
    }
  ]
}

GET /health

GET /health/ready

GET /health/live

GET /api/v1/traces?limit=50&cursor=eyJpZCI6ImFiYzEyMyJ9

{
  "data": [...],
  "next_cursor": "eyJpZCI6ImRlZjQ1NiJ9",
  "has_more": true,
  "total_count": 1284
}

{
  "error": {
    "code": "not_found",
    "message": "Trace not found",
    "details": {
      "trace_id": "trace-abc123"
    }
  }
}