API Reference
Full reference for the SentinelAI REST API — no external docs needed
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.
SDK
The Python SDK wraps these endpoints with retries, timeouts, and error handling.
pip install sentinelai-riskfrom sentinelai import SentinelAIClient
client = SentinelAIClient(api_key="sk_...")
result = client.verify(prompt=prompt, response=llm_output)