REST API Reference

Base URL:

https://inception-agents-api.inception-agents.workers.dev

All /api/v1/* endpoints require authentication via Bearer token. See Authentication for details.

Health

GET `/_health`

Returns service health status. No authentication required.

curl https://inception-agents-api.inception-agents.workers.dev/_health

Response 200 OK

{
  "status": "ok",
  "service": "api",
  "ts": "2026-02-27T12:00:00.000Z"
}

Knowledge

GET `/api/v1/knowledge/search`

Perform a semantic search across your indexed knowledge base. Returns ranked chunks with similarity scores.

Query Parameters

Parameter	Type	Required	Default	Description
`q`	string	Yes	—	Natural language search query
`limit`	number	No	10	Maximum number of results (1–100)

curl -G "https://inception-agents-api.inception-agents.workers.dev/api/v1/knowledge/search" \
  -H "Authorization: Bearer iak_your_api_key" \
  --data-urlencode "q=how does agent detection work" \
  -d "limit=5"

Response 200 OK

{
  "results": [
    {
      "chunkId": "chunk_8f3a1b2c",
      "content": "Agent detection uses a multi-signal classifier combining User-Agent analysis, behavioral heuristics, and TLS fingerprinting to identify AI crawlers with high confidence.",
      "score": 0.94,
      "chunkType": "paragraph",
      "sourceUrl": "https://example.com/docs/detection"
    },
    {
      "chunkId": "chunk_d4e5f6a7",
      "content": "The detection engine processes requests at the edge in under 5ms, classifying traffic as human, known AI agent, or unknown bot.",
      "score": 0.87,
      "chunkType": "paragraph",
      "sourceUrl": "https://example.com/docs/architecture"
    }
  ],
  "query": "how does agent detection work",
  "totalResults": 2
}

POST `/api/v1/knowledge/synthesize`

Generate an LLM-powered synthesis from your knowledge base. Returns a structured response with a markdown narrative and source citations. This endpoint consumes LLM credits.

Request Body

Field	Type	Required	Description
`query`	string	Yes	The question or topic to synthesize
`intent`	string	Yes	Context hint: `informational`, `comparison`, `how-to`, `troubleshooting`

curl -X POST "https://inception-agents-api.inception-agents.workers.dev/api/v1/knowledge/synthesize" \
  -H "Authorization: Bearer iak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the benefits of AI-optimized content?",
    "intent": "informational"
  }'

Response 200 OK

{
  "synthesis": {
    "narrative": "AI-optimized content improves how AI agents interpret and represent your brand...",
    "format": "markdown",
    "citations": [
      {
        "chunkId": "chunk_8f3a1b2c",
        "sourceUrl": "https://example.com/docs/optimization",
        "excerpt": "Content variants tailored to agent intent..."
      }
    ],
    "confidence": 0.91
  },
  "tokensUsed": 384
}

Ingestion

POST `/api/v1/ingestion/crawl`

Initiate a website crawl to ingest content into the knowledge base. The crawl runs asynchronously; use the returned jobId to poll for status.

Request Body

Field	Type	Required	Default	Description
`sourceUrl`	string	Yes	—	Root URL to begin crawling
`maxPages`	number	No	50	Maximum number of pages to crawl (1–500)

curl -X POST "https://inception-agents-api.inception-agents.workers.dev/api/v1/ingestion/crawl" \
  -H "Authorization: Bearer iak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://example.com",
    "maxPages": 100
  }'

Response 202 Accepted

{
  "jobId": "job_a1b2c3d4e5",
  "status": "queued",
  "sourceUrl": "https://example.com",
  "maxPages": 100,
  "createdAt": "2026-02-27T12:00:00.000Z"
}

POST `/api/v1/ingestion/variants/:chunkId`

Generate content variants for a specific chunk. Variants are alternative phrasings optimized for different AI agent intents.

Path Parameters

Parameter	Type	Description
`chunkId`	string	The chunk to generate variants for

curl -X POST "https://inception-agents-api.inception-agents.workers.dev/api/v1/ingestion/variants/chunk_8f3a1b2c" \
  -H "Authorization: Bearer iak_your_api_key"

Response 200 OK

{
  "chunkId": "chunk_8f3a1b2c",
  "variants": [
    {
      "variantId": "var_001",
      "content": "Agent detection combines User-Agent parsing, behavioral analysis, and TLS fingerprinting.",
      "optimizedFor": "concise"
    },
    {
      "variantId": "var_002",
      "content": "The agent detection system works by analyzing three signals: the User-Agent string, behavioral patterns such as request timing and navigation paths, and TLS fingerprint characteristics unique to automated clients.",
      "optimizedFor": "detailed"
    }
  ],
  "generatedAt": "2026-02-27T12:01:00.000Z"
}

Analytics

POST `/api/v1/analytics/events`

Record an agent visit event. Designed for high-throughput ingestion from edge workers.

Request Body

Field	Type	Required	Description
`agentType`	string	Yes	`crawler`, `assistant`, `search`, `unknown`
`agentIdentity`	string	Yes	Identified agent name (e.g., `GPTBot`)
`agentProvider`	string	Yes	Platform provider (e.g., `openai`)
`requestPath`	string	Yes	Path that was accessed
`responseType`	string	Yes	`full`, `partial`, `blocked`, `redirect`
`intentClassification`	string	No	Detected intent of the request
`processingTimeMs`	number	No	Edge processing latency in milliseconds

curl -X POST "https://inception-agents-api.inception-agents.workers.dev/api/v1/analytics/events" \
  -H "Authorization: Bearer iak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentType": "crawler",
    "agentIdentity": "GPTBot",
    "agentProvider": "openai",
    "requestPath": "/pricing",
    "responseType": "full",
    "intentClassification": "informational",
    "processingTimeMs": 12
  }'

Response 201 Created

{
  "eventId": "evt_f7e8d9c0b1a2",
  "recorded": true,
  "timestamp": "2026-02-27T12:02:00.000Z"
}

GET `/api/v1/analytics/summary`

Retrieve an analytics summary for the specified time period.

Query Parameters

Parameter	Type	Required	Default	Description
`period`	string	No	`7d`	Time period: `7d`, `30d`, or `90d`

curl "https://inception-agents-api.inception-agents.workers.dev/api/v1/analytics/summary?period=30d" \
  -H "Authorization: Bearer iak_your_api_key"

Response 200 OK

{
  "period": "30d",
  "totalVisits": 14523,
  "uniqueAgents": 8,
  "topAgents": [
    { "identity": "GPTBot", "provider": "openai", "visits": 6201 },
    { "identity": "ClaudeBot", "provider": "anthropic", "visits": 4102 },
    { "identity": "Googlebot", "provider": "google", "visits": 2890 }
  ],
  "topPaths": [
    { "path": "/", "visits": 3100 },
    { "path": "/pricing", "visits": 2450 }
  ],
  "responseBreakdown": {
    "full": 12100,
    "partial": 1800,
    "blocked": 423,
    "redirect": 200
  }
}

GET `/api/v1/analytics/agents`

Get a breakdown of agent traffic by platform.

curl "https://inception-agents-api.inception-agents.workers.dev/api/v1/analytics/agents" \
  -H "Authorization: Bearer iak_your_api_key"

Response 200 OK

{
  "agents": [
    {
      "identity": "GPTBot",
      "provider": "openai",
      "type": "crawler",
      "totalVisits": 6201,
      "lastSeen": "2026-02-27T11:45:00.000Z",
      "topPaths": ["/", "/pricing", "/docs"]
    },
    {
      "identity": "ClaudeBot",
      "provider": "anthropic",
      "type": "crawler",
      "totalVisits": 4102,
      "lastSeen": "2026-02-27T11:50:00.000Z",
      "topPaths": ["/", "/about", "/features"]
    }
  ]
}

GET `/api/v1/analytics/referrals`

Get AI referral attribution data showing users arriving from AI platforms.

curl "https://inception-agents-api.inception-agents.workers.dev/api/v1/analytics/referrals" \
  -H "Authorization: Bearer iak_your_api_key"

Response 200 OK

{
  "referrals": [
    {
      "provider": "chatgpt",
      "visits": 1240,
      "topLandingPages": ["/pricing", "/features"],
      "conversionRate": 0.032
    },
    {
      "provider": "perplexity",
      "visits": 890,
      "topLandingPages": ["/blog/ai-seo-guide", "/"],
      "conversionRate": 0.041
    }
  ],
  "totalReferrals": 2130,
  "period": "30d"
}

Content

GET `/api/v1/content/llms-txt/:domain`

Retrieve the generated llms.txt file for a domain.

Path Parameters

Parameter	Type	Description
`domain`	string	Target domain name

curl "https://inception-agents-api.inception-agents.workers.dev/api/v1/content/llms-txt/example.com" \
  -H "Authorization: Bearer iak_your_api_key"

Response 200 OK

{
  "domain": "example.com",
  "content": "# example.com\n\n> A platform for AI agent optimization.\n\n## Docs\n- [Getting Started](/docs/getting-started): Setup guide\n- [API Reference](/docs/api/reference): REST API docs\n\n## Features\n- [Agent Detection](/features/detection): Identify AI crawlers\n- [Content Optimization](/features/optimization): Optimize for AI agents\n",
  "generatedAt": "2026-02-27T10:00:00.000Z",
  "version": 3
}

PUT `/api/v1/content/llms-txt/:domain`

Update the llms.txt content for a domain.

Path Parameters

Parameter	Type	Description
`domain`	string	Target domain name

Request Body

Field	Type	Required	Description
`content`	string	Yes	Full llms.txt content

curl -X PUT "https://inception-agents-api.inception-agents.workers.dev/api/v1/content/llms-txt/example.com" \
  -H "Authorization: Bearer iak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# example.com\n\n> Updated description.\n\n## Docs\n- [API](/docs/api): API reference\n"
  }'

Response 200 OK

{
  "domain": "example.com",
  "version": 4,
  "updatedAt": "2026-02-27T12:05:00.000Z"
}

GET `/api/v1/content/agent-card/:domain`

Retrieve the agent card JSON for a domain. The agent card provides structured metadata that AI agents use to understand your site.

Path Parameters

Parameter	Type	Description
`domain`	string	Target domain name

curl "https://inception-agents-api.inception-agents.workers.dev/api/v1/content/agent-card/example.com" \
  -H "Authorization: Bearer iak_your_api_key"

Response 200 OK

{
  "domain": "example.com",
  "name": "Example Corp",
  "description": "A platform for AI agent optimization and visibility.",
  "category": "technology",
  "endpoints": {
    "llmsTxt": "https://example.com/llms.txt",
    "api": "https://api.example.com"
  },
  "capabilities": ["search", "synthesis", "structured-data"],
  "contactEmail": "support@example.com",
  "generatedAt": "2026-02-27T10:00:00.000Z"
}

GET `/api/v1/content/jsonld/:domain/*path`

Get enhanced JSON-LD structured data for a specific page. Returns schema.org-compliant JSON-LD with AI-optimized extensions.

Path Parameters

Parameter	Type	Description
`domain`	string	Target domain name
`*path`	string	Page path (e.g., `/pricing`)

curl "https://inception-agents-api.inception-agents.workers.dev/api/v1/content/jsonld/example.com/pricing" \
  -H "Authorization: Bearer iak_your_api_key"

Response 200 OK

{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "name": "Pricing — Example Corp",
  "url": "https://example.com/pricing",
  "description": "Plans and pricing for Example Corp.",
  "mainEntity": {
    "@type": "Product",
    "name": "Example Platform",
    "offers": [
      {
        "@type": "Offer",
        "name": "Free",
        "price": "0",
        "priceCurrency": "USD"
      },
      {
        "@type": "Offer",
        "name": "Pro",
        "price": "49",
        "priceCurrency": "USD",
        "billingPeriod": "month"
      }
    ]
  }
}

Detection

POST `/api/v1/detection/classify`

Classify an incoming request to determine whether it originates from an AI agent.

Request Body

Field	Type	Required	Description
`userAgent`	string	Yes	Raw User-Agent header value
`ip`	string	No	Client IP address
`headers`	object	No	Full request headers as key-value pairs
`requestPath`	string	Yes	Path of the incoming request

curl -X POST "https://inception-agents-api.inception-agents.workers.dev/api/v1/detection/classify" \
  -H "Authorization: Bearer iak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userAgent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.0; +https://openai.com/gptbot",
    "ip": "203.0.113.42",
    "headers": {
      "accept": "text/html",
      "accept-encoding": "gzip, br"
    },
    "requestPath": "/pricing"
  }'

Response 200 OK

{
  "isAgent": true,
  "identity": "GPTBot",
  "provider": "openai",
  "confidenceScore": 0.98,
  "intent": "indexing",
  "signals": {
    "userAgentMatch": true,
    "ipReputation": "known_ai_crawler",
    "behavioralScore": 0.95
  }
}

Optimization

GET `/api/v1/optimization/variants/:chunkId`

List all content variants for a given chunk, including performance metrics.

Path Parameters

Parameter	Type	Description
`chunkId`	string	Target chunk identifier

curl "https://inception-agents-api.inception-agents.workers.dev/api/v1/optimization/variants/chunk_8f3a1b2c" \
  -H "Authorization: Bearer iak_your_api_key"

Response 200 OK

{
  "chunkId": "chunk_8f3a1b2c",
  "variants": [
    {
      "variantId": "var_001",
      "content": "Agent detection combines User-Agent parsing, behavioral analysis, and TLS fingerprinting.",
      "optimizedFor": "concise",
      "selectionCount": 142,
      "citationRate": 0.68
    },
    {
      "variantId": "var_002",
      "content": "The agent detection system works by analyzing three signals...",
      "optimizedFor": "detailed",
      "selectionCount": 89,
      "citationRate": 0.74
    }
  ],
  "activeVariant": "var_001"
}

POST `/api/v1/optimization/select`

Record a variant selection event. Used by edge workers to report which variant was served and in what context.

Request Body

Field	Type	Required	Description
`chunkId`	string	Yes	Chunk that was served
`variantId`	string	Yes	Variant that was selected
`agentProvider`	string	Yes	Agent platform (e.g., `openai`)
`intent`	string	No	Detected intent of the request

curl -X POST "https://inception-agents-api.inception-agents.workers.dev/api/v1/optimization/select" \
  -H "Authorization: Bearer iak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chunkId": "chunk_8f3a1b2c",
    "variantId": "var_001",
    "agentProvider": "openai",
    "intent": "informational"
  }'

Response 200 OK

{
  "recorded": true,
  "chunkId": "chunk_8f3a1b2c",
  "variantId": "var_001",
  "timestamp": "2026-02-27T12:10:00.000Z"
}

GET `/api/v1/optimization/performance`

Get optimization performance metrics across all chunks and variants.

curl "https://inception-agents-api.inception-agents.workers.dev/api/v1/optimization/performance" \
  -H "Authorization: Bearer iak_your_api_key"

Response 200 OK

{
  "totalChunks": 245,
  "chunksWithVariants": 180,
  "overallCitationRate": 0.42,
  "topPerformingVariants": [
    {
      "chunkId": "chunk_8f3a1b2c",
      "variantId": "var_001",
      "citationRate": 0.68,
      "selectionCount": 142
    }
  ],
  "improvementOverBaseline": 0.31,
  "period": "30d"
}

Tenants

GET `/api/v1/tenants/me`

Get information about the currently authenticated tenant.

curl "https://inception-agents-api.inception-agents.workers.dev/api/v1/tenants/me" \
  -H "Authorization: Bearer iak_your_api_key"

Response 200 OK

{
  "tenantId": "tenant_a1b2c3d4",
  "name": "Example Corp",
  "domain": "example.com",
  "plan": "pro",
  "createdAt": "2025-11-01T00:00:00.000Z",
  "settings": {
    "autoOptimize": true,
    "crawlFrequency": "weekly",
    "webhookUrl": "https://example.com/webhooks/inception"
  }
}

PUT `/api/v1/tenants/me`

Update settings for the currently authenticated tenant.

Request Body

Field	Type	Required	Description
`name`	string	No	Display name for the tenant
`settings`	object	No	Settings object (partial update)

curl -X PUT "https://inception-agents-api.inception-agents.workers.dev/api/v1/tenants/me" \
  -H "Authorization: Bearer iak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "autoOptimize": false,
      "crawlFrequency": "daily"
    }
  }'

Response 200 OK

{
  "tenantId": "tenant_a1b2c3d4",
  "name": "Example Corp",
  "domain": "example.com",
  "plan": "pro",
  "settings": {
    "autoOptimize": false,
    "crawlFrequency": "daily",
    "webhookUrl": "https://example.com/webhooks/inception"
  },
  "updatedAt": "2026-02-27T12:15:00.000Z"
}

Error Responses

All endpoints return errors in a consistent format:

{
  "error": "not_found",
  "message": "The requested resource was not found.",
  "statusCode": 404
}

Status Code	Error Key	Description
400	`bad_request`	Invalid request body or parameters
401	`unauthorized`	Missing or invalid authentication
403	`forbidden`	Key lacks required scope
404	`not_found`	Resource does not exist
429	`rate_limit_exceeded`	Too many requests. See Rate Limits
500	`internal_error`	Unexpected server error

REST API Reference

REST API Reference

Health

GET /_health

Knowledge

GET /api/v1/knowledge/search

POST /api/v1/knowledge/synthesize

Ingestion

POST /api/v1/ingestion/crawl

POST /api/v1/ingestion/variants/:chunkId

Analytics

POST /api/v1/analytics/events

GET /api/v1/analytics/summary

GET /api/v1/analytics/agents

GET /api/v1/analytics/referrals

Content

GET /api/v1/content/llms-txt/:domain

PUT /api/v1/content/llms-txt/:domain

GET /api/v1/content/agent-card/:domain

GET /api/v1/content/jsonld/:domain/*path

Detection

POST /api/v1/detection/classify

Optimization

GET /api/v1/optimization/variants/:chunkId

POST /api/v1/optimization/select

GET /api/v1/optimization/performance

Tenants

GET /api/v1/tenants/me

PUT /api/v1/tenants/me

Error Responses

GET `/_health`

GET `/api/v1/knowledge/search`

POST `/api/v1/knowledge/synthesize`

POST `/api/v1/ingestion/crawl`

POST `/api/v1/ingestion/variants/:chunkId`

POST `/api/v1/analytics/events`

GET `/api/v1/analytics/summary`

GET `/api/v1/analytics/agents`

GET `/api/v1/analytics/referrals`

GET `/api/v1/content/llms-txt/:domain`

PUT `/api/v1/content/llms-txt/:domain`

GET `/api/v1/content/agent-card/:domain`

GET `/api/v1/content/jsonld/:domain/*path`

POST `/api/v1/detection/classify`

GET `/api/v1/optimization/variants/:chunkId`

POST `/api/v1/optimization/select`

GET `/api/v1/optimization/performance`

GET `/api/v1/tenants/me`

PUT `/api/v1/tenants/me`