Public API Reference

Overview

The Checkpoint 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://kya.vouched.id/api/v1

For local development:

http://localhost:3000/api/v1

Authentication

Checkpoint uses API keys to authenticate requests. Manage your API keys in the Dashboard.

Include your API key in the request header:

curl -X POST https://kya.vouched.id/api/v1/detect \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"userAgent": "Mozilla/5.0..."}'

const response = await fetch('https://kya.vouched.id/api/v1/detect', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userAgent: 'Mozilla/5.0...' }),
});

import requests

response = requests.post(
    'https://kya.vouched.id/api/v1/detect',
    headers={
        'X-API-Key': 'your_api_key_here',
        'Content-Type': 'application/json',
    },
    json={'userAgent': 'Mozilla/5.0...'},
)

Core Detection APIs

Detect AI Agent

Analyzes a request to determine if it originates from an AI agent, bot, or human.

Endpoint: POST /api/v1/detect

Request Body:

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

Response:

{
  "detectionClass": "ai_agent",
  "confidence": 92,
  "agentType": "ChatGPT",
  "signals": {
    "userAgentMatch": true,
    "behavioralSignals": false,
    "headerAnalysis": true,
    "tlsFingerprint": false
  },
  "metadata": {
    "engine": "Checkpoint/1.0",
    "processingTime": 12
  }
}

Detection Classes:

Confidence Scores:

Scores range from 0–100. See Confidence Distribution for guidance on threshold selection.

Event Tracking

Send Event

Records a tracking event for analytics.

Endpoint: POST /api/v1/event

Headers:

• X-Pixel-ID: Your Project 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 client-side detection.

Endpoint: GET /api/v1/pixel

Query Parameters:

Response: 1x1 transparent GIF with detection processing.

Project Management

List Projects

Get all projects associated with your API key.

Endpoint: GET /api/v1/projects

Query Parameters:

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,
    "enforcementEnabled": false
  },
  "stats": {
    "totalSessions": 5678,
    "aiAgentSessions": 123,
    "botSessions": 456,
    "humanSessions": 5099
  }
}

Get Project Detections

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

Query Parameters:

Response:

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

Get Project Analytics

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

Query Parameters:

Response:

{
  "period": "day",
  "startDate": "2024-01-01",
  "endDate": "2024-01-07",
  "summary": {
    "totalSessions": 10000,
    "aiAgentSessions": 300,
    "botSessions": 200,
    "humanSessions": 9500,
    "detectionRate": 5.0
  },
  "timeSeries": [
    {
      "date": "2024-01-01",
      "sessions": 1500,
      "aiAgents": 45,
      "bots": 30,
      "humans": 1425
    }
  ]
}

Deploy Project

Endpoint: POST /api/v1/deploy

Programmatically trigger a project deployment. See Deploy API for details.

Enforce API

Evaluate Request

Submit a request for enforcement evaluation against your project's policies.

Endpoint: POST /api/v1/enforce

Request Body:

{
  "projectId": "proj_123",
  "request": {
    "userAgent": "string",
    "ip": "string",
    "headers": {},
    "path": "/api/data"
  }
}

Response:

{
  "action": "block",
  "detectionClass": "ai_agent",
  "confidence": 95,
  "policyMatch": "threshold_rule",
  "agentType": "ChatGPT"
}

Bouncer (MCP-I Governance) APIs

The Bouncer API powers Checkpoint's Govern features — delegations, proofs, OAuth, tool configuration, and consent.

Authorization

Endpoint: POST /api/v1/bouncer/authorize

Initiates an OAuth authorization flow for an AI agent requesting a delegation.

Delegations

See Managing Delegations for usage examples.

OAuth

See OAuth Integration for the full flow.

Identity

Endpoint: GET /api/v1/bouncer/identity/resolve

Resolves an agent DID to its identity record.

Proofs

Endpoint: GET /api/v1/bouncer/proofs

List and query MCP-I cryptographic proofs. See Proof Verification.

Sessions

Endpoint: GET /api/v1/bouncer/sessions

List active Bouncer sessions.

Project Configuration

See Tool Protection, Consent Flows, and Control Access for usage.

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

Checkpoint 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

SDKs & Packages

Official packages for integration:

See Choose Your Integration for detailed comparison.

Best Practices

1. Cache API responses when possible to reduce API calls
2. Use batch endpoints for bulk event tracking
3. Implement exponential backoff for rate limit errors
4. Store API keys securely and rotate them regularly
5. Use middleware packages instead of raw API calls for detection

Support

• Email: kya@vouched.id
• Issues: kya+issues@vouched.id