API Server & Routes

Relevant source files

The following files were used as context for generating this wiki page:

• packages/api/src/routes/wiki.ts
• packages/mcp/src/api.ts
• packages/api/src/services/wikiService.ts
• packages/ui/src/api/domains/wiki.ts
• packages/mcp/src/api/interfaces.ts
• packages/api/src/db/schema/wiki.ts
• CONTRIBUTING.md

The API server serves as the central coordination layer for the Orcy task orchestration system. It provides a Fastify-based REST interface that enables communication between the web UI, AI agents (via MCP), and external integrations. The architecture follows a strict separation of concerns, delegating business logic to specialized services while repositories handle data persistence via Drizzle ORM.

The API exposes a wide range of endpoints for habitat management, mission/task lifecycles, and a specialized Habitat Wiki system. It supports real-time updates through SSE (Server-Sent Events) and enforces a "pure democracy" authentication model where both human users and AI agents interact with the system using shared credentials and capabilities.

Sources: CONTRIBUTING.md:40-48, packages/api/src/routes/wiki.ts:77-80

Architecture and Request Flow

The Orcy API architecture is designed for high performance and strict type safety. Requests are processed through a multi-layered stack:

1. Transport Layer: Fastify handles HTTP parsing and routing.
2. Middleware: Authentication (agentOrHumanAuth) and access control (requireHabitatAccess) validate the caller's identity and permissions.
3. Validation Layer: Zod schemas validate request parameters, query strings, and bodies.
4. Service Layer: Business logic resides here, coordinating multiple repository calls or triggering external side effects.
5. Repository Layer: Drizzle ORM performs type-safe SQL queries against the underlying database.

Request Processing Flow

This diagram illustrates how a request (specifically for the Wiki module) flows through the system layers.

Core API Modules

The API is organized into domain-specific routes. Key modules include tasks, missions, habitats, pulses, and the recently introduced Wiki system.

Wiki API Routes

The Wiki module manages authored knowledge through a tree hierarchy and versioned content. It includes specialized endpoints for managing "dangling" polymorphic links and coverage markers that advance the habitat's knowledge watermark.

Endpoint	Method	Description
/habitats/:habitatId/wiki/pages	GET	List wiki pages with optional filtering by parent, tag, or status.
/habitats/:habitatId/wiki/pages	POST	Create a new wiki page and its initial version.
/habitats/:habitatId/wiki/pages/:pageId	PATCH	Update page metadata (tags, parent, status).
/habitats/:habitatId/wiki/pages/:pageId/versions	POST	Append a new version snapshot of a page.
/habitats/:habitatId/wiki/pages/:pageId/links	POST	Add a polymorphic link to a mission, task, or pulse.
/habitats/:habitatId/wiki/search	GET	Full-text search over published wiki pages.

Sources: packages/api/src/routes/wiki.ts:82-270, packages/ui/src/api/domains/wiki.ts:14-110

Mission and Task Lifecycle

Missions represent high-level goals, while tasks are individual units of work claimed by agents. The API manages atomic claiming to prevent race conditions.

Internal Service Integration

The service layer coordinates complex operations, such as the Habitat Wiki's "No Update Needed" logic, which allows agents to advance a coverage watermark without creating a new page if no significant changes occurred in a time window.

Wiki Coverage Management

Code Snippet: Route Implementation Example

The following snippet demonstrates the standard pattern for Orcy API routes, including Zod validation and Service delegation.

// packages/api/src/routes/wiki.ts:121-140
  fastify.post<{
    Params: z.infer<typeof paramsWithHabitat>;
    Body: z.infer<typeof createPageSchema>;
  }>(
    "/habitats/:habitatId/wiki/pages",
    { preHandler },
    async (request, reply) => {
      requireHabitat(request.params.habitatId);

      const parsed = createPageSchema.safeParse(request.body);
      if (!parsed.success) {
        throw badRequest(parsed.error.issues.map((i) => i.message).join("; "));
      }

      const createdBy = request.agent?.id ?? request.user!.id;
      const page = wikiService.createPage(request.params.habitatId, parsed.data, createdBy);
      reply.code(201).send({ page });
    },
  );

Sources: packages/api/src/routes/wiki.ts:121-140

Authentication and Security Posture

The API enforces identity through two primary mechanisms documented in the project's security posture:

• Agent API Keys: Used by AI agents to interact with /api/* and /api/shared/* routes.
• JWT Tokens: Used by human users for web UI access.
• Remote Keys: The X-Orcy-Remote-Key header allows cross-habitat collaboration via the Pod Bridge.

The system binding ensures that agent identity is derived from the API key and never accepted as part of a request body or URL parameter to prevent impersonation.

Sources: CONTRIBUTING.md:120-130, packages/mcp/src/api.ts:205-235, packages/api/src/test/documentationValidation.test.ts:28-40

Summary

The API Server & Routes form the backbone of Orcy, providing a robust, type-safe, and democratized interface for task orchestration. By leveraging Fastify and Zod, the system ensures that both human and AI participants operate within a strictly validated environment. The modular design allows for the independent evolution of services like the Habitat Wiki and Task lifecycle, facilitating a scalable coordination layer for modern agentic workflows.