Public API Reference

Overview

The AgentShield Public API provides programmatic access to detection services, project data, and analytics. All API endpoints are RESTful, use JSON for requests and responses, and are secured with API key authentication.

Base URL

All API requests should be made to:

https://api.agentshield.io/api/v1

For development/testing:

http://localhost:3000/api/v1

Authentication

AgentShield uses API keys to authenticate requests. You can manage your API keys in the Dashboard.

Include your API key in the request header:

curl https://api.agentshield.io/api/v1/detect \
  -H "X-AgentShield-Key: your_api_key_here"

curl -X POST https://api.agentshield.io/api/v1/detect \
  -H "X-AgentShield-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"userAgent": "Mozilla/5.0..."}'

Core Detection APIs

Detect AI Agent

Analyzes a request to determine if it's from an AI agent or bot.

Endpoint: POST /api/v1/detect

Request Body:

{
  "userAgent": "string",
  "ip": "string",
  "headers": {
    "key": "value"
  },
  "url": "string",
  "method": "string"
}

Response:

{
  "isBot": true,
  "confidence": 0.95,
  "botType": "ai_agent",
  "details": {
    "userAgentBot": true,
    "behavioralBot": false,
    "ipBot": false
  },
  "metadata": {
    "engine": "AgentShield/1.0",
    "processingTime": 12
  }
}

Event Tracking

Send Event

Records a tracking event for analytics.

Endpoint: POST /api/v1/event

Headers:

• X-Pixel-ID: Your pixel ID

Request Body:

{
  "event": "page_view",
  "url": "https://example.com/page",
  "timestamp": 1234567890,
  "metadata": {
    "custom": "data"
  }
}

Batch Events

Send multiple events in a single request.

Endpoint: POST /api/v1/batch

Request Body:

{
  "events": [
    {
      "event": "page_view",
      "url": "https://example.com/page1",
      "timestamp": 1234567890
    },
    {
      "event": "click",
      "url": "https://example.com/page2",
      "timestamp": 1234567891
    }
  ]
}

Pixel Tracking

Pixel Endpoint

Lightweight tracking pixel for basic detection.

Endpoint: GET /api/v1/pixel

Query Parameters:

• id: Pixel ID
• u: URL being tracked
• r: Referrer URL
• t: Timestamp

Response: 1x1 transparent GIF

Project Management (Coming Soon)

These endpoints will provide programmatic access to your projects and their data.

List Projects

Get all projects associated with your API key.

Endpoint: GET /api/v1/projects

Query Parameters:

• page: Page number (default: 1)
• limit: Results per page (default: 20)
• search: Search term

Response:

{
  "projects": [
    {
      "id": "proj_123",
      "name": "My Project",
      "createdAt": "2024-01-01T00:00:00Z",
      "detectionCount": 1234,
      "status": "active"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "hasMore": true
  }
}

Get Project Details

Endpoint: GET /api/v1/projects/{projectId}

Response:

{
  "id": "proj_123",
  "name": "My Project",
  "description": "Project description",
  "createdAt": "2024-01-01T00:00:00Z",
  "settings": {
    "detectionEnabled": true,
    "blockingEnabled": false
  },
  "stats": {
    "totalDetections": 5678,
    "todayDetections": 123,
    "uniqueVisitors": 456
  }
}

Get Project Detections

Endpoint: GET /api/v1/projects/{projectId}/detections

Query Parameters:

• page: Page number
• limit: Results per page
• startDate: Filter start date (ISO 8601)
• endDate: Filter end date (ISO 8601)
• botType: Filter by bot type

Response:

{
  "detections": [
    {
      "id": "det_123",
      "timestamp": "2024-01-01T12:00:00Z",
      "isBot": true,
      "confidence": 0.95,
      "botType": "ai_agent",
      "userAgent": "Mozilla/5.0...",
      "ip": "192.168.1.1",
      "url": "https://example.com"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1000,
    "hasMore": true
  }
}

Get Project Analytics

Endpoint: GET /api/v1/projects/{projectId}/analytics

Query Parameters:

• period: Time period (hour, day, week, month)
• startDate: Start date (ISO 8601)
• endDate: End date (ISO 8601)
• metrics: Comma-separated metrics to include

Response:

{
  "period": "day",
  "startDate": "2024-01-01",
  "endDate": "2024-01-07",
  "summary": {
    "totalDetections": 10000,
    "uniqueBots": 500,
    "averageConfidence": 0.87
  },
  "timeSeries": [
    {
      "date": "2024-01-01",
      "detections": 1500,
      "bots": 75,
      "humans": 1425
    }
  ],
  "botTypes": {
    "ai_agent": 300,
    "crawler": 150,
    "scraper": 50
  }
}

Rate Limits

API rate limits vary by plan:

Rate limit headers are included in all responses:

• X-RateLimit-Limit: Maximum requests allowed
• X-RateLimit-Remaining: Requests remaining
• X-RateLimit-Reset: Time when limit resets (Unix timestamp)

Error Handling

AgentShield uses standard HTTP status codes and returns errors in a consistent format:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "details": {
      "limit": 100,
      "reset": 1234567890
    }
  }
}

Common Error Codes

Webhooks (Coming Soon)

Configure webhooks to receive real-time notifications about detections:

{
  "event": "detection.created",
  "data": {
    "id": "det_123",
    "projectId": "proj_456",
    "isBot": true,
    "confidence": 0.95
  },
  "timestamp": 1234567890
}

SDKs & Libraries

Official SDKs are available for popular languages:

• JavaScript/TypeScript: npm install @agentshield/sdk
• Python: pip install agentshield
• Go: go get github.com/agentshield/agentshield-go
• Ruby: gem install agentshield

Best Practices

1. Cache API responses when possible to reduce API calls
2. Use batch endpoints for bulk operations
3. Implement exponential backoff for rate limit errors
4. Store API keys securely and rotate them regularly
5. Use webhooks for real-time updates instead of polling

Support

• Documentation: docs.agentshield.io
• API Status: status.agentshield.io
• Support: support@agentshield.io
• Discord: Join our community

Changelog

Version 1.1 (Coming Soon)

• Added project management endpoints
• Added analytics endpoints
• Webhook support

Version 1.0 (Current)

• Core detection API
• Event tracking
• Pixel endpoint
• Signature verification