# Where Are the API Endpoints Defined in OpenWork?

> Discover where OpenWork defines API endpoints. Learn how route modules in apps/server/src/routes and registry.ts centralize endpoint registration for efficient development.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-08-13

---

**OpenWork defines all HTTP API endpoints in TypeScript route modules under `apps/server/src/routes/`, registering each route via the centralized `addRoute` helper exposed in [`registry.ts`](https://github.com/different-ai/openwork/blob/main/registry.ts).**

OpenWork is an open-source workspace management platform that exposes a RESTful HTTP API for managing local and remote workspaces, file operations, and sessions. Understanding where these API endpoints are defined is essential for contributors extending the server or developers integrating with the platform. The routing layer follows a modular architecture where each functional domain owns its route definitions in dedicated files within the server package.

## Route Registration Architecture

The endpoint registration flow follows a three-stage initialization process:

1. **[`apps/server/src/server.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/server.ts)** instantiates a `Route[]` collection and passes it to domain-specific registration functions.
2. **Route modules** (e.g., [`workspaces.ts`](https://github.com/different-ai/openwork/blob/main/workspaces.ts), [`sessions.ts`](https://github.com/different-ai/openwork/blob/main/sessions.ts)) import this array and invoke `addRoute(routes, METHOD, PATH, "host", handler)` for each endpoint.
3. **[`apps/server/src/routes/registry.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/registry.ts)** provides the `addRoute` utility and `Route` type definition, which the server mounts on the underlying Hono-compatible HTTP framework.

This design keeps routing logic encapsulated by feature while maintaining a single, type-safe registry of all available endpoints.

## Core Route Modules

All public API endpoints live in `*.ts` files inside `apps/server/src/routes/`. Each module encapsulates a specific domain:

### Workspace Management

**File:** [`apps/server/src/routes/workspaces.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/workspaces.ts)

Handles local and remote workspace lifecycle operations:

- `POST /workspaces/local` – Create a local workspace
- `POST /workspaces/remote` – Connect a remote workspace
- `PATCH /workspaces/:id/display-name` – Rename a workspace
- `POST /workspaces/:id/activate` – Switch active workspace
- `DELETE /workspaces/:id` – Remove a workspace

### Session Control

**File:** [`apps/server/src/routes/sessions.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/sessions.ts)

Manages long-running session lifecycles:

- `POST /sessions` – Create new session
- `GET /sessions` – List active sessions
- `DELETE /sessions/:id` – Terminate specific session

### File Operations

**File:** [`apps/server/src/routes/files.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/files.ts)

Provides read/write access to workspace contents:

- `GET /files/*` – Download files
- `PUT /files/*` – Upload or update files
- `POST /files/*/diff` – Generate file diffs

### Operations and Tasks

**File:** [`apps/server/src/routes/operations.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/operations.ts)

Handles short-lived and long-running background tasks:

- `POST /operations/:id/cancel` – Cancel running operation

### Cloud MCP Gateway

**File:** [`apps/server/src/routes/cloud-mcp.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/cloud-mcp.ts)

Routes MCP (Model Context Protocol) requests to remote OpenWork services:

- `GET /cloud-mcp/*`
- `POST /cloud-mcp/*`

### Health and Metadata

**File:** [`apps/server/src/routes/core.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/core.ts)

Exposes system status endpoints:

- `GET /health` – Server health check
- `GET /info` – Server metadata

## The Registration Pattern

Endpoints are registered using the `addRoute` helper imported from [`registry.ts`](https://github.com/different-ai/openwork/blob/main/registry.ts). This pattern standardizes middleware injection, host validation, and response formatting across the API.

Here is the typical registration pattern from [`apps/server/src/routes/workspaces.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/workspaces.ts):

```typescript
addRoute(routes, "POST", "/workspaces/local", "host", async (ctx) => {
  ensureWritable(config);
  const body = await readJsonBody(ctx.request);
  const folderPath = typeof body.folderPath === "string" ? body.folderPath.trim() : "";
  // …validation & workspace creation…
  const persisted = await persistServerWorkspaceState(config);
  onWorkspacesChanged();
  return jsonResponse({ activeId: workspace.id, workspaces: config.workspaces.map(serializeWorkspace), persisted }, 201);
});

```

Key components of this pattern:

- **`addRoute`** – Registers the HTTP method, path, and handler with the central route array
- **`"host"`** – Specifies the host context requirement for the route
- **`ensureWritable`** – Middleware guard preventing modifications in read-only mode
- **`jsonResponse`** – Utility formatting JSON responses with proper status codes

## Complete API File Reference

For developers navigating the codebase, here are the definitive locations where OpenWork API endpoints are defined:

- **Route Registry** – [`apps/server/src/routes/registry.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/registry.ts) – Defines `addRoute` and the `Route` interface
- **Server Bootstrap** – [`apps/server/src/server.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/server.ts) – Imports route modules and starts the HTTP listener
- **Workspace API** – [`apps/server/src/routes/workspaces.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/workspaces.ts) – Workspace CRUD and activation
- **Session API** – [`apps/server/src/routes/sessions.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/sessions.ts) – Session lifecycle management
- **File API** – [`apps/server/src/routes/files.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/files.ts) – File system operations
- **Operations API** – [`apps/server/src/routes/operations.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/operations.ts) – Task cancellation and status
- **Cloud MCP** – [`apps/server/src/routes/cloud-mcp.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/cloud-mcp.ts) – Remote service gateway
- **Core API** – [`apps/server/src/routes/core.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/core.ts) – Health and info endpoints
- **OpenAPI Spec** – [`packages/docs/openapi.json`](https://github.com/different-ai/openwork/blob/main/packages/docs/openapi.json) – Generated specification documenting all endpoints

## Summary

- OpenWork API endpoints are defined in TypeScript modules under `apps/server/src/routes/`
- The `addRoute` helper in [`apps/server/src/routes/registry.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/routes/registry.ts) provides the registration mechanism used by all route modules
- [`apps/server/src/server.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/server.ts) orchestrates the initialization by importing route functions and mounting them on the Hono-compatible server
- Domain-specific logic is split across files: [`workspaces.ts`](https://github.com/different-ai/openwork/blob/main/workspaces.ts), [`sessions.ts`](https://github.com/different-ai/openwork/blob/main/sessions.ts), [`files.ts`](https://github.com/different-ai/openwork/blob/main/files.ts), [`operations.ts`](https://github.com/different-ai/openwork/blob/main/operations.ts), [`cloud-mcp.ts`](https://github.com/different-ai/openwork/blob/main/cloud-mcp.ts), and [`core.ts`](https://github.com/different-ai/openwork/blob/main/core.ts)
- The generated OpenAPI specification is available at [`packages/docs/openapi.json`](https://github.com/different-ai/openwork/blob/main/packages/docs/openapi.json)

## Frequently Asked Questions

### How do I add a new API endpoint to OpenWork?

Create a new route handler in the appropriate module under `apps/server/src/routes/` (or create a new module if needed), then call `addRoute(routes, "METHOD", "/path", "host", async (ctx) => { ... })`. Import your registration function in [`apps/server/src/server.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/server.ts) and invoke it with the routes array before starting the server.

### What HTTP framework does OpenWork use for routing?

OpenWork uses a lightweight, Hono-compatible HTTP framework. The `addRoute` abstraction in [`registry.ts`](https://github.com/different-ai/openwork/blob/main/registry.ts) decouples the route definitions from the underlying framework, allowing the server to mount routes using Hono-style patterns while keeping endpoint definitions framework-agnostic.

### Where is the OpenAPI specification for OpenWork generated?

The OpenAPI specification is generated and stored at [`packages/docs/openapi.json`](https://github.com/different-ai/openwork/blob/main/packages/docs/openapi.json). This file documents all registered endpoints, their request/response schemas, and available HTTP methods based on the route definitions in `apps/server/src/routes/`.

### How does OpenWork handle read-only mode for file operations?

The `ensureWritable(config)` helper is called at the start of mutation endpoints (like `POST /workspaces/local`) to validate that the server configuration permits write operations. If the server is in read-only mode, this guard throws an error before any state changes occur.