API Reference

The TraceVault server exposes a REST API for programmatic access to traces, sessions, and configuration.

Authentication

All API requests require a bearer token:

curl -H "Authorization: Bearer <token>" \
  https://your-server.example.com/api/v1/sessions

Endpoints

Sessions

List sessions

GET /api/v1/sessions

Response:

{
  "sessions": [
    {
      "id": "sess_abc123",
      "author": "alice",
      "repo": "myproject",
      "started_at": "2025-01-15T10:30:00Z",
      "duration_secs": 342,
      "tool": "claude-code",
      "summary": "Refactored auth module"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Get session details

GET /api/v1/sessions/:id

Response:

{
  "id": "sess_abc123",
  "author": "alice",
  "repo": "myproject",
  "started_at": "2025-01-15T10:30:00Z",
  "ended_at": "2025-01-15T10:35:42Z",
  "tool": "claude-code",
  "messages": [
    {
      "role": "user",
      "content": "Refactor the auth module to use JWT",
      "timestamp": "2025-01-15T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "I'll refactor the auth module...",
      "timestamp": "2025-01-15T10:30:05Z"
    }
  ],
  "file_changes": [
    {
      "path": "src/auth.rs",
      "action": "modified",
      "additions": 45,
      "deletions": 12
    }
  ]
}

Traces

Push traces

POST /api/v1/traces

Request body:

{
  "repo": "myproject",
  "sessions": [
    {
      "id": "sess_abc123",
      "data": "..."
    }
  ]
}

Response:

{
  "accepted": 1,
  "rejected": 0
}

Policies

Get active policy

GET /api/v1/policy

Update policy

PUT /api/v1/policy
Content-Type: application/toml

Health

Health check

GET /api/v1/health

Response:

{
  "status": "ok",
  "version": "0.1.0",
  "uptime_secs": 86400
}

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "not_found",
    "message": "Session not found"
  }
}

Rate Limiting

The API enforces rate limits per token:

• Read endpoints: 100 requests/minute
• Write endpoints: 20 requests/minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312200