Edumaps

edumaps
FAQ Free Media Library
en
DE EN ES FR IT RU

Edumaps for AI agents and scripts

This page is for AI agents, browser agents and scripts that create maps in Edumaps on behalf of a logged-in teacher. The intended route: the map is written as one JSON file, and the teacher imports it once.

Such an agent runs on the teacher’s device, in their own session and with their rights. It sees what they see. On this route Edumaps itself transmits no data to any AI provider. Which content an agent may read is decided by the teacher who uses it.

How a map is created

  1. Build the map as one JSON document following the JSON format documentation, with "formatversion": 2. All fields and rules are listed there.
  2. The logged-in teacher uploads the file on the page “Import Edumaps file” (/import/json), on the server of their own account: www.edumaps.de, he.edumaps.de, nds.edumaps.de, nrw.edumaps.de or www.edumaps.ch. The page only accepts a file with the extension .json, no pasted text. The import requires a login, student accounts cannot use it.
  3. The import creates a new, unpublished map in the teacher’s account and then forwards to it. An existing map is never overwritten. If content was left out or shortened, the message after the import gives the number. Open the map and check it.

The content of a box is text in the Edumaps text format (Markdown-like). Besides text it can hold interactive elements: quiz (<quiz>), poll (<poll>), checklist (<check>), collapsible solution (?? at the start of a paragraph hides the whole paragraph up to the next blank line), tables, LaTeX formulas and read-aloud audio. A box holds at most one quiz and at most one poll or checklist. All notations are shown in the Editor Help. In the editor a box is created in two steps: the first dialog takes the title and the settings, the content editor (“Box Content”) opens only after “Create Box”, and the white preview in step one is not an input field. On a new map the editor offers the first column and then the first box with a confirmation dialog, further ones are added directly with “New Column” and “New Box”. If the map owner clicks “Check” in a quiz, the answer is stored like any visitor’s and shows in the results, only the first answer per box counts.

Images, PDFs and other files

  • A link to a file that is already on Edumaps, also on another Edumaps server, is copied into the teacher’s account during the import. The link then points to the copy, and the copy uses storage space of that account. A deleted file is not copied. If a copy fails, the original link stays.
  • Links to other websites, including images and PDFs, are not downloaded by the import, they stay links. If a link is the first word of a paragraph, the box shows a preview image.
  • The JSON file cannot contain files itself. A file that is not on Edumaps yet is uploaded by the teacher in the map.

Example

A map with two columns and three boxes: heading, bulleted list, bold text, two links in the form {Link text}{https://...} and a badge above the box title (field subject). It is the same file as the example of the JSON format, it imports without errors. 

{
	"formatversion": 2,
	"format": "Edumaps map export. Box content uses the Edumaps text markup (Markdown-like, raw HTML is shown literally). Documentation: https://www.edumaps.de/docs/json",
	"mapdata": {
		"title": "The water cycle",
		"subtitle": null,
		"tags": "geography grade5",
		"mapbg": "i10",
		"mapfont": "0",
		"mapformat": "0",
		"maptype": "0",
		"flags": "0",
		"language": "en",
		"extras": null
	},
	"paths": [
		{
			"title": "Basics",
			"visiblefrom": null,
			"visibleuntil": null,
			"annotation": null,
			"color": null,
			"flags": "0",
			"widthmode": "1",
			"extras": null,
			"boxes": [
				{
					"title": "What is the water cycle?",
					"content": "## In short\n\nWater is always on the move.\n\n- Evaporation\n- Condensation\n- Precipitation",
					"subject": "Geography",
					"booktime": null,
					"booklimit": "0",
					"color": null,
					"flags": "0",
					"ratingmode": "1",
					"position": null,
					"visiblefrom": null,
					"visibleuntil": null,
					"extras": null
				},
				{
					"title": "Read more",
					"content": "**Tip:** For an overview see {the Wikipedia article}{https://en.wikipedia.org/wiki/Water_cycle}.",
					"subject": null,
					"booktime": null,
					"booklimit": "0",
					"color": "#3a86ff",
					"flags": "16",
					"ratingmode": "0",
					"position": null,
					"visiblefrom": null,
					"visibleuntil": null,
					"extras": null
				}
			]
		},
		{
			"title": "Going further",
			"visiblefrom": null,
			"visibleuntil": null,
			"annotation": null,
			"color": null,
			"flags": "0",
			"widthmode": "0",
			"extras": null,
			"boxes": [
				{
					"title": "Rain, snow and hail",
					"content": "How water falls from the clouds is explained in the article {Precipitation}{https://en.wikipedia.org/wiki/Precipitation}.",
					"subject": null,
					"booktime": null,
					"booklimit": "0",
					"color": null,
					"flags": "0",
					"ratingmode": "0",
					"position": null,
					"visiblefrom": null,
					"visibleuntil": null,
					"extras": null
				}
			]
		}
	]
}

Text in boxes

The content of a box is plain text in the Edumaps text format (Markdown-like), never HTML. HTML tags appear in the box as visible text. Write links as {Link text}{https://...}. A line that starts with “1.” stays normal text, numbered lists start with -- . All notations are listed in the text format table.

Reading existing maps

  • The teacher gets the JSON file of a map via “Map options” → “Export” → “Edumaps file (json)”. The entry appears for maps the teacher owns or may edit. The file has the same format as the import.
  • A read link has the form https://<Server>/<Mapid>/<Userid>/<Readcode>. If the edit code of the map stands in this place, the same link opens the map for editing. With the access code for anonymous reading appended it reads https://<Server>/<Mapid>/<Userid>/<Readcode>/<Accesscode> and opens the map without a login. If the map is protected with a password, the password form appears first.
  • The handbook for AI systems: llms.txt (overview, English), llms-full.txt (complete, German) and handbook-en.md (complete, English).

What is not an interface

The requests the editor sends to the server in the background are internal functions of Edumaps. They change without notice and are not supported for use by third parties. Agents and scripts create maps through the JSON import as described above.

Edumaps does not offer a REST API, see the FAQ.

Import limits

  • The JSON file is at most 2 MB.
  • How many maps an account can create depends on the plan, see Pricing.
  • At most 5 imports per minute per account.
  • The storage space of the account must not be full.
  • With more than 100 columns the import is refused.
  • At most 500 boxes, 300 arrows and 300 labels per map. Anything beyond that is left out, the message after the import gives the number.
  • The maximum text lengths are listed in the tables of the JSON format.