{ "openapi": "3.1.0", "info": { "title": "Agile Domain API", "version": "1.0.0", "description": "Die REST-API von **Agile Domain** bietet alle Funktionen des Kundenbereichs: Verfügbarkeit, Domains, DNS, Nameserver, Weiterleitungen, Kontakte, DNSSEC, Transfer (Auth-Code), Bestellungen und Webhooks.\n\n## Schnellstart\n1. Im Kundenbereich unter **API und Webhooks** einen Schlüssel anlegen (Rechte wählen). Er wird nur einmal angezeigt.\n2. Erster Aufruf:\n```bash\ncurl -H \"Authorization: Bearer agile_dom_…\" https://domain.agiledeveloper.de/api/v1/domains\n```\n\n## Authentifizierung\n`Authorization: Bearer ` mit einem API-Schlüssel (`agile_dom_…`) oder einem OAuth-Access-Token (Authorization Code mit PKCE, siehe MCP). Rechte: `domains:lesen`, `domains:schreiben`, `dns:lesen`, `dns:schreiben`, `konto:lesen`, `konto:schreiben`, `bestellungen:lesen`, `bestellungen:kaufen`, `webhooks:verwalten`.\n\n## Fehler\nEinheitlich `{ \"fehler\": { \"code\", \"nachricht\", \"details\" } }` mit passendem HTTP-Status (400, 401, 403, 404, 409, 429, 500).\n\n## Pagination\nListen nehmen `limit` (1 bis 200, Standard 50) und `offset` und antworten mit `{ \"daten\": [...], \"seite\": { \"limit\", \"offset\", \"gesamt\" } }`.\n\n## Rate-Limits\n120 Anfragen pro Minute je Schlüssel bzw. App. Jede Antwort trägt `RateLimit-Limit`, `RateLimit-Remaining` und `RateLimit-Reset`; bei 429 zusätzlich `Retry-After`.\n\n## Idempotenz\nPOST-Anfragen akzeptieren `Idempotency-Key`. Eine Wiederholung mit demselben Schlüssel liefert die gespeicherte Antwort (Header `Idempotent-Replayed: true`).\n\n## Webhooks\nEreignisse: `domain.registriert` (Domain registriert), `domain.transfer_status` (Transfer-Status geändert), `domain.ablauf_naht` (Ablauf naht), `dns.geaendert` (DNS geändert), `zahlung.fehlgeschlagen` (Zahlung fehlgeschlagen), `bestellung.ausgefuehrt` (Bestellung ausgeführt). Zustellung per POST mit JSON (Schema WebhookEreignis) und Header `Agile-Signature: t=,v1=`; `v1` ist HMAC-SHA256 mit dem Webhook-Geheimnis über `.`. Antworten Sie mit 2xx; sonst wiederholen wir nach 1, 5, 30, 120, 360 und 1440 Minuten. Das Protokoll steht im Kundenbereich und unter `/api/v1/webhooks/{id}/zustellungen`.\n\n## MCP für Claude und ChatGPT\nMCP-Server: `https://domain.agiledeveloper.de/mcp` (Streamable HTTP, OAuth 2.1 mit Discovery und dynamischer Registrierung). Anleitung: [/docs/mcp](https://domain.agiledeveloper.de/docs/mcp).\n\n## Kostenpflichtige Aufrufe\nNur `POST /api/v1/bestellungen` kostet Geld und nur mit `bestaetigen: true`. Ohne Bestätigung kommt ein Angebot mit Preis zurück.", "contact": { "name": "Agile Developer", "email": "info@agiledeveloper.de", "url": "https://agiledeveloper.de" }, "license": { "name": "Proprietär, Nutzung gemäß AGB", "url": "https://domain.agiledeveloper.de/agb" } }, "servers": [ { "url": "https://domain.agiledeveloper.de", "description": "Produktion" } ], "tags": [ { "name": "Domains", "description": "Domains des Kontos: Status, Einstellungen, Nameserver, Kontakte, DNSSEC." }, { "name": "DNS", "description": "DNS-Einträge und Vorlagen der Zone bei Agile Domain." }, { "name": "Weiterleitungen", "description": "HTTP-Weiterleitungen für Domain und Subdomains." }, { "name": "Transfer", "description": "Umzug zu einem anderen Anbieter: Auth-Code und Transfersperre." }, { "name": "Suche und Preise", "description": "Verfügbarkeit und Preisliste." }, { "name": "Bestellungen", "description": "Kostenpflichtige Registrierungen, Transfers und Verlängerungen mit Rechnung." }, { "name": "Konto", "description": "Rechnungsdaten und Domain-Kontakte." }, { "name": "Webhook-Endpunkte", "description": "Endpunkte für signierte Ereignisse anlegen, testen und das Zustellprotokoll lesen. Die Ereignisse selbst stehen unter „Webhooks“." } ], "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ], "paths": { "/api/v1/konto": { "get": { "tags": [ "Konto" ], "summary": "Rechnungsdaten lesen", "operationId": "getKonto", "description": "Recht: `konto:lesen` (OAuth: lesen).", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Konto" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] }, "put": { "tags": [ "Konto" ], "summary": "Rechnungsdaten ändern", "operationId": "putKonto", "description": "USt-IdNr. von EU-Unternehmen wird bei VIES geprüft; gültig bedeutet Reverse Charge.\n\nRecht: `konto:schreiben` (OAuth: schreiben).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KontoEingabe" }, "example": { "art": "firma", "firma": "Muster GmbH", "vorname": "Max", "nachname": "Muster", "strasse": "Hauptstraße 1", "plz": "10115", "ort": "Berlin", "land": "DE", "telefon": "+49 30 1234567", "ust_idnr": "DE123456789" } } } }, "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Konto" } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/kontakte": { "get": { "tags": [ "Konto" ], "summary": "Kontakte auflisten", "operationId": "getKontakte", "description": "Recht: `konto:lesen` (OAuth: lesen).", "parameters": [ { "name": "limit", "in": "query", "description": "Anzahl (1 bis 200, Standard 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Versatz für die nächste Seite", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "daten": { "type": "array", "items": { "$ref": "#/components/schemas/Kontakt" } }, "seite": { "$ref": "#/components/schemas/Seite" } }, "required": [ "daten", "seite" ] } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] }, "post": { "tags": [ "Konto" ], "summary": "Kontakt anlegen", "operationId": "postKontakte", "description": "Kontakte dienen als Inhaber, Admin-, Tech- oder Rechnungskontakt.\n\nRecht: `konto:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional: gleiche Anfrage mit gleichem Schlüssel wird nur einmal ausgeführt (24 h).", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KontaktEingabe" }, "example": { "bezeichnung": "Firma", "art": "firma", "firma": "Muster GmbH", "vorname": "Max", "nachname": "Muster", "strasse": "Hauptstraße 1", "plz": "10115", "ort": "Berlin", "land": "DE", "email": "max@example.com", "telefon": "+49 30 1234567" } } } }, "responses": { "201": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Kontakt" } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/kontakte/{id}": { "get": { "tags": [ "Konto" ], "summary": "Kontakt lesen", "operationId": "getKontakteId", "description": "Recht: `konto:lesen` (OAuth: lesen).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kontakt-id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Kontakt" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] }, "put": { "tags": [ "Konto" ], "summary": "Kontakt ändern", "operationId": "putKontakteId", "description": "Ändern sich Name oder Firma, wird beim Registrar ein neuer Kontakt angelegt und an allen Domains getauscht.\n\nRecht: `konto:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kontakt-id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KontaktEingabe" }, "example": { "art": "person", "vorname": "Max", "nachname": "Muster", "strasse": "Neue Straße 2", "plz": "10115", "ort": "Berlin", "land": "DE", "email": "max@example.com", "telefon": "+49 30 1234567" } } } }, "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Kontakt" } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] }, "delete": { "tags": [ "Konto" ], "summary": "Kontakt löschen", "operationId": "deleteKontakteId", "description": "Nur, wenn er keiner Domain zugeordnet und nicht der Standardkontakt ist.\n\nRecht: `konto:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kontakt-id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Erledigt, ohne Inhalt" }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "409": { "description": "Konflikt (Zustand oder Registry)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/suche": { "get": { "tags": [ "Suche und Preise" ], "summary": "Verfügbarkeit prüfen", "operationId": "getSuche", "description": "Prüft einen Namen über alle Endungen und liefert Vorschläge. Preise netto in Cent (nur im Verkaufsbetrieb).\n\nJeder gültige Zugang.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Name oder Domain", "schema": { "type": "string", "maxLength": 200 }, "example": "meine-firma" } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suchergebnis" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] } }, "/api/v1/preise": { "get": { "tags": [ "Suche und Preise" ], "summary": "Preisliste", "operationId": "getPreise", "description": "Jeder gültige Zugang.", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preisliste" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] } }, "/api/v1/dns-vorlagen": { "get": { "tags": [ "DNS" ], "summary": "DNS-Vorlagen auflisten", "operationId": "getDnsVorlagen", "description": "Jeder gültige Zugang.", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "daten": { "type": "array", "items": { "$ref": "#/components/schemas/Vorlage" } } } } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] } }, "/api/v1/ereignisse": { "get": { "tags": [ "Webhook-Endpunkte" ], "summary": "Ereignistypen auflisten", "operationId": "getEreignisse", "description": "Jeder gültige Zugang.", "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "daten": { "type": "array", "items": { "type": "object", "properties": { "typ": { "type": "string" }, "titel": { "type": "string" } } } } } } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] } }, "/api/v1/domains": { "get": { "tags": [ "Domains" ], "summary": "Domains auflisten", "operationId": "getDomains", "description": "Recht: `domains:lesen` (OAuth: lesen).", "parameters": [ { "name": "limit", "in": "query", "description": "Anzahl (1 bis 200, Standard 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Versatz für die nächste Seite", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "description": "Filter, z. B. aktiv", "schema": { "type": "string" } }, { "name": "sortierung", "in": "query", "description": "name (Standard) oder laeuft_bis", "schema": { "type": "string", "enum": [ "name", "laeuft_bis" ] } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "daten": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "seite": { "$ref": "#/components/schemas/Seite" } }, "required": [ "daten", "seite" ] }, "example": { "daten": [ { "name": "beispiel.de", "unicode": "beispiel.de", "endung": "de", "status": "aktiv", "laeuft_bis": "2027-10-10T12:00:00.000Z", "registriert_seit": "2026-10-10T12:00:00.000Z", "auto_verlaengerung": true, "transfersperre": true, "whois_datenschutz": false, "dns_modus": "agile", "nameserver": [ "ns1.openprovider.nl", "ns2.openprovider.be", "ns3.openprovider.eu" ] } ], "seite": { "limit": 50, "offset": 0, "gesamt": 1 } } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] } }, "/api/v1/domains/{name}": { "get": { "tags": [ "Domains" ], "summary": "Domain lesen", "operationId": "getDomainsName", "description": "Mit DNS-Einträgen, Weiterleitungen, Kontakten und DNSSEC.\n\nRecht: `domains:lesen` (OAuth: lesen).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDetail" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] }, "patch": { "tags": [ "Domains" ], "summary": "Einstellungen ändern", "operationId": "patchDomainsName", "description": "Auto-Verlängerung, Transfersperre, WHOIS-Datenschutz.\n\nRecht: `domains:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_verlaengerung": { "type": "boolean" }, "transfersperre": { "type": "boolean" }, "whois_datenschutz": { "type": "boolean" } } }, "example": { "transfersperre": false } } } }, "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDetail" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "409": { "description": "Konflikt (Zustand oder Registry)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/domains/{name}/abgleich": { "post": { "tags": [ "Domains" ], "summary": "Status beim Registrar abfragen", "operationId": "postDomainsNameAbgleich", "description": "Recht: `domains:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDetail" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/domains/{name}/nameserver": { "put": { "tags": [ "Domains" ], "summary": "Nameserver setzen", "operationId": "putDomainsNameNameserver", "description": "modus agile: DNS bei Agile Domain. modus extern: mindestens zwei eigene Nameserver (bei .de vorab von DENIC geprüft).\n\nRecht: `domains:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "modus" ], "properties": { "modus": { "type": "string", "enum": [ "agile", "extern" ] }, "nameserver": { "type": "array", "items": { "type": "string" } } } }, "example": { "modus": "extern", "nameserver": [ "ns1.hoster.de", "ns2.hoster.de" ] } } } }, "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDetail" } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "409": { "description": "Konflikt (Zustand oder Registry)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/domains/{name}/auth-code": { "post": { "tags": [ "Transfer" ], "summary": "Auth-Code erzeugen", "operationId": "postDomainsNameAuthCode", "description": "Für den Umzug zu einem anderen Anbieter. Jede Ausgabe wird protokolliert.\n\nRecht: `domains:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_code": { "type": "string" }, "transfersperre": { "type": "boolean" }, "hinweis": { "type": [ "string", "null" ] } } }, "example": { "auth_code": "Kq7mT2x-Rb9wPz4h!", "transfersperre": false, "hinweis": null } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "409": { "description": "Konflikt (Zustand oder Registry)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/domains/{name}/kontakte": { "put": { "tags": [ "Domains" ], "summary": "Kontakte setzen (Inhaberwechsel)", "operationId": "putDomainsNameKontakte", "description": "Neuer Inhaber = Inhaberwechsel; bei generischen Endungen folgt eine 60-Tage-Transfersperre, außer opt_out_sperre ist true.\n\nRecht: `domains:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inhaber": { "type": "string", "format": "uuid" }, "admin": { "type": "string", "format": "uuid" }, "technik": { "type": "string", "format": "uuid" }, "rechnung": { "type": "string", "format": "uuid" }, "opt_out_sperre": { "type": "boolean" } } }, "example": { "technik": "0b8a3a5e-0000-4000-8000-000000000001" } } } }, "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDetail" } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/domains/{name}/dnssec": { "put": { "tags": [ "Domains" ], "summary": "DNSSEC-Schlüssel setzen", "operationId": "putDomainsNameDnssec", "description": "Leere Liste entfernt DNSSEC.\n\nRecht: `domains:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schluessel": { "type": "array", "items": { "$ref": "#/components/schemas/DnssecSchluessel" } } } }, "example": { "schluessel": [ { "flags": 257, "algorithmus": 13, "oeffentlicher_schluessel": "mdsswUyr3DPW132mOi8V9xESWE8jTo0dxCjjnopKl+GqJxpVXckHAeF+KkxLbxILfDLUT0rAK9iUzy1L53eKGQ==" } ] } } } }, "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainDetail" } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/domains/{name}/dns": { "get": { "tags": [ "DNS" ], "summary": "DNS-Einträge lesen", "operationId": "getDomainsNameDns", "description": "Recht: `dns:lesen` (OAuth: lesen).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" }, { "name": "limit", "in": "query", "description": "Anzahl (1 bis 200, Standard 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Versatz für die nächste Seite", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "daten": { "type": "array", "items": { "$ref": "#/components/schemas/DnsEintrag" } }, "seite": { "$ref": "#/components/schemas/Seite" } }, "required": [ "daten", "seite" ] }, "example": { "daten": [ { "id": "6f1c2c0e-2a6b-4a77-9a55-1f9d5d3b1a11", "typ": "A", "name": "www", "wert": "203.0.113.10", "ttl": 3600, "prioritaet": null } ], "seite": { "limit": 50, "offset": 0, "gesamt": 1 } } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] }, "post": { "tags": [ "DNS" ], "summary": "DNS-Eintrag anlegen", "operationId": "postDomainsNameDns", "description": "Recht: `dns:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" }, { "name": "Idempotency-Key", "in": "header", "description": "Optional: gleiche Anfrage mit gleichem Schlüssel wird nur einmal ausgeführt (24 h).", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsEingabe" }, "example": { "typ": "MX", "name": "@", "wert": "mx.example.com", "ttl": 3600, "prioritaet": 10 } } } }, "responses": { "201": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "dns": { "type": "array", "items": { "$ref": "#/components/schemas/DnsEintrag" } } } } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/domains/{name}/dns/{id}": { "put": { "tags": [ "DNS" ], "summary": "DNS-Eintrag ändern", "operationId": "putDomainsNameDnsId", "description": "Recht: `dns:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" }, { "name": "id", "in": "path", "required": true, "description": "Eintrags-id", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsEingabe" }, "example": { "typ": "A", "name": "www", "wert": "203.0.113.11", "ttl": 3600 } } } }, "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "dns": { "type": "array", "items": { "$ref": "#/components/schemas/DnsEintrag" } } } } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] }, "delete": { "tags": [ "DNS" ], "summary": "DNS-Eintrag löschen", "operationId": "deleteDomainsNameDnsId", "description": "Recht: `dns:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" }, { "name": "id", "in": "path", "required": true, "description": "Eintrags-id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Erledigt, ohne Inhalt" }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/domains/{name}/dns/vorlagen/{vorlage}": { "post": { "tags": [ "DNS" ], "summary": "DNS-Vorlage anwenden", "operationId": "postDomainsNameDnsVorlagenVorlage", "description": "Ersetzt bestehende MX/SPF bzw. A-Einträge passend zur Vorlage.\n\nRecht: `dns:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" }, { "name": "vorlage", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "agile-email", "google-workspace", "microsoft-365", "vercel", "agile-hosting" ] } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "dns": { "type": "array", "items": { "$ref": "#/components/schemas/DnsEintrag" } } } } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/domains/{name}/weiterleitungen": { "get": { "tags": [ "Weiterleitungen" ], "summary": "Weiterleitungen auflisten", "operationId": "getDomainsNameWeiterleitungen", "description": "Recht: `domains:lesen` (OAuth: lesen).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" }, { "name": "limit", "in": "query", "description": "Anzahl (1 bis 200, Standard 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Versatz für die nächste Seite", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "daten": { "type": "array", "items": { "$ref": "#/components/schemas/Weiterleitung" } }, "seite": { "$ref": "#/components/schemas/Seite" } }, "required": [ "daten", "seite" ] } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] }, "post": { "tags": [ "Weiterleitungen" ], "summary": "Weiterleitung anlegen", "operationId": "postDomainsNameWeiterleitungen", "description": "Setzt für den Host einen A-Eintrag auf den Weiterleitungsserver.\n\nRecht: `domains:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" }, { "name": "Idempotency-Key", "in": "header", "description": "Optional: gleiche Anfrage mit gleichem Schlüssel wird nur einmal ausgeführt (24 h).", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ziel" ], "properties": { "host": { "type": "string", "default": "@" }, "ziel": { "type": "string", "format": "uri" }, "code": { "type": "integer", "enum": [ 301, 302, 307, 308 ] }, "pfad_mitnehmen": { "type": "boolean", "default": true } } }, "example": { "host": "www", "ziel": "https://neue-seite.de", "code": 301 } } } }, "responses": { "201": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "weiterleitungen": { "type": "array", "items": { "$ref": "#/components/schemas/Weiterleitung" } } } } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/domains/{name}/weiterleitungen/{id}": { "delete": { "tags": [ "Weiterleitungen" ], "summary": "Weiterleitung löschen", "operationId": "deleteDomainsNameWeiterleitungenId", "description": "Recht: `domains:schreiben` (OAuth: schreiben).", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Domainname (ASCII/Punycode), z. B. beispiel.de", "schema": { "type": "string" }, "example": "beispiel.de" }, { "name": "id", "in": "path", "required": true, "description": "Weiterleitungs-id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Erledigt, ohne Inhalt" }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/bestellungen": { "get": { "tags": [ "Bestellungen" ], "summary": "Bestellungen auflisten", "operationId": "getBestellungen", "description": "Recht: `bestellungen:lesen` (OAuth: lesen).", "parameters": [ { "name": "limit", "in": "query", "description": "Anzahl (1 bis 200, Standard 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Versatz für die nächste Seite", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "daten": { "type": "array", "items": { "$ref": "#/components/schemas/Bestellung" } }, "seite": { "$ref": "#/components/schemas/Seite" } }, "required": [ "daten", "seite" ] } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] }, "post": { "tags": [ "Bestellungen" ], "summary": "Bestellen (kostenpflichtig)", "operationId": "postBestellungen", "description": "Zweistufig. Ohne bestaetigen: Antwort 200 mit Angebot (Preise, Steuer, Summe), nichts wird angelegt. Mit bestaetigen=true und agb_akzeptiert=true (Verbraucher zusätzlich widerrufsverzicht=true): Antwort 201. Mit hinterlegtem Zahlungsmittel wird abgebucht, sonst enthält die Antwort einen Zahlungslink. Die Ausführung beginnt nach Zahlungseingang; Ergebnis per Webhook domain.registriert bzw. GET /bestellungen/{id}.\n\nRecht: `bestellungen:kaufen` (OAuth: kaufen).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional: gleiche Anfrage mit gleichem Schlüssel wird nur einmal ausgeführt (24 h).", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BestellEingabe" }, "example": { "positionen": [ { "art": "registrierung", "domain": "meine-firma.de", "jahre": 1 } ], "bestaetigen": false } } } }, "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BestellAntwort" } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "409": { "description": "Konflikt (Zustand oder Registry)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "kaufen" ] } ], "x-kostenpflichtig": true } }, "/api/v1/bestellungen/{id}": { "get": { "tags": [ "Bestellungen" ], "summary": "Bestellung lesen", "operationId": "getBestellungenId", "description": "Recht: `bestellungen:lesen` (OAuth: lesen).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Bestell-id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bestellung" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "lesen" ] } ] } }, "/api/v1/webhooks": { "get": { "tags": [ "Webhook-Endpunkte" ], "summary": "Webhooks auflisten", "operationId": "getWebhooks", "description": "Recht: `webhooks:verwalten` (OAuth: schreiben).", "parameters": [ { "name": "limit", "in": "query", "description": "Anzahl (1 bis 200, Standard 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Versatz für die nächste Seite", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "daten": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "seite": { "$ref": "#/components/schemas/Seite" } }, "required": [ "daten", "seite" ] } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] }, "post": { "tags": [ "Webhook-Endpunkte" ], "summary": "Webhook anlegen", "operationId": "postWebhooks", "description": "Nur https-Ziele. Das Geheimnis zum Prüfen der Signatur steht nur in dieser Antwort.\n\nRecht: `webhooks:verwalten` (OAuth: schreiben).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional: gleiche Anfrage mit gleichem Schlüssel wird nur einmal ausgeführt (24 h).", "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "ereignisse" ], "properties": { "url": { "type": "string", "format": "uri" }, "ereignisse": { "type": "array", "items": { "type": "string", "enum": [ "domain.registriert", "domain.transfer_status", "domain.ablauf_naht", "dns.geaendert", "zahlung.fehlgeschlagen", "bestellung.ausgefuehrt" ] } }, "beschreibung": { "type": "string" } } }, "example": { "url": "https://example.com/hooks/agile", "ereignisse": [ "domain.registriert", "domain.ablauf_naht" ] } } } }, "responses": { "201": { "description": "Erfolg", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "geheimnis": { "type": "string" } } } ] } } } }, "400": { "description": "Eingabe ungültig", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "409": { "description": "Konflikt (Zustand oder Registry)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/webhooks/{id}": { "delete": { "tags": [ "Webhook-Endpunkte" ], "summary": "Webhook löschen", "operationId": "deleteWebhooksId", "description": "Recht: `webhooks:verwalten` (OAuth: schreiben).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook-id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Erledigt, ohne Inhalt" }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/webhooks/{id}/zustellungen": { "get": { "tags": [ "Webhook-Endpunkte" ], "summary": "Zustellprotokoll", "operationId": "getWebhooksIdZustellungen", "description": "Recht: `webhooks:verwalten` (OAuth: schreiben).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook-id", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Anzahl (1 bis 200, Standard 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Versatz für die nächste Seite", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "daten": { "type": "array", "items": { "$ref": "#/components/schemas/Zustellung" } }, "seite": { "$ref": "#/components/schemas/Seite" } }, "required": [ "daten", "seite" ] } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } }, "/api/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhook-Endpunkte" ], "summary": "Testereignis senden", "operationId": "postWebhooksIdTest", "description": "Recht: `webhooks:verwalten` (OAuth: schreiben).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook-id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolg", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "versuche": { "type": "integer" }, "letzter_status": { "type": [ "integer", "null" ] }, "fehler": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Nicht angemeldet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "403": { "description": "Recht fehlt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "404": { "description": "Nicht gefunden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } }, "429": { "description": "Rate-Limit überschritten", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fehler" } } } } }, "security": [ { "apiSchluessel": [] }, { "oauth2": [ "schreiben" ] } ] } } }, "webhooks": { "domain.registriert": { "post": { "operationId": "webhookDomainRegistriert", "security": [], "summary": "Domain registriert", "description": "Ereignis `domain.registriert`. Signatur im Header Agile-Signature prüfen.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEreignis" } } } }, "responses": { "200": { "description": "Empfang bestätigt" } } } }, "domain.transfer_status": { "post": { "operationId": "webhookDomainTransferStatus", "security": [], "summary": "Transfer-Status geändert", "description": "Ereignis `domain.transfer_status`. Signatur im Header Agile-Signature prüfen.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEreignis" } } } }, "responses": { "200": { "description": "Empfang bestätigt" } } } }, "domain.ablauf_naht": { "post": { "operationId": "webhookDomainAblaufNaht", "security": [], "summary": "Ablauf naht", "description": "Ereignis `domain.ablauf_naht`. Signatur im Header Agile-Signature prüfen.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEreignis" } } } }, "responses": { "200": { "description": "Empfang bestätigt" } } } }, "dns.geaendert": { "post": { "operationId": "webhookDnsGeaendert", "security": [], "summary": "DNS geändert", "description": "Ereignis `dns.geaendert`. Signatur im Header Agile-Signature prüfen.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEreignis" } } } }, "responses": { "200": { "description": "Empfang bestätigt" } } } }, "zahlung.fehlgeschlagen": { "post": { "operationId": "webhookZahlungFehlgeschlagen", "security": [], "summary": "Zahlung fehlgeschlagen", "description": "Ereignis `zahlung.fehlgeschlagen`. Signatur im Header Agile-Signature prüfen.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEreignis" } } } }, "responses": { "200": { "description": "Empfang bestätigt" } } } }, "bestellung.ausgefuehrt": { "post": { "operationId": "webhookBestellungAusgefuehrt", "security": [], "summary": "Bestellung ausgeführt", "description": "Ereignis `bestellung.ausgefuehrt`. Signatur im Header Agile-Signature prüfen.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEreignis" } } } }, "responses": { "200": { "description": "Empfang bestätigt" } } } } }, "components": { "schemas": { "Fehler": { "type": "object", "required": [ "fehler" ], "properties": { "fehler": { "type": "object", "required": [ "code", "nachricht" ], "properties": { "code": { "type": "string", "description": "Maschinenlesbarer Code, z. B. anmeldung, recht, eingabe, limit" }, "nachricht": { "type": "string" }, "details": {} } } }, "example": { "fehler": { "code": "recht", "nachricht": "Diesem Zugang fehlt das Recht „dns:schreiben“.", "details": { "benoetigt": "dns:schreiben" } } } }, "Seite": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "gesamt": { "type": "integer" } } }, "Domain": { "type": "object", "description": "Domain im Konto", "properties": { "name": { "type": "string" }, "unicode": { "type": "string" }, "endung": { "type": "string" }, "status": { "type": "string", "enum": [ "registrierung_laeuft", "aktiv", "transfer_laeuft", "transfer_fehler", "abgelaufen", "wiederherstellbar", "ausgezogen", "fehler" ] }, "laeuft_bis": { "type": [ "string", "null" ], "format": "date-time" }, "registriert_seit": { "type": [ "string", "null" ], "format": "date-time" }, "auto_verlaengerung": { "type": "boolean" }, "transfersperre": { "type": "boolean" }, "whois_datenschutz": { "type": "boolean" }, "dns_modus": { "type": "string", "enum": [ "agile", "extern" ] }, "nameserver": { "type": "array", "items": { "type": "string" } } }, "example": { "name": "beispiel.de", "unicode": "beispiel.de", "endung": "de", "status": "aktiv", "laeuft_bis": "2027-10-10T12:00:00.000Z", "registriert_seit": "2026-10-10T12:00:00.000Z", "auto_verlaengerung": true, "transfersperre": true, "whois_datenschutz": false, "dns_modus": "agile", "nameserver": [ "ns1.openprovider.nl", "ns2.openprovider.be", "ns3.openprovider.eu" ] } }, "DomainDetail": { "allOf": [ { "$ref": "#/components/schemas/Domain" }, { "type": "object", "properties": { "dnssec": { "type": "array", "items": { "$ref": "#/components/schemas/DnssecSchluessel" } }, "kontakte": { "type": "object", "properties": { "inhaber": { "type": "string" }, "admin": { "type": "string" }, "technik": { "type": "string" }, "rechnung": { "type": "string" } } }, "inhaberwechsel_sperre_bis": { "type": [ "string", "null" ] }, "transfer_status": { "type": [ "string", "null" ] }, "dns": { "type": "array", "items": { "$ref": "#/components/schemas/DnsEintrag" } }, "weiterleitungen": { "type": "array", "items": { "$ref": "#/components/schemas/Weiterleitung" } }, "whois_datenschutz_moeglich": { "type": "boolean" }, "dnssec_moeglich": { "type": "boolean" }, "agile_nameserver": { "type": "array", "items": { "type": "string" } } } } ] }, "DnsEintrag": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "typ": { "type": "string" }, "name": { "type": "string" }, "wert": { "type": "string" }, "ttl": { "type": "integer" }, "prioritaet": { "type": [ "integer", "null" ] } }, "example": { "id": "6f1c2c0e-2a6b-4a77-9a55-1f9d5d3b1a11", "typ": "A", "name": "www", "wert": "203.0.113.10", "ttl": 3600, "prioritaet": null } }, "DnsEingabe": { "type": "object", "required": [ "typ", "name", "wert" ], "properties": { "typ": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "MX", "TXT", "SRV", "CAA", "NS", "TLSA", "SSHFP" ] }, "name": { "type": "string", "description": "„@“ für die Domain selbst" }, "wert": { "type": "string" }, "ttl": { "type": "integer", "minimum": 60, "maximum": 86400, "default": 3600 }, "prioritaet": { "type": "integer", "description": "Nur MX und SRV" } } }, "DnssecSchluessel": { "type": "object", "properties": { "flags": { "type": "integer", "enum": [ 256, 257 ] }, "algorithmus": { "type": "integer" }, "oeffentlicher_schluessel": { "type": "string" } } }, "Weiterleitung": { "type": "object", "properties": { "id": { "type": "string" }, "host": { "type": "string" }, "ziel": { "type": "string" }, "code": { "type": "integer" }, "pfad_mitnehmen": { "type": "boolean" } } }, "Vorlage": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "beschreibung": { "type": "string" }, "hinweis": { "type": [ "string", "null" ] } } }, "Suchergebnis": { "type": "object", "properties": { "anfrage": { "type": "string" }, "modus": { "type": "string", "enum": [ "vorschau", "live" ] }, "treffer": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "unicode": { "type": "string" }, "endung": { "type": "string" }, "status": { "type": "string", "enum": [ "frei", "vergeben", "premium", "ungueltig", "unbekannt" ] }, "art": { "type": "string", "enum": [ "exakt", "endung", "vorschlag" ] }, "preis_netto_cent": { "type": [ "integer", "null" ] }, "verlaengerung_netto_cent": { "type": [ "integer", "null" ] } } } } }, "example": { "anfrage": "meine-firma", "modus": "live", "treffer": [ { "domain": "meine-firma.de", "unicode": "meine-firma.de", "endung": "de", "status": "frei", "art": "exakt", "preis_netto_cent": 705, "verlaengerung_netto_cent": 705 } ] } }, "Preisliste": { "type": "object", "properties": { "modus": { "type": "string" }, "endungen": { "type": "array", "items": { "type": "object", "properties": { "endung": { "type": "string" }, "registrierung_netto_cent": { "type": [ "integer", "null" ] }, "verlaengerung_netto_cent": { "type": [ "integer", "null" ] }, "transfer_netto_cent": { "type": [ "integer", "null" ] }, "whois_datenschutz": { "type": "boolean" }, "hinweis": { "type": [ "string", "null" ] } } } } } }, "Konto": { "type": "object", "properties": { "art": { "type": "string" }, "firma": { "type": [ "string", "null" ] }, "vorname": { "type": "string" }, "nachname": { "type": "string" }, "strasse": { "type": "string" }, "plz": { "type": "string" }, "ort": { "type": "string" }, "land": { "type": "string" }, "telefon": { "type": "string" }, "ust_idnr": { "type": [ "string", "null" ] }, "ust_idnr_geprueft": { "type": "boolean" }, "rechnungs_email": { "type": "string" }, "vollstaendig": { "type": "boolean" }, "zahlungsmittel_hinterlegt": { "type": "boolean" } } }, "KontoEingabe": { "type": "object", "required": [ "art", "vorname", "nachname", "strasse", "plz", "ort", "land", "telefon" ], "properties": { "art": { "type": "string", "enum": [ "person", "firma" ] }, "firma": { "type": "string" }, "vorname": { "type": "string" }, "nachname": { "type": "string" }, "strasse": { "type": "string" }, "plz": { "type": "string" }, "ort": { "type": "string" }, "land": { "type": "string", "description": "ISO-Ländercode" }, "telefon": { "type": "string" }, "ust_idnr": { "type": "string" } } }, "Kontakt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "bezeichnung": { "type": "string" }, "art": { "type": "string" }, "firma": { "type": [ "string", "null" ] }, "vorname": { "type": "string" }, "nachname": { "type": "string" }, "strasse": { "type": "string" }, "plz": { "type": "string" }, "ort": { "type": "string" }, "land": { "type": "string" }, "email": { "type": "string" }, "telefon": { "type": "string" } } }, "KontaktEingabe": { "type": "object", "required": [ "art", "vorname", "nachname", "strasse", "plz", "ort", "land", "email", "telefon" ], "properties": { "bezeichnung": { "type": "string" }, "art": { "type": "string", "enum": [ "person", "firma" ] }, "firma": { "type": "string" }, "vorname": { "type": "string" }, "nachname": { "type": "string" }, "strasse": { "type": "string" }, "plz": { "type": "string" }, "ort": { "type": "string" }, "land": { "type": "string" }, "email": { "type": "string", "format": "email" }, "telefon": { "type": "string" } } }, "Bestellung": { "type": "object", "properties": { "id": { "type": "string" }, "nummer": { "type": "string" }, "herkunft": { "type": "string" }, "status": { "type": "string" }, "netto_cent": { "type": "integer" }, "steuer_cent": { "type": "integer" }, "brutto_cent": { "type": "integer" }, "steuer": { "type": "string" }, "rechnungsnummer": { "type": [ "string", "null" ] }, "rechnung_pdf": { "type": [ "string", "null" ] }, "rechnung_online": { "type": [ "string", "null" ] }, "erstellt": { "type": "string" }, "bezahlt": { "type": [ "string", "null" ] }, "positionen": { "type": "array", "items": { "type": "object", "properties": { "art": { "type": "string" }, "domain": { "type": "string" }, "jahre": { "type": "integer" }, "netto_cent": { "type": "integer" }, "status": { "type": "string" }, "fehler": { "type": [ "string", "null" ] } } } } } }, "BestellEingabe": { "type": "object", "required": [ "positionen" ], "properties": { "positionen": { "type": "array", "items": { "type": "object", "required": [ "art", "domain" ], "properties": { "art": { "type": "string", "enum": [ "registrierung", "transfer", "verlaengerung" ] }, "domain": { "type": "string" }, "jahre": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, "auth_code": { "type": "string" }, "whois_datenschutz": { "type": "boolean" } } } }, "bestaetigen": { "type": "boolean", "default": false }, "agb_akzeptiert": { "type": "boolean" }, "widerrufsverzicht": { "type": "boolean" }, "inhaber_kontakt_id": { "type": "string", "format": "uuid" } } }, "BestellAntwort": { "type": "object", "properties": { "bestaetigung_erforderlich": { "type": "boolean" }, "kostenpflichtig": { "type": "boolean" }, "hinweis": { "type": "string" }, "angebot": { "type": "object" }, "bestellung": { "$ref": "#/components/schemas/Bestellung" }, "zahlung": { "type": "object", "properties": { "art": { "type": "string", "enum": [ "abbuchung", "zahlungsseite" ] }, "zahlungslink": { "type": [ "string", "null" ] }, "hinweis": { "type": "string" } } } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "ereignisse": { "type": "array", "items": { "type": "string" } }, "beschreibung": { "type": [ "string", "null" ] }, "aktiv": { "type": "boolean" }, "erstellt": { "type": "string" }, "fehlgeschlagen": { "type": "integer" } } }, "Zustellung": { "type": "object", "properties": { "id": { "type": "string" }, "ereignis_id": { "type": "string" }, "typ": { "type": "string" }, "status": { "type": "string", "enum": [ "offen", "zugestellt", "fehlgeschlagen" ] }, "versuche": { "type": "integer" }, "letzter_status": { "type": [ "integer", "null" ] }, "fehler": { "type": [ "string", "null" ] }, "erstellt": { "type": "string" }, "zugestellt": { "type": [ "string", "null" ] }, "naechster_versuch": { "type": [ "string", "null" ] } } }, "WebhookEreignis": { "type": "object", "description": "Body jeder Webhook-Zustellung", "properties": { "id": { "type": "string", "format": "uuid" }, "typ": { "type": "string", "enum": [ "domain.registriert", "domain.transfer_status", "domain.ablauf_naht", "dns.geaendert", "zahlung.fehlgeschlagen", "bestellung.ausgefuehrt" ] }, "erstellt": { "type": "string", "format": "date-time" }, "daten": { "type": "object" } }, "example": { "id": "9b1f…", "typ": "domain.registriert", "erstellt": "2026-10-10T12:00:00Z", "daten": { "domain": "beispiel.de", "status": "aktiv", "laeuft_bis": "2027-10-10T12:00:00Z", "bestellung": "AD-2026-00042" } } } }, "securitySchemes": { "apiSchluessel": { "type": "http", "scheme": "bearer", "bearerFormat": "agile_dom_…", "description": "API-Schlüssel aus dem Kundenbereich (API und Webhooks)." }, "oauth2": { "type": "oauth2", "description": "Authorization Code mit PKCE (S256). Clients registrieren sich dynamisch unter /oauth/register.", "flows": { "authorizationCode": { "authorizationUrl": "https://domain.agiledeveloper.de/oauth/authorize", "tokenUrl": "https://domain.agiledeveloper.de/oauth/token", "refreshUrl": "https://domain.agiledeveloper.de/oauth/token", "scopes": { "lesen": "Lesen", "schreiben": "Ändern", "kaufen": "Kostenpflichtig bestellen" } } } } } } }