Skip to main content
The Lesson Plan Builder writes a class-ready lesson plan for a board, grade, subject, and topic: what to cover, what students should be able to do, which materials to use, and a minute-by-minute script for each stage of the period. It takes four calls, and a teacher can review and edit between each one. This guide is for developers. For a non-technical overview, see Lesson Plan Builder features.
Each call starts a background job. Wait until the job’s status is Completed before the next call. The wait_for helper below does this for you.

Set up

You need an access token. If you don’t have one, follow the Quickstart.
While a job is starting, the API returns 404 with a step not found message. A failed job returns 400 with "status": "Failed", except Get lesson plan content which returns 200 with "status": "Failed". wait_for handles all three.

Step 1: Start the lesson plan

Send the board, grade, and subject, how long the period is, and one source: a topic, up to four images, or one audio recording. The fields go in a form, not in JSON.
Get BOARD_ID, GRADE_ID, and SUBJECT_ID from List boards, List grades, and List subjects. They don’t change, so you can store them.
duration_minutes must be between 30 and 90. Send exactly one of topic, documents, or audio.
A teacher can remove items, or add their own to additional_recommendations.

Step 2: Finalize the metadata

Send subject_matter and learning_standards back, with any edits. You get the materials, the teaching strategies, and the six stages of the lesson with minutes for each.
The API adjusts the six duration values so they add up to duration_minutes, aiming to keep each stage at 5 minutes or more. The 5 minute floor is a target, not a rule the API enforces, so read the values rather than assuming a minimum.

Step 3: Build the lesson content

Send the alignment back, wrapped in an alignment key. Keep only the options the teacher chose. You get a script for every stage.
The six duration values must still add up to duration_minutes. If the teacher adds 5 minutes to one stage, take 5 off another.
Each stage has a components list. The summative_assessment stage comes back as assessment_block.
The stages are written in parallel, so they appear one at a time while status is still In Progress.

Step 4: Add enrichment blocks (optional)

Add extra sections to the finished plan, such as differentiation notes or real-life connections. Ask for all the blocks you want in one call: this step runs only once.
The six block keys come from List enrichment block options.
The response repeats the whole lesson plan and adds additional_blocks.

Good to know

Register a webhook for each step, then fetch the result when the event arrives. See Async jobs and webhooks.Every event fires for both outcomes, so read status in the payload: Completed or Failed.

Lesson Plan API reference

Every field, response, and error.

Lesson Plan Builder features

What the product does, without the code.

How the workflow runs

The same four steps, from a teacher’s side.

List lesson plans

Show a teacher’s lesson plan history.
Looking for classroom examples? See Lesson Plan Builder use cases.