# Project-Based Learning (PBL) Endpoints in OpenMAIC: Complete API Reference

> Explore OpenMAIC's Project-Based Learning PBL endpoints in this complete API reference. Discover how to manage mutations, simulations, tasks, and evaluations for PBL workflows.

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

---

**OpenMAIC exposes five stateless HTTP endpoints under `/api/pbl/v2` that handle project mutations, simulations, task retrieval, instructor actions, and final evaluations for Project-Based Learning workflows.**

The OpenMAIC repository implements its Project-Based Learning (PBL) system as a deterministic, server-side API architecture. All PBL functionality is accessible through dedicated routes that process `PBLProjectV2` objects and return mutated states to the client without maintaining server-side session data.

## API Architecture and Design Principles

The PBL endpoints follow a strict **stateless handler pattern** located in the `app/api/pbl/v2` directory. Each route acts as a thin wrapper that accepts a JSON payload, performs pure deterministic operations on the provided project object, and returns the result via standardized `apiSuccess` or `apiError` helpers.

Key architectural constraints include:

- **Pure functions**: Endpoints never invoke LLMs directly; all logic is deterministic
- **Client-side persistence**: The caller must store the returned `PBLProjectV2` and resend it on subsequent requests
- **Standardized contracts**: Every endpoint expects a `project` field in the request body and returns a consistent response shape

## The Five Core PBL Endpoints

### Task State Management (`/api/pbl/v2/task/update`)

The `POST /api/pbl/v2/task/update` endpoint serves as the primary workspace UI state mutator. Implemented in [`app/api/pbl/v2/task/update/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/pbl/v2/task/update/route.ts), this route handles micro-task lifecycle transitions through specific action types.

Supported operations include:
- **`start`**: Invokes `startMicrotask` to begin a new micro-task
- **`continue_handover`**: Triggers `continueAfterHandover` for milestone transitions
- **`complete_pending_task`**: Executes `advanceMicrotask` to finish active tasks
- **`enter_scenario`**: Prepares the project state for scene entry
- **`complete_act`**: Calls `completeRoleplayAct` to finalize role-play segments

### Project Simulation (`/api/pbl/v2/simulator`)

Located at [`app/api/pbl/v2/simulator/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/pbl/v2/simulator/route.ts), this `POST` endpoint runs deterministic simulations of PBL projects. It enables "preview" or "dry-run" functionality by invoking the simulator agent to generate a `PBLProjectV2` snapshot without actual LLM involvement, allowing clients to validate project flow before deployment.

### Task Retrieval (`/api/pbl/v2/open-task`)

The `GET /api/pbl/v2/open-task` endpoint (file: [`app/api/pbl/v2/open-task/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/pbl/v2/open-task/route.ts)) retrieves the next available micro-task for a given project. It examines the active milestone structure and returns the associated task configuration used by the frontend to render the current UI state.

### Instructor Events (`/api/pbl/v2/instructor`)

Implemented in [`app/api/pbl/v2/instructor/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/pbl/v2/instructor/route.ts), this `POST` route processes instructor-driven interactions. It accepts events such as role-play dialogue or act completion signals, invokes the instructor agent to process these events, and applies the resulting state mutations to the project object.

### Final Evaluation (`/api/pbl/v2/evaluate`)

The evaluation endpoint at [`app/api/pbl/v2/evaluate/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/pbl/v2/evaluate/route.ts) performs comprehensive project assessment. This `POST` route calls the evaluator agent to score completed milestones and generate structured learner-visible feedback, returning a complete evaluation result object to the client.

## Client Integration and Code Examples

The following TypeScript patterns demonstrate how to interact with the OpenMAIC PBL endpoints from a client application:

```typescript
// Helper to POST JSON and parse responses
async function postPbl<T>(path: string, body: any): Promise<T> {
  const r = await fetch(path, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  if (!r.ok) throw new Error(`API error ${r.status}`);
  return r.json();
}

// Start a specific micro-task
await postPbl('/api/pbl/v2/task/update', {
  project,           // Current PBLProjectV2 object
  action: 'start',
  microtaskId: 'micro-42',
});

// Continue after handover
await postPbl('/api/pbl/v2/task/update', {
  project,
  action: 'continue_handover',
});

// Run simulator preview
await postPbl('/api/pbl/v2/simulator', { project });

// Retrieve current task
const { task } = await fetch('/api/pbl/v2/open-task?projectId=123')
  .then(r => r.json());

// Send instructor dialogue
await postPbl('/api/pbl/v2/instructor', {
  project,
  event: { type: 'speak', content: 'Hello!' },
});

// Evaluate completed project
await postPbl('/api/pbl/v2/evaluate', { project });

```

Supporting libraries in `lib/pbl/v2` (including `agents/` and `operations/` directories) provide the underlying logic consumed by these route handlers.

## Summary

- OpenMAIC implements **five primary PBL endpoints** under the `/api/pbl/v2` namespace
- All endpoints are **stateless** and require the client to persist the `PBLProjectV2` object between calls
- The **`/api/pbl/v2/task/update`** route handles all workspace UI mutations through deterministic operations like `startMicrotask` and `completeRoleplayAct`
- **Simulation, evaluation, and instructor actions** are handled by dedicated POST endpoints that process project objects without LLM latency
- Source files are organized under `app/api/pbl/v2/` with each route living in its own [`route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/route.ts) file

## Frequently Asked Questions

### What is the base path for all PBL endpoints in OpenMAIC?

All Project-Based Learning endpoints are mounted under **`/api/pbl/v2`**. This namespace contains the complete set of routes for task management, simulation, and evaluation.

### Are the OpenMAIC PBL endpoints stateless?

Yes. The endpoints are **completely stateless**; they do not maintain session data or server-side project storage. The client must include the full `PBLProjectV2` object in each request and handle persistence (typically in local storage or a database) between API calls.

### Do these endpoints make direct LLM calls?

No. The PBL endpoints perform **pure, deterministic operations** only. Any LLM interactions are handled by separate agent systems; these API routes strictly mutate the project state object through functions like `advanceMicrotask` and `continueAfterHandover` without non-deterministic processing.

### How do I retrieve the current micro-task for a project?

Use the **`GET /api/pbl/v2/open-task`** endpoint with a `projectId` query parameter. This route, defined in [`app/api/pbl/v2/open-task/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/pbl/v2/open-task/route.ts), inspects the project's milestone structure and returns the active micro-task configuration for UI rendering.