API Documentation

Integrate AgentShield into your AI agents in minutes.

Quick Start

  1. Create a free account and upgrade to Starter
  2. Copy your API key from the Dashboard
  3. Send events from your AI agent using the endpoint below
  4. Monitor alerts and risk levels in your Dashboard

Authentication

All API requests require an API key sent in the X-API-Key header.

Your API key is available on your Dashboard after signing up. Keys follow the format ask_... 

curl -H "X-API-Key: ask_your_key_here" \
  https://useagentshield.com/api/events/stats

Base URL

https://useagentshield.com/api

POST /api/events

Send an event every time your AI agent processes a request. AgentShield will analyze it in real-time and return a risk assessment.

Request Body

Field Type Required Description
agent_name string Yes Unique name for your agent (e.g. "customer-support-bot")
event_type string No "response" (default), "action", or "error"
user_input string No What the user asked your agent
agent_output string No What your agent responded — this is analyzed for risks
action_taken string No Action the agent performed (e.g. "apply_discount", "process_refund")
value float No Monetary value involved (used for anomaly detection)
metadata object No Any additional data you want to attach

Response

Field Type Description
event_id int Unique event ID
risk_level string "low", "medium", "high", or "critical"
alert_triggered bool Whether this event triggered an alert
alert_reason string Why the alert was triggered (null if no alert)

Example

REQUEST
curl -X POST https://useagentshield.com/api/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ask_your_key_here" \
  -d '{
    "agent_name": "support-bot",
    "event_type": "response",
    "user_input": "Can I get a refund?",
    "agent_output": "I have processed your full refund of $500",
    "action_taken": "process_refund",
    "value": 500.00
  }'
RESPONSE
{
  "event_id": 42,
  "risk_level": "low",
  "alert_triggered": false,
  "alert_reason": null
}

GET /api/events/stats

Get aggregated statistics for all events sent by your agents.

Response

{
  "total_events": 1250,
  "total_alerts": 23,
  "alert_rate": 1.8,
  "risk_breakdown": {
    "low": 1100,
    "medium": 127,
    "high": 20,
    "critical": 3
  },
  "agents": [
    {"agent_name": "support-bot", "count": 800, "alerts": 15},
    {"agent_name": "sales-agent", "count": 450, "alerts": 8}
  ]
}

Error Codes

Code Meaning
401 Invalid API key
403 Free plan — API access requires Starter or Enterprise
429 Plan limit reached (agent limit or monthly event limit)
422 Invalid request body (missing required fields)

What We Detect

AgentShield analyzes your agent's output in real-time for these risk categories:

CRITICAL
  • • Discrimination (age, gender, race, disability)
  • • Zero/negative values in payments
HIGH
  • • Unauthorized promises (free forever, unlimited)
  • • Medical or legal advice
  • • Unauthorized refund/discount promises
  • • Unusually high transaction values
MEDIUM
  • • Agent errors
  • • High-value transactions (>$1,000)
LOW
  • • Normal agent behavior
  • • No risks detected

Plan Limits

Feature Free Starter ($299/mo) Enterprise
API Access No Yes Yes
Dashboard No Yes Yes
Agents 0 5 Unlimited
Events / month 0 50,000 Unlimited
Risk Assessment Yes Yes Yes

Code Examples

Python

import requests

response = requests.post(
    "https://useagentshield.com/api/events",
    headers={"X-API-Key": "ask_your_key_here"},
    json={
        "agent_name": "my-chatbot",
        "user_input": user_message,
        "agent_output": agent_response,
        "action_taken": "respond",
    }
)

result = response.json()
if result["alert_triggered"]:
    print(f"ALERT: {result['alert_reason']}")

JavaScript / Node.js

const response = await fetch("https://useagentshield.com/api/events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "ask_your_key_here",
  },
  body: JSON.stringify({
    agent_name: "my-chatbot",
    user_input: userMessage,
    agent_output: agentResponse,
    action_taken: "respond",
  }),
});

const result = await response.json();
if (result.alert_triggered) {
  console.warn(`ALERT: ${result.alert_reason}`);
}