# How Is the API Structured in HollaOS? Server, Routes, and SDK Explained > Explore the HollaOS API structure. Understand its Fastify-based RESTful API, route organization under /api/v1/, and the typed TypeScript SDK for seamless integration. - Repository: [holaboss.ai/holaOS](https://github.com/holaboss-ai/holaOS) - Tags: api-reference - Published: 2026-08-15 --- **HollaOS exposes a RESTful HTTP API built on Fastify with all routes mounted under `/api/v1/`, organized by domain (workspaces, sessions, memory, integrations, apps), and consumed through a typed TypeScript SDK.** The **HollaOS API structure** follows a clean separation between server-side route handlers and a client-side SDK. According to the holaboss-ai/holaOS source code, the runtime functionality is delivered through a Fastify-based HTTP layer with domain-specific routers and a matching TypeScript client that abstracts network details. --- ## Server Architecture: Fastify Foundation The API server launches from [`runtime/api-server/src/index.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/index.ts), which delegates instance creation to `buildRuntimeApiServer` in [`runtime/api-server/src/app.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/app.ts). This function wires all domain routers, configures **Pino logging**, and attaches the `apiError` middleware for normalized error responses. All endpoints share the base path **`/api/v1/`** and are grouped by functional domain. Each domain has a dedicated router module that registers HTTP verbs and validation schemas. ### Domain Organization | Domain | Router File | Key Endpoints | |--------|-------------|---------------| | **Workspaces** | `runtime/api-server/src/workspace-*.ts` (implied) | `GET /workspaces`, `POST /workspaces`, `PATCH /workspaces/:id`, `POST /workspaces/:id/activate` | | **Sessions** | [`runtime/api-server/src/workspace-sessions.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-sessions.ts) | `GET /sessions`, `POST /sessions`, `PATCH /sessions/:id`, `DELETE /sessions/:id` | | **Memory** | [`runtime/api-server/src/workspace-memory.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-memory.ts) | `GET /memory/:workspaceId`, `POST /memory/:workspaceId`, `PATCH /memory/:workspaceId/:nodeId` | | **Integrations** | [`runtime/api-server/src/workspace-integrations.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-integrations.ts) (implied) | `GET /integrations`, `POST /integrations`, `PATCH /integrations/:id`, `DELETE /integrations/:id` | | **Apps** | [`runtime/api-server/src/workspace-apps.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-apps.ts) | `GET /apps`, `POST /apps/ensure-running` | Route handlers delegate to **service classes** that interact with the state store. Error handling and fatal-error recovery are centralized in the server entry point. --- ## Route Implementation Example The apps domain demonstrates the registration pattern used across all modules: ```typescript // runtime/api-server/src/workspace-apps.ts export function registerWorkspaceAppsRoutes(app: FastifyInstance) { app.get("/api/v1/apps", listAppsHandler); app.post( "/api/v1/apps/ensure-running", { schema: { body: ensureRunningSchema }, timeout: 300_000, }, ensureAppsRunningHandler, ); } ``` Each route specifies: - **HTTP verb and path** (prefixed with `/api/v1/`) - **Validation schema** for request bodies - **Timeout configuration** (300 seconds for long-running app startup) - **Handler function** implementing business logic --- ## Client SDK: Typed Abstraction Layer The **TypeScript SDK** (`packages/runtime-client`) mirrors the server structure with method groups that correspond to each API domain. The core request factory in [`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts) handles base URL resolution, JSON serialization, retries, and timeouts. ### SDK Method Factory Pattern Each domain exports a factory function that builds typed methods: ```typescript // Example: workspaces.ts (client) export function makeWorkspacesMethods(request: RequestFn): WorkspacesMethods { return { list(params) { /* GET /api/v1/workspaces */ }, get(id) { /* GET /api/v1/workspaces/:id */ }, create(payload) { /* POST /api/v1/workspaces */ }, update(id, payload) { /* PATCH /api/v1/workspaces/:id */ }, delete(id, options) { /* DELETE /api/v1/workspaces/:id */ }, activate(id) { /* POST /api/v1/workspaces/:id/activate */ }, ensureAppsRunning(id) { /* POST /api/v1/apps/ensure-running */ }, }; } ``` All method groups are composed in [`packages/runtime-client/src/index.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/index.ts) and exposed through a single entry point: ```typescript import { createRuntimeClient } from "@/packages/runtime-client"; const client = createRuntimeClient("http://localhost:3060"); ``` --- ## Practical SDK Usage ### Creating a Workspace ```typescript await client.workspaces.create({ name: "Demo Workspace", harness: "default", status: "active", onboarding_status: "pending", }); ``` ### Listing Sessions ```typescript const { items: sessions } = await client.sessions.list({ limit: 20 }); console.log("Running sessions:", sessions); ``` ### Activating a Workspace ```typescript await client.workspaces.activate("workspace-abc123"); ``` --- ## Running the API Server ```bash # Start the runtime API (listening on 127.0.0.1:3060 by default) node runtime/api-server/src/index.js ``` Graceful shutdown and fatal error handling are implemented directly in the entry point. --- ## Key Source Files | Path | Purpose | |------|---------| | [`runtime/api-server/src/index.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/index.ts) | Server entry point, graceful shutdown wiring | | [`runtime/api-server/src/app.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/app.ts) | Fastify instance builder, router registration | | [`runtime/api-server/src/workspace-apps.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-apps.ts) | Apps domain routes | | [`runtime/api-server/src/workspace-sessions.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-sessions.ts) | Sessions domain routes | | [`runtime/api-server/src/workspace-memory.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/workspace-memory.ts) | Memory domain routes | | [`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts) | HTTP abstraction with retry/timeout | | [`packages/runtime-client/src/methods/workspaces.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/methods/workspaces.ts) | Workspace client methods | | [`packages/runtime-client/src/methods/sessions.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/methods/sessions.ts) | Session client methods | | [`packages/runtime-client/src/methods/memory.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/methods/memory.ts) | Memory client methods | | [`packages/runtime-client/src/methods/integrations.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/methods/integrations.ts) | Integration client methods | | [`packages/runtime-client/src/index.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/index.ts) | Public SDK export (`createRuntimeClient`) | --- ## Summary - **HollaOS API structure** uses **Fastify** as the HTTP framework with all routes under `/api/v1/` - Domains (workspaces, sessions, memory, integrations, apps) each have **dedicated router modules** - **Route handlers** delegate to service classes; **errors** are normalized via middleware - The **TypeScript SDK** (`packages/runtime-client`) provides fully typed, ergonomic client methods - **Factory functions** generate domain-specific method groups that mirror server routes - Versioning under `/api/v1/` supports future API evolution without breaking changes --- ## Frequently Asked Questions ### What HTTP framework does HollaOS use for its API? HollaOS uses **Fastify** as its HTTP framework. The server instance is created by `buildRuntimeApiServer` in [`runtime/api-server/src/app.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/api-server/src/app.ts), which configures routing, logging with Pino, and error handling middleware. ### How is the HollaOS API versioned? All routes are prefixed with **`/api/v1/`**, establishing a clear versioning boundary. This allows future API versions to be introduced under `/api/v2/` without disrupting existing integrations. ### What domains does the HollaOS API cover? The API spans six primary domains: **Workspaces** (environment management), **Sessions** (execution contexts), **Memory** (semantic storage), **Integrations** (external service connectors), **Apps** (application lifecycle), and **Cronjobs/Tools** (background job scheduling). ### How does the TypeScript SDK handle HTTP details? The SDK centralizes HTTP concerns in [`packages/runtime-client/src/request.ts`](https://github.com/holaboss-ai/holaOS/blob/main/packages/runtime-client/src/request.ts), which manages base URL resolution, JSON parsing, automatic retries, and configurable timeouts. Domain-specific modules like [`workspaces.ts`](https://github.com/holaboss-ai/holaOS/blob/main/workspaces.ts) and [`sessions.ts`](https://github.com/holaboss-ai/holaOS/blob/main/sessions.ts) provide typed methods that consumers call directly.