Skip to main content
The ChainGuard API provides programmatic access to our security intelligence and threat detection capabilities.

​
Base URL

https://api.chainguardai.dev/v1
All API requests must be made over HTTPS. HTTP requests will be rejected.

​
Authentication

All endpoints require authentication via Bearer token: 
Authorization: Bearer cg_live_xxxxxxxxxxxxxxxxxxxxxxxx
See Authentication for details on obtaining API keys.

​
Request Format

​
Headers

  • Authorization (required): Bearer token for authentication.
  • Content-Type (required for POST/PUT): application/json.
  • X-Request-ID (optional): Client-provided request ID for tracing.

​
Example Request

curl --request POST \
  --url https://api.chainguardai.dev/v1/scan/url \
  --header 'Authorization: Bearer cg_live_xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://suspicious-site.com",
    "options": {
      "includeContent": true
    }
  }'

​
Response Format

All responses are JSON with the following structure: 
interface APIResponse<T> {
  success: boolean;
  data: T;
  meta: {
    requestId: string;
    timestamp: string;
    processingTime: number;  // milliseconds
  };
}

​
Successful Response

{
  "success": true,
  "data": {
    "riskScore": 85,
    "threats": ["phishing", "new_domain"]
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2024-01-15T14:32:00.847Z",
    "processingTime": 47
  }
}

​
Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {}
  },
  "meta": {
    "requestId": "req_xyz789ghi012",
    "timestamp": "2024-01-15T14:32:00.847Z"
  }
}

​
Rate Limits

  • Free: 60 requests/min. 1,000 requests/day. Burst 10.
  • Pro: 300 requests/min. 50,000 requests/day. Burst 50.
  • Enterprise: 1,000 requests/min. Unlimited requests/day. Burst 200.
Rate limit headers are included in every response: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705329720
Exceeding rate limits returns 429 Too Many Requests. Implement exponential backoff.

​
Versioning

The API is versioned via URL path (/v1/, /v2/). Breaking changes require a new version.
  • v1: Active. End of life not scheduled.

​
SDKs

Official SDKs are available:

JavaScript

NPM: @chainguard/sdk

Python

PyPI: chainguard

CLI

NPM: chainguard-cli

​
Endpoints Overview

​
Scanning

  • POST /v1/scan/url: Scan a URL for phishing.
  • POST /v1/scan/contract: Analyze a smart contract.
  • GET /v1/scan/wallet/{address}: Assess wallet risk.
  • POST /v1/scan/transaction: Analyze a transaction.

​
Risk Analysis

  • GET /v1/risk/score/{entity}: Get a risk score.
  • GET /v1/risk/report/{entity}: Get a full risk report.

​
Webhooks

  • POST /v1/webhooks: Create a webhook.
  • GET /v1/webhooks: List webhooks.
  • DELETE /v1/webhooks/{id}: Delete a webhook.

​
Support