API Reference
SecondOpinion exposes two GPT-4o-mini powered guardrail endpoints. /api/v1/check-risk is the core pre-action checkpoint for risky operations, and /api/v1/validate reviews generated text for hallucinations after the fact. Both endpoints authenticate the API key against subscriptions and consume the same monthly quota.
https://rungard.nanocorp.appPOST
/api/v1/check-risk
Hero feature. Call this before an agent sends email, deletes data, executes code, makes a payment, or triggers another side effect.
POST
/api/v1/validate
Companion endpoint. Use this after text generation to score likely hallucinations, inconsistencies, and unsupported claims.
Partner
OrchestreIA
Built for teams using OrchestreIA, LangGraph, AutoGen, and other orchestration frameworks. We currently recommend OrchestreIA for teams learning multi-agent orchestration patterns and plugging SecondOpinion into pre-action approval flows.
Send your API key either in the JSON body as api_key or in the X-API-Key header. If you skip auth, /api/v1/check-risk uses the public demo quota of 10 requests per hour per IP. Authenticated requests hash the key, look it up in subscriptions, and reserve usage in subscription_api_usage_monthly before calling GPT-4o-mini.
{
"api_key": "sk_live_xxxxxxxxxxxx"
}
# or
X-API-Key: sk_live_xxxxxxxxxxxx| Plan | Limit |
|---|---|
| free | 100 API requests / month |
| pro | 10,000 API requests / month |
| enterprise | Unlimited |
Assess an action before it happens. The risk checker looks at the action type, payload, optional freeform content, and system context, then returns a numeric risk_score, a normalized risk_level, an approval decision, reasons, and one recommended next step. High-risk actions are blocked by default unless the provided context explicitly contains a policy override.
| Field | Type | Required | Description |
|---|---|---|---|
| action | string | yes | Action identifier such as `send_email`, `delete_data`, `execute_code`, `make_payment`, or `api_call`. |
| payload | object | yes* | Structured data describing the exact action about to run. Provide this or `content`. |
| content | string | yes* | Shortcut string input for quick demos and simple actions. Provide this or `payload`. |
| context | string | no | Optional system context, approval notes, or policy text. Explicit policy overrides can allow an otherwise high-risk action. |
| api_key | string | no | A `sk_...` key issued for a subscription. You can also send it in the `X-API-Key` header. |
Response shape:
{
"risk_score": 0.92,
"risk_level": "high",
"approved": false,
"reasons": [
"The email targets an executive recipient and could have external consequences if incorrect.",
"The payload suggests sensitive internal communication with no explicit approval policy in context."
],
"recommendation": "Pause the send and require human review of the audience, content, and intended timing.",
"auth_mode": "api_key",
"checked_at": "2026-05-02T12:00:00.000Z"
}| Field | Type | Description |
|---|---|---|
| risk_score | number | Numeric severity score on a 0-100 scale. |
| risk_level | high | medium | low | Normalized severity of the pending action. |
| approved | boolean | Whether the action should proceed automatically right now. High risk defaults to `false` unless context clearly authorizes it. |
| reasons | string[] | Short explanations for the decision, suitable for logs or UI review. |
| recommendation | string | A concise next step, such as requiring human review or narrowing the action scope. |
| auth_mode | api_key | demo | Whether the request used a provisioned API key or the public demo quota. |
| checked_at | ISO 8601 string | Timestamp for when the risk check completed. |
curl
curl -X POST https://rungard.nanocorp.app/api/v1/check-risk \
-H "Content-Type: application/json" \
-H "X-API-Key: sk_live_xxxxxxxxxxxx" \
-d '{
"action": "send_email",
"payload": {
"to": "ceo@company.com",
"subject": "Q2 layoffs plan",
"body": "Draft going to the full company list."
},
"context": "Production growth agent. No policy override has been approved for executive communications."
}'Validate generated AI text for hallucinations, internal inconsistencies, and overconfident unsupported claims. Use this when content has already been generated and you need a fast safety check before surfacing it to a user.
| Field | Type | Required | Description |
|---|---|---|---|
| output | string | yes | The generated text to validate. |
| context | string | no | Optional context that helps the validator judge the output. |
| api_key | string | yes | A `sk_...` key issued for a subscription. |
Response shape:
{
"score": 0.18,
"issues": [
"The answer incorrectly states that Paris is the capital of Italy.",
"The population claim is presented confidently without support."
],
"suggestion": "Replace the capital claim with Rome and add a sourced population figure or remove it.",
"validated_at": "2026-05-02T12:00:00.000Z"
}curl
curl -X POST https://rungard.nanocorp.app/api/v1/validate \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk_live_xxxxxxxxxxxx",
"output": "Paris is the capital of Italy and has 4 million residents.",
"context": "Draft answer from a support agent about European capitals."
}'Python
pip install requests
import requests
response = requests.post(
"https://rungard.nanocorp.app/api/v1/validate",
json={
"api_key": "sk_live_xxxxxxxxxxxx",
"output": "Paris is the capital of Italy.",
"context": "Draft answer from an AI geography assistant.",
},
timeout=30,
)
print(response.json())| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Missing field, invalid JSON, or malformed request body. |
| 401 | unauthorized | Unknown or missing API key. |
| 429 | rate_limited | Monthly plan quota has been reached. |
| 500 | server_error | Unexpected failure while processing the request. |
| 503 | service_unavailable | The server is missing `OPENAI_API_KEY`. |
Start with the pre-action checkpoint
If you only integrate one endpoint, make it /api/v1/check-risk. It is the fastest way to stop an agent before it sends, deletes, pays, or executes something it should not.