API reference

Ingestion API

The Clairist ingestion API accepts structured JSON events over HTTPS. Most users should use the official SDK, but you can also call the API directly from any environment that can make HTTP requests.

Endpoint

All events are sent as POST requests to:

POST https://api.clairist.com/v1/events

If you are using a self-hosted or regional deployment, your base URL may differ. Set CLAIRIST_INGEST_URL or configure baseUrl in the SDK to point at the correct origin.

Authentication

Requests are authenticated with a Bearer token. Use an ingestion API key created from Settings > API keys.

Authorization: Bearer <CLAIRIST_API_KEY>
Content-Type: application/json

Event schema

The API accepts a union of event types. Each event has a type field that determines the rest of the payload.

Model call event

{
  "type": "model_call",
  "system_id": "support-assistant",
  "model_id": "gpt-4.1-mini",
  "request_count": 1,
  "token_usage": 1024,
  "prompt": "User input...",
  "response": "Model output...",
  "latency_ms": 320,
  "metadata": {
    "route": "/api/chat",
    "tenant_id": "tenant_123"
  }
}

Prompt event

{
  "type": "prompt",
  "team_id": "team_123",
  "actor_id": "user_456",
  "scope": "ai_assistant",
  "action": "prompt_logged",
  "channel": "web",
  "subject_id": "conversation_789",
  "prompt": "User message...",
  "response": "Assistant reply...",
  "metadata": {
    "locale": "en-US"
  }
}

Incident event

{
  "type": "incident",
  "team_id": "team_123",
  "level": "error",
  "title": "PII detected in model output",
  "message": "The redaction pipeline missed PII in 3 responses.",
  "incident_id": "incident_001",
  "lifecycle_type": "critical_alert",
  "actor_id": null,
  "metadata": {
    "pipeline": "redaction-v2",
    "sample_size": 100
  }
}

Evidence event

{
  "type": "evidence",
  "team_id": "team_123",
  "subject_id": "incident_001",
  "actor_id": null,
  "scope": "ai_governance",
  "action": "evidence_attached",
  "channel": "api",
  "metadata": {
    "control": "human-review"
  },
  "evidence": [
    {
      "kind": "policy",
      "body_text": "AI incident response runbook v1.0"
    },
    {
      "kind": "link",
      "body_json": {
        "url": "https://example.com/incidents/001"
      }
    }
  ]
}

Example request (cURL)

curl -X POST "https://api.clairist.com/v1/events" \
  -H "Authorization: Bearer $CLAIRIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "model_call",
    "system_id": "support-assistant",
    "model_id": "gpt-4.1-mini",
    "request_count": 1,
    "token_usage": 1024
  }'