Reference

API Keys & v1 API

Automate crawling, dataset generation, and training via the REST API. Create scoped API keys for programmatic access.

Creating API Keys

Go to Dashboard → API Keys and click Create Key. You'll configure:

1.Name — a label to identify the key (e.g. "CI/CD Pipeline" or "Staging").
2.Permissions — scope the key to specific actions: crawl, dataset, train, or * for all.
3.Expiration — optionally set the key to auto-expire after 30, 60, 90, or 365 days.

Important: The secret key is only shown once at creation time. Copy it immediately and store it securely. You cannot retrieve it later.

Each key has two parts: a key ID (knh_kid_...) which is safe to log, and a secret (knh_sec_...) which you use for authentication.

Authentication

Pass your secret key in the X-API-Key header on every request:

curl -X POST https://api.kanha.ai/api/v1/pages/{page_id}/recrawl \
-H "X-API-Key: knh_sec_your_secret_here" \
-H "Content-Type: application/json"

The API key is tied to a team. All resources accessed via the key are scoped to that team — no need to pass a team ID header separately.

You can also use a JWT token with Authorization: Bearer ... and X-Team-Id headers instead of an API key. JWT auth has all permissions implicitly.

v1 Endpoints

POST/api/v1/pages/{page_id}/recrawl

Re-crawl a page to update its indexed content. Requires crawl permission.

// Request body (optional)
{
"render_js": false // set true for JS-rendered pages
}

// Response
{
"success": true,
"data": {
"page_id": "uuid",
"status": "queued",
"auth": { "method": "api_key", "key_id": "knh_kid_..." }
}
}

POST/api/v1/sites/{site_id}/datasets

Generate a QA training dataset from all indexed pages in a site. Requires dataset permission. No request body needed.

// Response
{
"success": true,
"data": {
"dataset_id": "uuid",
"status": "queued",
"auth": { "method": "api_key", "key_id": "knh_kid_..." }
}
}

POST/api/v1/bots/{bot_id}/train

Start a training job for a bot. Requires train permission.

// Request body
{
"dataset_id": "uuid",
"model_sizes": ["small", "medium", "large"],
"training_config": { // optional overrides
"epochs": 3,
"learning_rate": 0.0002
}
}

// Response
{
"success": true,
"data": {
"bot_id": "uuid",
"jobs": [
{ "id": "uuid", "model_size": "small", "status": "queued" },
{ "id": "uuid", "model_size": "medium", "status": "queued" }
],
"auth": { "method": "api_key", "key_id": "knh_kid_..." }
}
}

Permissions Reference

Permission	Grants access to
`crawl`	`POST /api/v1/pages/{page_id}/recrawl`
`dataset`	`POST /api/v1/sites/{site_id}/datasets`
`train`	`POST /api/v1/bots/{bot_id}/train`
`*`	All of the above

A key with crawl permission cannot start training jobs — requests to unpermitted endpoints return 403 Forbidden.

Rate Limits & Quotas

Limit	Value
Requests per minute (per key)	60
Monthly page scrapes	Based on your subscription tier
Monthly trains	Based on your subscription tier

Rate-limited requests return 429 Too Many Requests. Quota-exceeded requests return a 200 with "success": false and an error message describing the limit. Check your current usage in Dashboard → Billing.

Error Handling

All responses follow the same envelope:

{
"success": false,
"data": null,
"error": "Page scrape limit reached (100/100 this month)"
}

HTTP Status	Meaning
`401`	Missing or invalid API key / JWT
`403`	Key lacks required permission, or resource belongs to another team
`404`	Resource not found
`429`	Rate limit exceeded (60 req/min per key)

Example: Automate the full pipeline

With a single API key scoped to *, you can automate the entire crawl → dataset → train pipeline:

API_KEY="knh_sec_your_secret"
BASE="https://api.kanha.ai"

# 1. Re-crawl a page
curl -X POST "$BASE/api/v1/pages/$PAGE_ID/recrawl" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"render_js": false}'

# 2. Generate dataset from site
curl -X POST "$BASE/api/v1/sites/$SITE_ID/datasets" \
-H "X-API-Key: $API_KEY"

# 3. Start training
curl -X POST "$BASE/api/v1/bots/$BOT_ID/train" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"dataset_id": "DATASET_ID", "model_sizes": ["small", "medium"]}'

Tip: All operations are asynchronous. The API returns immediately with a queued status. Use the dashboard or check training status via GET /api/training/status/{bot_id} (authenticated) to monitor progress.

Key Management

•Revoke a key instantly from the dashboard. Revoked keys stop working immediately.
•Last used timestamp is tracked per key so you can identify unused keys.
•Expiring keys automatically stop working after their expiration date — no manual cleanup needed.
•Keys are scoped to your team. Team members with Developer or Admin roles can create and revoke keys.

Ready to automate? Create your first API key and start building.

Go to API Keys