Course builds

A complete course, with every lesson and quiz written, from your brief and teaching material.

Price20 credits (£2.00) per course
Typical time60 s to 7 min
Scopeauthoring:write
Runs asA background job

Try it

Run course builds 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.

Aurora plans the course (2 to 6 modules, at most 20 lessons and quizzes), then writes every lesson as varied editor blocks (pages, key terms, tips, tables, worked steps and quick checks) and every quiz as multiple-choice questions. Lessons teach in Aurora's own words from your sources; with only a brief, Aurora uses accurate, mainstream knowledge. The result is portable JSON. Set save_to_lms to also save it as an unpublished draft course in EduMark (the key needs courses:write), ready to review in Course Studio.

Requires authoring:write. Costs 20 credits per course. 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.

Course builds

POST/v1/authoring/course-builds

Scope authoring:write

Headers

Course builds: 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

Course builds: request body
Field	Details
`brief`	stringWhat the course is, who it is for and anything it must cover, for example "GCSE Biology: photosynthesis, four short lessons with a quiz after each module".Up to 6,000 charactersDefault `""`
`sources`	array of BuildSourceUp to 10 sources to teach from. Lessons are written in Aurora's own words and cite the parts they use.Up to 10 items
`title`sources[].title	string, optionalA short name for this source.Up to 200 characters
`text`sources[].text	string, optionalTeaching text (at most 10,000 words).Up to 120,000 characters
`document`sources[].document	FileReference or DocumentInput, optionalA PDF, DOCX or TXT: `{"file_id"}` from POST /v1/files, or inline base64.
`file_id`sources[].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`sources[].document.filename	stringRequiredWhen sending DocumentInputUp to 200 characters
`base64`sources[].document.base64	stringRequiredWhen sending DocumentInputUp to 27,962,028 characters
`mime_type`sources[].document.mime_type	string, optionalWhen sending DocumentInputUp to 150 characters
`title`	string, optionalThe course title. Aurora suggests one when left out.Up to 200 characters
`save_to_lms`	booleanAlso save the course as an unpublished draft in EduMark (needs the courses:write permission) and return its id.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/course-builds' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "brief": "Photosynthesis for GCSE Biology: short lessons with a quiz after each module.",
  "sources": [
    {
      "title": "Class notes",
      "text": "Photosynthesis happens in the chloroplasts. Chlorophyll absorbs light energy..."
    }
  ]
}'

# 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": "course_builds",
  "status": "queued",
  "poll_after_seconds": 2,
  "credits": 20,
  "result_available": false
}

Finished job: resultJSON

{
  "status": "needs_review",
  "requires_review": true,
  "course": {
    "title": "Photosynthesis for GCSE Biology",
    "description": "How plants make their own food, and what speeds it up or slows it down.",
    "level": "GCSE (ages 14-16)",
    "outcomes": [
      "Describe the products and reactants of photosynthesis",
      "Explain the role of chlorophyll",
      "Explain how light, carbon dioxide and temperature limit the rate"
    ],
    "modules": [
      {
        "title": "How plants make food",
        "description": "What photosynthesis is and where it happens.",
        "lessons": [
          {
            "kind": "content",
            "title": "Light into food",
            "estimated_minutes": 12,
            "blocks": [
              {
                "kind": "page",
                "title": "What you will learn",
                "body": "By the end of this lesson you can describe what photosynthesis makes, what it needs and where in the plant it happens.",
                "label": "Lesson aims"
              },
              {
                "kind": "definition",
                "title": "Photosynthesis",
                "term": "Photosynthesis",
                "body": "The process plants use to make glucose from carbon dioxide and water, using light energy.",
                "label": "Key term"
              },
              {
                "kind": "callout",
                "title": "Remember the equation",
                "tone": "info",
                "body": "carbon dioxide + water → glucose + oxygen",
                "label": "Word equation"
              },
              {
                "kind": "question",
                "title": "Quick check",
                "body": "",
                "prompt": "Which gas do plants release?",
                "mode": "single",
                "options": [
                  {
                    "text": "Oxygen",
                    "correct": true,
                    "feedback": "Yes: oxygen is a product."
                  },
                  {
                    "text": "Carbon dioxide",
                    "correct": false,
                    "feedback": "That is taken in."
                  }
                ],
                "explanation": "Oxygen is released; carbon dioxide is used up.",
                "label": "Quick check"
              }
            ]
          },
          {
            "kind": "quiz",
            "title": "Check: how plants make food",
            "estimated_minutes": 6,
            "pass_mark_percent": 60,
            "questions": [
              {
                "prompt": "Where does photosynthesis happen?",
                "options": [
                  "Chloroplasts",
                  "Mitochondria",
                  "Nucleus"
                ],
                "correct_option": 0,
                "explanation": "Chloroplasts contain chlorophyll, which absorbs light."
              }
            ]
          }
        ]
      },
      {
        "title": "What limits photosynthesis",
        "description": "Light, carbon dioxide and temperature.",
        "lessons": [
          {
            "kind": "content",
            "title": "The three limiting factors",
            "estimated_minutes": 15,
            "blocks": [
              {
                "kind": "table",
                "title": "Limiting factors",
                "body": "",
                "headers": [
                  "Factor",
                  "Effect when it is low"
                ],
                "rows": [
                  [
                    "Light intensity",
                    "Less energy for the reaction"
                  ],
                  [
                    "Carbon dioxide",
                    "Less raw material"
                  ],
                  [
                    "Temperature",
                    "Enzymes work more slowly"
                  ]
                ],
                "label": "Factor table"
              },
              {
                "kind": "callout",
                "title": "Common mistake",
                "tone": "warning",
                "body": "Raising one factor only helps until another factor becomes the limit.",
                "label": "Common mistake"
              }
            ]
          }
        ]
      }
    ],
    "lesson_count": 3,
    "estimated_minutes": 33
  },
  "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_course_build",
    "sources": 0,
    "sandbox": true
  }
}