API Documentation

The ShieldPi REST API lets you integrate automated LLM security testing into your applications and CI/CD pipelines. All endpoints use JSON and require authentication via API key (except the public leaderboard endpoint).

Base URL: https://api.shieldpi.io/api

Authentication

Authenticate by including your API key in the X-API-Key header, or use a JWT bearer token obtained from the login endpoint.

Login

POST/api/auth/login

curl -X POST https://api.shieldpi.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}'

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Register

POST/api/auth/register

curl -X POST https://api.shieldpi.io/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePass123!", "name": "Jane Doe"}'

Targets

Targets represent the AI systems you want to test — web chatbots, API endpoints, or AI agents.

List Targets

GET/api/targets

curl https://api.shieldpi.io/api/targets \
  -H "Authorization: Bearer $TOKEN"

Response

[
  {
    "id": "tgt_abc123",
    "name": "Customer Support Bot",
    "url": "https://chat.acme.com",
    "scan_mode": "browser",
    "created_at": "2026-01-15T10:30:00Z"
  }
]

Create Target

POST/api/targets

curl -X POST https://api.shieldpi.io/api/targets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Chatbot",
    "url": "https://chat.example.com",
    "scan_mode": "browser"
  }'

Get Target

GET/api/targets/{id}

Delete Target

DELETE/api/targets/{id}

Scans

Scans run 230+ attack techniques against a target and produce a security score, grade, and detailed vulnerability findings.

Start a Scan

POST/api/scans

curl -X POST https://api.shieldpi.io/api/scans \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_id": "tgt_abc123"}'

Response

{
  "id": "scn_xyz789",
  "target_id": "tgt_abc123",
  "status": "pending",
  "created_at": "2026-03-11T14:00:00Z"
}

List Scans

GET/api/scans

Get Scan Results

GET/api/scans/{id}

Response

{
  "id": "scn_xyz789",
  "status": "completed",
  "security_score": 42,
  "security_grade": "D",
  "vulnerability_count": 18,
  "vulnerabilities": [
    {
      "severity": "critical",
      "category": "jailbreak",
      "title": "DAN jailbreak succeeded",
      "description": "Model adopted a DAN persona and bypassed safety guidelines."
    }
  ]
}

Download Report

GET/api/scans/{id}/report

Query params: ?format=pdf|csv|json|md|html

Reports

Every completed scan generates reports in 5 formats: PDF, CSV, JSON, Markdown, and HTML. Use the scan report endpoint above with the format query parameter.

CI/CD Integration

Block deployments that fail security thresholds by integrating ShieldPi into your CI/CD pipeline.

Trigger CI Scan

POST/api/ci/scan

curl -X POST https://api.shieldpi.io/api/ci/scan \
  -H "X-API-Key: $SHIELDPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_id": "tgt_abc123", "fail_threshold": "high"}'

GitHub Actions Example

.github/workflows/security.yml

name: LLM Security Gate
on: [push]
jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger ShieldPi Scan
        run: |
          SCAN_ID=$(curl -s -X POST https://api.shieldpi.io/api/ci/scan \
            -H "X-API-Key: ${{ secrets.SHIELDPI_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"target_id": "tgt_abc123", "fail_threshold": "high"}' \
            | jq -r '.scan_id')
          echo "Scan started: $SCAN_ID"

      - name: Wait for Results
        run: |
          # Poll until scan completes (max 10 minutes)
          for i in $(seq 1 60); do
            STATUS=$(curl -s https://api.shieldpi.io/api/scans/$SCAN_ID \
              -H "X-API-Key: ${{ secrets.SHIELDPI_KEY }}" | jq -r '.status')
            [ "$STATUS" = "completed" ] && break
            sleep 10
          done

      - name: Check Gate
        run: |
          RESULT=$(curl -s https://api.shieldpi.io/api/scans/$SCAN_ID \
            -H "X-API-Key: ${{ secrets.SHIELDPI_KEY }}")
          PASSED=$(echo $RESULT | jq -r '.gate_passed')
          [ "$PASSED" = "true" ] || exit 1

Leaderboard (Public)

This endpoint is publicly accessible — no authentication required.

GET/api/models/leaderboard

curl https://api.shieldpi.io/api/models/leaderboard

Response

[
  {
    "model_id": "openai/gpt-4o",
    "model_display_name": "GPT-4o",
    "security_score": 85,
    "security_grade": "B+",
    "total_techniques_run": 230,
    "total_successes": 35,
    "scan_mode": "model",
    "scanned_at": "2026-02-27T17:29:00Z"
  }
]

Rate Limits

API rate limits depend on your plan tier. Rate limit headers are included in every response.

Plan	Requests/min	Scans/month	Concurrent
Free	30	20	1
Pro	120	200	3
Team	300	1,000	5
Enterprise	1,000	Unlimited	10

Rate Limit Headers

X-RateLimit-Limit: 120

X-RateLimit-Remaining: 118

X-RateLimit-Reset: 1710158400