OpenMAIC API Route Handlers: Complete Directory Guide and Usage Examples

OpenMAIC exposes all API route handlers under the app/api/ directory using Next.js App Router, with each 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 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 – 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 – Monitors runner status and execution environment
• 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 – 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 – 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 – Streaming outline generation
• app/api/generate/scene-content/route.ts – Generates slide content and educational text
• app/api/generate/image/route.ts – Image generation handlers
• app/api/generate/tts/route.ts – Text-to-speech audio generation
• app/api/generate/video/route.ts – Video synthesis endpoints

Utility and Health Checks

System maintenance routes:

• app/api/health/route.ts – Simple health-check endpoint for monitoring
• app/api/verify-model/route.ts – Validates AI model configuration before deployment
• app/api/server-providers/route.ts – Server-side provider configuration management
• 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:

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:

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:

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:

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:

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

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