API Reference

The MindReef REST API allows you to ingest traces, query data, and manage your workspace programmatically. All endpoints require authentication via API key.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer mr_live_your_api_key_here

Base URL

https://api.mindreef.com/v1

Trace Endpoints

POST /traces

Ingest a batch of traces and spans.

Request Body:

{
    "traces": [
        {
            "trace_id": "abc123",
            "name": "my_agent",
            "start_time": "2025-01-15T10:30:00Z",
            "end_time": "2025-01-15T10:30:02Z",
            "status": "success",
            "spans": [...]
        }
    ]
}

Response: 201 Created

GET /traces

Query traces with filters.

Query Parameters:

  • agent - Filter by agent name
  • status - Filter by status (success, error)
  • start_time - ISO timestamp for range start
  • end_time - ISO timestamp for range end
  • limit - Max results (default 100)
  • offset - Pagination offset

Response:

{
    "traces": [...],
    "total": 1234,
    "limit": 100,
    "offset": 0
}

GET /traces/{trace_id}

Get a single trace with all spans.

Response:

{
    "trace_id": "abc123",
    "name": "my_agent",
    "spans": [...],
    "hallucination_analysis": {...}
}

Metrics Endpoints

GET /metrics

Query aggregated metrics.

Query Parameters:

  • metric - Metric name (e.g., trace.latency.p95)
  • agent - Filter by agent
  • start_time - Range start
  • end_time - Range end
  • interval - Aggregation interval (1m, 5m, 1h, 1d)

Agent Endpoints

GET /agents

List all agents in your workspace.

GET /agents/{agent_id}

Get agent details and recent statistics.

WebSocket API

Connect to the WebSocket endpoint for real-time trace streaming:

wss://api.mindreef.com/v1/live?token=mr_live_xxx

Messages are JSON objects representing new traces and spans as they arrive.

Rate Limits

Rate limit headers are included in all responses:

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

Error Responses

Errors return appropriate HTTP status codes with a JSON body:

{
    "error": {
        "code": "invalid_request",
        "message": "Missing required field: trace_id"
    }
}