API Reference

The SentinelAI REST API is a FastAPI service. This page is the canonical reference — you do not need to visit any external API docs.

Base URL

Deployment	Base URL
Managed cloud	`https://sentinel-ai-dml3.onrender.com`
Self-hosted	`http://localhost:8000`

Interactive OpenAPI docs remain available at <base_url>/api/docs for your instance, but everything you need is documented here.

Authentication

Every request must include an API key:

Authorization: Bearer sk_...

Endpoints

`POST /api/analyze`

The core risk-analysis endpoint.

Request body

{
  "prompt": "Summarize the Q3 report",
  "response": "Revenue grew 45% year over year."
}

Field	Type	Required	Description
`prompt`	`string`	yes	The user prompt
`response`	`string`	yes	The model's response to score

Response

{
  "final_risk_score": 0.72,
  "flags": ["violence", "harmful_instructions"],
  "confidence": 0.88,
  "decision": "block",
  "action_taken": "block",
  "decision_reason": "Multiple high-severity output risk categories triggered",
  "settings_version": 3,
  "thresholds_applied": {"block": 0.6},
  "log_id": "analysis-241"
}

Field	Type	Description
`final_risk_score`	`float`	Aggregated risk score, 0–1
`flags`	`array`	Triggered detectors and risk categories (e.g. `prompt_anomaly`, `jailbreak_detected`, `unsafe_output`, `violence`)
`confidence`	`float \| null`	Confidence of the risk classification
`decision`	`string`	`allow`, `warn`, `block`, or `escalate`
`action_taken`	`string`	The action executed by the policy engine
`decision_reason`	`string`	Human-readable explanation from the risk reasoner
`settings_version`	`int \| null`	Which policy version produced this verdict
`thresholds_applied`	`any \| null`	The exact thresholds used
`log_id`	`string \| null`	ID for feedback reporting

Status codes

Code	Meaning
`200`	Analysis complete
`401`	Missing or invalid API key
`422`	Invalid request body
`429`	Rate limit exceeded
`500`	Internal error — your prompt/response was never served unverified

`POST /api/analyze/external`

The endpoint the Python SDK calls. Extends /api/analyze with source (your application identifier), plus optional user_id, session_id, and client_metadata for per-user/session tracking.

`GET /api/logs`

Full interaction audit trail — every analyzed pair with score and disposition.

`GET /api/settings`

Current detection rules configuration.

`POST /api/settings`

Update detection rules. Every change is versioned.

`GET /api/settings/history`

Version history of your detection policy — see exactly what policy was active when any score was produced.

`GET /api/baselines` · `POST /api/baselines`

Stored baseline profiles for distribution-shift detection — flag when production traffic drifts from the norm.

Organization usage endpoints

The following endpoints return per-organization usage and risk data. All require the usage.view permission and a valid Authorization: Bearer sk_... header.

Paths use {org_id} — the organization identifier resolved from the request.

`GET /api/orgs/{org_id}/usage`

Aggregated usage for an organization. Accepts an optional days query parameter (default 30, range 1–365) controlling the aggregation window.

Query parameters

Parameter	Type	Default	Range	Description
`days`	`int`	`30`	`1`–`365`	Aggregation window in days

Response

{
  "total_requests": 1280,
  "requests_24h": 45,
  "success_count": 1263,
  "success_rate": 98.67,
  "error_count": 17,
  "error_rate": 1.33,
  "avg_latency_ms": 142.5
}

Field	Type	Description
`total_requests`	`int`	Total analyzed events for the org
`requests_24h`	`int`	Events in the last 24 hours
`success_count`	`int`	Events that completed successfully
`success_rate`	`float`	Success percentage, 0–100
`error_count`	`int`	Failed events
`error_rate`	`float`	Error percentage, 0–100
`avg_latency_ms`	`float \| null`	Mean latency in milliseconds

`GET /api/orgs/{org_id}/usage/stats`

Dashboard usage statistics for an organization. Returns the same aggregated usage shape as /usage, optimized for dashboard widgets.

`GET /api/orgs/{org_id}/usage/trend`

Daily risk trend buckets for an organization — the data source for the dashboard Risk Trend chart. Returns one bucket per day across the requested window, ordered chronologically.

Query parameters

Parameter	Type	Default	Range	Description
`days`	`int`	`30`	`1`–`365`	Number of daily buckets to return

Response

A JSON array of daily buckets:

[
  {
    "date": "2026-08-01",
    "avg_risk_score": 0.23,
    "event_count": 45,
    "critical_count": 2
  },
  {
    "date": "2026-08-02",
    "avg_risk_score": 0.31,
    "event_count": 52,
    "critical_count": 4
  }
]

Field	Type	Description
`date`	`string`	ISO date (`YYYY-MM-DD`) of the bucket
`avg_risk_score`	`float`	Mean risk score for the day, 0–1
`event_count`	`int`	Total events recorded that day
`critical_count`	`int`	Events that reached critical risk threshold

Status codes

Code	Meaning
`200`	Trend buckets returned
`401`	Missing or invalid API key
`403`	Caller lacks `usage.view` permission for this org
`422`	`days` outside the allowed 1–365 range

Example (curl)

curl -H "Authorization: Bearer sk_..." \
  "https://sentinel-ai-dml3.onrender.com/api/orgs/42/usage/trend?days=30"

SDK

The Python SDK wraps these endpoints with retries, timeouts, and error handling.

pip install sentinelai-risk

from sentinelai import SentinelAIClient

client = SentinelAIClient(api_key="sk_...")
result = client.verify(prompt=prompt, response=llm_output)

SDK reference

Fields, options, conversation context

Quick start

End-to-end in 60 seconds

API Reference

SDK reference

Quick start

On this page