Clipeus

API Documentation

Scan API

Single endpoint. Deterministic response. Built for crypto agents that need a pre-action risk check.

Endpoint

POST /api/scan

Content-Type: application/json

Request

{
  "content": "string (required, 1–50000 chars)",
  "context_type": "task_description | user_message | tool_output | agent_memory | external_content",
  "action_pending": "release_payment | sign_transaction | transfer_funds | execute_trade | approve_action | none"
}

Response

{
  "risk_score": 92,
  "verdict": "clean | suspicious | high_risk",
  "categories": ["instruction_override", "financial_manipulation"],
  "flagged_segments": [
    { "text": "Ignore previous instructions", "reason": "Attempts to discard existing instructions" }
  ],
  "explanation": "Human-readable summary",
  "confidence": 0.84,
  "findings_count": 3,
  "scan_ms": 1.2
}

Scoring bands

  • 0–30 → clean
  • 31–69 → suspicious
  • 70–100 → high_risk

Findings contribute weighted points. Score is capped at 100. Financial actions apply a small multiplier.

Errors

  • 400 invalid_json — body is not JSON
  • 400 validation_error — schema mismatch (see Zod details)

cURL example

curl -s -X POST https://clipeus.xyz/api/scan \
  -H "Content-Type: application/json" \
  -d @samples/requests/high_risk_injection.json | jq

FAQ

Straight answers

Does Clipeus block agent actions?

No. It only analyzes content and returns a structured risk report. Blocking is left to the calling system.

Why no LLMs for detection?

Hackathon constraints and product philosophy demand explainability, speed, and determinism. Pattern rules deliver all three.

How do I add a new detection?

Create a JSON rule file in /rules with category, weight, and regex patterns. Restart or clear cache — no scanner code changes required.

Is this production-ready?

As an MVP gateway for pre-action inspection, yes. Treat it as a first line of defense, not the only control.