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

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, 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, 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, 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) 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) 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): /api/column/* – Manages Kanban columns including creation, reordering, and deletion
• Label router (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): /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:

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

// 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);

// 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
• 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, 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.

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