Lesson drafts

One lesson or quiz written in full, ready for learners, from a title and what it should teach.

Price5 credits (50p) per draft
Typical time15 s to 2 min
Scopeauthoring:write
Runs asA background job

Try it

Run lesson drafts in the sandbox

No key and nothing to pay. The sandbox returns a realistic example in a couple of seconds; no AI runs and no data is kept.

Queued202 and a job id, straight away
ProcessingPoll, stream or wait for a webhook
SucceededResult and files on the job

Every AI request runs as a background job, so nothing times out.

A content lesson comes back as 4 to 8 varied editor blocks (an opening, key terms, tips and common mistakes, worked steps, tables and quick checks); a quiz as 4 to 6 multiple-choice questions with explanations. Add source_text or a document to ground the lesson in your material. Set save_to_lms to also save it in a new unpublished draft course in EduMark (the key needs courses:write).

Requires authoring:write. Costs 5 credits per draft. Send a unique Idempotency-Key; reuse it with the identical body when retrying. Returns 202 with a job: poll GET /jobs/{job_id}, stream GET /jobs/{job_id}/events, or use a signed webhook.

Lesson drafts

POST/v1/authoring/lessons

Scope authoring:write

Headers

Lesson drafts: headers
Field	Details
`Idempotency-Key`	stringRequiredA unique key per new operation; reuse it with the identical body when retrying.
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Request body

Lesson drafts: request body
Field	Details
`title`	stringRequiredThe lesson title, for example "Calculating a notice period".Up to 240 characters
`focus`	stringWhat the lesson should teach, in a sentence or two.Up to 2,000 charactersDefault `""`
`kind`	enumcontent: a lesson of varied blocks with quick checks. quiz: 4 to 6 multiple-choice questions.One of `content`, `quiz`Default `"content"`
`minutes`	integerHow long the lesson should take, in minutes.3 to 120Default `15`
`course_title`	string, optionalThe course this lesson belongs to, for context.Up to 200 characters
`module_title`	string, optionalThe module this lesson belongs to, for context.Up to 200 characters
`level`	string, optionalWho it is for, for example "GCSE (ages 14-16)" or "Workplace beginners".Up to 240 characters
`source_text`	string, optionalTeaching text to write from (at most 10,000 words).Up to 120,000 characters
`document`	FileReference or DocumentInput, optionalA PDF, DOCX or TXT to write from: `{"file_id"}` or inline base64.
`file_id`document.file_id	stringRequiredThe id returned by POST /v1/files, after POST /v1/files/{id}/complete reported ready.When sending FileReferencePattern `^file_[a-f0-9]{32}$`
`filename`document.filename	stringRequiredWhen sending DocumentInputUp to 200 characters
`base64`document.base64	stringRequiredWhen sending DocumentInputUp to 27,962,028 characters
`mime_type`document.mime_type	string, optionalWhen sending DocumentInputUp to 150 characters
`save_to_lms`	booleanAlso save the lesson in a new unpublished draft course in EduMark (needs the courses:write permission).Default `false`

Responses

Status	Meaning
202	Successful Response
400	Request rejected. Inspect error.code and request_id; failed work is not billed.
401	Request rejected. Inspect error.code and request_id; failed work is not billed.
402	Request rejected. Inspect error.code and request_id; failed work is not billed.
403	Request rejected. Inspect error.code and request_id; failed work is not billed.
404	Request rejected. Inspect error.code and request_id; failed work is not billed.
409	Request rejected. Inspect error.code and request_id; failed work is not billed.
410	Request rejected. Inspect error.code and request_id; failed work is not billed.
413	Request rejected. Inspect error.code and request_id; failed work is not billed.
415	Request rejected. Inspect error.code and request_id; failed work is not billed.
422	Validation Error
429	Request rejected. Inspect error.code and request_id; failed work is not billed.
503	Request rejected. Inspect error.code and request_id; failed work is not billed.

Request

curl -X POST 'https://api.edumark.ai/v1/authoring/lessons' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Calculating a notice period",
  "focus": "Work out statutory notice from length of service.",
  "level": "Workplace beginners",
  "course_title": "Employment law basics"
}'

# Then poll until the job finishes (wait poll_after_seconds between calls)
curl 'https://api.edumark.ai/v1/jobs/job_01JB7Q8M4X2V9R' \
  -H "Authorization: Bearer $EDUMARK_API_KEY"

Queued202 and a job id, straight away
ProcessingPoll, stream or wait for a webhook
SucceededResult and files on the job

Every AI request runs as a background job, so nothing times out.

Response 202JSON

{
  "id": "job_0123456789abcdef0123456789abcdef01234567",
  "product": "lesson_drafts",
  "status": "queued",
  "poll_after_seconds": 2,
  "credits": 5,
  "result_available": false
}

Finished job: resultJSON

{
  "status": "needs_review",
  "requires_review": true,
  "lesson": {
    "kind": "content",
    "title": "Calculating a notice period",
    "estimated_minutes": 15,
    "blocks": [
      {
        "kind": "page",
        "title": "What you will learn",
        "label": "Lesson aims",
        "body": "By the end of this lesson you can work out the statutory notice an employee is owed."
      },
      {
        "kind": "definition",
        "title": "Statutory notice",
        "term": "Statutory notice",
        "label": "Key term",
        "body": "The minimum notice the law requires an employer to give, based on how long the employee has worked."
      },
      {
        "kind": "steps",
        "title": "Work it out",
        "body": "",
        "label": "Worked example",
        "entries": [
          {
            "title": "Find the length of service",
            "body": "Count complete years worked: 6 years."
          },
          {
            "title": "Apply the rule",
            "body": "One week per complete year, up to 12 weeks: 6 weeks."
          }
        ]
      },
      {
        "kind": "callout",
        "title": "Common mistake",
        "tone": "warning",
        "label": "Common mistake",
        "body": "Contracts can give more notice than the law, never less."
      },
      {
        "kind": "question",
        "title": "Quick check",
        "body": "",
        "label": "Quick check",
        "prompt": "An employee has worked for 14 years. What statutory notice are they owed?",
        "mode": "single",
        "options": [
          {
            "text": "12 weeks",
            "correct": true,
            "feedback": "Right: the statutory maximum is 12 weeks."
          },
          {
            "text": "14 weeks",
            "correct": false,
            "feedback": "The statutory notice stops at 12 weeks."
          }
        ],
        "explanation": "One week per complete year of service, capped at 12 weeks."
      }
    ]
  },
  "lms_draft": null,
  "warnings": [],
  "notice": "This is an AI draft for a person to review. Nothing was published and learners cannot see it.",
  "provenance": {
    "engine": "edumark_aurora_lesson_writer",
    "grounded": false,
    "sandbox": true
  }
}