# OpenMAIC API Route Handlers: Complete Directory Guide and Usage Examples

> Discover OpenMAIC API route handlers in the app api directory. This guide shows usage examples for each route.ts file mapping to HTTP endpoints via folder path.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: api-reference
- Published: 2026-08-30

---

**OpenMAIC exposes all API route handlers under the `app/api/` directory using Next.js App Router, with each [`route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/route.ts) file mapping to a specific HTTP endpoint based on its folder path.**

OpenMAIC is a Next.js-based educational AI platform that organizes its server-side logic through the App Router convention. The **API route handlers** are implemented as TypeScript files following Next.js 13+ standards, where the directory structure directly determines the URL path structure.

## Directory Structure and Routing Conventions

OpenMAIC leverages the **Next.js App Router** pattern where any file named [`route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/route.ts) inside `app/api/` automatically becomes an HTTP endpoint. The subfolder hierarchy maps directly to the URL path, and dynamic segments use bracket notation like `[id]`.

For example, the file at `app/api/agent/sessions/[id]/route.ts` handles requests at `/api/agent/sessions/:id`. This convention applies across all features, from agent management to content generation.

## Core API Route Handler Groups

### Agent Workbench (`app/api/agent/`)

The agent system routes handle session lifecycle and runtime control:

- **[`app/api/agent/sessions/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/agent/sessions/route.ts)** – Creates new agent sessions via POST requests
- **`app/api/agent/sessions/[id]/route.ts`** – Retrieves session details, status, and message history  
- **[`app/api/agent/runtime/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/agent/runtime/route.ts)** – Monitors runner status and execution environment
- **[`app/api/agent/skills/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/agent/skills/route.ts)** – Manages available agent capabilities and skill registration

### Stage Management (`app/api/stages/`)

Course content (stages) operations are centralized here:

- **[`app/api/stages/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/stages/route.ts)** – Lists and creates educational stages
- **`app/api/stages/[id]/route.ts`** – Handles CRUD operations, publishing, and manifest retrieval for individual stages
- **`app/api/stages/[id]/scenes/route.ts`** – Manages scene sequences (slides, quizzes) within a specific stage

### Material Processing (`app/api/materials/`)

Upload and extraction pipelines:

- **[`app/api/materials/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/materials/route.ts)** – Accepts file uploads for course materials
- **`app/api/materials/[id]/route.ts`** – Retrieves or deletes specific materials and triggers content extraction

### Generation Pipeline (`app/api/generate/`)

AI content creation endpoints:

- **[`app/api/generate/scene-outlines-stream/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/generate/scene-outlines-stream/route.ts)** – Streaming outline generation
- **[`app/api/generate/scene-content/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/generate/scene-content/route.ts)** – Generates slide content and educational text
- **[`app/api/generate/image/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/generate/image/route.ts)** – Image generation handlers
- **[`app/api/generate/tts/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/generate/tts/route.ts)** – Text-to-speech audio generation
- **[`app/api/generate/video/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/generate/video/route.ts)** – Video synthesis endpoints

### Utility and Health Checks

System maintenance routes:

- **[`app/api/health/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/health/route.ts)** – Simple health-check endpoint for monitoring
- **[`app/api/verify-model/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/verify-model/route.ts)** – Validates AI model configuration before deployment
- **[`app/api/server-providers/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/server-providers/route.ts)** – Server-side provider configuration management
- **[`app/api/access-code/verify/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/access-code/verify/route.ts)** – Access code validation for site-wide protection

## Dynamic Route Parameters

OpenMAIC uses Next.js dynamic route segments for resource-specific operations. Files located in directories named `[id]` or `[...path]` catch variable URL segments.

For instance, `app/api/persistence/[...path]/route.ts` implements catch-all routing for the swappable storage layer façade, while `app/api/stages/[id]/scenes/route.ts` handles scene operations for a specific stage ID.

## Practical Usage Examples

Below are minimal client implementations using standard fetch API to interact with the OpenMAIC **API route handlers**.

Create a new agent session:

```typescript
async function createAgentSession() {
  const resp = await fetch('/api/agent/sessions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ownerId: 'user-123' })
  });
  return await resp.json(); // => { sessionId: "...", status: "running", ... }
}

```

Upload course materials:

```typescript
async function uploadMaterial(file: File) {
  const form = new FormData();
  form.append('file', file);
  const resp = await fetch('/api/materials', { method: 'POST', body: form });
  return await resp.json(); // => material metadata
}

```

Generate scene content:

```typescript
async function generateSceneContent(stageId: string, sceneId: string, outline: any) {
  const resp = await fetch('/api/generate/scene-content', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ stageId, sceneId, outline })
  });
  return await resp.json();
}

```

Retrieve stage manifest:

```typescript
async function getStageManifest(stageId: string) {
  const resp = await fetch(`/api/stages/${stageId}/manifest`);
  return await resp.json(); // => { id, title, scenes: [...], freshness: … }
}

```

Cancel running agent session:

```typescript
async function cancelAgentSession(sessionId: string) {
  await fetch(`/api/agent/sessions/${sessionId}/cancel`, { method: 'POST' });
}

```

## Project-Based Learning Routes

The PBL v2 functionality resides under `app/api/pbl/v2/`, with specific handlers like [`app/api/pbl/v2/task/update/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/pbl/v2/task/update/route.ts) managing task state updates and instructor communications. These routes support the simulation and collaborative features specific to project-based learning modules.

## Summary

- OpenMAIC organizes all **API route handlers** under the `app/api/` directory following Next.js App Router conventions
- Each [`route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/route.ts) file corresponds to an HTTP endpoint, with folder paths mapping directly to URL routes
- Dynamic parameters use bracket notation, such as `[id]` for resource-specific operations
- Major functional groups include agent management (`app/api/agent/`), stage/course handling (`app/api/stages/`), material processing (`app/api/materials/`), and AI generation (`app/api/generate/`)
- Utility endpoints for health checks, model verification, and access control reside alongside business logic routes

## Frequently Asked Questions

### What file naming convention does OpenMAIC use for API routes?

OpenMAIC follows the Next.js App Router convention where files must be named exactly [`route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/route.ts) to be recognized as **API route handlers**. This file must reside within a subdirectory of `app/api/`, and the folder structure determines the final URL path.

### How do dynamic route parameters work in OpenMAIC?

Dynamic segments are defined using square brackets in the directory name. For example, `app/api/stages/[id]/route.ts` handles URLs like `/api/stages/123`, where `123` becomes the `id` parameter. Catch-all routes use `[...path]` syntax, such as in `app/api/persistence/[...path]/route.ts`, which matches any number of path segments.

### Where is the health check endpoint located?

The health check endpoint is implemented in [`app/api/health/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/health/route.ts). This route provides a simple status response used for deployment monitoring and load balancer health verification.

### How can I verify if a specific API feature is enabled?

Check the feature flags in your `.env` configuration file (e.g., `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED`). If a specific **API route handler** returns a 404 status, verify that the corresponding environment variable is set to enable that feature module, as OpenMAIC conditionally exposes routes based on these configuration flags.