REST API

Complete REST API reference.

Complete reference for the Risicare REST API.

Base URL

https://app.risicare.ai/v1

Authentication

All requests require Bearer token authentication:

curl -H "Authorization: Bearer rsk-..."

Traces

List Traces

GET /v1/traces

Query parameters:

Parameter	Type	Description
`limit`	int	Max results (default 50)
`cursor`	string	Pagination cursor
`status`	string	Filter by status
`agent`	string	Filter by agent name
`start_time`	ISO8601	Start of time range
`end_time`	ISO8601	End of time range

Get Trace

GET /v1/traces/{trace_id}

Response includes full span tree.

Sessions

List Sessions

GET /v1/sessions

Get Session

GET /v1/sessions/{session_id}

Response includes all traces in session.

Agents

List Agents

GET /v1/agents

Returns agent performance statistics.

Get Agent

GET /v1/agents/{agent_id}

Diagnoses

List Diagnoses

GET /v1/diagnoses

Get Diagnosis

GET /v1/diagnoses/{diagnosis_id}

Trigger Diagnosis

POST /v1/diagnoses
Content-Type: application/json
 
{
  "trace_id": "trace-abc123"
}

Fixes

List Fixes

GET /v1/fixes

Get Fix

GET /v1/fixes/{fix_id}

Create Fix

POST /v1/fixes
Content-Type: application/json
 
{
  "type": "retry",
  "target": {
    "error_codes": ["TOOL.EXECUTION.TIMEOUT"]
  },
  "config": {
    "max_retries": 3,
    "initial_delay_ms": 1000,
    "exponential_base": 2.0,
    "max_delay_ms": 30000,
    "jitter": true,
    "retry_on": []
  }
}

Update Fix

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

Deployments

List Deployments

GET /v1/deployments

Get Deployment

GET /v1/deployments/{deployment_id}

Create Deployment

POST /v1/deployments
Content-Type: application/json
 
{
  "fix_id": "fix-abc123",
  "stage": "canary"
}

Rollback Deployment

DELETE /v1/deployments/{deployment_id}
Content-Type: application/json
 
{
  "reason": "Manual rollback"
}

Projects

List Projects

GET /v1/projects

Update Project

PATCH /v1/projects/{project_id}
Content-Type: application/json
 
{
  "settings": {
    "retention_days": 90
  }
}

API Keys

List Keys

GET /v1/api-keys

Create Key

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

The key is automatically scoped to the project associated with the API key used for authentication. To create a key for a different project within your organization, pass projectId:

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

Revoke Key

DELETE /v1/api-keys/{key_id}

Evaluations

List Evaluations

GET /v1/evaluations

Query parameters:

Parameter	Type	Description
`trace_id`	string	Filter by trace
`scorer`	string	Filter by scorer name
`passed`	boolean	Filter by pass/fail

Get Evaluation

GET /v1/evaluations/{evaluation_id}

Create Evaluation

POST /v1/evaluations
Content-Type: application/json
 
{
  "trace_id": "trace-abc123",
  "scorers": ["faithfulness", "toxicity", "g_eval"]
}

Datasets

List Datasets

GET /v1/datasets

Get Dataset

GET /v1/datasets/{dataset_id}

Create Dataset

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

Add Examples

POST /v1/datasets/{dataset_id}/examples
Content-Type: application/json
 
{
  "examples": [
    {"input": "What is AI?", "expected": "Artificial Intelligence..."}
  ]
}

Alerts

List Alerts

GET /v1/alerts

Create Alert

POST /v1/alerts
Content-Type: application/json
 
{
  "name": "High Error Rate",
  "condition": {
    "metric": "error_rate",
    "operator": "gt",
    "threshold": 0.1
  },
  "channels": ["slack"],
  "webhook_url": "https://hooks.slack.com/..."
}

Update Alert

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

Webhooks

List Webhooks

GET /v1/webhooks

Create Webhook

POST /v1/webhooks
Content-Type: application/json
 
{
  "url": "https://your-server.com/risicare-webhook",
  "events": ["trace.completed", "diagnosis.created", "fix.deployed"],
  "secret": "your-webhook-secret"
}

Delete Webhook

DELETE /v1/webhooks/{webhook_id}

Agent Topology

Get Topology

GET /v1/agents/topology

Returns the agent interaction graph:

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

Gateway Endpoints

SDK-facing endpoints for span ingestion:

Single Span

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": {...}
}

Batch Spans

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

Trace Ingestion

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

Event Ingestion

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}
}

OTLP Ingestion

POST /v1/otlp/v1/traces
Content-Type: application/x-protobuf
Authorization: Bearer rsk-...
 
<OTLP protobuf data>

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:00:00Z"
}

Pagination

All list endpoints support cursor-based pagination:

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

Response includes pagination info:

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6ImRlZjQ1NiJ9",
    "has_more": true
  }
}

Error Responses

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

Code	HTTP Status	Description
`invalid_request`	400	Malformed request
`unauthorized`	401	Invalid API key
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource not found
`rate_limited`	429	Too many requests
`internal_error`	500	Server error

Rate Limits

Headers included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1705312800

When rate limited:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Next Steps

Python SDK Reference

Complete Python SDK reference

Learn more

JS SDK Reference

TypeScript and JavaScript SDK reference

Learn more

PreviousJavaScript SDK