Concept map

A concept map: one root topic, grouped concepts beneath it, and cross-links explaining how ideas connect.

Price1 credit (10p) per set
Typical time15 s to 2 min
Scopelearning:write
Runs asA background job

Try it

Run concept map 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.

TopicA subject to study from general knowledge, for example "Photosynthesis for GCSE Biology".

Source TextYour own teaching text (at least 200 characters, at most 10,000 words). Material stays grounded in it.

TitleA name for your text or document, such as the lesson or chapter title.

FocusConcepts to concentrate on, in plain words.

LevelHow to pitch the material. Leave it out for upper-secondary to first-year university level.

AudienceWho the material is for, for example "Year 10 learners who find maths hard".

LanguageThe language to write in. British English unless you choose another.

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.

root is a tree of nodes (id, label, detail, optional example, children), at most six levels deep. links connect concepts in different branches: read from_id verb to_id, or the other way with back_verb, and explanation says how they connect.

Requires learning:write. Costs 1 credit per set. 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.

Concept map

POST/v1/concept-maps

Scope learning:write

Headers

Concept map: 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

Concept map: request body
Field	Details
`topic`	string, optionalA subject to study from general knowledge, for example "Photosynthesis for GCSE Biology".Up to 200 characters
`source_text`	string, optionalYour own teaching text (at least 200 characters, at most 10,000 words). Material stays grounded in it.Up to 120,000 characters
`document`	FileReference or DocumentInput, optionalA PDF, DOCX or TXT to study from: `{"file_id"}` from POST /v1/files, 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
`title`	string, optionalA name for your text or document, such as the lesson or chapter title.Up to 200 characters
`focus`	stringConcepts to concentrate on, in plain words.Up to 500 charactersDefault `""`
`level`	enum, optionalHow to pitch the material. Leave it out for upper-secondary to first-year university level.One of `new_to_this`, `foundation`, `intermediate`, `advanced`, `exam_revision`, `deep_dive`
`audience`	string, optionalWho the material is for, for example "Year 10 learners who find maths hard".Up to 200 characters
`language`	enumThe language to write in. British English unless you choose another.One of `English`, `Welsh`, `Irish`, `Gaelic`, `French`, `Spanish`, `German`, `Italian`, `Portuguese`, `Dutch`, `Polish`, `Arabic`, `Urdu`, `Hindi`, `Punjabi`, `Bengali`, `Chinese`, `Mandarin`, `Cantonese`, `Japanese`, `Korean`, `Russian`, `Turkish`, `Greek`, `Swedish`, `Norwegian`, `Danish`, `Finnish`, `Romanian`, `Hungarian`, `Czech`, `Ukrainian`, `Farsi`, `Persian`, `Hebrew`, `Swahili`, `Somali`, `Tamil`, `Gujarati`, `Vietnamese`, `Thai`, `Indonesian`, `Malay`, `Tagalog`, `Latin`Default `"English"`

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/concept-maps' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "Photosynthesis for GCSE Biology"
}'

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

Finished job: resultJSON

{
  "status": "completed",
  "title": "Photosynthesis for GCSE Biology",
  "root": {
    "id": "n1",
    "label": "Photosynthesis",
    "detail": "How plants make glucose from light, water and carbon dioxide.",
    "children": [
      {
        "id": "n2",
        "label": "Inputs",
        "detail": "What the reaction needs.",
        "children": [
          {
            "id": "n3",
            "label": "Light energy",
            "detail": "Absorbed by chlorophyll in the chloroplasts.",
            "children": []
          },
          {
            "id": "n4",
            "label": "Carbon dioxide",
            "detail": "Taken in through the stomata.",
            "children": [],
            "example": "A leaf in sunlight takes in CO2 all day."
          }
        ]
      },
      {
        "id": "n5",
        "label": "Outputs",
        "detail": "What the reaction makes.",
        "children": [
          {
            "id": "n6",
            "label": "Glucose",
            "detail": "Used for respiration, growth and storage as starch.",
            "children": []
          },
          {
            "id": "n7",
            "label": "Oxygen",
            "detail": "Released into the air as a by-product.",
            "children": []
          }
        ]
      }
    ]
  },
  "node_count": 7,
  "links": [
    {
      "id": "l1",
      "from_id": "n3",
      "to_id": "n6",
      "verb": "is stored in",
      "back_verb": "stores",
      "explanation": "Light energy is converted into chemical energy stored in glucose."
    },
    {
      "id": "l2",
      "from_id": "n4",
      "to_id": "n7",
      "verb": "is swapped for",
      "back_verb": "replaces",
      "explanation": "Carbon dioxide enters the leaf while oxygen leaves it through the stomata."
    }
  ],
  "link_count": 2,
  "language": "English",
  "source": {
    "kind": "topic",
    "title": "Photosynthesis for GCSE Biology",
    "truncated": false
  },
  "warnings": [],
  "provenance": {
    "engine": "edumark_study",
    "sandbox": true
  }
}

Files and errors

Product errors

SOURCE_REQUIREDHTTP 422. Provide exactly one of topic, source_text or document.
SOURCE_TOO_SHORTHTTP 422. source_text needs at least 200 characters to study from.
INPUT_TOO_LARGEHTTP 422. source_text supports at most 10,000 words.
MODEL_RESULT_INVALIDOn the finished job. The generated material did not pass EduMark's checks. No charge was applied.
PROCESSING_UNAVAILABLEOn the finished job. Processing could not complete safely. No complete result was issued.
DOCUMENT_READ_FAILEDOn the finished job. The document could not be read safely.