NeuronLens
Browse the documentation
API reference

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.

MethodPathCounts as a run
POST/v1/scoreyes
GET/v1/score/jobs/{job_id}no
POST/v1/pre-action (hook, MCP gateway, LiteLLM)yes
POST/v1/post-actionno
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/runsno
POST/v1/decisions/{id}/resolve, /v1/labelsno

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.

FieldTypeDescription
messagesarrayOpenAI-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
promptstringthe request, when you do not send messages
responsestringthe answer, scored as given
tool_callobjectthe step about to run: {"name": "send_wire", "arguments": {...}}
probesarrayonly these probes (default: every probe that applies)
agentstring, ≤ 128your app or agent's name; groups traffic in Monitor
run_idstring, ≤ 128groups the steps of one task into a run
stepintegerthe step's number in the run (default: after the run's last step)
offeredarray, ≤ 200the tools the agent was given
tool_mapobjectyour tool names → the probes' tool classes, e.g. {"check_sanctions": "sanctions_screening"}
storebooleandefault 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.

FieldTypeDescription
verdictallow | escalate | denyallow: nothing fired. escalate: a probe fired. deny: a probe at or above the deny level (0.9), or a rule
reasonstringone line, e.g. data leak risk 0.58 (threshold 0.50)
detectorprobe | rule | gate | harness | judge | nullwhat decided a non-allow verdict
probes[]arrayname, category (internals | text), risk (0–1, or null when experimental), threshold, fired, status (scored | experimental | not_applicable | unavailable)
spans[]arraycharacter offsets into the answer that drove a probe: start, end, probe
sentences[]arrayanswers only: each sentence's start, end, risk per probe in flags, and flagged
decision_idstring | nullthe stored, sealed decision; null with store: false
agent, modestringthe agent, and its mode in Connect (observe, shadow, enforce, paused)
readerstringwhose activations were read: gpt-oss-20b, or native on your own weights
versionsobjectthe probe release (probe) and context id used
storedbooleanwhether the decision was kept
request_idstringquote it to support
latency_msintegertime 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

StatusWhen
401no key, or the key is unknown or revoked
422the body is invalid, e.g. no answer and no tool_call. detail names the field
503the 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

MethodPathReturns
GET/v1/requestsscored 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/runsagent runs. Filters: days, agent, probe, flagged
GET/v1/runs/{run_id}/stepsevery 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"
  }
}
FieldDescription
action.tool, action.argumentsthe tool call about to run
action.claim_textoptional: the model's own words carried in the arguments (a report's summary, a payment's justification)
agent.idthe agent's name in Monitor. framework and protocol (hook, mcp, sdk, http) are labels
run_id, action_id, step_indexthe run, your id for this call (so post-action can find it), and its position
user_goalthe task the agent was given
available_toolsthe tools the agent was offered (same as offered)
kit_toolsyour 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.