# Kaneo API Endpoints: Complete REST API Reference for Project Management

> Explore Kaneo API endpoints for seamless project management. Access a complete REST API reference for projects, tasks, labels, workspaces, and more. Integrate easily.

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

---

**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](https://github.com/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/workspace/index.ts)):
- `GET /api/workspace/:workspaceId/members` – List workspace members

**Invitations** ([`apps/api/src/invitation/index.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/github-integration/index.ts)): Verify installation, list repositories, import issues
- **Gitea** ([`apps/api/src/gitea-integration/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/gitea-integration/index.ts)): Gitea-specific repository integration
- **Generic Webhooks** ([`apps/api/src/generic-webhook-integration/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/generic-webhook-integration/index.ts)): Custom webhook handlers

### Messaging Integrations

- **Slack** ([`apps/api/src/slack-integration/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/slack-integration/index.ts)): Slack workspace connections
- **Discord** ([`apps/api/src/discord-integration/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/discord-integration/index.ts)): Discord server integrations
- **Telegram** ([`apps/api/src/telegram-integration/index.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts) and implemented in [`apps/api/src/ws/index.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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

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

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

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

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

```javascript
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`](https://github.com/usekaneo/kaneo/blob/main/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.