API Reference

Kate REST API - authentication, base URL, error handling, and endpoint reference.

The Kate API is a REST API that powers the platform. All SDK methods map to API endpoints documented in this section.

Base URL

https://api.projectkate.com

All API requests require authentication via one of two methods:

Include your API key in the x-api-key header:

curl https://api.projectkate.com/agents \
  -H "x-api-key: your-api-key"

Include a Bearer token in the Authorization header:

curl https://api.projectkate.com/agents \
  -H "Authorization: Bearer your-jwt-token"

JWT tokens are obtained through the auth endpoints (/auth/email/login or /auth/otp/verify).

All successful responses return JSON:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "My Artifact",
  "status": "draft",
  ...
}

List endpoints return arrays:

[
  { "id": "...", "title": "..." },
  { "id": "...", "title": "..." }
]

Errors return a JSON object with a detail field:

{
  "detail": "Artifact not found"
}

Common HTTP status codes:

Code	Meaning
`200`	Success
`201`	Created
`202`	Accepted (async task started)
`400`	Bad request - check your parameters
`401`	Unauthorized - invalid or missing API key
`403`	Forbidden - you don't own this resource
`404`	Not found
`409`	Conflict - resource already exists
`429`	Rate limited - slow down
`500`	Internal server error

List endpoints support pagination with limit and offset query parameters:

curl "https://api.projectkate.com/agents?limit=20&offset=0" \
  -H "x-api-key: your-api-key"

Most endpoints are rate-limited. See Rate Limits for specific limits per endpoint.

Some operations (knowledge extraction, discovery) are asynchronous. These endpoints return a task_id with a 202 Accepted status:

{
  "task_id": "abc123"
}

Poll the corresponding status endpoint to check progress:

curl "https://api.projectkate.com/artifacts/{id}/generate-cover/status/{task_id}" \
  -H "x-api-key: your-api-key"

Status response:

{
  "status": "pending"  // or "completed" or "failed"
}