Schnittstelle

Alles, was die Seite selbst tut — ein geteiltes Programm holen, einen Kurzlink anlegen, eine Aufgabe ablegen — geht über eine kleine HTTP-Schnittstelle. Sie ist hier beschrieben, damit ein Kurssystem, ein Skript oder ein eigenes Werkzeug dasselbe tun kann.

Nur auf Einladung. Lesen kann jeder, und Kurzlinks legt auch der Teilen-Dialog im Browser an. Alles unter /api/pub — Aufgaben unter einem selbst gewählten Namen — braucht ein Konto, und Konten geben wir einzeln aus. Frag uns, wenn du eins brauchst.

Grundlagen

Alle Adressen beginnen mit https://python.jetzt/api.
Hin und zurück geht JSON in UTF-8. Beim Senden gehört Content-Type: application/json dazu.
Anmeldung, wo nötig: HTTP Basic mit Benutzername und Passwort.
Geht etwas schief, kommt der passende Status und {"error": "…"} mit einem Satz auf Deutsch — er ist dafür gedacht, Menschen gezeigt zu werden.

Die Adressen

Aufruf	Tut	Konto
`GET /api/config`	Grenzen und Captcha-Einstellungen	nein
`GET /api/s/{id}`	ein geteiltes Programm lesen	nein
`POST /api/s`	einen Kurzlink anlegen	nein
`GET /api/pub`	alle dauerhaften Aufgaben auflisten	ja
`PUT /api/pub/{name}`	eine Aufgabe anlegen oder ersetzen	ja
`DELETE /api/s/{id}` `DELETE /api/pub/{name}`	löschen	ja
`GET /api/whoami`	ob die Anmeldung ankommt	nein

Ein Name mit Bindestrich gehört zum dauerhaften Bereich, einer ohne ist ein Kurzlink auf Zeit. Deshalb können sich die beiden nie in die Quere kommen, und /s/{id} findet beides.

Ein Programm lesen

curl https://python.jetzt/api/s/kara-schleifen-01

{
  "v": 1,
  "title": "Beeren einsammeln",
  "code": "from kara import *\nworld(\"\"\"#####\n#@ .#\n#####\"\"\")\nmove()\n",
  "created": "2026-05-04T10:12:33+02:00",
  "run": {
    "kara": { "world": "#####\n#@ .#\n#####", "commands": ["move"] },
    "output": "fertig\n"
  }
}

code ist das Programm, mehr braucht es nicht. run ist die Aufzeichnung des letzten Laufs und kann fehlen; sie ist dafür da, ein eingebettetes Ergebnis zu zeigen, ohne Python zu laden. Wer die Aufgabe nur öffnen will, nimmt statt der Schnittstelle gleich https://python.jetzt/s/{id} — das ist die Seite dazu.

Einen Link, den es nicht (mehr) gibt, beantwortet der Server mit 404.

Eine Aufgabe ablegen

Der Weg für eine Sammlung: derselbe Name überschreibt, ein Übertragungslauf darf also beliebig oft laufen, ohne Dubletten zu erzeugen.

curl -u name:passwort -X PUT \
  -H 'Content-Type: application/json' \
  -d '{"title":"Beeren einsammeln","code":"from kara import *\nmove()\n"}' \
  https://python.jetzt/api/pub/kara-schleifen-01

run darf hier genauso mitkommen wie beim Kurzlink — dieselbe Form, dieselbe Prüfung. Wer keine Aufzeichnung hat, lässt es weg: Bei einem Kara-Programm steht die Startwelt im Quelltext, und die eingebettete Ergebnisansicht zeichnet sie von dort, ohne irgendetwas auszuführen. Eine Turtle-Zeichnung braucht dagegen einen Lauf und bleibt sonst beim Link auf das große Werkzeug.

Zurück kommt {"id": "…", "url": "/s/…"}, mit 201 beim ersten Mal und 200 beim Ersetzen. Der Name darf Kleinbuchstaben, Ziffern und Bindestriche enthalten und braucht mindestens einen Bindestrich — sonst antwortet der Server mit 422.

GET /api/pub listet auf, was da ist, DELETE /api/pub/{name} nimmt eines wieder weg. Beides braucht dieselbe Anmeldung.

Wenn die Anmeldung nicht klappt

Ein 401 sagt nicht, woran es lag — das ist von außen nicht zu unterscheiden. GET /api/whoami sagt es:

curl -u name:passwort https://python.jetzt/api/whoami

user ist der angemeldete Name oder null. http_authorization zeigt, ob der Anmeldekopf überhaupt bei PHP angekommen ist — manche Server behalten ihn für sich. config nennt die gelesene Konfigurationsdatei und accounts, wie viele Konten darin stehen. Steht dort 0, hätte kein Passwort der Welt funktioniert.

Einen Kurzlink anlegen

Das ist der Weg ohne Konto, und es ist derselbe, den der Teilen-Dialog geht:

POST /api/s
{
  "code": "from kara import *\nmove()\n",
  "title": "Beeren einsammeln",
  "captcha": "…",
  "run": { "kara": { "world": "#####\n#@ .#\n#####", "commands": ["move"] } }
}

title, captcha und run sind freiwillig. Ob ein Captcha verlangt wird und wie lang ein Programm sein darf, steht in GET /api/config. Zurück kommt 201 mit {"id": "…", "url": "/s/…"}. Solche Links verfallen, wenn sie zwei Jahre lang niemand öffnet.

Ohne gelöstes Captcha gilt ein knapperes Stundenlimit. Das zählt je Internet-Anschluss, und eine Schule hat davon einen — die Grenze ist deshalb so gesetzt, dass eine ganze Klasse in einer Stunde darunter bleibt. Wer sie doch erreicht, bekommt 429; der lange Link funktioniert dann weiterhin, denn er trägt das Programm in sich.

Wenn etwas schiefgeht

Status	Heißt
`400`	Da ist kein Programm dabei.
`401`	Anmeldung fehlt oder stimmt nicht.
`403`	Das Captcha wurde nicht anerkannt.
`404`	Diese Adresse oder diesen Link gibt es nicht.
`413`	Das Programm ist länger als erlaubt.
`422`	Der gewünschte Name passt nicht ins Schema.
`429`	Von diesem Anschluss kamen gerade zu viele Anfragen.

Und die KI?

Für Chat-Programme gibt es keinen eigenen Schlüssel und keinen eigenen Weg über diese Schnittstelle, sondern einen MCP-Server unter /mcp — siehe KI-Anbindung. Er zeigt Kara-Welten und Turtle-Zeichnungen direkt im Gespräch an, ohne dabei etwas zu speichern.