# How AI Tools Can Interact with Kaneo Programmatically: Complete TypeScript Client Guide

> Learn how AI tools can interact with Kaneo programmatically using the type-safe TypeScript client from @kaneo/libs. Automate Kaneo operations seamlessly with Hono's RPC generator.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-30

---

**AI agents can fully automate Kaneo operations by importing the type-safe HTTP client from the @kaneo/libs package, which exposes strongly-typed methods for every API endpoint via Hono's RPC generator.**

The open-source project management platform **Kaneo** (`usekaneo/kaneo`) provides a programmatic interface specifically designed for AI automation and third-party integrations. The official client library—published as **@kaneo/libs**—eliminates manual HTTP handling by exporting a strongly-typed client that maps directly to the server's OpenAPI specification, enabling AI tools to call endpoints with full TypeScript IntelliSense.

## Architecture of the Kaneo Programmatic Client

### Base URL Resolution with resolveApiBaseUrl

In [`packages/libs/src/api-url.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/api-url.ts), the **`resolveApiBaseUrl()`** function dynamically determines the API endpoint by reading the `VITE_API_URL` environment variable. If undefined, it falls back to `http://localhost:1337` and guarantees the URL terminates with `/api`, ensuring consistent routing for all subsequent requests.

### Per-Tab Session Identification

The client generates a random `windowId` for each browser context inside [`packages/libs/src/hono.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/hono.ts), transmitting this value as the **`X-Kaneo-Window-Id`** header on every HTTP request. This mechanism allows the Kaneo server to distinguish between concurrent AI agent connections and maintain isolated session contexts.

### Type-Safe RPC via Hono

The exported **`client`** singleton utilizes Hono's **`hc<AppType>()`** factory defined in [`packages/libs/src/hono.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/hono.ts), where `AppType` represents the complete application type declared in [`apps/api/src/openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts). This architecture provides compile-time type checking for every route—such as `getWorkspaces`, `createTask`, and `uploadAvatar`—while automatically injecting `credentials: "include"` to maintain cookie-based authentication sessions.

## Implementing AI Automation with @kaneo/libs

### Importing the Typed Client

To begin programmatic interaction, import the ready-made client singleton from the package entry point. The client is pre-configured and requires no manual instantiation.

```typescript
import { client } from "@kaneo/libs";

```

### Querying Workspace Data

AI tools can retrieve organizational context by calling **`client.getWorkspaces()`**, which returns a fully-typed response matching the Zod schemas defined in the API layer.

```typescript
async function listWorkspaces() {
  const { data, error } = await client.getWorkspaces({});
  
  if (error) throw new Error(error.message);
  console.log("Available workspaces:", data);
  
  return data;
}

```

### Creating Tasks Programmatically

The **`client.createTask()`** method accepts a project identifier and structured payload, enabling automated task generation from AI analysis pipelines without manual JSON construction.

```typescript
async function createTask(projectId: string) {
  const { data, error } = await client.createTask({
    projectId,
    body: {
      title: "AI-generated documentation task",
      description: "Automatically created via programmatic interaction",
    },
  });
  
  if (error) throw new Error(error.message);
  console.log("Created task:", data);
  
  return data;
}

```

### Uploading Binary Assets

For file operations, the client accepts base64-encoded buffers through **`client.uploadAvatar()`**, handling the `contentType` metadata required by the server's validation logic.

```typescript
async function uploadAvatar(file: File) {
  const buffer = await file.arrayBuffer();
  const base64 = Buffer.from(buffer).toString("base64");

  const { data, error } = await client.uploadAvatar({
    body: { 
      contentType: file.type, 
      data: base64 
    },
  });
  
  if (error) throw new Error(error.message);
  console.log("Avatar URL:", data.url);
  
  return data;
}

```

### Subscribing to Real-Time Events

Beyond REST operations, AI agents can establish WebSocket connections using the **`subscribe`** utility from `@kaneo/libs/websocket` to listen for live task updates without polling.

```typescript
import { subscribe } from "@kaneo/libs/websocket";

function listenToTaskUpdates(taskId: string) {
  const ws = subscribe(`tasks/${taskId}`);
  
  ws.onmessage = (msg) => {
    console.log("Realtime update:", msg.data);
  };
  
  return ws;
}

```

## Summary

- **@kaneo/libs** provides a zero-configuration, type-safe HTTP client generated from the server's OpenAPI specification in [`apps/api/src/openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts).
- The **`resolveApiBaseUrl()`** function in [`packages/libs/src/api-url.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/api-url.ts) handles environment-specific endpoint resolution with a localhost fallback.
- Every request automatically includes the **`X-Kaneo-Window-Id`** header for session isolation, managed transparently in [`packages/libs/src/hono.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/hono.ts).
- AI tools can perform CRUD operations on workspaces, projects, and tasks using methods like `getWorkspaces` and `createTask` with full TypeScript autocomplete.
- Binary uploads require base64 encoding before transmission via `client.uploadAvatar()`.
- Real-time capabilities are available through the separate `subscribe` WebSocket helper.

## Frequently Asked Questions

### What authentication method does the Kaneo client use?

The Kaneo client relies on cookie-based session authentication automatically managed by the browser or HTTP agent. The client configuration in [`packages/libs/src/hono.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/hono.ts) explicitly sets `credentials: "include"`, ensuring cookies are transmitted with every request without manual header management.

### Can the Kaneo client be used outside of a browser environment?

Yes, the `@kaneo/libs` package is pure TypeScript and functions in Node.js or edge runtime environments. While the `windowId` generation logic sounds browser-specific, the underlying HTTP client operates via standard `fetch`, making it suitable for server-side AI agents and automation scripts.

### How does the Kaneo client handle type safety?

Type safety is enforced through Hono's RPC client (`hc<AppType>`), where `AppType` is the complete application type exported from [`apps/api/src/openapi.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/openapi.ts). Because the API routes are defined using `createRoute()` with Zod schemas in the backend, the frontend client receives generated types that prevent calling non-existent endpoints or sending malformed request bodies.

### Is there a way to interact with Kaneo without using the official client?

While direct HTTP calls to the REST API are possible, the `@kaneo/libs` package is the recommended approach because it manages the `X-Kaneo-Window-Id` header, base URL resolution, and cookie credentials automatically. Bypassing the client requires manually implementing these behaviors, including reading `VITE_API_URL` and ensuring the `/api` suffix is present on all routes.