> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesolab.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Unit planning

> Turn curriculum learning outcomes into a sequenced unit plan.

Generates a full unit of learning: sequenced lessons, curriculum mapping against
learning outcomes, Bloom's taxonomy classification, and assessment milestones.

## Request

**subject** `string` *required*

Curriculum subject, e.g. `"Science"`.

**topic** `string` *required*

The unit topic, e.g. `"Photosynthesis"`.

**learningOutcomes** `string[]` *required*

Specification codes for the outcomes this unit covers, e.g. `["1.1", "1.5"]`.

**yearGroup** `string` *required*

Post-primary year, `"1"` through `"6"`.

**lessonsCount** `number` *required*

How many lessons the unit should span.

**assessment** `object` *required*

**properties**

**method** `string` *required*

How learning is assessed.

**timing** `string` *required*

When assessment occurs.

**category** `string` *required*

Formative, summative, and so on.

**lessonLength** `number` (default: 60)

Lesson length in minutes.

**additionalConstraints** `string`

Free-text constraints — available equipment, prior knowledge, access needs.

**mode** `string` (default: fast)

`"fast"` runs the single-pass flow. `"detailed"` runs the slower multi-agent
flow surfaced in the product as **MESO Think**.

## Response

**curriculumMapping** `object[]`

One entry per mapped outcome, carrying `active_verb`, `learning_outcome`,
`lesson_implementation`, `bloom_domain`, `bloom_taxonomy_level` and
`assessment`.

**lessons** `object[]`

Sequenced lesson entries, each numbered by `lesson_number`.

**assessmentMilestones** `object[]`

Milestones with a `milestone_number`, a `description`, and the `lessons` array
they span.

```bash cURL theme={null}
curl -X POST "$BASE_URL/unit-planning" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Science",
    "topic": "Photosynthesis",
    "learningOutcomes": ["1.1", "1.5"],
    "yearGroup": "2",
    "lessonsCount": 6,
    "assessment": {
      "method": "Investigation",
      "timing": "End of unit",
      "category": "Formative"
    },
    "lessonLength": 40,
    "mode": "fast"
  }'
```

> [!WARNING]
>
> The persisted unit plan is stored on the `units` table in the `unit_plan`
> column. Several older integrations assume a differently named column — check
> against the live schema before writing a reader.

## Sessions

Unit planning is the only capability with a session concept. `POST /create`
returns a `sessionId`, and `GET /session` reads it back.

> [!WARNING]
>
> **Sessions are held in memory, in the serving isolate.** They are not persisted
> to the database and are not shared between isolates. A worker recycle, a cold
> start, or a request landing on a different isolate loses the session — and
> Supabase gives no guarantee that two consecutive calls hit the same one.
>
> Treat `sessionId` as a best-effort convenience within a single burst of
> activity. Anything that must survive belongs in `units`, written by the client.

## Sub-paths

Besides the generation call, the handler answers:

| Path | Purpose |
| - | - |
| `GET /health` | Liveness. |
| `GET /debug` | Reports the resolved agent and whether credentials are configured. Echoes no secret values. |
| `GET /session` | Reads back a session, subject to the caveat above. |

The generation call accepts three body shapes: an explicit `/create` path, a
wrapped `{ "inputs": { ... } }`, or a flat body carrying `subject`. All three
are equivalent.

> [!NOTE]
>
> `usage.provider` reads `"vertex-agent"`. The TypeScript type still declares
> `"bedrock"` — the type lags the running code, which moved to the Vertex agents
> on 2026-08-18. Trust the response, not the type.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.