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

# AI actions

> Five bounded generation helpers for objectives, activities, outcomes, rubrics and questions.

Five named, bounded helpers that generate a short list from unit context. Each
call names one `actionType`; there is no free-form prompt field.

> [!WARNING]
>
> These are **not** general rewrite operations. There is no shorten, expand or
> retone action — the five below are the complete set, and any other value is
> rejected with a 400.

## Actions

| `actionType` | Produces |
| - | - |
| `generate_objectives` | Learning objectives for a lesson, using Bloom's taxonomy verbs. |
| `suggest_activities` | Classroom activities that fit the unit and year group. |
| `enhance_outcomes` | Sharper phrasing for existing learning outcomes. |
| `create_rubric` | Rubric criteria for the unit. |
| `generate_questions` | Assessment questions. |

## Request

**actionType** `string` *required*

One of the five values above.

**context** `object` *required*

**properties**

**unitData** `object`

`title`, `subject`, `topic`, `yearGroup` and `learningOutcomes`
(`string[]`). Every field is optional — the prompt is built from whatever
is present.

**additionalData** `object`

Lesson-level context: `lessonId`, `lessonTitle`, `lessonNumber`,
`existingObjectives` and `existingActivities`. Supply the existing lists when
you want suggestions that don't duplicate what the teacher already has.

```bash cURL theme={null}
curl -X POST "$BASE_URL/ai-actions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "actionType": "generate_objectives",
        "context": {
          "unitData": {
            "subject": "Science",
            "topic": "Photosynthesis",
            "yearGroup": "2nd Year"
          }
        },
        "additionalData": { "lessonTitle": "Light and chlorophyll" }
      }'
```

## Response

**success** `boolean`

`true` when the action ran.

**content** `string`

The raw model output, as markdown.

**structuredContent** `object`

The same output parsed into a list: `type` (echoes `actionType`), `items`
(`string[]`), and `metadata` carrying `generatedAt` and `itemCount`.

```json Response theme={null}
{
  "success": true,
  "content": "- Describe the role of chlorophyll...\n- Explain how light intensity...",
  "structuredContent": {
    "type": "generate_objectives",
    "items": [
      "Describe the role of chlorophyll in photosynthesis",
      "Explain how light intensity affects the rate of reaction"
    ],
    "metadata": { "generatedAt": "2026-08-21T12:00:00.000Z", "itemCount": 2 }
  }
}
```

> [!NOTE]
>
> `items` is derived by parsing bullets and numbered lines out of `content`. When
> nothing parses as a list, `items` falls back to a single element holding the
> whole of `content` — so it is never empty, but it is not always a list. Read
> `metadata.itemCount` to tell the two cases apart: a real list has
> `itemCount > 0`, the fallback reports `0`.

> [!NOTE]
>
> Runs on `gpt-4o-mini` at `temperature` 0.7, capped at 2000 output tokens —
> a different provider from the planning capabilities, which go to the Vertex
> agents. Long inputs are not chunked; they are truncated by that cap.


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