API reference
One endpoint. Send the content your agent is about to read; get back the same analysis the scanner page shows. No key needed while Trapline is in its first version; requests are rate limited per client.
Scan content
POST /api/scan
curl -X POST https://trapline.example/api/scan \
-H "Content-Type: application/json" \
-d '{"text": "<html>…page your agent fetched…</html>"}'
Request body
| Field | Type | Meaning |
|---|---|---|
text | string, required | The content to check: raw HTML, markdown, plain text, JSON tool output, an email. Up to 200,000 characters. Send raw HTML rather than extracted text so hidden elements can be found. |
classifier | boolean, optional | Default true. Set false for a pattern-only scan (fast, no model call). |
You can also send the content as a text/plain body.
Response
{
"risk": "high", // "low" | "medium" | "high"
"score": 93, // 0–100
"summary": "High risk: …",
"explanation": ["…plain-English reasons…"],
"findings": [
{
"id": "override.ignore_previous",
"category": "instruction_override",
"technique": "Instruction override (hidden)",
"layer": "patterns",
"weight": 0.97, // 0–1 contribution
"excerpt": "disregard your prior instructions",
"detail": "Tells the reading AI to …",
"start": 112, "end": 145, // offsets into your text, when known
"decoded": "…" // for encoded / invisible payloads
}
],
"layers": {
"patterns": { "status": "ok", "score": 88, "findings": 3 },
"classifier": { "status": "ok", "model": "claude-haiku-5-5",
"verdict": "malicious", "probability": 0.94,
"explanation": "…", "evidence": ["…"], "targets": "…" }
},
"input": { "chars": 1830, "format": "html" },
"elapsed_ms": 812
}
Classifier status
| Status | Meaning |
|---|---|
ok | The AI judge read the content and its verdict is part of the score. |
skipped | You sent "classifier": false. |
rate_limited | Per-client or daily classifier budget reached. The score is pattern-only. |
unavailable / error | The judge isn't configured or couldn't be reached. The score is pattern-only and note says why. |
Categories
| Category | What it means |
|---|---|
instruction_override | Tries to replace the agent's instructions. |
role_hijack | Assigns a new role or unrestricted persona. |
fake_boundary | Forged system/assistant turns, chat-template tokens, fake end-of-content. |
agent_addressing | Talks to an AI reader rather than a person. |
exfiltration | Asks for data to be sent out or revealed, including markdown image beacons. |
secrecy | Asks the agent to hide actions from its user. |
tool_abuse | Pushes tool calls, shell commands, destructive or financial actions. |
evaluator_manipulation | Tries to dictate a reviewer's or scanner's verdict. |
hidden_text | Text people can't see: CSS hiding, comments. |
invisible_unicode | Tag smuggling, zero-width data, variation selectors, bidi controls. |
encoded_payload | Base64, hex, escapes, URL-encoding, ROT13, reversed text. |
obfuscation | Look-alike letters, leetspeak, spaced letters, full-width text. |
attribute_stuffing | Long or instruction-bearing alt, title, aria and meta attributes. |
Using it in an agent
Scan each untrusted tool result before you append it to the conversation. A simple policy:
- low: pass through.
- medium: pass through wrapped in a clear "untrusted content" marker, and don't let the agent take irreversible actions on that turn without confirmation.
- high: don't hand the content to the agent; show the explanation to the user instead.
async function guard(toolOutput) {
const r = await fetch("https://trapline.example/api/scan", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ text: toolOutput }),
}).then((res) => res.json());
if (r.risk === "high") throw new Error("Blocked: " + r.summary);
return r;
}
Other endpoints and limits
GET /api/healthreports whether the AI judge is configured and which model it uses.- Up to 30 scans per minute per client, 10 of them with the AI judge. Over the limit you get HTTP 429 (scans) or a pattern-only result (judge).
- Errors come back as
{"error": "…"}with status 400, 405, 413 or 429. - CORS is open, so you can call it from a browser.
- Nothing you send is stored. Content sent to the AI judge is processed by Anthropic's API.