# Kaneo API Request Lifecycle: From HTTP Request to Real-Time Broadcast

> Explore the Kaneo API request lifecycle. See how it handles HTTP requests through Hono, OpenAPI, Zod, Drizzle, and WebSockets for a typed JSON response.

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

---

**An inbound API request in Kaneo traverses a Hono-based pipeline that includes OpenAPI route registration, authentication middleware, Zod schema validation, controller execution with Drizzle ORM transactions, event publishing, and WebSocket broadcasting before returning a typed JSON response.**

Kaneo is an open-source project management platform built on the Hono framework. Understanding the request lifecycle for an API call in Kaneo is essential for developers extending the backend or debugging authentication workflows. Every HTTP request follows a predictable path through middleware chains, database operations, and real-time event propagation as implemented in the `apps/api/src` directory.

## Route Registration with createRoute

All API endpoints are declared using the `createRoute` helper exported from [`apps/api/src/openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts). This utility, provided by `@hono/zod-openapi`, registers the HTTP method, URL path, request/response Zod schemas, and attaches route-specific metadata for OpenAPI documentation generation.

Individual feature modules, such as [`apps/api/src/task/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/task/index.ts), import `createRoute` to define their specific endpoints. The centralized `apiRouter` instance in [`openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/openapi.ts) aggregates these routes and configures the global middleware pipeline, validation hooks, and the `jsonResponse` helper used for consistent response formatting.

## The Pre-Validation Middleware Pipeline

Before Zod schema validation executes, the request passes through a configurable chain of Hono middleware functions. This pre-validation stage handles security, identity resolution, and access control using raw request headers and cookies.

### Authentication and Identity Resolution

The primary authentication layer resides in [`apps/api/src/utils/authenticate-api-request.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/utils/authenticate-api-request.ts). This middleware inspects the incoming request for a valid session cookie or API key header, verifies the credentials against the database, and populates the Hono context variables—including `c.get("userId")`—for downstream handlers. If authentication fails, the middleware throws an `HTTPException` with an appropriate 401 status code.

### API Key Verification

For requests using API key authentication, the system invokes [`apps/api/src/utils/verify-api-key.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/utils/verify-api-key.ts). This module validates the key's signature, checks expiration dates, and enforces key-specific permissions before allowing the request to proceed to workspace-level authorization.

### Workspace Access Control

The [`apps/api/src/utils/workspace-access-middleware.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/utils/workspace-access-middleware.ts) middleware validates that the authenticated user has membership in the workspace referenced by the URL parameter (e.g., `/api/v1/workspaces/:workspaceId`). This ensures that project-scoped resources remain isolated between different organizations.

### Bot Protection

When enabled, the pipeline includes [`apps/api/src/utils/verify-turnstile.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/utils/verify-turnstile.ts) to validate Cloudflare Turnstile captcha tokens. This middleware runs early in the chain to mitigate automated abuse against public endpoints such as user registration or login.

## Schema Validation and Route Handling

After the middleware chain completes, Hono's validation hook—configured in the `apiRouter` within [`openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/openapi.ts)—executes the Zod schemas defined during route registration. If the request body, query parameters, or path variables fail validation, the framework automatically throws an `HTTPException(400)` with a detailed error message, preventing invalid data from reaching the controller layer.

## Controller Execution and Database Operations

Once validation passes, the request enters the route's controller function, typically located in `apps/api/src/**/controllers/`. For example, [`apps/api/src/workspace/controllers/get-workspace-members.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/workspace/controllers/get-workspace-members.ts) implements the domain logic for fetching workspace membership data. Controllers interact with PostgreSQL through the Drizzle ORM, utilizing the schema definitions exported from [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts).

Controllers handle database transactions using typed queries such as `db.select()`, `db.insert()`, or `db.update()`. They may also call utility functions, apply business rules, and prepare the response payload before handing it to the response formatter.

## Event Publishing and Real-Time Broadcast

For mutating operations (create, update, delete), controllers trigger side effects by calling `publishEvent()` from [`apps/api/src/mcp/tools.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/mcp/tools.ts). This function emits domain events—such as `task.created` or `workspace.member.added`—that are consumed by the WebSocket layer.

The broadcast system, implemented in [`apps/api/src/ws/in-memory-broadcast-adapter.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/ws/in-memory-broadcast-adapter.ts) (or [`redis-broadcast-adapter.ts`](https://github.com/usekaneo/kaneo/blob/main/redis-broadcast-adapter.ts) when Redis is configured), listens for these events and pushes updates to connected clients. This ensures that frontend applications receive real-time updates without requiring manual cache invalidation.

## Response Serialization and Completion

Controllers return data using the `jsonResponse` helper defined in [`apps/api/src/openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts). This utility wraps the payload with OpenAPI metadata, serializes the response body to JSON, and sets the correct `Content-Type` header. After the handler finishes, any configured `after` hooks execute for logging or metrics collection before Hono streams the final HTTP response back to the client.

## Summary

- **Route Registration**: Endpoints are defined using `createRoute` in [`apps/api/src/openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts) with Zod schemas for type safety.
- **Pre-Validation Middleware**: [`authenticate-api-request.ts`](https://github.com/usekaneo/kaneo/blob/main/authenticate-api-request.ts) resolves identity, [`verify-api-key.ts`](https://github.com/usekaneo/kaneo/blob/main/verify-api-key.ts) validates keys, and [`workspace-access-middleware.ts`](https://github.com/usekaneo/kaneo/blob/main/workspace-access-middleware.ts) enforces workspace permissions.
- **Schema Validation**: Hono validates requests against Zod definitions immediately after middleware execution.
- **Controller Logic**: Domain handlers in `apps/api/src/**/controllers/` execute business logic using Drizzle ORM against [`apps/api/src/database/schema.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts).
- **Real-Time Events**: Mutations call `publishEvent()` from [`apps/api/src/mcp/tools.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/mcp/tools.ts) to trigger WebSocket broadcasts via adapters in `apps/api/src/ws/`.
- **Response Handling**: `jsonResponse` from [`openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/openapi.ts) formats the final JSON payload with OpenAPI metadata.

## Frequently Asked Questions

### What middleware runs before request validation in Kaneo?

The pre-validation middleware chain includes [`authenticate-api-request.ts`](https://github.com/usekaneo/kaneo/blob/main/authenticate-api-request.ts) for session/API key verification, [`verify-api-key.ts`](https://github.com/usekaneo/kaneo/blob/main/verify-api-key.ts) for key-specific permissions, [`workspace-access-middleware.ts`](https://github.com/usekaneo/kaneo/blob/main/workspace-access-middleware.ts) for workspace membership checks, and optionally [`verify-turnstile.ts`](https://github.com/usekaneo/kaneo/blob/main/verify-turnstile.ts) for bot protection. These execute sequentially in the Hono pipeline before Zod validation occurs.

### How does Kaneo handle real-time updates after a database mutation?

After a controller commits changes to the database using Drizzle ORM, it calls `publishEvent()` from [`apps/api/src/mcp/tools.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/mcp/tools.ts). This emits a domain event that the WebSocket broadcast adapter—either [`in-memory-broadcast-adapter.ts`](https://github.com/usekaneo/kaneo/blob/main/in-memory-broadcast-adapter.ts) or [`redis-broadcast-adapter.ts`](https://github.com/usekaneo/kaneo/blob/main/redis-broadcast-adapter.ts)—pushes to connected clients, ensuring UI synchronization across all active sessions.

### Which file defines the OpenAPI route helpers in Kaneo?

The [`apps/api/src/openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts) file exports the `createRoute` helper for registering endpoints, the `jsonResponse` utility for response formatting, and the centralized `apiRouter` instance that configures global middleware and validation hooks for the Hono application.

### Where is the authentication logic implemented in the Kaneo API?

Authentication logic is centralized in [`apps/api/src/utils/authenticate-api-request.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/utils/authenticate-api-request.ts), which verifies session cookies or API key headers and populates the request context with user identity. Supplementary verification for API keys specifically occurs in [`apps/api/src/utils/verify-api-key.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/utils/verify-api-key.ts).