Kaneo API Documentation: How to Access the OpenAPI 3.0 Spec

Yes, the Kaneo project provides comprehensive API documentation through a dynamically generated OpenAPI 3.0 specification available both as a runtime endpoint and a static file.

The Kaneo open-source project ships with full API documentation built directly into its codebase. Every public endpoint is documented using the OpenAPI standard, making it easy to integrate with the platform or generate type-safe clients. This documentation is automatically generated from route definitions using hono-openapi decorators and exposed through multiple channels for developer convenience.

Where to Find the Kaneo API Documentation

You have two primary ways to access the Kaneo API documentation, depending on whether you need the live spec or a version-controlled copy:

Method	URL	Best For
Live endpoint	GET /api/openapi on your Kaneo instance	Always up-to-date spec matching deployed code
Static file	apps/docs/openapi.json in the repository	Offline access, version history, client generation

The live endpoint is registered in apps/api/src/index.ts at lines 359-392, where the /api/openapi route is configured to serve the dynamically built specification. This guarantees the documentation matches exactly what the running API supports.

How the OpenAPI Spec Is Generated

Kaneo uses hono-openapi decorators throughout its route definitions to annotate endpoints. Key decorators include:

• describeRoute — Documents endpoint metadata, summary, and responses
• validator — Adds request validation schemas that feed into the spec

The generation pipeline works as follows:

1. Runtime generation: The Hono app collects all decorated routes and builds an OpenAPI document in memory
2. Normalization: Helpers in apps/api/src/utils/openapi-spec.ts merge the Hono spec with Better Auth's authentication schema
3. Deployment: The /api/openapi endpoint serves this document as JSON

A convenience script at apps/api/scripts/export-openapi.ts fetches from this endpoint and writes the result to apps/docs/openapi.json, ensuring the Mintlify documentation site stays synchronized with the API.

Accessing the Spec Programmatically

Fetch the live OpenAPI spec with curl

curl -s https://cloud.kaneo.app/api/openapi | jq .

This returns the same JSON structure committed to apps/docs/openapi.json, containing all paths, parameters, request/response schemas, and Bearer token security definitions.

Load the spec in a Node.js script

import fetch from "node-fetch";

async function getSpec() {
  const res = await fetch("https://cloud.kaneo.app/api/openapi");
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const spec = await res.json();
  console.log(spec.info.title); // "Kaneo API"
  console.log(Object.keys(spec.paths)); // List all available endpoints
}
getSpec();

Preview with Swagger UI locally

npm i -g swagger-ui-watcher
swagger-ui-watcher ./apps/docs/openapi.json

Then open http://localhost:8000 for interactive documentation with request execution.

Generating Type-Safe Clients from Kaneo API Documentation

The Kaneo API documentation enables automatic client generation. Using openapi-typescript:

npx openapi-typescript ./apps/docs/openapi.json --output ./src/kaneo-types.ts

This produces a TypeScript file containing typed interfaces for every request and response in the API. Import these types for compile-time safety when calling Kaneo endpoints.

Key Source Files for API Documentation

File Path	Purpose
apps/api/src/index.ts	Registers /api/openapi endpoint, configures hono-openapi
apps/api/src/utils/openapi-spec.ts	Merges Hono and Better Auth schemas, normalizes output
apps/api/scripts/export-openapi.ts	CLI tool to export live spec to the docs package
apps/docs/openapi.json	Version-controlled OpenAPI specification
apps/docs/README.md	Local docs preview instructions
tests/api-integration/openapi.test.ts	Validates the spec endpoint returns valid OpenAPI

The integration test ensures the documentation contract remains intact across changes.

Summary

• Kaneo provides complete API documentation via OpenAPI 3.0, generated automatically from code annotations
• Access the spec through the /api/openapi endpoint or the static apps/docs/openapi.json file
• The build-time generation uses hono-openapi decorators (describeRoute, validator) with normalization helpers in apps/api/src/utils/openapi-spec.ts
• Use standard OpenAPI tools like Swagger UI or openapi-typescript to explore the API and generate typed clients

Frequently Asked Questions

Where is the Kaneo API documentation hosted?

The Kaneo API documentation is built into every Kaneo deployment at the /api/openapi endpoint. The production instance at cloud.kaneo.app exposes this publicly. Additionally, the Mintlify documentation site in apps/docs/ renders a browsable HTML version from the same OpenAPI source file.

How do I generate a TypeScript client from the Kaneo API?

Run npx openapi-typescript ./apps/docs/openapi.json --output ./types.ts after cloning the repository, or fetch the live spec from your Kaneo instance's /api/openapi endpoint and pass it to any OpenAPI code generator.

What authentication does the Kaneo API use?

The OpenAPI specification documents Bearer token authentication as implemented by the Better Auth integration. The security schemes are included in the generated spec, visible in apps/docs/openapi.json under the components.securitySchemes section.

Is the API documentation kept up to date automatically?

Yes. The spec is regenerated at runtime from the actual route definitions using hono-openapi, so it always reflects the deployed code. The static file in apps/docs/openapi.json is refreshed via apps/api/scripts/export-openapi.ts as part of the documentation release process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}