Zum Inhalt springen
Adler AI
Neuer Chat

Anleitungen

Mit der Adler-API helfen Ihre Anwendung, Ihr KI-Assistent oder Ihr Agent Bürgern bei Behördengängen: mit demselben Wissen wie der Chat auf FragDenAdler. Alle Endpunkte im Detail: API-Referenz. Ohne eigenen Code, direkt in Claude oder ChatGPT: MCP-Server.

Zugang

Die API liegt unter https://api.fragdenadler.de. Jede Anfrage braucht einen API-Key im Header Authorization: Bearer adler_…. Einen Key bekommen Sie auf Anfrage per E-Mail an kontakt@fragdenadler.de.

Ein Key darf, was seine Scopes erlauben; jeder Endpunkt der Referenz nennt den, den er braucht. Fehlt er, antwortet die API mit 403.

  • search:read: Behördengänge suchen
  • places:read: Orte bestimmen
  • plans:read: Pläne erstellen

Versionen

Die Version steht im Header Adler-Version: 2026-10-24, benannt nach dem Tag ihrer Veröffentlichung. Ohne den Header gilt die Version, die beim Erstellen Ihres Keys aktuell war; jede Antwort nennt ihre Version im selben Header. Was bestehende Anwendungen brechen würde, kommt nur mit einer neuen Version; die alte antwortet weiter wie bisher.

Erste Schritte: Jagdschein beantragen

Ein Bürger fragt seinen KI-Assistenten: „Wie beantrage ich einen Jagdschein?“ Drei Aufrufe führen zum Plan.

1. Den Behördengang finden

GET /search sucht mit den Worten des Bürgers und liefert höchstens 8 Treffer, den wahrscheinlichsten zuerst. Passt keiner, hat Adler nichts dazu.

curl "https://api.fragdenadler.de/search?q=Jagdschein%20beantragen" \
  -H "Authorization: Bearer $ADLER_API_KEY" \
  -H "Adler-Version: 2026-10-24"
{
  "query": "Jagdschein beantragen",
  "results": [
    {
      "id": "99067004001000",
      "kind": "service",
      "title": "Jagdschein beantragen",
      "description": "Den Jagdschein, die Erlaubnis zur Jagd, bei der unteren Jagdbehörde beantragen …",
      "placeQuestion": null
    },
    { "id": "99067004236002", "kind": "service", "title": "Jagdschein verlängern", … },
    { "id": "99067003007000", "kind": "service", "title": "Zur Jägerprüfung anmelden", … }
  ]
}

2. Den Plan anfragen

POST /plans mit der id des Treffers. Fehlt noch etwas, sagt die Antwort, was: hier der Ort, denn die zuständige Stelle hängt davon ab.

curl https://api.fragdenadler.de/plans \
  -H "Authorization: Bearer $ADLER_API_KEY" \
  -H "Adler-Version: 2026-10-24" \
  -H "Content-Type: application/json" \
  -d '{"subject": "99067004001000"}'
{
  "status": "need_place",
  "subject": { "id": "99067004001000", "title": "Jagdschein beantragen", … },
  "question": "Wo wohnen Sie?",
  "questions": []
}

3. Nachfragen und erneut senden

Der Assistent fragt „Wo wohnen Sie?“ und sendet die Antwort als place, so wie der Bürger sie nennt: Ort, Postleitzahl, Bezirk oder Ortsteil.

curl https://api.fragdenadler.de/plans \
  -H "Authorization: Bearer $ADLER_API_KEY" \
  -H "Adler-Version: 2026-10-24" \
  -H "Content-Type: application/json" \
  -d '{"subject": "99067004001000", "place": "85356 Freising"}'
{
  "status": "ok",
  "plan": {
    "title": "Jagdschein und Falknerjagdschein; Beantragung der Erteilung und Verlängerung",
    "place": { "id": "091780124124", "name": "Freising", … },
    "steps": [
      {
        "position": 1,
        "title": "Jagdschein beantragen",
        "todo": [
          "Beantragen Sie den Jagdschein bei der zuständigen Stelle (Landratsamt Freising, …).",
          "Für die erste Erteilung legen Sie dem Antrag das Zeugnis über die bestandene Jägerprüfung bei.",
          …
        ],
        "service": {
          "sections": {
            "required_documents": "• Prüfungszeugnis über die bestandene Jägerprüfung im Original …",
            "costs": "• Dreijahresjagdschein: 150,00 EUR …",
            …
          },
          "source": {
            "url": "https://www.bayernportal.de/dokumente/leistung/53553314483",
            "retrievedAt": "2026-10-05T13:01:59.954Z"
          }
        },
        "offices": [
          {
            "name": "Landratsamt Freising",
            "address": "Landshuter Str. 31, 85356 Freising",
            "phone": "+49 8161 600-0",
            "email": "poststelle@kreis-fs.de",
            "source": { … }
          }
        ],
        …
      }
    ],
    "portal": { "title": "BayernPortal", "url": "https://www.bayernportal.de/" }
  }
}

Was die Antwort von POST /plans bedeutet

  • ok

    Der Plan. Zeigen Sie die Schritte mit ihren Quellen.

  • need_place

    Der Ort fehlt. Stellen Sie question und senden Sie die Antwort als place.

  • need_answers

    Fragen fehlen, etwa bei einer Lebenslage wie Heiraten. Stellen Sie sie (die mit changesSubject zuerst) und senden Sie die Antworten in answers, als value oder label.

  • other_subject

    Eine Antwort meint einen anderen Behördengang. Senden Sie erneut mit subject.id.

  • which_place

    Mehrere Orte heißen so. Lassen Sie den Bürger eine der Optionen wählen, oder fragen Sie nach Land oder Kreis.

  • place_too_broad

    Ein Land oder ein Kreis, kein Ort. Fragen Sie nach dem Ort.

  • unknown_place

    Adler kennt den Ort nicht: ein Tippfehler, oder er liegt im Ausland.

  • not_covered

    Den Ort deckt Adler noch nicht ab. Nennen Sie das Portal.

  • no_record

    Für diesen Ort hat Adler keine Quelle. Nennen Sie das Portal und die Behördennummer 115.

Für KI-Assistenten und Agenten

  • Suchen Sie zuerst, auch wenn Sie den Behördengang zu kennen glauben: Die id aus der Suche führt zum richtigen Eintrag.
  • Nennen Sie nur, was in der Antwort steht. Gebühren, Fristen, Adressen und Unterlagen kommen aus den amtlichen Quellen; ergänzen Sie nichts aus eigenem Wissen und verweisen Sie auf die source.
  • Fragen Sie den Bürger, statt zu raten: Die Antwort sagt, welche Frage fehlt und welche Antworten möglich sind.
  • Die Texte sind Deutsch. Erklären Sie sie in der Sprache des Bürgers und in einfachen Worten.
  • Ob die Voraussetzungen erfüllt sind, entscheidet die Behörde. Adler und Ihr Assistent geben keine Rechts- oder Steuerberatung.

Regeln

  • Höchstens 60 Anfragen pro Minute und Key. Darüber antwortet die API mit 429; nach Retry-After Sekunden geht es weiter.
  • Die API ist für Anfragen von Bürgern gedacht, nicht zum Kopieren des Katalogs. Sie listet deshalb nichts vollständig auf.
  • Adler protokolliert jede Anfrage für die Statistik: Endpunkt, Key, Zeitpunkt, Antwortzeit, Status und die gesendeten Felder (Suchbegriff, Behördengang, Ort, Antworten). Senden Sie deshalb keine personenbezogenen Daten: Die Felder sind für Behördengänge und Orte da, nicht für Angaben über den Bürger.
  • Fehler kommen als application/problem+json (RFC 9457) mit type, title und status.