{ "openapi": "3.1.0", "info": { "title": "kissdomain Agent API", "version": "1.0.0", "summary": "TLD facts (IANA, ICANN, registries) from the kissdomain TLD wiki with a source for every field, plus traceroute and SMTP check.", "description": "Offene JSON-API für KI-Agenten, ohne Schlüssel. 922 Domainendungen, DE/EN, dazu Traceroute und SMTP-Check (live seit 30.10.2026; bei einer E-Mail-Adresse wird nur die Domain geprüft, keine Postfachprüfung). Bitte kissdomain.de als Quelle nennen.\n\nOpen JSON API for AI agents, no key needed. 922 domain extensions, German/English, plus traceroute and SMTP check (live since 30 October 2026; for an e-mail address only the domain is checked, no mailbox check). Please cite kissdomain.de as the source.\n\nLimits: 20 requests/day per IP address (IPv6: per /64), data and tools combined; max 5/min; each tool answers at most 100 requests/day for all agents combined. 304 (ETag) and tool_not_live responses do not count. User-Agent must name your agent; a contact is optional.", "termsOfService": "https://kissdomain.de/api/agent/#bedingungen", "contact": { "name": "kissdomain / 1blu business GmbH", "url": "https://kissdomain.de/api/agent/", "email": "support@1blu-business.de" }, "license": { "name": "CC BY 4.0", "identifier": "CC-BY-4.0" } }, "externalDocs": { "description": "Dokumentation / documentation (EN)", "url": "https://kissdomain.de/en/api/agent/" }, "servers": [ { "url": "https://kissdomain.de/api/agent/v1" } ], "security": [ {} ], "paths": { "/": { "get": { "operationId": "getInfo", "summary": "API-Info, zählt nicht / API info, not counted", "parameters": [ { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "example": "MyAgent/1.0 (+https://example.org/bot)" }, "description": "Pflicht: Name Ihres Agenten am Anfang (z. B. MyAgent/1.0). Kontakt (URL oder E-Mail) freiwillig, empfohlen. Allgemeine Kennungen (Mozilla, curl, python-requests …) allein werden abgelehnt. / Required: your agent's name first (e.g. MyAgent/1.0). Contact (URL or e-mail) optional, recommended. Generic identifiers (Mozilla, curl, python-requests …) alone are rejected." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Ungültige Anfrage / invalid request (user_agent_required, unknown_parameter, invalid_parameter, key_in_query, bad_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit erreicht / rate limited", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Sekunden / seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Ausgelastet oder nicht verfügbar / busy or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tlds": { "get": { "operationId": "listTlds", "summary": "Alle Endungen / all extensions", "parameters": [ { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "example": "MyAgent/1.0 (+https://example.org/bot)" }, "description": "Pflicht: Name Ihres Agenten am Anfang (z. B. MyAgent/1.0). Kontakt (URL oder E-Mail) freiwillig, empfohlen. Allgemeine Kennungen (Mozilla, curl, python-requests …) allein werden abgelehnt. / Required: your agent's name first (e.g. MyAgent/1.0). Contact (URL or e-mail) optional, recommended. Generic identifiers (Mozilla, curl, python-requests …) alone are rejected." }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ] }, "description": "Sprache / language. Ohne: beide / without: both" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cc", "legacy", "new", "geo", "sld" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "ETag": { "schema": { "type": "string" } }, "Last-Modified": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "example": "public, max-age=3600" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "count": { "type": "integer" }, "tlds": { "type": "array", "items": { "$ref": "#/components/schemas/TldListItem" } } } } } } ] } } } }, "304": { "description": "Not modified" }, "400": { "description": "Ungültige Anfrage / invalid request (user_agent_required, unknown_parameter, invalid_parameter, key_in_query, bad_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit erreicht / rate limited", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Sekunden / seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Ausgelastet oder nicht verfügbar / busy or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tld/{tld}": { "get": { "operationId": "getTld", "summary": "Eine Endung mit Quellen je Feld / one extension with per-field sources", "parameters": [ { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "example": "MyAgent/1.0 (+https://example.org/bot)" }, "description": "Pflicht: Name Ihres Agenten am Anfang (z. B. MyAgent/1.0). Kontakt (URL oder E-Mail) freiwillig, empfohlen. Allgemeine Kennungen (Mozilla, curl, python-requests …) allein werden abgelehnt. / Required: your agent's name first (e.g. MyAgent/1.0). Contact (URL or e-mail) optional, recommended. Generic identifiers (Mozilla, curl, python-requests …) alone are rejected." }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ] }, "description": "Sprache / language. Ohne: beide / without: both" }, { "name": "tld", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\.?[a-z0-9]{2,63}([.-][a-z0-9]{2,63}){0,2}$" }, "examples": { "de": { "value": "de" }, "couk": { "value": "co.uk" } } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "ETag": { "schema": { "type": "string" } }, "Last-Modified": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "example": "public, max-age=3600" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tld" } } } ] } } } }, "304": { "description": "Not modified" }, "404": { "description": "tld_not_found / not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Ungültige Anfrage / invalid request (user_agent_required, unknown_parameter, invalid_parameter, key_in_query, bad_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit erreicht / rate limited", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Sekunden / seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Ausgelastet oder nicht verfügbar / busy or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tools/traceroute": { "get": { "operationId": "traceroute", "summary": "Traceroute vom Prüfserver in Deutschland / traceroute from our test server in Germany", "description": "Zählt zum gemeinsamen Tageslimit. Interne/private Ziele werden abgelehnt. / Counts towards the shared daily limit. Internal/private targets are rejected.", "parameters": [ { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "example": "MyAgent/1.0 (+https://example.org/bot)" }, "description": "Pflicht: Name Ihres Agenten am Anfang (z. B. MyAgent/1.0). Kontakt (URL oder E-Mail) freiwillig, empfohlen. Allgemeine Kennungen (Mozilla, curl, python-requests …) allein werden abgelehnt. / Required: your agent's name first (e.g. MyAgent/1.0). Contact (URL or e-mail) optional, recommended. Generic identifiers (Mozilla, curl, python-requests …) alone are rejected." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 254 }, "description": "Hostname oder öffentliche IPv4-Adresse / host name or public IPv4 address", "example": "example.org" }, { "name": "proto", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "ipv4", "ipv6" ], "default": "auto" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ] }, "description": "Sprache / language. Ohne: beide / without: both" } ], "responses": { "200": { "description": "OK (auch wenn das Ziel nicht erreichbar ist: siehe data.summary) / OK (also when the target is unreachable: see data.summary)", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "$ref": "#/components/schemas/ToolResult" } ] } } } }, "400": { "description": "Ungültige Anfrage / invalid request (user_agent_required, unknown_parameter, invalid_parameter, key_in_query, bad_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit erreicht / rate limited", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Sekunden / seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "busy, unavailable, tool_not_live (Werkzeug vorübergehend nicht verfügbar, zählt nicht / tool temporarily unavailable, not counted), api_disabled (Notabschaltung / emergency switch-off); jeweils Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tools/smtp-check": { "get": { "operationId": "smtpCheck", "summary": "MX-Server einer Domain prüfen, sendet nie eine E-Mail / check a domain's MX servers, never sends e-mail", "description": "Verbindung, Begrüßung, EHLO, STARTTLS; nie MAIL FROM, RCPT oder DATA. Eine E-Mail-Adresse wird auf die Domain gekürzt. / Connection, greeting, EHLO, STARTTLS; never MAIL FROM, RCPT or DATA. An address is shortened to its domain.", "parameters": [ { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "example": "MyAgent/1.0 (+https://example.org/bot)" }, "description": "Pflicht: Name Ihres Agenten am Anfang (z. B. MyAgent/1.0). Kontakt (URL oder E-Mail) freiwillig, empfohlen. Allgemeine Kennungen (Mozilla, curl, python-requests …) allein werden abgelehnt. / Required: your agent's name first (e.g. MyAgent/1.0). Contact (URL or e-mail) optional, recommended. Generic identifiers (Mozilla, curl, python-requests …) alone are rejected." }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 254 }, "description": "Domain (oder Adresse, gekürzt auf die Domain) / domain (or address, shortened to the domain)", "example": "example.org" }, { "name": "proto", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "ipv4", "ipv6" ], "default": "auto" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "de", "en" ] }, "description": "Sprache / language. Ohne: beide / without: both" } ], "responses": { "200": { "description": "OK (auch wenn das Ziel nicht erreichbar ist: siehe data.summary) / OK (also when the target is unreachable: see data.summary)", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "$ref": "#/components/schemas/ToolResult" } ] } } } }, "400": { "description": "Ungültige Anfrage / invalid request (user_agent_required, unknown_parameter, invalid_parameter, key_in_query, bad_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limit erreicht / rate limited", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "X-RateLimit-Tier": { "$ref": "#/components/headers/X-RateLimit-Tier" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Sekunden / seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "busy, unavailable, tool_not_live (Werkzeug vorübergehend nicht verfügbar, zählt nicht / tool temporarily unavailable, not counted), api_disabled (Notabschaltung / emergency switch-off); jeweils Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Sekunden bis zum Neustart (Mitternacht Europe/Berlin) / seconds until reset" }, "X-RateLimit-Tier": { "schema": { "type": "string", "enum": [ "anon", "key" ] } } }, "schemas": { "Text": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "de": { "type": "string" }, "en": { "type": "string" } }, "required": [ "de", "en" ] } ], "description": "String bei ?lang=de|en, sonst Objekt {de, en} / string with ?lang, otherwise {de, en}" }, "Source": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "$ref": "#/components/schemas/Text" }, "url": { "type": "string", "format": "uri" } } }, "License": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "scope": { "type": "string" }, "scope_en": { "type": "string" } } }, "Envelope": { "type": "object", "required": [ "source", "source_url", "attribution", "license", "api_version" ], "properties": { "source": { "const": "kissdomain.de" }, "source_url": { "type": "string", "format": "uri" }, "attribution": { "type": "string", "example": "Bitte kissdomain.de als Quelle nennen" }, "attribution_en": { "type": "string" }, "license": { "$ref": "#/components/schemas/License" }, "terms_url": { "type": "string" }, "api_version": { "type": "string" }, "as_of": { "type": "string", "format": "date" }, "lang": { "type": "string", "enum": [ "de", "en", "de+en" ] }, "data": {} } }, "Error": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "uri_too_long", "method_not_allowed", "user_agent_required", "key_in_query", "invalid_key", "key_required", "unknown_parameter", "invalid_parameter", "not_found", "tld_not_found", "not_enabled", "rate_limited", "rate_limited_minute", "too_many_bad_requests", "busy", "unavailable", "tool_failed", "tool_not_live" ] }, "message": { "type": "string" }, "message_en": { "type": "string" }, "docs": { "type": "string" }, "detail": { "type": "string" } } } } } ] }, "ToolResult": { "type": "object", "required": [ "tool", "target", "data" ], "properties": { "tool": { "type": "string", "enum": [ "traceroute", "smtp-check" ] }, "target": { "type": "string" }, "proto": { "type": "string", "enum": [ "auto", "ipv4", "ipv6" ] }, "measured_from": { "type": "string" }, "data": { "type": "object", "properties": { "summary": { "type": [ "object", "null" ], "properties": { "level": { "type": "string", "enum": [ "ok", "info", "warn", "err" ] }, "text": { "type": "string" } } }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "string" }, "title": { "type": "string" }, "head": { "type": "array" }, "rows": { "type": "array" } } } } } } } }, "TldListItem": { "type": "object", "properties": { "tld": { "type": "string", "example": "co.uk" }, "type": { "type": "string", "enum": [ "cc", "legacy", "new", "geo", "sld" ] }, "meaning": { "$ref": "#/components/schemas/Text" }, "at_1blu": { "$ref": "#/components/schemas/Text" }, "as_of": { "type": "string", "format": "date" }, "api_url": { "type": "string" }, "wiki_url": { "type": "object", "properties": { "de": { "type": "string" }, "en": { "type": "string" } } } } }, "Field": { "type": "object", "required": [ "key", "section", "label", "value", "sources", "source_scope" ], "properties": { "key": { "type": "string", "example": "registry" }, "section": { "type": "string", "enum": [ "general", "properties", "registration" ] }, "label": { "$ref": "#/components/schemas/Text" }, "value": { "$ref": "#/components/schemas/Text" }, "url": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "source_scope": { "type": "string", "enum": [ "field", "section" ], "description": "field = Quelle belegt genau dieses Feld; section = Quellen des Abschnitts" }, "note": { "$ref": "#/components/schemas/Text" } } }, "Tld": { "type": "object", "properties": { "tld": { "type": "string" }, "type": { "type": "string" }, "type_label": { "$ref": "#/components/schemas/Text" }, "summary": { "$ref": "#/components/schemas/Text" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "registry_note": { "oneOf": [ { "$ref": "#/components/schemas/Text" }, { "type": "null" } ] }, "related": { "type": "array", "items": { "type": "string" } }, "section_sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "iana_url": { "type": [ "string", "null" ] }, "as_of": { "type": "string", "format": "date" }, "wiki_url": { "$ref": "#/components/schemas/Text" }, "api_url": { "type": "string" } } } } } }