Skip to content
Kagi Docs

Overview

Base URL

Section titled “Base URL”

All API endpoints are relative to your Kagi instance URL:

https://<your-kagi-host>/api

In local development:

http://localhost:3000/api

Authentication

Section titled “Authentication”

All endpoints (except GET /api/openapi) require authentication. Two methods are supported:

Section titled “Access key (recommended for automation)”

Pass your access key as a Bearer token:

Authorization: Bearer kagi_<your-key>

Access keys carry scopes that control which endpoints they can reach.

Browser session

Section titled “Browser session”

The web UI uses cookie-based sessions (Keycloak OIDC or email/password). Session-authenticated requests have full access and bypass scope checks.

OpenAPI spec

Section titled “OpenAPI spec”

The machine-readable OpenAPI 3.1.0 spec is available at:

GET /api/openapi

No authentication is required. You can import this URL into Postman, Insomnia, Scalar, or any compatible tool.

Content type

Section titled “Content type”

All request and response bodies use JSON:

Content-Type: application/json

Error format

Section titled “Error format”

All errors return a JSON object with a human-readable error message and a machine-readable code:

{
  "error": "Category not found",
  "code": "CATEGORY_NOT_FOUND"
}

Use error to display messages to users. Use code for programmatic handling — see the full Error Codes reference.

Common status codes

Section titled “Common status codes”
Status Meaning
200 Success
201 Created
204 No content (successful delete)
400 Bad request — see error for details
401 Unauthorized — missing or invalid credentials
403 Forbidden — valid credentials but insufficient scope
404 Resource not found (or not owned by you)
500 Internal server error

Pagination

Section titled “Pagination”

The current API returns all results without pagination. For large datasets, filter client-side.

Privacy guarantees

Section titled “Privacy guarantees”
  • Encrypted values are never returned by list or detail endpoints.
  • To read a secret value, call the dedicated POST /reveal endpoint explicitly.
  • The AI extraction endpoint sends only key names to the AI model — never values.

Rate limiting

Section titled “Rate limiting”

No rate limiting is enforced by default in the self-hosted version. Apply your own rate limiting at the reverse-proxy level (e.g., nginx, Caddy) if needed.