# Kaneo API Documentation: How to Access the OpenAPI 3.0 Spec

> Access Kaneo API documentation via OpenAPI 3.0 spec. Get runtime endpoint and static file for usekaneo/kaneo for seamless integration.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: api-reference
- Published: 2026-08-04

---

**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`](https://github.com/usekaneo/kaneo/blob/main/apps/docs/openapi.json) in the repository | Offline access, version history, client generation |

The live endpoint is registered in [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/scripts/export-openapi.ts) fetches from this endpoint and writes the result to [`apps/docs/openapi.json`](https://github.com/usekaneo/kaneo/blob/main/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

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

```

This returns the same JSON structure committed to [`apps/docs/openapi.json`](https://github.com/usekaneo/kaneo/blob/main/apps/docs/openapi.json), containing all paths, parameters, request/response schemas, and Bearer token security definitions.

### Load the spec in a Node.js script

```javascript
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

```bash
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`:

```bash
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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts) | Registers `/api/openapi` endpoint, configures `hono-openapi` |
| [`apps/api/src/utils/openapi-spec.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/utils/openapi-spec.ts) | Merges Hono and Better Auth schemas, normalizes output |
| [`apps/api/scripts/export-openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/scripts/export-openapi.ts) | CLI tool to export live spec to the docs package |
| [`apps/docs/openapi.json`](https://github.com/usekaneo/kaneo/blob/main/apps/docs/openapi.json) | Version-controlled OpenAPI specification |
| [`apps/docs/README.md`](https://github.com/usekaneo/kaneo/blob/main/apps/docs/README.md) | Local docs preview instructions |
| [`tests/api-integration/openapi.test.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/docs/openapi.json) is refreshed via [`apps/api/scripts/export-openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/scripts/export-openapi.ts) as part of the documentation release process.