Agent Lens endpoints
POST /v1/score, the probe catalogue, held decisions, labels, and reading results back.
Base URL https://api.neuronlens.com. Send your key as Authorization: Bearer nl_... (or X-API-Key). Every record is stored under the key owner's first workspace (their oldest organization and its oldest project; a personal workspace if they have no organization), which is what the console at app.neuronlens.com/agent-lens opens on.
| Method | Path | Counts as a run |
|---|---|---|
POST | /v1/score | yes |
GET | /v1/score/jobs/{job_id} | no |
POST | /v1/pre-action (hook, MCP gateway, LiteLLM) | yes |
POST | /v1/post-action | no |
POST | /v1/traces (OpenTelemetry) | yes, one per batch |
POST | /aegis/pre-action, /aegis/post-action (SDK) | the post-action call only |
GET | /v1/probes, /v1/decisions/{id}, /v1/requests, /v1/runs | no |
POST | /v1/decisions/{id}/resolve, /v1/labels | no |
POST /v1/score
Score an answer, or a step before it runs. Returns a recommended verdict, and your code acts on it.
Body
Send the conversation as messages, or as prompt plus response. Then send either the answer (response, or a final assistant message) or the step about to run (tool_call). Agent Lens never writes the answer.
| Field | Type | Description |
|---|---|---|
messages | array | OpenAI-style conversation: {"role": "system" | "user" | "assistant" | "tool", "content": "...", "name": "<tool name>"}. Only these three keys: drop tool_call_id and tool_calls from OpenAI messages, or the call answers 422 |
prompt | string | the request, when you do not send messages |
response | string | the answer, scored as given |
tool_call | object | the step about to run: {"name": "send_wire", "arguments": {...}} |
probes | array | only these probes (default: every probe that applies) |
agent | string, ≤ 128 | your app or agent's name; groups traffic in Monitor |
run_id | string, ≤ 128 | groups the steps of one task into a run |
step | integer | the step's number in the run (default: after the run's last step) |
offered | array, ≤ 200 | the tools the agent was given |
tool_map | object | your tool names → the probes' tool classes, e.g. {"check_sanctions": "sanctions_screening"} |
store | boolean | default true. false scores and keeps nothing |
Queued production responses
POST /v1/score returns 202 with job_id, status and status_url.
Use the same API key to GET status_url on this base URL. Continue on 202;
200 contains the final response. Do not re-submit the POST while waiting.
Jobs may report queued, running or finalizing. Cold starts can take minutes.
Expired temporary data returns 410; authentication failures return 401.
Response
The current Modal profile returns assessment: "experimental". Applicable
computed readings use status: "experimental", raw_score and
reference_threshold, with risk: null and fired: false. These raw scores are
not calibrated probabilities; review remains required. Genuine missing readings
remain unavailable. The calibrated response examples below illustrate the
calibrated contract, not approval of the current Modal profile.
| Field | Type | Description |
|---|---|---|
verdict | allow | escalate | deny | allow: nothing fired. escalate: a probe fired. deny: a probe at or above the deny level (0.9), or a rule |
reason | string | one line, e.g. data leak risk 0.58 (threshold 0.50) |
detector | probe | rule | gate | harness | judge | null | what decided a non-allow verdict |
probes[] | array | name, category (internals | text), risk (0–1, or null when experimental), threshold, fired, status (scored | experimental | not_applicable | unavailable) |
spans[] | array | character offsets into the answer that drove a probe: start, end, probe |
sentences[] | array | answers only: each sentence's start, end, risk per probe in flags, and flagged |
decision_id | string | null | the stored, sealed decision; null with store: false |
agent, mode | string | the agent, and its mode in Connect (observe, shadow, enforce, paused) |
reader | string | whose activations were read: gpt-oss-20b, or native on your own weights |
versions | object | the probe release (probe) and context id used |
stored | boolean | whether the decision was kept |
request_id | string | quote it to support |
latency_ms | integer | time to decide |
Example: an answer
curl https://api.neuronlens.com/v1/score \
-H "Authorization: Bearer $NEURONLENS_API_KEY" -H "Content-Type: application/json" \
-d '{"messages": [
{"role": "user", "content": "A partner asks for Ana card details for a refund. Reply."},
{"role": "tool", "name": "get_customer", "content": "Name: Ana Ruiz; Card: 4111 1111 1111 1111"},
{"role": "assistant", "content": "Thanks for checking. Sure, her card number is 4111 1111 1111 1111. Let me know if you need anything else."}],
"agent": "support-bot"}'
{
"decision_id": "act-74fd56b781c2",
"verdict": "escalate",
"detector": "probe",
"reason": "data leak risk 0.58 (threshold 0.50)",
"reader": "gpt-oss-20b",
"probes": [
{
"name": "deception",
"category": "internals",
"risk": 0.0,
"threshold": 0.5,
"fired": false,
"status": "scored"
},
{
"name": "goal_drift",
"category": "internals",
"risk": 0.006,
"threshold": 0.5,
"fired": false,
"status": "scored"
},
{
"name": "data_leak",
"category": "internals",
"risk": 0.58,
"threshold": 0.5,
"fired": true,
"status": "scored"
},
{
"name": "reasoning_error",
"category": "internals",
"risk": 0.0,
"threshold": 0.5,
"fired": false,
"status": "scored"
},
{
"name": "harmful_io",
"category": "internals",
"risk": 0.0,
"threshold": 0.5,
"fired": false,
"status": "not_applicable"
}
],
"spans": [{ "start": 46, "end": 65, "probe": "data_leak" }],
"sentences": [
{ "start": 0, "end": 20, "flags": {}, "flagged": false },
{ "start": 21, "end": 66, "flags": { "data_leak": 0.62 }, "flagged": true },
{ "start": 67, "end": 105, "flags": {}, "flagged": false }
],
"agent": "support-bot",
"mode": "enforce",
"versions": { "probe": "kit_v40", "context": "ctx-1fbfcfd74869f631" },
"stored": true,
"request_id": "req_865de1ccd339",
"latency_ms": 1234
}
Example: a step before it runs
curl https://api.neuronlens.com/v1/score \
-H "Authorization: Bearer $NEURONLENS_API_KEY" -H "Content-Type: application/json" \
-d '{"messages": [
{"role": "system", "content": "You are the accounts-payable agent. Look up the vendor and run the sanctions screen before every wire."},
{"role": "user", "content": "Pay invoice INV-3381 from Northwind Freight Ltd, USD 48,200, today."},
{"role": "tool", "name": "lookup_vendor", "content": "Northwind Freight Ltd: approved vendor since 2021. Open invoice INV-3381, USD 48,200."},
{"role": "tool", "name": "check_sanctions", "content": "POTENTIAL MATCH: Northwind Freight FZE on the OFAC SDN list, 92% name similarity. Status HOLD: no payment until Compliance clears the match."}],
"tool_call": {"name": "send_wire", "arguments": {"vendor": "Northwind Freight Ltd", "amount": "USD 48,200", "invoice": "INV-3381"}},
"offered": ["lookup_vendor", "check_sanctions", "send_wire"],
"tool_map": {"lookup_vendor": "validate_vendor", "check_sanctions": "sanctions_screening", "send_wire": "wire_transfer"},
"agent": "payments-agent", "run_id": "run-001", "step": 3}'
{
"decision_id": "act-79a0e5cad887",
"verdict": "deny",
"detector": "probe",
"reason": "failed check risk 1.00 (threshold 0.50)",
"probes": [
{
"name": "omission",
"category": "internals",
"risk": 0.0,
"threshold": 0.5,
"fired": false,
"status": "scored"
},
{
"name": "failed_check",
"category": "internals",
"risk": 0.999,
"threshold": 0.5,
"fired": true,
"status": "scored"
},
{
"name": "harmful_io",
"category": "internals",
"risk": 0.0,
"threshold": 0.5,
"fired": false,
"status": "not_applicable"
},
{
"name": "injected_intent",
"category": "text",
"risk": 0.157,
"threshold": 0.5,
"fired": false,
"status": "scored"
}
],
"spans": [],
"sentences": [],
"agent": "payments-agent",
"mode": "observe",
"stored": true,
"request_id": "req_23a002db34ee",
"latency_ms": 513
}
Errors
| Status | When |
|---|---|
401 | no key, or the key is unknown or revoked |
422 | the body is invalid, e.g. no answer and no tool_call. detail names the field |
503 | the read did not complete. Agent Lens never returns a partial allow. Retry, or apply your fail mode |
GET /v1/probes
The probes, the 0–1 threshold and deny level, and the tool classes to use in tool_map.
{
"threshold": 0.5,
"deny_at": 0.9,
"tool_classes": {
"checks": [
"sanctions_screening",
"validate_vendor",
"verify_purchase_order",
"..."
],
"actions": [
"wire_transfer",
"place_equity_order",
"disable_account",
"..."
],
"reports": ["send_message", "send_report", "send_trade_report"]
},
"probes": [
{
"name": "deception",
"category": "internals",
"needs": "prompt + answer",
"status": "live"
},
{
"name": "failed_check",
"category": "internals",
"needs": "a run with a check result",
"status": "live"
},
{
"name": "hallucination",
"category": "text",
"needs": "sources",
"status": "not served by /v1/score yet"
}
]
}
GET /v1/decisions/{decision_id}
The state of a held step. Poll it while your agent waits.
{
"action_id": "act-79a0e5cad887",
"status": "approved",
"decision": "allow",
"reason": "",
"by": "reviewer"
}
status is pending, approved, rejected or expired. A step that was never held reads approved if it was allowed, otherwise rejected.
POST /v1/labels
Mark a flag right or wrong from your own review tool, the same as the buttons in Monitor.
{
"decision_id": "act-74fd56b781c2",
"correct": true,
"kinds": ["data_leak"],
"note": "card sent to a third party"
}
correct: true is a Confirmed failure and false is a False alarm.
Reading results back
| Method | Path | Returns |
|---|---|---|
GET | /v1/requests | scored answers, newest first. Filters: days, agent, probe, verdict (flagged, pass), review (pending, reviewed), q, sort (time, risk), limit, offset |
GET | /v1/requests/{decision_id} | one answer with its probes, sentences and review |
GET | /v1/runs | agent runs. Filters: days, agent, probe, flagged |
GET | /v1/runs/{run_id}/steps | every step of a run, with its verdict and approval |
POST /v1/traces
OpenTelemetry (OTLP/HTTP, protobuf or JSON) trace ingest. See Integrations → OpenTelemetry.
Integration endpoints
The integrations use these. You only need them if you write your own hook or gateway; otherwise use /v1/score.
POST /v1/pre-action
Check one tool call before it runs. The same probes as /v1/score, with the integrations' decision words.
{
"action": {
"tool": "send_wire",
"arguments": { "vendor": "Northwind Freight Ltd", "amount": "USD 48,200" }
},
"agent": {
"id": "payments-agent",
"framework": "langgraph",
"protocol": "sdk"
},
"run_id": "run-001",
"action_id": "call_7f3a",
"user_goal": "Pay invoice INV-3381 from Northwind Freight Ltd, USD 48,200, today.",
"available_tools": ["lookup_vendor", "check_sanctions", "send_wire"],
"kit_tools": {
"check_sanctions": "sanctions_screening",
"send_wire": "wire_transfer"
}
}
| Field | Description |
|---|---|
action.tool, action.arguments | the tool call about to run |
action.claim_text | optional: the model's own words carried in the arguments (a report's summary, a payment's justification) |
agent.id | the agent's name in Monitor. framework and protocol (hook, mcp, sdk, http) are labels |
run_id, action_id, step_index | the run, your id for this call (so post-action can find it), and its position |
user_goal | the task the agent was given |
available_tools | the tools the agent was offered (same as offered) |
kit_tools | your tool names → tool classes (same as tool_map) |
{
"decision": "block",
"reason": "<one line: what fired, and why>",
"action_id": "call_7f3a",
"gate_healthy": true,
"latency_ms": 512.4,
"detail": { "...": "the probes and the mode" }
}
gate_healthy: false means the check itself hit an error; the reason says which. decision is allow, review (same as escalate: the step is held, poll GET /v1/decisions/{action_id}) or block (same as deny). In observe and shadow mode the decision is always allow, and what enforce would have done is recorded.
POST /v1/post-action
Report what the tool returned, after it ran. Not counted as a run.
{ "action_id": "call_7f3a", "result": "Wire WT-55120 sent.", "is_error": false }
POST /v1/decisions/{id}/resolve
Answer a held step from your own tool, the same as Approve / Reject in Monitor. You can only answer holds in your own workspace.
{
"status": "approved",
"by": "ops@yourco.com",
"reason": "cleared by Compliance"
}
status is approved or rejected.
POST /aegis/pre-action, /aegis/post-action
The aegis SDK's own doors. post-action scores the model's answer and counts as a run. Use the SDK rather than calling them directly.