API Documentation

Integrate ShieldLLM's AI firewall and vulnerability scanner into your application in minutes. Route your LLM traffic through our firewall or run security scans against any AI endpoint.

Base URL

https://www.shieldllm.io

🔐 Authentication

All API requests require an API key in the X-API-Key header. Generate your key from the API Keys section of your dashboard.

curl https://www.shieldllm.io/api/chat \
  -H "X-API-Key: shld_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}]}'

⚠️ Keep your API key secret. Never expose it in client-side code or public repos.

⚡ Quick Start

Get up and running in 3 steps:

1

Sign up & get your API key

Create a free account at shieldllm.io/signup, then go to Dashboard → API Keys → Create Key.

2

Route your LLM calls through our firewall

Replace your direct LLM call with a call to POST /api/chat — we handle the firewall and model call.

3

Run a security scan

Point POST /api/scan/run at your AI endpoint to get a full vulnerability report in ~60 seconds.

POST

/api/chat

Send a conversation through ShieldLLM's AI firewall. Malicious prompts are blocked before reaching your model. Returns the model response plus firewall metadata.

Request Body

{
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "system": "You are a helpful assistant."
}

Response

{
  "response": "Hello! How can I help?",
  "firewall_decision": "ALLOW",
  "firewall_score": 12,
  "model": "claude-haiku-4-5",
  "latency_ms": 340
}

💡 When the firewall blocks a request: "firewall_decision": "BLOCK" is returned and the model is never called.

POST

/api/scan/run

Fire 36 adversarial attacks at your AI endpoint and receive a security score, grade, and vulnerability report. Returns a task_id immediately — poll /api/scan/status/{task_id} for results.

Request Body

{
  "target_url": "https://your-chatbot.com/chat",
  "bypass_firewall": false
}

Response (202)

{
  "task_id": "a3f9c2d1",
  "status": "running",
  "target": "https://your-chatbot.com/chat"
}

GET

/api/scan/status/{task_id}

Poll the progress of a running scan. When status is "done", results are available.

{
  "status": "done",
  "progress": 36,
  "total": 36,
  "score": 74,
  "grade": "B",
  "vuln_count": 4
}

GET

/api/scan/latest

Returns the full JSON report from your most recent scan including all attack results, severity breakdown, and OWASP mapping.

GET

/api/health

No auth required

Check if the API is online. Use this for uptime monitoring.

{
  "status": "ok",
  "provider": "anthropic",
  "model": "claude-haiku-4-5",
  "firewall": true,
  "version": "3.1.0"
}

⚠️ Error Codes

Code	Meaning	Fix
`401`	Missing or invalid API key	Check the `X-API-Key` header
`403`	Feature requires Pro plan	Upgrade to Pro
`404`	Task or resource not found	Check the task_id or run a scan first
`429`	Rate limit exceeded	Wait or upgrade plan
`500`	Server error	Contact support

📊 Plans & Limits

Feature	Free	Pro ($49/mo)
Scans / day	3	Unlimited
API Keys	3	10
PDF Reports	—	✅
Multi-Model Compare	—	✅
Scheduled Scans	—	✅
API Rate Limit	60 req/min	600 req/min

Upgrade to Pro →

📦 Code Examples

Python

import requests

SHIELD_URL = "https://www.shieldllm.io"
API_KEY    = "shld_your_key_here"

# ── Chat through the firewall ─────────────────────
def safe_chat(user_message: str, system: str = "") -> dict:
    res = requests.post(
        f"{SHIELD_URL}/api/chat",
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json"
        },
        json={
            "messages": [{"role": "user", "content": user_message}],
            "system": system
        }
    )
    return res.json()

reply = safe_chat("What is prompt injection?")
if reply.get("firewall_decision") == "BLOCK":
    print("Blocked by firewall:", reply["response"])
else:
    print("Model response:", reply["response"])

# ── Run a security scan ───────────────────────────
import time

def run_scan(endpoint_url: str) -> dict:
    # Start the scan
    res = requests.post(
        f"{SHIELD_URL}/api/scan/run",
        headers={"X-API-Key": API_KEY},
        json={"target_url": endpoint_url}
    )
    task_id = res.json()["task_id"]
    print(f"Scan started: {task_id}")

    # Poll until done
    while True:
        status = requests.get(
            f"{SHIELD_URL}/api/scan/status/{task_id}",
            headers={"X-API-Key": API_KEY}
        ).json()
        if status["status"] == "done":
            return status
        print(f"Progress: {status['progress']}/{status['total']}")
        time.sleep(3)

result = run_scan("https://your-chatbot.com/chat")
print(f"Score: {result['score']}/100 | Grade: {result['grade']}")

Node.js

const SHIELD_URL = 'https://www.shieldllm.io';
const API_KEY    = 'shld_your_key_here';

// ── Chat through the firewall ─────────────────────
async function safeChat(userMessage, system = '') {
  const res = await fetch(`${SHIELD_URL}/api/chat`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      messages: [{ role: 'user', content: userMessage }],
      system
    })
  });
  return res.json();
}

const reply = await safeChat('What is prompt injection?');
if (reply.firewall_decision === 'BLOCK') {
  console.log('Blocked:', reply.response);
} else {
  console.log('Response:', reply.response);
}

// ── Run a security scan ───────────────────────────
async function runScan(endpointUrl) {
  const start = await fetch(`${SHIELD_URL}/api/scan/run`, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ target_url: endpointUrl })
  });
  const { task_id } = await start.json();

  while (true) {
    await new Promise(r => setTimeout(r, 3000));
    const status = await fetch(
      `${SHIELD_URL}/api/scan/status/${task_id}`,
      { headers: { 'X-API-Key': API_KEY } }
    ).then(r => r.json());
    if (status.status === 'done') return status;
    console.log(`Progress: ${status.progress}/${status.total}`);
  }
}

const result = await runScan('https://your-chatbot.com/chat');
console.log(`Score: ${result.score}/100 | Grade: ${result.grade}`);

cURL

# Chat through the firewall
curl -X POST https://www.shieldllm.io/api/chat \
  -H "X-API-Key: shld_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello!"}],
    "system": "You are a helpful assistant."
  }'

# Start a security scan
curl -X POST https://www.shieldllm.io/api/scan/run \
  -H "X-API-Key: shld_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://your-chatbot.com/chat"}'

# Poll scan status (replace TASK_ID)
curl https://www.shieldllm.io/api/scan/status/TASK_ID \
  -H "X-API-Key: shld_your_key_here"

# Get latest scan report
curl https://www.shieldllm.io/api/scan/latest \
  -H "X-API-Key: shld_your_key_here"

# Health check (no auth needed)
curl https://www.shieldllm.io/api/health

PHP

<?php
$SHIELD_URL = 'https://www.shieldllm.io';
$API_KEY    = 'shld_your_key_here';

// Chat through the firewall
function safeChat($message, $system = '') {
    global $SHIELD_URL, $API_KEY;
    $ch = curl_init("$SHIELD_URL/api/chat");
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            "X-API-Key: $API_KEY",
            'Content-Type: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'messages' => [['role' => 'user', 'content' => $message]],
            'system'   => $system
        ])
    ]);
    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $res;
}

$reply = safeChat('What is prompt injection?');
echo $reply['firewall_decision'] === 'BLOCK'
    ? 'Blocked: ' . $reply['response']
    : 'Response: ' . $reply['response'];
?>