Kaneo API Endpoints: Complete REST API Reference for Project Management

Kaneo exposes a comprehensive REST API built on Hono, featuring OpenAPI-documented endpoints for managing projects, tasks, labels, workspaces, integrations, and real-time WebSocket connections, all organized under apps/api/src/*/index.ts.

The usekaneo/kaneo repository is an open-source project management platform that provides a feature-rich backend API for team collaboration. Built with the Hono framework and structured by domain-driven modules, the Kaneo API offers full CRUD capabilities, third-party integrations, and real-time updates via WebSocket connections.

API Architecture and Routing Structure

Kaneo’s backend follows a clean, feature-based routing layout. All routes are registered in apps/api/src/index.ts and delegated to sub-routers located under apps/api/src/*. Each sub-router (Projects, Tasks, Labels, Workspaces, etc.) declares its own OpenAPI-decorated endpoints using describeRoute, validator, and resolver from hono-openapi.

The generated OpenAPI specification is served at GET /api/openapi, enabling automatic documentation and client generation.

Core System Endpoints

Health and Instance Status

The root router in apps/api/src/index.ts defines essential system endpoints:

• GET /api/health – Returns service health status
• GET /api/instance/status – Returns instance setup status
• GET /api/openapi – Serves the generated OpenAPI specification

Configuration Management

The configuration module in apps/api/src/config/index.ts exposes endpoints for retrieving and updating application settings, enabling dynamic configuration of the Kaneo instance without restarts.

Resource Management Endpoints

Projects

Located in apps/api/src/project/index.ts, the Projects API provides full lifecycle management:

• GET /api/project – List all projects (optionally filtered by workspace)
• POST /api/project – Create a new project
• GET /api/project/:id – Fetch a specific project
• PUT /api/project/:id – Update project details
• DELETE /api/project/:id – Delete a project
• PUT /api/project/:id/archive – Archive a project
• PUT /api/project/:id/unarchive – Restore an archived project

Tasks

The Tasks module in apps/api/src/task/index.ts offers the most extensive endpoint set, supporting granular operations:

Task CRUD and Listing:

• GET /api/task/tasks/:projectId – List tasks for a specific project
• POST /api/task/:projectId – Create a new task
• GET /api/task/:id – Fetch a specific task
• PUT /api/task/:id – Full task update
• DELETE /api/task/:id – Delete a task

Task Operations:

• PATCH /api/task/bulk – Bulk update multiple tasks
• PUT /api/task/move/:id – Move a task between projects or positions
• PUT /api/task/status/:id – Change task status
• PUT /api/task/priority/:id – Update task priority
• PUT /api/task/assignee/:id – Change task assignee
• PUT /api/task/due-date/:id – Update due date
• PUT /api/task/title/:id – Update task title
• PUT /api/task/description/:id – Update task description

Image Handling:

• PUT /api/task/image-upload/:id – Get presigned URL for image upload
• POST /api/task/image-upload/:id/finalize – Finalize image upload after client-side upload

Import/Export:

• GET /api/task/export/:projectId – Export tasks from a project
• POST /api/task/import/:projectId – Import tasks into a project

Labels

The Labels API in apps/api/src/label/index.ts manages categorical tagging:

• GET /api/label/task/:taskId – List labels attached to a task
• GET /api/label/workspace/:workspaceId – List labels in a workspace
• POST /api/label – Create a new label
• GET /api/label/:id – Fetch a specific label
• PUT /api/label/:id – Update label details
• DELETE /api/label/:id – Delete a label
• PUT /api/label/:id/task – Attach label to a task
• DELETE /api/label/:id/task – Detach label from a task

Workspaces and Invitations

Workspaces (apps/api/src/workspace/index.ts):

• GET /api/workspace/:workspaceId/members – List workspace members

Invitations (apps/api/src/invitation/index.ts):

• Various invitation-related routes for creating, listing, and managing workspace invitations (specific paths defined in the router).

Workflow and Automation Endpoints

Workflow Rules

Located in apps/api/src/workflow-rule/index.ts, these endpoints manage automated workflow logic:

• List, upsert, and delete workflow rules that trigger based on task events.

Time Tracking

The Time Entries module in apps/api/src/time-entry/index.ts provides:

• Full CRUD operations for time-tracking entries associated with tasks.

Integration Endpoints

Kaneo supports extensive third-party integrations, each with dedicated routers:

Git and Webhook Integrations

• GitHub (apps/api/src/github-integration/index.ts): Verify installation, list repositories, import issues
• Gitea (apps/api/src/gitea-integration/index.ts): Gitea-specific repository integration
• Generic Webhooks (apps/api/src/generic-webhook-integration/index.ts): Custom webhook handlers

Messaging Integrations

• Slack (apps/api/src/slack-integration/index.ts): Slack workspace connections
• Discord (apps/api/src/discord-integration/index.ts): Discord server integrations
• Telegram (apps/api/src/telegram-integration/index.ts): Telegram bot integrations

Each integration module defines CRUD-style endpoints for verifying installations, managing connections, and synchronizing data.

Search, Notifications, and Real-Time Updates

Search

The Search module (apps/api/src/search/index.ts) provides:

• GET /api/search – Global search across projects, tasks, and other resources

Notifications

Located in apps/api/src/notification/index.ts:

• GET /api/notification – List user notifications
• Notification Preferences (/api/notification-preferences): Manage user notification settings

WebSocket Connections

Real-time functionality is exposed through WebSocket endpoints defined in apps/api/src/index.ts and implemented in apps/api/src/ws/index.ts:

• /api/ws/user – User-specific real-time events
• /api/ws/:projectId – Project-specific real-time updates for collaborative editing

Authentication and Asset Management

Authentication

Authentication routes are handled by the Better-Auth plugin, mounted in apps/api/src/index.ts (lines 95-124) under /api/auth/*. This includes session management, device flow authentication, and API key generation.

Assets

Binary asset downloads are served via:

• GET /api/asset/:id – Stream an uploaded asset (binary stream), defined in apps/api/src/index.ts

Practical API Usage Examples

Below are practical examples using JavaScript fetch. Replace BASE_URL with your KANEO_API_URL environment variable (default: http://localhost:1337).

List Projects in a Workspace

async function listProjects(workspaceId) {
  const res = await fetch(
    `${BASE_URL}/api/project?workspaceId=${workspaceId}`,
    { credentials: "include" } // sends session cookie
  );
  return res.json(); // → [{ id, name, ... }, …]
}

Create a New Task

async function createTask(projectId, title, description) {
  const body = { 
    title, 
    description, 
    status: "todo", 
    priority: "medium", 
    projectId 
  };
  const res = await fetch(`${BASE_URL}/api/task/${projectId}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
    credentials: "include",
  });
  return res.json(); // → created task object
}

Attach a Label to a Task

async function attachLabel(labelId, taskId) {
  const res = await fetch(`${BASE_URL}/api/label/${labelId}/task`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ taskId }),
    credentials: "include",
  });
  return res.json(); // → updated label
}

Get Presigned URL for Image Upload

async function getUploadUrl(taskId, filename) {
  const body = {
    filename,
    contentType: "image/png",
    size: 12345,
    surface: "description",
  };
  const res = await fetch(`${BASE_URL}/api/task/image-upload/${taskId}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
    credentials: "include",
  });
  return res.json(); // → { uploadUrl, fields… }
}

Download an Asset

async function downloadAsset(assetId) {
  const res = await fetch(`${BASE_URL}/api/asset/${assetId}`, {
    credentials: "include",
  });
  const blob = await res.blob();
  const link = document.createElement("a");
  link.href = URL.createObjectURL(blob);
  link.download = "asset";
  link.click();
}

Summary

• Kaneo API endpoints are organized by domain in apps/api/src/*/index.ts files, following a modular Hono-based architecture.
• Core resources (Projects, Tasks, Labels) support full CRUD operations with additional specialized endpoints for archiving, bulk updates, and file uploads.
• Integration endpoints support GitHub, Gitea, Slack, Discord, Telegram, and generic webhooks for external connectivity.
• Real-time features are available via WebSocket connections at /api/ws/user and /api/ws/:projectId.
• OpenAPI documentation is automatically generated and served at GET /api/openapi, reflecting all routes decorated with hono-openapi validators.

Frequently Asked Questions

What framework does Kaneo use for its API?

Kaneo uses the Hono web framework with hono-openapi middleware for type-safe routing and automatic OpenAPI documentation generation. Authentication is handled by the Better-Auth plugin integrated in apps/api/src/index.ts.

Where can I find the OpenAPI specification for Kaneo?

The OpenAPI specification is dynamically generated from route decorators and served at GET /api/openapi. This endpoint reflects all registered routes including Projects, Tasks, Labels, and Integrations defined across the modular router files.

Does Kaneo support bulk operations on tasks?

Yes. The Tasks API includes a PATCH /api/task/bulk endpoint for updating multiple tasks simultaneously, along with dedicated endpoints for moving tasks (PUT /api/task/move/:id) and modifying specific fields like status, priority, and assignee without full object replacement.

How are real-time updates handled in the Kaneo API?

Real-time updates are provided via WebSocket connections at /api/ws/user for user-specific notifications and /api/ws/:projectId for project-specific collaborative events. These endpoints enable live task updates without polling the REST API.

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