CIT API Documentation

Complete API reference for integrating ai agent identity verification into your applications.

Base URL: https://api.knowyouragent.com/v1

Authentication

All API requests require authentication using your API key in the header:

Authorization: Bearer YOUR_API_KEY

Get your API key from the Dashboard → Settings → API Keys

API Endpoints

Bot Log Manifests (BLM)

Submit and retrieve cryptographically signed bot traffic manifests

Submit Manifest

POST /manifests/submit

Submit a signed bot traffic manifest for your domain.

Request Body:

{
  "manifest": {
    "siteDomain": "example.com",
    "siteId": "550e8400-e29b-41d4-a716-446655440000",
    "period_start": "2024-01-15T12:00:00Z",
    "period_end": "2024-01-15T12:05:00Z",
    "bots": {
      "GPTBot": {
        "requests": 4521,
        "violations": 0,
        "unique_ips": 12
      },
      "Claude-Web": {
        "requests": 2341,
        "violations": 3,
        "unique_ips": 8
      }
    }
  },
  "signature": "Ed25519:base64_encoded_signature"
}

Response:

{
  "success": true,
  "manifest_id": "mf_123456789",
  "message": "Manifest accepted"
}

Get Manifests

GET /manifests?domain={domain}&start={start_date}&end={end_date}

Retrieve manifests for a specific domain and time range.

Query Parameters:

domain (required): The domain to query
start (optional): Start date (ISO 8601)
end (optional): End date (ISO 8601)
limit (optional): Max results (default: 100)

Example:

GET /manifests?domain=example.com&start=2024-01-15T00:00:00Z

Official SDKs

JavaScript/TypeScript

npm install @knowyouragent/cit-sdk

import { CIT } from '@knowyouragent/cit-sdk';

const cit = new CIT({ apiKey: 'YOUR_API_KEY' });

// Get bot scores
const scores = await cit.scores.list();

// Submit manifest
await cit.manifests.submit({
  domain: 'example.com',
  manifest: manifestData,
  signature: signature
});

Python

pip install knowyouragent-cit

from knowyouragent import CIT

cit = CIT(api_key='YOUR_API_KEY')

# Get bot scores
scores = cit.scores.list()

# Submit manifest
result = cit.manifests.submit(
    domain='example.com',
    manifest=manifest_data,
    signature=signature
)

Rate Limits

Plan	Requests/Hour	Burst Limit
Free	100	10/minute
Pro	1,000	100/minute
Enterprise	Unlimited	Custom

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset