How to Access the Kaneo API OpenAPI Documentation

The Kaneo API exposes its OpenAPI 3.1 specification via a live HTTP endpoint at /api/openapi, accessible at https://cloud.kaneo.app/api/openapi by default or through your local development server.

Kaneo is an open-source project management platform that dynamically generates its API documentation from the underlying Hono routes and Zod schemas. Retrieving this Kaneo API OpenAPI documentation enables you to generate typed clients, validate request payloads, and automate API integrations without manual specification maintenance.

Endpoint Location and Configuration

The specification endpoint is registered in apps/api/src/index.ts where the Hono application defines the route handler:

api.get("/openapi", ...)

The base URL used to serve the documentation is constructed from the KANEO_API_URL environment variable. When this variable is unset, the system defaults to https://cloud.kaneo.app as defined in lines 2-17 of the entry file. Consequently, the public production URL is:

https://cloud.kaneo.app/api/openapi

For local development using pnpm dev in the apps/api directory, substitute the host with your local server address, typically http://localhost:3000/api/openapi.

Retrieving the OpenAPI Specification

You can fetch the JSON specification using standard HTTP clients or the repository's built-in export utility.

Using curl

For quick inspection or piping to JSON formatters like jq:

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

Using Node.js

To fetch the spec programmatically within a Node.js application:

import { fetch } from 'node-fetch';

async function getOpenAPISpec() {
  const base = process.env.KANEO_API_URL || 'https://cloud.kaneo.app';
  const resp = await fetch(`${base}/api/openapi`);
  if (!resp.ok) throw new Error(`Failed: ${resp.status}`);
  const spec = await resp.json();
  console.log(JSON.stringify(spec, null, 2));
}

getOpenAPISpec();

Exporting to a Static File

The repository includes a utility script that retrieves the spec and persists it to disk. Located at apps/api/scripts/export-openapi.ts, this script is used in CI pipelines to generate docs/openapi.json:

pnpm --filter @kaneo/api exec ts-node scripts/export-openapi.ts

Implementation Details

The OpenAPI document is generated on-the-fly via the api.getOpenAPI31Document(...) method, which assembles the specification from the routed endpoints and shared Zod schemas defined in apps/api/src/openapi.ts. The handler returns the complete JSON document dynamically, ensuring the documentation always reflects the current API surface without requiring manual updates.

Integration tests in tests/api-integration/openapi.test.ts validate that the endpoint returns a valid OpenAPI 3.1.0 document, specifically verifying that the openapi field matches the expected version string.

Summary

• Access the live Kaneo API OpenAPI documentation at https://cloud.kaneo.app/api/openapi for production or http://localhost:3000/api/openapi for local development.
• The endpoint is registered in apps/api/src/index.ts and relies on the KANEO_API_URL environment variable to construct server metadata.
• Retrieve the specification via standard HTTP requests, Node.js fetch, or the repository's export-openapi.ts script.
• The specification conforms to OpenAPI 3.1.0 and is generated dynamically using getOpenAPI31Document from the active API routes.

Frequently Asked Questions

What is the URL for Kaneo API OpenAPI documentation?

The public endpoint is https://cloud.kaneo.app/api/openapi. For local instances, use http://localhost:3000/api/openapi (or substitute the port where your development server is running).

How does Kaneo generate its OpenAPI specification?

The API server generates the specification dynamically at runtime using api.getOpenAPI31Document(...) in apps/api/src/index.ts. This method introspects the registered Hono routes and Zod schemas to produce a compliant OpenAPI 3.1 JSON document on each request.

Can I download the OpenAPI spec as a JSON file?

Yes. Execute the script at apps/api/scripts/export-openapi.ts using the command pnpm --filter @kaneo/api exec ts-node scripts/export-openapi.ts to write the current specification to docs/openapi.json. Alternatively, save the JSON response from the /api/openapi endpoint using curl or a browser.

Where is the OpenAPI route defined in the Kaneo source code?

The route handler is registered in apps/api/src/index.ts (lines 2-22), where the api.get("/openapi", ...) endpoint is configured to return the generated document constructed from the KANEO_API_URL environment variable.

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