# Complete Guide to API Endpoints in Kaneo: REST, WebSockets, and Integrations

> Explore Kaneo API endpoints, including REST APIs under /api for projects, tasks, and integrations, plus real-time WebSockets. Seamlessly integrate your tools.

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

---

**Kaneo exposes a comprehensive REST API built on the Hono framework, with all endpoints mounted under the `/api` base path, including domain-specific sub-routers for projects, tasks, columns, and third-party integrations, plus WebSocket endpoints for real-time collaboration.**

Kaneo is an open-source project management platform whose backend architecture centers on a lightweight, high-performance HTTP server. All API endpoints in the usekaneo/kaneo repository are organized under a central `/api` router defined in [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts), which delegates requests to specialized sub-routers for each functional domain. This structure provides a clean separation between core system endpoints, authentication flows, CRUD operations, and real-time communication channels.

## API Architecture and Base Configuration

### The Central Router

The entry point for every API request is [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts), where the main Hono application instance mounts the `/api` router and registers all sub-routers. This file defines the base configuration and wires together the entire API surface, from health checks to WebSocket upgrades. Each functional area is implemented as a dedicated module (e.g., [`apps/api/src/project/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/project/index.ts), [`apps/api/src/task/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/task/index.ts)) that exports a router instance attached to the main API path.

## System and Public Endpoints

### Health and Status Monitoring

Kaneo provides explicit endpoints for system health and instance status:

- **`GET /api/health`** – Returns a simple status check to verify the API is operational
- **`GET /api/instance/status`** – Provides detailed instance metadata and system configuration

### Public Access Routes

Certain endpoints bypass authentication to support public sharing and invitations:

- **`GET /api/public-project/:id`** – Retrieves project details for publicly shared projects without requiring session authentication
- **`GET /api/invitation/public/:id`** – Validates and retrieves public invitation data for workspace onboarding

### Configuration and Assets

- **`GET /api/config/*`** – Router handling system configuration values
- **`GET /api/asset/:id`** – Serves uploaded files and attachments stored in the system

## Authentication and Session Management

### Session and Device Flows

Authentication endpoints handle user sessions, device authorization, and OAuth proxying:

- **`GET /api/auth/get-session`** – Retrieves the current user session and authentication state
- **`GET /api/auth/device`** – Handles device authorization redirects for CLI and mobile applications
- **`* /api/auth/*`** – Catch-all proxy route for authentication providers and token exchange

### OAuth Integration

- **`* /api/oauth/*`** – Dedicated router managing OAuth 2.0 flows for external identity providers

## Core Domain REST Routers

Each primary domain implements a full CRUD interface through its own router mounted under `/api`. These routers follow REST conventions and use the `hono-openapi` decorators for automatic documentation generation.

### Project Management

The project router ([`apps/api/src/project/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/project/index.ts)) handles workspace containers:

- **`GET /api/project`** – List all projects accessible to the current user in a workspace
- **`GET /api/project/:id`** – Fetch detailed information for a specific project
- **`POST /api/project`** – Create a new project with title, description, and configuration
- **`PATCH /api/project/:id`** – Update project properties and settings
- **`DELETE /api/project/:id`** – Remove a project and associated data

### Task Operations

The task router ([`apps/api/src/task/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/task/index.ts)) manages the core work items:

- **`GET /api/task/:id`** – Retrieve task details including assignees, labels, and comments
- **`POST /api/task`** – Create a new task within a project column
- **`PATCH /api/task/:id`** – Update task title, description, status, or position
- **`DELETE /api/task/:id`** – Delete a task and its associated time entries and relations

### Board Structure and Organization

- **Column router** ([`apps/api/src/column/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/column/index.ts)): **`/api/column/*`** – Manages Kanban columns including creation, reordering, and deletion
- **Label router** ([`apps/api/src/label/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/label/index.ts)): **`/api/label/*`** – Handles label CRUD operations and task assignments

### Collaboration and Activity

- **Comment router** ([`apps/api/src/comment/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/comment/index.ts)): **`/api/comment/*`** – Post, edit, and delete task comments
- **Activity router**: **`/api/activity/*`** – Retrieves audit logs and change history for projects and tasks
- **Time tracking**: **`/api/time-entry/*`** – Records and manages time spent on specific tasks
- **Task relations**: **`/api/task-relation/*`** – Creates dependencies and relationships between tasks (blocking, related, etc.)
- **External links**: **`/api/external-link/*`** – Attaches external URLs and references to tasks

## Integration Endpoints

Kaneo provides extensive webhook and API endpoints for third-party integrations, organized by platform.

### Version Control Webhooks

Incoming webhooks from Git repositories trigger automated actions:

- **`POST /api/github-integration/webhook`** – Receives GitHub events (push, pull request, issues) to sync with tasks
- **`POST /api/gitea-integration/webhook/:integrationId`** – Handles Gitea repository events using the specific integration ID

Management routes for these integrations are available at:
- **`/api/github-integration/*`** – Configure GitHub connections and repository mappings
- **`/api/gitea-integration/*`** – Manage Gitea integration settings

### Communication Platform Integrations

Routers for chat and notification platforms enable bidirectional sync:

- **`/api/discord-integration/*`** – Discord bot commands and webhook management
- **`/api/slack-integration/*`** – Slack workspace connections and channel notifications
- **`/api/telegram-integration/*`** – Telegram bot integration and message routing

### Generic Webhooks

- **`/api/generic-webhook-integration/*`** – Custom webhook endpoints for arbitrary external systems

## Workspace and Administrative Routers

### Workspace Management

- **`/api/workspace/*`** – CRUD operations for workspaces, member management, and settings

### Billing and Usage

- **`/api/billing/*`** – Subscription management, payment methods, and usage analytics

### Notifications and Search

- **`/api/notification/*`** – Fetch and mark notifications as read
- **`/api/notification-preferences/*`** – Configure email and push notification settings
- **`/api/search/*`** – Global search across projects, tasks, and comments

### Workflow Automation

- **`/api/workflow-rule/*`** – Define automated rules triggered by status changes or time-based conditions

### Invitations

- **`/api/invitation/*`** – Create, revoke, and manage workspace invitations (distinct from the public invitation endpoint)

## Real-Time Communication via WebSockets

Kaneo supports live updates through WebSocket connections for real-time collaboration:

- **`GET /api/ws/user`** – User-scoped WebSocket connection for personal notifications and cross-project updates (handled in `apps/api/src/ws/*`)
- **`GET /api/ws/:projectId`** – Project-scoped WebSocket for live board updates, task movements, and comment streaming within a specific project

These endpoints upgrade HTTP connections to WebSocket protocols, pushing JSON events to connected clients when data changes.

## API Documentation and Discovery

### OpenAPI Specification

Kaneo generates comprehensive API documentation using `hono-openapi` decorators (`describeRoute`, `validator`, etc.) defined alongside each route:

- **`GET /api/openapi`** – Returns the complete OpenAPI 3.0 specification as JSON, documenting all available endpoints, request schemas, and response formats

This endpoint aggregates metadata from all sub-routers, providing a machine-readable schema for client generation and testing tools.

## Practical Usage Examples

The following examples demonstrate how to interact with key API endpoints in Kaneo using standard HTTP clients:

```typescript
// Example: Health check
await fetch(`${process.env.KANEO_API_URL}/api/health`).then(r => r.json());
// → { status: "ok" }

```

```typescript
// Example: Fetch a public project (no auth required)
const projId = "prj_01G8XYZ...";
await fetch(`${process.env.KANEO_API_URL}/api/public-project/${projId}`)
  .then(r => r.json())
  .then(console.log);

```

```typescript
// Example: Create a new task (requires auth)
// Assume a Bearer token stored in `token`
await fetch(`${process.env.KANEO_API_URL}/api/task`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    title: "Write knowledge-base article",
    projectId: "prj_01G8XYZ...",
  }),
}).then(r => r.json())
  .then(console.log);

```

## Summary

- **All Kaneo API endpoints are prefixed with `/api`** and mounted through the central Hono router in [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts)
- **Core domains** (projects, tasks, columns, labels) provide full RESTful CRUD operations through dedicated sub-routers
- **Public endpoints** (`/api/public-project/:id`, `/api/invitation/public/:id`) allow unauthenticated access for shared resources
- **Integration endpoints** support webhooks from GitHub, Gitea, Discord, Slack, and Telegram, plus generic HTTP webhooks
- **Real-time features** use WebSocket connections at `/api/ws/user` and `/api/ws/:projectId` for live collaboration
- **Automatic documentation** is available via `GET /api/openapi`, generated from `hono-openapi` decorators throughout the codebase

## Frequently Asked Questions

### What base URL should I use for Kaneo API endpoints?

All endpoints are relative to your Kaneo instance domain with the `/api` prefix. For a self-hosted instance at `https://kaneo.example.com`, the health endpoint would be `https://kaneo.example.com/api/health`. The API does not use versioning in the URL path; breaking changes are managed through the OpenAPI specification and client libraries.

### Does Kaneo require authentication for all API endpoints?

No, authentication requirements vary by endpoint. Public project endpoints (`/api/public-project/:id`) and public invitation endpoints (`/api/invitation/public/:id`) are accessible without authentication. However, all task management, project creation, workspace administration, and WebSocket endpoints require a valid session obtained through `/api/auth/get-session` or an OAuth flow via `/api/oauth/*`.

### How can I access the OpenAPI specification for Kaneo?

The complete OpenAPI 3.0 specification is available at `GET /api/openapi` on any running Kaneo instance. This endpoint aggregates metadata from all sub-routers including [`apps/api/src/project/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/project/index.ts), [`apps/api/src/task/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/task/index.ts), and integration modules, returning a JSON document that describes available endpoints, request bodies, validation schemas, and authentication requirements.

### What real-time capabilities does the Kaneo API support?

Kaneo provides WebSocket endpoints at `/api/ws/user` for user-scoped notifications and `/api/ws/:projectId` for project-specific updates. These connections deliver live events for task movements, comment additions, status changes, and member activities without requiring client polling. The WebSocket handlers are implemented in the `apps/api/src/ws/*` directory and upgrade standard HTTP requests to persistent connections.