Public API Reference

Overview

The Checkpoint Public API provides programmatic access to detection services, project data, and analytics. Endpoints are RESTful and use JSON. Most endpoints require API key authentication; the public client-ingestion endpoints (/event, /pixel, /pixel/track) authenticate by project/pixel ID in the request body instead — see 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...'},
)

Which endpoints need a key?

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

Public endpoint — authenticated by the pixelId in the body (no API key required).

Request Body:

{
  "pixelId": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
  "sessionId": "session_abc",
  "url": "https://example.com/page",
  "userAgent": "Mozilla/5.0...",
  "referrer": "https://google.com",
  "metadata": { "custom": "data" }
}

Required fields: pixelId (UUID), sessionId, url, userAgent. Returns { success, eventId, sessionId, detection }.

Batch Events

Send multiple events in a single request.

Endpoint: POST /api/v1/batch

Requires an API key (write). Each event uses the same shape as Send Event — every event must include its own pixelId. Maximum 100 events per batch.

Request Body:

{
  "events": [
    {
      "pixelId": "b1c2d3e4-...",
      "sessionId": "s1",
      "url": "https://example.com/p1",
      "userAgent": "Mozilla/5.0..."
    },
    {
      "pixelId": "b1c2d3e4-...",
      "sessionId": "s2",
      "url": "https://example.com/p2",
      "userAgent": "Mozilla/5.0..."
    }
  ]
}

Pixel Tracking

Pixel Endpoint

Ingestion endpoint for the Marketing Pixel. Public — authenticated by the project/pixel ID in the body.

Endpoint: POST /api/v1/pixel

Request Body: a JSON pixel-tracking request — pixelId/projectId, sessionId, url, userAgent, plus optional behavioral and fingerprint signals.

Response: a JSON detection result (classification + confidence). This endpoint is POST/JSON — it does not serve a 1×1 tracking GIF.

Log Detection

Persists a detection produced out-of-band (e.g. by the Gateway Worker) to your dashboard. The middleware SDKs call this after an edge detection so it appears in Analytics.

Endpoint: POST /api/v1/log-detection

Requires an API key scoped to a project. Returns 202 Accepted — the write happens asynchronously.

Request Body: the detection detail plus request context (and optional enforcement / engine / SDK / identity metadata).

Project Management

List Projects

Get all projects associated with your API key.

Endpoint: GET /api/v1/projects

Query Parameters:

Response:

{
  "projects": [
    {
      "id": "acme-corp",
      "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": "acme-corp",
  "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": "acme-corp",
  "request": {
    "userAgent": "string",
    "ip": "string",
    "headers": {},
    "path": "/api/data"
  }
}

Response:

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

Bouncer (KYA-OS 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 KYA-OS 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