Where Are the API Endpoints Defined in OpenWork?

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.

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 instantiates a Route[] collection and passes it to domain-specific registration functions.
2. Route modules (e.g., workspaces.ts, sessions.ts) import this array and invoke addRoute(routes, METHOD, PATH, "host", handler) for each endpoint.
3. 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

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

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

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

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

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

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. 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:

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 – Defines addRoute and the Route interface
• Server Bootstrap – apps/server/src/server.ts – Imports route modules and starts the HTTP listener
• Workspace API – apps/server/src/routes/workspaces.ts – Workspace CRUD and activation
• Session API – apps/server/src/routes/sessions.ts – Session lifecycle management
• File API – apps/server/src/routes/files.ts – File system operations
• Operations API – apps/server/src/routes/operations.ts – Task cancellation and status
• Cloud MCP – apps/server/src/routes/cloud-mcp.ts – Remote service gateway
• Core API – apps/server/src/routes/core.ts – Health and info endpoints
• OpenAPI Spec – 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 provides the registration mechanism used by all route modules
• 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, sessions.ts, files.ts, operations.ts, cloud-mcp.ts, and core.ts
• The generated OpenAPI specification is available at 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 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 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. 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.

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