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:

Class	Description
`human`	Regular browser traffic
`ai_agent`	AI assistants (ChatGPT, Claude, Perplexity, Gemini)
`bot`	Traditional bots (Googlebot, Bingbot, scrapers)
`incomplete_data`	Insufficient signals for classification

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:

Parameter	Description
`projectId`	Your Project ID
`u`	URL being tracked
`r`	Referrer URL
`t`	Timestamp

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:

Parameter	Default	Description
`page`	`1`	Page number
`limit`	`20`	Results per page
`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,
    "enforcementEnabled": false
  },
  "stats": {
    "totalSessions": 5678,
    "aiAgentSessions": 123,
    "botSessions": 456,
    "humanSessions": 5099
  }
}

Get Project Detections

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

Query Parameters:

Parameter	Description
`page`	Page number
`limit`	Results per page
`startDate`	Filter start (ISO 8601)
`endDate`	Filter end (ISO 8601)
`detectionClass`	Filter by class (`ai_agent`, `bot`, `human`)

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:

Parameter	Description
`period`	Time period (`hour`, `day`, `week`, `month`)
`startDate`	Start date (ISO 8601)
`endDate`	End date (ISO 8601)

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"
}

Rate Limits

API rate limits vary by plan:

Plan	Requests per Second	Requests per Day
Free	10	10,000
Pro	100	100,000
Enterprise	1,000	Unlimited

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

Status	Code	Description
400	`INVALID_REQUEST`	Request validation failed
401	`UNAUTHORIZED`	Invalid or missing API key
403	`FORBIDDEN`	Access denied to resource
404	`NOT_FOUND`	Resource not found
429	`RATE_LIMIT_EXCEEDED`	Too many requests
500	`INTERNAL_ERROR`	Server error

SDKs & Packages

Official packages for integration:

Package	Install
Next.js Middleware	`npm install @kya-os/agentshield-nextjs`
Express Middleware	`npm install @kya-os/agentshield-express`
JavaScript Beacon	`npm install @kya-os/agentshield-beacon`
Govern Middleware	`npm install @kya-os/bouncer-middleware`

See Choose Your Integration for detailed comparison.

Best Practices

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

Support

Email: hello@knowthat.ai
Issues: GitHub Issues

Public API Reference

Overview

Base URL

Authentication

Core Detection APIs

Detect AI Agent

Event Tracking

Send Event

Batch Events

Pixel Tracking

Pixel Endpoint

Project Management

List Projects

Get Project Details

Get Project Detections

Get Project Analytics

Deploy Project

Enforce API

Evaluate Request

Rate Limits

Error Handling

Common Error Codes

SDKs & Packages

Best Practices

Support

On this page