RessourcenAPI v2

Entwicklerdokumentation

Aktuelle Kleinanzeigen-Daten per API abrufen: Suche, Inseratdetails, Verkäufer, Kategorien und Standorte.

Markdown direkt einfügen oder die URL an deine KI schicken.

Schnellstart

Mit der API rufst du aktuelle Kleinanzeigen-Daten direkt in deiner eigenen Anwendung ab: Suche, Inseratdetails, Verkäuferprofile, Verkäufer-Inserate, Kategorien und Standorte. Du arbeitest mit normalen HTTP-Requests und JSON-Antworten.

Was du brauchst

Einen aktiven Kleinanzeigen-Agent Account.
Einen API-Key aus deinem Dashboard.
Ausreichend Credits für die Anfragen, die du ausführen willst.

Basis-URL

https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen

api.kleinanzeigen-agent.de ist die produktive API-Subdomain. Alle Beispiele in der Dokumentation verwenden diese URL.

Erste Suche

curl "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/search?q=iphone&location_id=3331&distance=25" \
  -H "klaz_key: klaz_live_..."

Beispiel in JavaScript

const url = new URL(
  "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/search"
);

url.searchParams.set("q", "iphone");
url.searchParams.set("location_id", "3331");
url.searchParams.set("distance", "25");

const response = await fetch(url, {
  headers: {
    klaz_key: process.env.KLAZ_API_KEY!,
  },
});

const result = await response.json();

Antwort lesen

Jede Antwort hat dieselbe Grundstruktur. Bei einer erfolgreichen Suche findest du die Treffer unter data.ads und Informationen zur Seite unter data.meta.

{
  "success": true,
  "message": "Kleinanzeigen live search completed",
  "data": {
    "meta": {
      "page": 0,
      "size": 31,
      "total": 126,
      "exact_total": true,
      "has_next_page": true,
      "next_page": 1,
      "source": "live"
    },
    "ads": [
      {
        "ad_id": "1234567890",
        "title": "iPhone 15",
        "price": {
          "amount": 650,
          "currency_code": "EUR"
        },
        "ad_url": "https://www.kleinanzeigen.de/..."
      }
    ]
  },
  "request_id": "req_..."
}

request_id ist die ID der Anfrage. Gib sie bei Support-Fragen mit an, damit wir den Request schneller finden können.

Defaults

page startet bei 0. size ist standardmäßig 31 und maximal 100. Alle Parameter und Antwortfelder verwenden snake_case.

Die Suche liefert standardmäßig „Neueste zuerst“, ohne Sortierparameter. sort_type lässt du weg; eine frei wählbare Sortierung wird aktuell nicht unterstützt.

Authentifizierung

Dein API-Key identifiziert deinen Account und ordnet die verbrauchten Credits deinem Guthaben zu. Sende ihn bei jeder API-Anfrage im Header klaz_key.

klaz_key: klaz_live_...

Den MCP Server richtest du am besten mit einem Login im Browser ein. Wenn dein MCP-Client das noch nicht unterstützt, kannst du denselben Key als Bearer Token senden:

Authorization: Bearer klaz_live_...

API-Key verwalten

Du findest deinen API-Key im Dashboard. Der vollständige Key wird nur beim Erstellen oder Rotieren angezeigt. Danach siehst du aus Sicherheitsgründen nur noch eine maskierte Version.

Wenn ein Key versehentlich geteilt wurde, rotiere ihn im Dashboard. Der alte Key wird dadurch ungültig und du erhältst einen neuen.

Sicherer Einsatz

Speichere den Key in deiner Serverumgebung, zum Beispiel als Secret oder Environment Variable. Nutze ihn nicht direkt in öffentlichem Browser-Code und committe ihn nicht in dein Repository.

Sende den Key immer als Header. Verwende ihn nicht als Query-Parameter, weil URLs oft in Logs, Monitoring-Systemen oder Browser-Historien landen.

Typische Auth-Fehler

401 bedeutet, dass der Header fehlt oder der Key ungültig ist. Prüfe in diesem Fall den Headernamen klaz_key, den vollständigen Key-Wert und ob der Key im Dashboard rotiert wurde.

429 bedeutet, dass dein aktuelles Rate Limit erreicht wurde. Reduziere die Anfragefrequenz oder wähle einen Plan mit höherem Limit.

API Referenz

Diese Endpunkte sind für deine Anwendung gedacht. Alle Requests sind GET-Requests, benötigen den Header klaz_key und liefern JSON zurück.

Inserate suchen

GET /api/v2/kleinanzeigen/search

Nutze diesen Endpoint für Suchseiten, Preisvergleiche, Monitoring oder Matching in deiner Anwendung.

Parameter:

q string: Suchbegriff.
page integer, Default 0: Ergebnis-Seite, startet bei 0.
size integer, Default 31: Ergebnisse pro Seite, maximal 100.
category_id string: Kleinanzeigen-Kategorie.
location_id string: Kleinanzeigen-Standort. Nicht zusammen mit latitude und longitude verwenden.
distance string: Umkreis in Kilometern.
min_price integer: Mindestpreis.
max_price integer: Höchstpreis.
picture_required boolean: Nur Inserate mit Bildern.
buy_now_only boolean: Nur Direktkauf-Inserate.
shippable boolean: Nur Inserate mit Versand.
ad_type enum: OFFER oder WANTED. OFFER ist die normale Angebotssuche und wird nicht extra an Kleinanzeigen gesendet. Nur WANTED wird als Gesuch-Filter weitergereicht.
poster_type enum: PRIVATE oder COMMERCIAL.
latitude number: Breitengrad. Nur zusammen mit longitude.
longitude number: Längengrad. Nur zusammen mit latitude.
attr[...] string: Kategorieattribute, zum Beispiel attr[condition]=new.

Die Suche liefert standardmäßig „Neueste zuerst“. Dafür ist kein Sortierparameter nötig. Eine andere Sortierung per sort_type ist aktuell nicht verfügbar; die API antwortet mit 400, wenn der Parameter gesendet wird.

curl "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/search?q=sofa&min_price=50&max_price=300&picture_required=true" \
  -H "klaz_key: klaz_live_..."

Die Antwort enthält data.meta und data.ads. data.meta enthält page, size, total, exact_total, has_next_page, next_page und source; Paging bleibt damit auf unserer API-Oberfläche und enthält keine Upstream-URLs. Jedes Inserat kommt in einem konsistenten Format zurück. shipping_available ist true, false oder null, wenn Kleinanzeigen in der Antwort kein zuverlässiges Versandsignal liefert; shippable=true filtert trotzdem serverseitig bei Kleinanzeigen.

{
  "ad_id": "1234567890",
  "title": "Sofa",
  "description": "Guter Zustand",
  "price": {
    "amount": 120,
    "currency_code": "EUR",
    "currency_label": "Euro",
    "price_type": "FIXED",
    "negotiable": false
  },
  "shipping_available": true,
  "buy_now_available": false,
  "images": [],
  "ad_url": "https://www.kleinanzeigen.de/...",
  "views": null,
  "created_at": "2026-05-04T10:00:00.000Z",
  "status": "ACTIVE",
  "deleted": false,
  "seller": {
    "seller_id": "abc123",
    "name": "Max",
    "type": "PRIVATE"
  },
  "location": {
    "id": "3331",
    "name": "Berlin",
    "city": "Berlin"
  },
  "category": {
    "id": "88",
    "name": "Sofas",
    "parent_id": "80"
  },
  "attributes": [],
  "details": {}
}

Kleinanzeigen liefert in Suchantworten oft keine user-id. seller.seller_id kann deshalb bei /search null sein; nutze GET /api/v2/kleinanzeigen/ads/:ad_id, wenn du die Verkäufer-ID zuverlässig brauchst. Weitere Inserate desselben Verkäufers bekommst du auch direkt über GET /api/v2/kleinanzeigen/ads/:ad_id/seller-ads.

Genau diese Filter kannst du auch für Webhooks verwenden. Wir fragen die Live-Suche im gebuchten Intervall automatisch für dich ab und schicken dir jedes passende Inserat genau einmal.

Treffer pro Kategorie

GET /api/v2/kleinanzeigen/search/category-counts

Zeigt, wie viele Inserate eine Suche in jeder Kategorie findet, ohne dafür Inserate zu laden. Nutze den Endpoint für Marktanalysen, um das Angebot zu einem Produkt einzuschätzen, oder um eine Suche gezielt in die passende Kategorie zu lenken.

Parameter: dieselben Filter wie bei der Suche, also q, category_id, location_id, distance, min_price, max_price, picture_required, buy_now_only, shippable, ad_type, poster_type, latitude, longitude und attr[...]. page und size entfallen.

curl "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/search/category-counts?q=iphone%2015" \
  -H "klaz_key: klaz_live_..."

{
  "success": true,
  "message": "Kleinanzeigen search category counts fetched",
  "data": {
    "meta": {
      "total": 21258,
      "exact_total": true,
      "source": "live"
    },
    "categories": [
      { "category_id": "161", "name": "Elektronik", "parent_id": "0", "count": 20541 },
      { "category_id": "153", "name": "Mode & Beauty", "parent_id": "0", "count": 525 },
      { "category_id": "297", "name": "Dienstleistungen", "parent_id": "0", "count": 274 }
    ]
  },
  "request_id": "req_..."
}

Die Kategorien sind nach Trefferzahl absteigend sortiert. Ohne category_id bekommst du die Hauptkategorien. Setzt du category_id, enthält die Liste diese Kategorie selbst und ihre direkten Unterkategorien, zum Beispiel mit category_id=161 die Kategorie Elektronik mit ihrer Gesamtzahl und darunter Smartphones, Wearables und weitere Unterkategorien. So kannst du Schritt für Schritt tiefer gehen.

Inseratdetails abrufen

GET /api/v2/kleinanzeigen/ads/:ad_id

Parameter:

ad_id numeric string, erforderlich: Kleinanzeigen-Inserat-ID im Pfad.
include_views boolean, Default false: Lädt zusätzlich die Aufrufzahl und berechnet einen Extra-Credit.

curl "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/ads/1234567890?include_views=true" \
  -H "klaz_key: klaz_live_..."

Antwort:

{
  "success": true,
  "message": "Kleinanzeigen ad fetched",
  "data": {
    "source": "live",
    "ad": {
      "ad_id": "1234567890",
      "title": "Sofa",
      "views": 42
    }
  },
  "request_id": "req_..."
}

Inseratstatus prüfen

GET /api/v2/kleinanzeigen/ads/:ad_id/status

Nutze diesen Endpoint, wenn du nur wissen willst, ob ein Inserat noch aktiv ist. include_views=true ist auch hier möglich.

{
  "success": true,
  "data": {
    "source": "live",
    "status": {
      "ad_id": "1234567890",
      "status": "ACTIVE",
      "deleted": false,
      "views": null
    }
  },
  "request_id": "req_..."
}

Weitere Inserate zum Verkäufer eines Inserats

GET /api/v2/kleinanzeigen/ads/:ad_id/seller-ads

Liefert bis zu 30 weitere Inserate vom Verkäufer eines Inserats. Dafür reicht die Inserat-ID. Das ist praktisch bei Suchergebnissen, in denen Kleinanzeigen keine seller_id mitliefert.

Parameter:

ad_id numeric string, erforderlich: Kleinanzeigen-Inserat-ID im Pfad.

curl "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/ads/1234567890/seller-ads" \
  -H "klaz_key: klaz_live_..."

{
  "success": true,
  "message": "Kleinanzeigen seller ads for ad fetched",
  "data": {
    "meta": {
      "ad_id": "1234567890",
      "total": 70,
      "has_more": true,
      "source": "live"
    },
    "ads": []
  },
  "request_id": "req_..."
}

Das Ausgangsinserat selbst ist nicht in der Liste. meta.total ist die Gesamtzahl der weiteren Inserate des Verkäufers, meta.has_more ist true, wenn es mehr als die gelieferten 30 gibt. Für alle Inserate mit Paging nimmst du ads[0].seller.seller_id und rufst damit GET /api/v2/kleinanzeigen/sellers/:seller_id/ads auf.

Verkäuferprofil abrufen

GET /api/v2/kleinanzeigen/sellers/:seller_id/profile

Parameter:

seller_id string, erforderlich: Verkäufer-ID aus ad.seller.seller_id.

Die Antwort nutzt das echte öffentliche Kleinanzeigen-Profil. Sie ist nicht aus den Inseraten zusammengesetzt. Je nach Verkäufer kann Kleinanzeigen einzelne Felder weglassen; deshalb sind viele Felder nullable.

{
  "success": true,
  "data": {
    "source": "live",
    "profile": {
      "seller_id": "12345678",
      "name": "Max",
      "initials": "M",
      "type": "PRIVATE",
      "account_type": "PRIVATE",
      "since": "2021-03-12T10:15:30.000Z",
      "counters": {
        "historical_ads": 120,
        "online_ads": 8,
        "followers": 4,
        "following": 0
      },
      "ratings": {
        "average_rating": 4.8
      },
      "badges": [
        {
          "name": "friendly",
          "level": 1,
          "value": null
        }
      ],
      "biz_branding": null
    }
  },
  "request_id": "req_..."
}

Weitere Inserate eines Verkäufers

GET /api/v2/kleinanzeigen/sellers/:seller_id/ads

Parameter:

seller_id string, erforderlich: Verkäufer-ID aus ad.seller.seller_id.
page integer, Default 0: Ergebnis-Seite.
size integer, Default 31: Ergebnisse pro Seite, maximal 100.

Die Antwort entspricht der Suchantwort mit data.meta und data.ads.

Kategorien

GET /api/v2/kleinanzeigen/categories
GET /api/v2/kleinanzeigen/categories/:category_id/metadata
GET /api/v2/kleinanzeigen/categories/:category_id/search-metadata

Nutze Kategorien, um Suchanfragen genauer einzugrenzen und passende Filter für deine Oberfläche zu bauen.

/categories liefert den Kategoriebaum. metadata liefert verfügbare Felder für eine Kategorie. search-metadata liefert Suchfilter und Attribute, die du für attr[...] verwenden kannst.

curl "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/categories/161/search-metadata" \
  -H "klaz_key: klaz_live_..."

Standorte

GET /api/v2/kleinanzeigen/locations
GET /api/v2/kleinanzeigen/locations/:location_id

Parameter:

q string: Standortsuche nach Name oder PLZ.
latitude number: Breitengrad. Nur zusammen mit longitude.
longitude number: Längengrad. Nur zusammen mit latitude.
limit integer, Default 100: Maximale Anzahl normalisierter Standorte, maximal 500.

curl "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/locations?q=Berlin&limit=10" \
  -H "klaz_key: klaz_live_..."

Nutze Standorte für Autocomplete, regionale Suchen und Umkreissuchen. Die Standortliste wird flach zurückgegeben, damit du sie direkt in Suchfeldern oder Matchern verwenden kannst.

Kleinanzeigen Historie

GET /api/v2/kleinanzeigen/history

Die Historie ist unser Archiv für Marktanalysen. Kleinanzeigen zeigt nur, was gerade online ist. Seit dem 21. Oktober 2026 erfassen wir deshalb laufend jedes Inserat, das in ganz Deutschland neu erscheint oder hochgeschoben wird, und speichern es dauerhaft. Das Archiv wächst jeden Tag. Daten von vor dem 21. Oktober 2026 gibt es nicht.

Typische Anwendungen:

Preisentwicklung eines Produkts über Wochen und Monate, zum Beispiel gebrauchte E-Bike-Akkus oder Smartphones.
Angebotsmenge pro Kategorie oder Region verfolgen.
Anteil privater und gewerblicher Anbieter vergleichen.
Eigene Dashboards und Preisempfehlungen mit echten Marktdaten füttern.

Parameter

q string: Suchbegriffe im Titel. Alle Wörter müssen vorkommen, Groß- und Kleinschreibung spielt keine Rolle. Erlaubt sind Buchstaben, Ziffern, Leerzeichen und . , : / + & -, maximal 8 Wörter.
category_id string: Kategorie-ID. Trifft die Kategorie selbst und, bei einer Hauptkategorie, alle direkten Unterkategorien.
poster_type enum: PRIVATE oder COMMERCIAL.
min_price integer: Mindestpreis in Euro.
max_price integer: Höchstpreis in Euro.
zip string: PLZ oder PLZ-Anfang, zum Beispiel 10 für Berlin oder 80331 für eine einzelne PLZ.
from string: Beginn des Zeitraums als ISO-Datum (2026-11-01) oder ISO-Zeitpunkt. Default: 30 Tage vor to.
to string: Ende des Zeitraums. Default: jetzt. Ein Zeitraum darf höchstens 366 Tage umfassen.
size integer, Default 50: Treffer pro Seite, maximal 1000.
cursor string: data.meta.next_cursor der vorherigen Antwort, um die nächste Seite zu laden.

Kosten

Die erste Seite kostet 20 Credits pro angefangene 30 Tage des abgefragten Zeitraums. Je länger der Zeitraum, desto mehr Daten durchsuchen wir für dich.

Zeitraum	Credits
bis 30 Tage (Default)	`20`
bis 90 Tage	`60`
bis 180 Tage	`120`
366 Tage	`260`

Jede Folgeseite mit cursor kostet 20 Credits. Dafür durchsuchen wir höchstens die 30 Tage vor dem Cursor. Ein ganzes Jahr zu einem Produkt mit rund 1.000 Treffern pro Tag sind mit size=1000 etwa 365 Seiten: 260 Credits für die erste und 20 für jede weitere Seite, zusammen rund 7.540 Credits. Was eine Anfrage gekostet hat, steht in data.meta.credits_charged. Schlägt eine Abfrage fehl, berechnen wir nichts.

Beispiel

curl "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/history?q=bosch%20powertube%20625&from=2026-10-21&size=100" \
  -H "klaz_key: klaz_live_..."

{
  "success": true,
  "message": "Kleinanzeigen history search completed",
  "data": {
    "meta": {
      "size": 100,
      "from": "2026-10-21T00:00:00.000Z",
      "to": "2026-11-15T09:15:00.000Z",
      "has_next_page": true,
      "next_cursor": "eyJvIjoi...",
      "credits_charged": 20,
      "source": "history"
    },
    "ads": [
      {
        "ad_id": "3547540813",
        "listing_key": "5f0c7d3e9a1b2c4d6e8f0a1b2c3d4e5f",
        "title": "Bosch PowerTube 625 Akku",
        "price": { "amount": 290, "price_type": "NEGOTIABLE", "negotiable": true },
        "category": { "id": "217", "name": "Fahrräder & Zubehör", "parent_id": "210" },
        "location": { "zip": "10115", "city": "Berlin", "state": "Berlin" },
        "poster_type": "PRIVATE",
        "shipping_available": true,
        "buy_now_available": false,
        "details": { "Art": "Zubehör", "Zustand": "Gut" },
        "published_at": "2026-11-14T11:08:56.000Z",
        "observed_at": "2026-11-14T11:08:57.250Z"
      }
    ]
  },
  "request_id": "req_..."
}

So liest du die Treffer

Jeder Treffer ist eine Beobachtung: ein Inserat zu dem Zeitpunkt, an dem es auf Kleinanzeigen erschienen ist. Wird dasselbe Inserat später hochgeschoben, bekommst du eine weitere Beobachtung, oft mit neuem Preis. So siehst du Preisänderungen über die Zeit.

published_at ist der Veröffentlichungszeitpunkt laut Kleinanzeigen. Nach dem Hochschieben ist das das neue Datum.
observed_at ist der Zeitpunkt unserer Erfassung. Danach sind die Treffer absteigend sortiert, die neuesten zuerst.
listing_key hält ein Inserat über alle Beobachtungen zusammen. Kleinanzeigen vergibt Inserat-IDs mehrfach an völlig verschiedene Inserate. Gruppiere deshalb immer über listing_key und nie über ad_id. Ändert der Verkäufer den Titel, beginnt ein neuer listing_key.
details enthält die Kategoriemerkmale als Text, zum Beispiel Zustand oder Art.

Für eine Preisentwicklung pro Monat holst du alle Seiten eines Zeitraums, nimmst pro listing_key und Monat die letzte Beobachtung und bildest daraus zum Beispiel Median und Anzahl. Für einen Überblick reicht oft schon ein kurzer Zeitraum mit size=100.

Alle Seiten laden

let cursor;
const observations = [];
do {
  const params = new URLSearchParams({ q: "iphone 15", from: "2026-11-01", size: "1000" });
  if (cursor) params.set("cursor", cursor);
  const response = await fetch(`https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/history?${params}`, {
    headers: { klaz_key: process.env.KLAZ_KEY },
  });
  const { data } = await response.json();
  observations.push(...data.ads);
  cursor = data.meta.next_cursor;
} while (cursor);

Lass from und die anderen Filter auf allen Seiten gleich und ändere nur cursor. Eine Folgeseite kann weniger Treffer als size enthalten oder leer sein, wenn in den 30 Tagen vor dem Cursor wenig erschienen ist. Lade deshalb weiter, bis next_cursor null ist.

Was die Historie nicht enthält

Beschreibungen, Bilder, Verkäufernamen und Verkäufer-IDs speichern wir nicht. Ob und wann ein Inserat beendet oder verkauft wurde, ist ebenfalls nicht enthalten. Für den aktuellen Stand eines einzelnen Inserats nutzt du GET /api/v2/kleinanzeigen/ads/:ad_id/status.

Die Daten darfst du für eigene Marktanalysen und Preisentscheidungen nutzen. Eine Weitergabe als Rohdaten an Dritte ist nach unseren AGB nicht gestattet.

Fehler

Zusätzlich zu den allgemeinen Fehlercodes:

HISTORY_UNAVAILABLE (HTTP 503): Die Historie ist kurzzeitig nicht erreichbar.
HISTORY_QUERY_FAILED (HTTP 502): Die Archivabfrage ist fehlgeschlagen. Versuche es erneut.

In beiden Fällen berechnen wir keine Credits.

Konto-API

Mit der Konto-API liest dein Programm die Chats deines eigenen Kleinanzeigen-Kontos und sendet Nachrichten in deinem Namen. Du richtest sie einmalig im Bereich Konto-API ein. Danach reicht dein gewohnter API-Schlüssel im Header klaz_key.

Konto-API-Zugang erforderlich. Die Konto-API ist in der Beta und für alle Konten verfügbar. Du brauchst ein verbundenes Kleinanzeigen-Konto und den Konto-API-Zugang für 9,90 € netto im Monat. Die einzelnen Aktionen werden zusätzlich in Credits berechnet.

Was du heute schon machen kannst

Alle Chats deines Kontos abrufen, mit ungelesenen Nachrichten und Vorschau.
Einen Chat öffnen und alle Nachrichten lesen.
Auf Nachrichten antworten.
Einen neuen Chat zu einem Inserat starten.

Inserate bereitest du als Entwurf vor und überträgst sie in deine Kleinanzeigen-App, siehe Inserate erstellen.

Hinweis zur Beta

Die Konto-API ist in der Beta. Wir tun viel dafür, dass alles zuverlässig läuft, können aber nicht vorhersagen, wie Kleinanzeigen auf die Nutzung reagiert. Kleinanzeigen kann Funktionen ändern und Konten prüfen, einschränken oder sperren. Wir empfehlen deshalb ein neu angelegtes Kleinanzeigen-Konto ohne Historie statt deines persönlichen Hauptkontos. Wir überwachen die Nutzung anhand von Anfrage-Metadaten, um Missbrauch wie Spam oder Massennachrichten zu verhindern. Details stehen in den AGB unter §9a.

Einrichtung

Alle Schritte findest du in der App unter Konto-API:

Buche deinen Konto-API-Zugang. Wir richten dir automatisch eine feste IP-Adresse in Deutschland ein. Das dauert meist ein paar Minuten.
Installiere die Login-Erweiterung für Chrome.
Melde dich direkt bei Kleinanzeigen an. Dein Passwort gibst du nur dort ein. Die Erweiterung brauchst du danach erst wieder, wenn Kleinanzeigen eine neue Anmeldung verlangt.

Sobald alle drei Schritte erledigt sind, zeigt die Seite Alles bereit.

So bleibt dein Konto geschützt

Jeder Konto-API-Zugang bekommt eine feste IP-Adresse in Deutschland, die kein anderer Nutzer verwendet. Jede API-Anfrage, die wir in Verbindung mit deinem Konto senden, stammt von dieser gebuchten IP-Adresse: die Verknüpfung nach deiner Anmeldung, Chats lesen, Nachrichten senden und das Erneuern deiner Sitzung. Deshalb buchst du den Zugang vor der Anmeldung.

Dein Kleinanzeigen-Passwort sehen wir nie. Du meldest dich direkt auf kleinanzeigen.de an, danach arbeiten wir nur mit einem Sitzungstoken. Genau dafür gibt es die Chrome-Erweiterung: Sie reicht deine Anmeldung einmalig an uns weiter und liest keine Passwörter, Cookies oder Chats.

Ohne aktiven Zugang oder solange deine IP-Adresse noch eingerichtet wird, antwortet die Konto-API mit einem Fehler und berechnet keine Credits.

Kosten

Aktion	Credits
Chats auflisten	5
Chat öffnen	10
Nachricht senden	25
Neuen Chat starten	50

Der Verbindungsstatus ist kostenlos. Schlägt das Lesen eines Chats oder der Chatliste fehl, buchen wir die Credits automatisch zurück. Eine leere Chatliste ist ein erfolgreicher Abruf.

Verbindungsstatus

GET /api/v2/kleinanzeigen/account/status

Zeigt, ob dein Kleinanzeigen-Konto verbunden ist. status ist connected, disconnected oder reauth_required. Bei reauth_required meldest du dich unter Konto-API erneut an.

curl "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/account/status" \
  -H "klaz_key: klaz_live_..."

{
  "success": true,
  "data": {
    "status": "connected",
    "email": "du@example.com",
    "connected_at": "2026-10-13T10:00:00.000Z"
  },
  "request_id": "req_..."
}

Chats auflisten

GET /api/v2/kleinanzeigen/account/conversations

Parameter:

page integer, Default 0: Ergebnis-Seite, 0 bis 1000.
size integer, Default 25: Chats pro Seite, 1 bis 100.

curl "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/account/conversations?size=25" \
  -H "klaz_key: klaz_live_..."

{
  "success": true,
  "data": {
    "conversations": [
      {
        "conversation_id": "a1b2c3:d4e5f6",
        "ad_id": "1234567890",
        "ad_title": "Sofa",
        "counterparty": "Max",
        "unread": true,
        "preview": "Ist das Sofa noch da?",
        "received_at": "2026-10-13T10:00:00.000+0200"
      }
    ],
    "page": 0,
    "size": 25,
    "has_more": false
  },
  "request_id": "req_..."
}

counterparty ist der Name deines Gegenübers, je nach Chat also Anbieter oder Interessent. received_at übernehmen wir unverändert von Kleinanzeigen. has_more ist true, wenn die Seite voll war, und ist keine Gesamtzahl.

Chat öffnen

POST /api/v2/kleinanzeigen/account/conversations/:conversation_id/open

Liefert den Chat mit allen Nachrichten. Kleinanzeigen kann den Chat dabei als gelesen markieren. conversation_id kann Doppelpunkte enthalten, kodiere sie deshalb im Pfad.

curl -X POST "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/account/conversations/a1b2c3%3Ad4e5f6/open" \
  -H "klaz_key: klaz_live_..."

Die Antwort enthält dieselben Felder wie ein Eintrag der Chatliste und zusätzlich messages:

{
  "messages": [
    {
      "message_id": "m-1",
      "text": "Ist das Sofa noch da?",
      "direction": "received",
      "received_at": "2026-10-13T10:00:00.000+0200"
    }
  ]
}

direction ist received, sent oder unknown.

Nachricht senden

POST /api/v2/kleinanzeigen/account/conversations/:conversation_id/messages

Body:

message string, erforderlich: 1 bis 4000 Zeichen.
request_id UUID, optional: Macht Wiederholungen sicher, siehe unten.

curl -X POST "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/account/conversations/a1b2c3%3Ad4e5f6/messages" \
  -H "klaz_key: klaz_live_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"Danke für die Antwort!"}'

{
  "success": true,
  "data": {
    "request_id": "40f08247-dea6-4294-8ae0-bb1b1cda58cb",
    "conversation_id": "a1b2c3:d4e5f6",
    "sent": true
  },
  "request_id": "req_..."
}

Neuen Chat starten

POST /api/v2/kleinanzeigen/account/conversations

Schreibt den Anbieter eines Inserats über das Kontaktformular von Kleinanzeigen an und sendet die erste Nachricht.

Body:

ad_id numeric string, erforderlich: Kleinanzeigen-Inserat-ID.
message string, erforderlich: 1 bis 4000 Zeichen.
request_id UUID, optional: Macht Wiederholungen sicher, siehe unten.

Den Absendernamen übernehmen wir automatisch aus deinem verbundenen Kleinanzeigen-Konto, so wie ihn Kleinanzeigen im Kontaktformular vorgibt.

curl -X POST "https://api.kleinanzeigen-agent.de/api/v2/kleinanzeigen/account/conversations" \
  -H "klaz_key: klaz_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ad_id":"1234567890","message":"Hallo, ist der Artikel noch verfügbar?"}'

Die Antwort hat dieselbe Form wie beim Senden und enthält die conversation_id des neuen Chats. Liefert Kleinanzeigen keinen Absendernamen oder verlangt das Formular weitere Angaben, senden wir nichts, berechnen nichts und antworten mit einem Fehlercode aus der Tabelle unten.

sent: true heißt, dass Kleinanzeigen die Nachricht angenommen hat. Eine Zustell- oder Lesebestätigung des Empfängers ist das nicht.

Sicher wiederholen mit request_id

Ohne request_id erzeugen wir für jeden Aufruf eine neue UUID und geben sie als data.request_id zurück. Die äußere request_id der Antwort ist davon getrennt und dient nur der Fehlersuche.

Für sichere Wiederholungen schickst du dieselbe request_id erneut, entweder eine selbst erzeugte UUID oder den Wert aus data.request_id. Dann verschicken wir die Nachricht kein zweites Mal und berechnen keine weiteren Credits. Du bekommst die ursprüngliche Bestätigung zurück. Zwei Aufrufe ohne gemeinsame request_id behandeln wir als zwei Nachrichten, auch bei gleichem Text.

Bei MESSAGE_OUTCOME_UNKNOWN oder einem Fehler mit data.outcome: "unknown" konnten wir nicht bestätigen, ob die Nachricht angekommen ist. Prüfe zuerst den Chat, bevor du mit einer neuen request_id noch einmal sendest. Der Versandversuch bleibt berechnet. Bei data.outcome: "not_sent" wurde nichts gesendet und nichts berechnet.

Inserate erstellen

Du legst private Abholanzeigen als Entwurf an, prüfst sie und überträgst die geprüfte Fassung in dein Kleinanzeigen-Konto. Veröffentlicht wird in der Kleinanzeigen-App. Entwürfe, Bilder und Statusabfragen kosten keine Credits. Du verwaltest sie auch unter Inserate.

Letzter Schritt in der App. Nach POST .../publish liegt ein privater Entwurf in deinem Kleinanzeigen-Konto. Der Ort kommt aus deinem Profil und lässt sich in der App ändern. Online geht die Anzeige erst, wenn du sie dort veröffentlichst.

Methode und Pfad	Zweck
`GET /ad-creation/capabilities`	Einstieg: Kontostatus, Kategorien, Limits
`GET /ad-creation/requirements?category_id=88`	Pflichtfelder und erlaubte Werte einer Kategorie
`POST /ad-drafts`	Entwurf anlegen, auch unvollständig
`GET /ad-drafts`, `GET /ad-drafts/{id}`	Entwürfe wiederfinden
`PUT /ad-drafts/{id}`	Fassung ersetzen, mit `expected_revision`
`DELETE /ad-drafts/{id}`	Bei uns archivieren, bei Kleinanzeigen wird nichts gelöscht
`POST /ad-images`	Bild hochladen (Multipart `file`) oder importieren (`source_url`)
`GET /ad-images/{id}`, `DELETE /ad-images/{id}`	Prüfstatus lesen, Bild entfernen
`POST /ad-drafts/{id}/validate`	Feldfehler oder vollständige Vorschau samt `public_validation_id`
`POST /ad-drafts/{id}/publish`	Geprüfte Fassung in die Kleinanzeigen-App übertragen
`GET /ad-publications/{id}`	Ergebnis abrufen

Jede Änderung am Entwurf verlangt eine neue Prüfung, eine Prüfung gilt 15 Minuten. Ein wiederholter Publish-Aufruf liefert denselben Auftrag und erstellt keinen zweiten Entwurf.

Bei state: "handed_off" mit next_action: "finish_in_app" liegt der Entwurf in der App und remote_draft_id nennt ihn. Bei failed hat die Übertragung nicht geklappt, die Credits gehen zurück, und du kannst neu prüfen. Ob die Anzeige später online geht, sehen wir nicht: Das passiert in der App.

Bilder: JPEG oder PNG, höchstens 10 MiB und 40 Megapixel, bis zu zehn pro Entwurf. Wir entfernen EXIF- und GPS-Daten. Lokale Pfade kann unser Server nicht lesen; lade solche Dateien per Multipart oder in der App hoch.

Der erste Release unterstützt private Angebote mit Abholung in freigeschalteten Kategorien, mit Festpreis oder VB. Versand, Direkt-kaufen, gewerbliche Inserate und das Bearbeiten veröffentlichter Anzeigen gehören nicht dazu.

Fehlercodes

Code	Status	Bedeutung
`ACCOUNT_SUBSCRIPTION_REQUIRED`	402	Kein aktiver Konto-API-Zugang. Buche ihn unter Konto-API.
`ACCOUNT_CONNECTION_PENDING`	409	Deine IP-Adresse wird noch eingerichtet. Versuche es in ein paar Minuten erneut.
`ACCOUNT_RECONNECT`	409	Kein Konto verbunden oder Kleinanzeigen verlangt eine neue Anmeldung.
`ACCOUNT_BUSY`	409	Für dein Konto läuft gerade eine andere Anfrage. Kurz warten und erneut senden.
`INSUFFICIENT_CREDITS`	402	Nicht genug Credits für die Aktion.
`REQUEST_ID_CONFLICT`	409	Dieselbe `request_id` wurde schon mit anderem Inhalt verwendet.
`CONTACT_NAME_UNAVAILABLE`	422	Kleinanzeigen liefert für dein Konto keinen Absendernamen. Prüfe dein Profil bei Kleinanzeigen. Nichts gesendet.
`CONTACT_FORM_UNSUPPORTED`	422	Das Kontaktformular verlangt Angaben, die die Konto-API nicht ausfüllen kann. Nichts gesendet.
`MESSAGE_TOO_LONG`	422	Kleinanzeigen erlaubt für diese Anfrage weniger Zeichen. Nichts gesendet.
`CONTACT_FORM_UNAVAILABLE`	502	Das Kontaktformular konnte nicht geladen werden, etwa weil die Anzeige nicht mehr online ist. Nichts gesendet.
`MESSAGE_OUTCOME_UNKNOWN`	409	Versand nicht bestätigt. Erst den Chat prüfen.
`PROVIDER_RATE_LIMIT`	429	Kleinanzeigen begrenzt gerade die Anfragen. Später erneut versuchen.
`PROVIDER_UNAVAILABLE`	502	Kleinanzeigen ist vorübergehend nicht erreichbar.

Bei Fragen zur Beta schreib uns an office@kleinanzeigen-agent.de.

MCP Server

Mit dem MCP Server kann ein KI-Client Kleinanzeigen Agent selbst nutzen. Er kann live suchen, Inseratdetails laden, Verkäufer prüfen und die Ergebnisse für dich weiterverarbeiten. Mit der Konto-API liest er außerdem die Chats deines eigenen Kleinanzeigen-Kontos und antwortet auf deine Anweisung.

Kurz gesagt: MCP passt, wenn du einer KI eine Rechercheaufgabe gibst. Für feste Abläufe in deiner eigenen Software ist die API weiterhin der richtige Weg.

Wann du MCP verwenden solltest

Nutze MCP, wenn ein KI-Client interaktiv mit Live-Daten arbeiten soll:

Recherche-Assistenten, die erst suchen und dann einzelne Treffer prüfen.
Agenten, die Verkäufer, Kategorien oder Standorte abhängig vom Zwischenergebnis nachladen.
Interne Tools, in denen ein Mensch Fragen stellt und der Client passende Kleinanzeigen-Tools aufruft.
Marktanalysen, bei denen ein Modell mehrere Suchen ausführt und daraus eine Tabelle oder Shortlist erstellt.

Nutze stattdessen die API, wenn deine eigene Software feste Anfragen ausführt. Nutze Webhooks, wenn du dauerhaft neue Inserate zu gespeicherten Filtern überwachen willst.

Server-URL

https://api.kleinanzeigen-agent.de/mcp

Diese URL trägst du in deinem MCP-Client ein. Die technischen Nachrichten erzeugt dein Client automatisch; du musst sie normalerweise nicht selbst schreiben.

Automatische Discovery

Kompatible Clients und Agenten können die Verbindung auch über die öffentlichen Discovery-Dokumente erkennen:

MCP Server Card: https://kleinanzeigen-agent.de/.well-known/mcp/server-card.json
A2A Agent Card: https://kleinanzeigen-agent.de/.well-known/agent-card.json
Authentifizierung: https://kleinanzeigen-agent.de/auth.md
Agent Skill: https://kleinanzeigen-agent.de/.well-known/agent-skills/kleinanzeigen-research/SKILL.md
API-Katalog: https://kleinanzeigen-agent.de/.well-known/api-catalog

Die Server Card beschreibt denselben MCP-Endpoint und dieselben Tools wie diese Dokumentation. Es ist kein zweiter Server und kein separater Tarif.

A2A ist ein separater Protokoll-Endpoint unter https://api.kleinanzeigen-agent.de/a2a. Er verwendet dieselben geprüften Tool-Funktionen, ist aber kein MCP-Transport. Details stehen in der A2A-Dokumentation.

Authentifizierung

Empfohlen ist der Login im Browser: Dein MCP-Client öffnet einmal Kleinanzeigen Agent, du meldest dich an und erlaubst den Zugriff. Danach merkt sich der Client die Verbindung; dein API-Key muss nicht mehr in die lokale MCP-Konfiguration.

Wenn dein Client diesen Login unterstützt, füge nur die Server-URL hinzu und starte danach den Login im Client:

https://api.kleinanzeigen-agent.de/mcp

Für ältere Clients bleibt die Einrichtung mit API-Key möglich. Verwende dafür:

Authorization: Bearer klaz_live_...

Aus Kompatibilitätsgründen akzeptiert der MCP Server auch den bestehenden API-Header:

klaz_key: klaz_live_...

Speichere den Key nur als Secret in deinem MCP-Client. Gib ihn nicht in einen Prompt ein, hänge ihn nicht an die URL und committe ihn nicht in eine Config-Datei. Wenn ein Key öffentlich geworden ist, rotiere ihn im Dashboard.

Tools

Alle Werkzeuge liefern Ergebnisse im gleichen Format wie die API zurück. Dein Client kann sie anzeigen, zusammenfassen oder für den nächsten Schritt weiterverwenden.

Wenn dein System sehr viele Treffer sammeln, stark filtern oder eigene Zwischenergebnisse bauen soll, kann es statt MCP auch direkt die API nutzen. Die komplette API-Doku gibt es als Markdown unter https://kleinanzeigen-agent.de/api/docs-raw, damit KI-Clients sie direkt lesen können. Für die API brauchst du weiterhin deinen klaz_live_... API-Key als Authorization: Bearer ... Header oder als klaz_key Header. Der Key gehört trotzdem in Secrets oder Umgebungsvariablen, nicht in Prompts, Logs oder Code.

Tool	Typische Eingaben	Zweck	Credits
`search_kleinanzeigen`	`q`, `category_id`, `location_id`, `distance`, Preisfilter, Versandfilter, Attribute	Live-Inserate suchen	1
`get_kleinanzeigen_search_category_counts`	dieselben Filter wie `search_kleinanzeigen`, ohne `page` und `size`	Trefferzahl je Kategorie zählen, ohne Inserate zu laden	1
`get_kleinanzeigen_ad`	`ad_id`, optional `include_views`	Inseratdetails laden	1
`get_kleinanzeigen_ad_status`	`ad_id`, optional `include_views`	Prüfen, ob ein Inserat aktiv oder gelöscht ist	1
`get_kleinanzeigen_similar_ads`	`ad_id`, optional `size` (1 bis 10)	Bis zu 10 ähnliche Inserate laden	1
`get_kleinanzeigen_ad_seller_ads`	`ad_id`	Bis zu 30 weitere Inserate vom Verkäufer eines Inserats laden	1
`get_kleinanzeigen_seller_profile`	`seller_id`	Öffentliches Verkäuferprofil mit Name, Badges und Zählern laden	1
`get_kleinanzeigen_seller_ads`	`seller_id`, `page`, `size`	Weitere Inserate eines Verkäufers laden	2
`list_kleinanzeigen_categories`	keine	Kategoriebaum laden	1
`get_kleinanzeigen_category_metadata`	`category_id`	Felder einer Kategorie ansehen	1
`get_kleinanzeigen_category_search_metadata`	`category_id`	Suchfilter und Attribute einer Kategorie laden	1
`search_kleinanzeigen_locations`	`q` oder Koordinaten, optional `limit`	Standorte suchen	1
`get_kleinanzeigen_location`	`location_id`	Standortdetails laden	1

Bei get_kleinanzeigen_ad und get_kleinanzeigen_ad_status kostet include_views=true einen zusätzlichen Credit.

Konto-API-Tools

Mit verbundenem Kleinanzeigen-Konto und aktivem Konto-API-Zugang stehen fünf weitere Tools bereit. Sie arbeiten mit deinem eigenen Konto, die Einrichtung findest du unter Konto-API.

Der Zugriff auf dein Konto ist eine eigene Freigabe: Schalte beim Verbinden des MCP-Clients auf der Anmeldeseite „Dein Kleinanzeigen-Konto“ ein. Hast du den Client früher ohne diese Freigabe verbunden, antworten die Konto-Tools mit MCP_ACCOUNT_SCOPE_REQUIRED. Dann meldest du den Client ab und verbindest ihn neu, zum Beispiel in Codex mit codex mcp logout <name> und codex mcp login <name> oder in Claude über Trennen und erneutes Verbinden des Connectors.

Tool	Typische Eingaben	Zweck	Credits
`get_kleinanzeigen_account_status`	keine	Prüfen, ob dein Konto verbunden und die Konto-API bereit ist	0
`list_kleinanzeigen_account_conversations`	`page`, `size`	Deine Chats mit Vorschau und Ungelesen-Markierung abrufen	5
`open_kleinanzeigen_account_conversation`	`conversation_id`	Einen Chat mit allen Nachrichten öffnen, markiert ihn bei Kleinanzeigen gegebenenfalls als gelesen	10
`send_kleinanzeigen_account_message`	`conversation_id`, `message`, optional `request_id`	In einem bestehenden Chat in deinem Namen antworten	25
`start_kleinanzeigen_account_conversation`	`ad_id`, `message`, optional `request_id`	Den Anbieter eines Inserats anschreiben	50

Dazu kommen die Tools für Inserate: get_kleinanzeigen_ad_creation_capabilities, get_kleinanzeigen_ad_creation_requirements, create_kleinanzeigen_ad_draft, list_kleinanzeigen_ad_drafts, get_kleinanzeigen_ad_draft, update_kleinanzeigen_ad_draft, import_kleinanzeigen_ad_image, get_kleinanzeigen_ad_image, validate_kleinanzeigen_ad_draft, publish_kleinanzeigen_ad_draft und get_kleinanzeigen_ad_publication. publish_kleinanzeigen_ad_draft legt einen privaten Entwurf in deinem Kleinanzeigen-Konto an. Du veröffentlichst ihn in der Kleinanzeigen-App.

Den Absendernamen für einen neuen Chat übernimmt der Server automatisch aus deinem Kleinanzeigen-Konto. Die request_id (UUID) ist optional. Fehlt sie, erzeugt der Server eine neue und liefert sie als data.request_id zurück. Sicher wiederholen kannst du nur mit derselben request_id: Sie verschickt nie zweimal und kostet nie doppelt. Aufrufe ohne gemeinsame request_id sind getrennte Nachrichten. Bei MESSAGE_OUTCOME_UNKNOWN prüfst du zuerst den Chat, bevor du mit einer neuen request_id erneut sendest. Alle weiteren Regeln stehen in der Konto-API-Dokumentation.

page ist 0-basiert: Die erste Ergebnisseite ist page: 0. Wenn ein MCP Client versehentlich eine Seite außerhalb des vorhandenen Ergebnisbereichs anfragt, lädt das Tool automatisch die letzte verfügbare Seite nach.

Die Live-Suche liefert standardmäßig „Neueste zuerst“, ohne Sortierparameter. sort_type wird aktuell nicht unterstützt. Für eine andere Reihenfolge kannst du deinen MCP Client die bereits abgerufenen Inserate beispielsweise nach Preis sortieren lassen; das sortiert nur diese Treffer, nicht den gesamten Suchbestand.

Ungültige Angaben kosten keine Credits. Wenn eine Live-Abfrage bei Kleinanzeigen fehlschlägt, wird der Credit wie bei der API automatisch zurückerstattet. Die Limits hängen weiter an deinem Plan.

Beispiel für ältere Clients mit API-Key

Wenn dein MCP-Client den Login im Browser noch nicht unterstützt, kannst du den Server mit deinem API-Key verbinden:

{
  "mcpServers": {
    "kleinanzeigen-agent": {
      "url": "https://api.kleinanzeigen-agent.de/mcp",
      "headers": {
        "Authorization": "Bearer klaz_live_..."
      }
    }
  }
}

Danach sollte dein Client die Werkzeuge selbst finden. Je nach Client heißt die Funktion zum Hinzufügen eines Servers anders, aber die wichtigen Teile bleiben gleich: Server-URL und, bei älteren Clients, der API-Key.

Codex CLI

Wenn du Codex lokal nutzt, kannst du den MCP Server direkt über die CLI hinzufügen und danach den Login starten:

codex mcp add kleinanzeigen-agent \
  --url https://api.kleinanzeigen-agent.de/mcp

codex mcp login kleinanzeigen-agent

Prüfen kannst du die Verbindung mit:

codex mcp list

In der Codex-Oberfläche zeigt /mcp die verbundenen MCP Server.

Wenn deine Codex-Version diesen Login noch nicht unterstützt, nutze die API-Key-Variante mit --bearer-token-env-var KLAZ_API_KEY.

Claude Code CLI

Wenn du Claude Code nutzt, kannst du den Server ebenfalls per CLI eintragen und danach den Login starten:

claude mcp add --transport http kleinanzeigen-agent \
  https://api.kleinanzeigen-agent.de/mcp

claude mcp login kleinanzeigen-agent

Prüfen kannst du die Verbindung mit:

claude mcp list

In Claude Code zeigt /mcp den Serverstatus und die verfügbaren Tools.

Der Befehl schreibt die Verbindung in deine lokale Claude-Code-Konfiguration. Wenn du die API-Key-Variante nutzt, speichere den Key nur als lokales Secret und nicht in einem geteilten Projekt.

Beispiel-Fragen an den Client

Nachdem der Server verbunden ist, kannst du dem Client normale Aufgaben geben. Gute Prompts nennen Ziel, Filter und gewünschtes Ausgabeformat:

Suche private iPhone 15 Angebote im Umkreis von 25 km um Berlin.
Lade Details für die 5 günstigsten Treffer nach und gib mir eine Tabelle mit Preis, Standort, Versand, Verkäufer und URL.

Finde Sofas bis 300 EUR in München, nur mit Bildern.
Markiere auffällige Angebote und erkläre kurz, warum sie interessant sein könnten.

Mit Konto-API-Zugang funktionieren auch Aufgaben rund um deine Chats:

Zeig mir meine ungelesenen Kleinanzeigen-Chats und fasse jeweils zusammen, was die Person möchte.
Schlag mir für jeden Chat eine kurze Antwort vor. Sende erst, wenn ich die Antwort bestätigt habe.

Der Client entscheidet dann selbst, ob er nur search_kleinanzeigen braucht oder zusätzlich Details, Verkäuferprofile, Verkäufer-Inserate, Kategorien oder Standorte nachladen sollte.

Sicherheit und Grenzen

MCP gibt deinem KI-Client Zugriff auf die Kleinanzeigen-Werkzeuge, nicht auf dein ganzes Konto. Beim Login im Browser muss dein API-Key nicht kopiert werden. Wenn du die API-Key-Variante nutzt, bleibt der Key in deinem MCP-Client.

Hast du die Konto-API eingerichtet, kann dein Client zusätzlich deine Kleinanzeigen-Chats lesen und in deinem Namen schreiben. Lass Nachrichten nur senden, wenn du den genauen Text gesehen und bestätigt hast. Die meisten MCP-Clients fragen vor jedem Tool-Aufruf nach; diese Abfrage solltest du für die Sende-Tools eingeschaltet lassen.

Der MCP Server speichert keine Inserate und ersetzt keinen Webhook. Er ist für interaktive Recherche gedacht. Für produktive Entscheidungen solltest du wichtige Ergebnisse mit ad_id, Preis, URL und Zeitpunkt ausgeben lassen und bei Bedarf selbst prüfen.

Was dein MCP Client können muss

Dein MCP-Client muss Online-MCP-Server verbinden können. Für die einfachste Einrichtung sollte er den Login im Browser unterstützen. Wenn nicht, muss er einen API-Key mitsenden können:

Authorization: Bearer klaz_live_...

Wenn dein Client weder den Login noch API-Keys für MCP-Server erlaubt, kannst du diesen MCP Server dort aktuell nicht direkt verbinden. Nutze in dem Fall die API oder einen MCP-Client, der eine der beiden Anmeldearten unterstützt.

Häufige Fehler

Problem	Ursache	Lösung
`401 MCP_AUTH_REQUIRED`	Kein Login und kein API-Key gesetzt	Login im MCP-Client starten oder `Authorization: Bearer klaz_live_...` setzen
`401 API_KEY_INVALID`	Key falsch, rotiert oder deaktiviert	Key im Dashboard prüfen oder rotieren
`401 MCP_OAUTH_INVALID_TOKEN`	Login ist abgelaufen oder wurde widerrufen	Login im Client erneut starten
`402 INSUFFICIENT_CREDITS`	Zu wenig Guthaben	Credits kaufen oder Plan upgraden
`MCP_ACCOUNT_SCOPE_REQUIRED`	Verbindung ohne Freigabe für dein Konto	Client neu verbinden und „Dein Kleinanzeigen-Konto“ einschalten
`ACCOUNT_SUBSCRIPTION_REQUIRED`	Kein aktiver Konto-API-Zugang	Zugang unter Konto-API buchen
`ACCOUNT_RECONNECT`	Kein Kleinanzeigen-Konto verbunden oder neue Anmeldung nötig	Unter Konto-API erneut anmelden
`MESSAGE_OUTCOME_UNKNOWN`	Versand nicht bestätigt	Chat prüfen, erst dann mit neuer `request_id` senden
`403 MCP_ORIGIN_NOT_ALLOWED`	Verbindung kommt aus einer nicht erlaubten Umgebung	Client-Einstellung prüfen oder Support kontaktieren
Client findet keine Tools	MCP Server nicht korrekt verbunden	URL und Login-Status im Client prüfen

A2A 1.0

Mit dem A2A-Endpoint kann ein anderes Agentensystem Kleinanzeigen Agent beauftragen. Es sendet einen strukturierten Auftrag über das Agent2Agent-Protokoll und erhält einen Task mit Status und Ergebnis-Artefakt zurück.

Kurz gesagt: A2A passt, wenn eine Agentenplattform bereits Tasks, Statusabfragen und Artefakte spricht. Für interaktive Recherche mit einem KI-Client ist der MCP Server der richtige Weg, für feste Abläufe in deiner eigenen Software die API.

Wann du A2A verwenden solltest

Deine Plattform orchestriert mehrere Agenten und erwartet überall dasselbe Task-Modell.
Ein aufrufender Agent plant die Schritte selbst und braucht nur einen geprüften Datenschritt.
Du willst Aufträge asynchron starten und den Status später abfragen.
Du willst Ergebnisse als maschinenlesbares Artefakt weiterreichen, ohne HTML zu scrapen.

Verbindung

Agent Card: https://kleinanzeigen-agent.de/.well-known/agent-card.json
Kanonische Agent Card: https://api.kleinanzeigen-agent.de/.well-known/agent-card.json
A2A Endpoint: https://api.kleinanzeigen-agent.de/a2a
Protokoll: A2A 1.0, Binding JSON-RPC

Sende bei A2A-Anfragen diese Header:

A2A-Version: 1.0
Content-Type: application/json

Die Agent Cards werden als application/a2a+json ausgeliefert. Das JSON-RPC-Binding erwartet für Requests dagegen application/json.

Die Agent Card beschreibt Endpoint, Version, Skills, Authentifizierung und Grenzen. Kompatible Clients können die Verbindung darüber automatisch einrichten.

Authentifizierung

A2A verwendet denselben API-Key wie die REST API:

Authorization: Bearer klaz_live_...

Aus Kompatibilitätsgründen funktioniert auch der bestehende Header:

klaz_key: klaz_live_...

Speichere den Key nur in der Secret-Verwaltung deines Clients. Er gehört nicht in den Request-Body, nicht in einen Prompt, nicht in eine URL und nicht in ein Log. Ist ein Key öffentlich geworden, rotiere ihn im Dashboard.

Die OAuth-Tokens des MCP Servers gelten hier nicht. Sie sind auf die Ressource /mcp beschränkt. A2A-OAuth kommt erst, wenn es dafür eine eigene geschützte Ressource und einen passenden Scope gibt.

Aufbau eines Auftrags

Jede SendMessage-Anfrage enthält genau einen strukturierten Data-Part mit einem vorhandenen Tool und dessen Argumenten:

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "client-message-1",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "tool": "search_kleinanzeigen",
            "arguments": {
              "q": "Lastenrad",
              "page": 0,
              "size": 20
            }
          },
          "mediaType": "application/json"
        }
      ]
    }
  }
}

Der Endpoint interpretiert keine frei formulierten Prompts. Tool und Argumente wählt der aufrufende Agent ausdrücklich aus.

Verfügbare Tools

Es sind dieselben 18 Tools wie beim MCP Server verfügbar, mit denselben Argumenten und denselben Credit-Kosten. 13 Tools lesen öffentliche Kleinanzeigen-Daten:

Tool	Zweck	Credits
`search_kleinanzeigen`	Live-Inserate suchen	1
`get_kleinanzeigen_search_category_counts`	Trefferzahl je Kategorie für eine Suche zählen	1
`get_kleinanzeigen_ad`	Inseratdetails laden	1
`get_kleinanzeigen_ad_status`	Prüfen, ob ein Inserat aktiv oder gelöscht ist	1
`get_kleinanzeigen_similar_ads`	Bis zu 10 ähnliche Inserate laden	1
`get_kleinanzeigen_ad_seller_ads`	Bis zu 30 weitere Inserate vom Verkäufer eines Inserats laden	1
`get_kleinanzeigen_seller_profile`	Öffentliches Verkäuferprofil laden	1
`get_kleinanzeigen_seller_ads`	Weitere Inserate eines Verkäufers laden	2
`list_kleinanzeigen_categories`	Kategoriebaum laden	1
`get_kleinanzeigen_category_metadata`	Felder einer Kategorie ansehen	1
`get_kleinanzeigen_category_search_metadata`	Suchfilter einer Kategorie laden	1
`search_kleinanzeigen_locations`	Standorte suchen	1
`get_kleinanzeigen_location`	Standortdetails laden	1

Bei get_kleinanzeigen_ad und get_kleinanzeigen_ad_status kostet include_views=true einen zusätzlichen Credit.

Fünf weitere Tools arbeiten mit deinem eigenen Kleinanzeigen-Konto. Sie brauchen ein verbundenes Konto und einen aktiven Konto-API-Zugang:

Tool	Zweck	Credits
`get_kleinanzeigen_account_status`	Prüfen, ob dein Konto verbunden und die Konto-API bereit ist	0
`list_kleinanzeigen_account_conversations`	Deine Chats abrufen	5
`open_kleinanzeigen_account_conversation`	Einen Chat mit allen Nachrichten öffnen	10
`send_kleinanzeigen_account_message`	In einem bestehenden Chat antworten	25
`start_kleinanzeigen_account_conversation`	Den Anbieter eines Inserats anschreiben	50

Die Tools für Inserate stehen ebenfalls bereit. Ein abgeschlossener Aufruf von publish_kleinanzeigen_ad_draft bedeutet nur, dass der Auftrag angenommen wurde. Das Ergebnis liefert get_kleinanzeigen_ad_publication, auch nach Ablauf des Tasks. Bei handed_off liegt der Entwurf in der Kleinanzeigen-App und wird dort veröffentlicht.

Die Sende-Tools verschicken Nachrichten in deinem Namen. Löse sie nur auf ausdrückliche Anweisung aus. Für einen neuen Chat reichen ad_id und message; den Absendernamen übernimmt der Server aus deinem Kleinanzeigen-Konto. Die request_id (UUID) ist optional und wird sonst erzeugt und als data.request_id zurückgegeben. Ein Retry mit derselben messageId und unverändertem Inhalt führt das Tool nicht erneut aus (siehe unten). Wiederholst du den Versand als neuen Auftrag mit neuer messageId, verhindert erst dieselbe request_id, dass zweimal gesendet oder doppelt berechnet wird.

search_kleinanzeigen liefert standardmäßig „Neueste zuerst“, genau wie API und MCP. Dafür ist kein Sortierparameter nötig; sort_type wird nicht unterstützt.

Unbekannte Tools und ein falsches Nachrichtenformat werden vor dem Tool-Aufruf abgelehnt und kosten keine Credits. Die Argumente prüft danach dasselbe Schema wie bei MCP; Validierungsfehler kommen mit ihren Details als Fehler-Artefakt zurück.

Requests dürfen höchstens 64 KiB groß sein. Das Feld tenant lässt du leer oder weg, denn frei wählbare Tenant-Namespaces werden nicht unterstützt.

Tasks und Ergebnisse

Eine gültige Anfrage erzeugt einen Task, der die Zustände SUBMITTED und WORKING durchläuft und mit COMPLETED oder FAILED endet. Das strukturierte Tool-Ergebnis hängt als application/json-Artefakt am Task.

Unterstützt sind SendMessage, GetTask und ListTasks. Task-Snapshots liegen pro Benutzer getrennt für eine Stunde in Redis; pro Benutzer werden höchstens 500 Tasks indexiert. Sie sind als kurzfristiger Abholpunkt gedacht und können bei Betriebsarbeiten früher verschwinden.

Weitere Aufträge dürfen dieselbe Context-ID verwenden, erzeugen aber jeweils einen neuen Task. Sende dafür eine neue messageId ohne taskId. Follow-up-Nachrichten mit vorhandener taskId werden abgelehnt, und abgeschlossene Tasks bleiben unverändert. Jeder Auftrag enthält genau einen Tool-Aufruf.

Wiederholte Anfragen

messageId ist zugleich der Idempotenz-Schlüssel für kostenrelevante Wiederholungen. Sendet derselbe angemeldete Benutzer dieselben vollständigen SendMessage-Parameter mit derselben messageId erneut, liefert der Server den bereits angelegten Task zurück und führt das Tool kein zweites Mal aus. Das gilt auch für zeitgleiche Requests.

Dieselbe messageId mit verändertem Inhalt wird als ungültiger Request abgelehnt. Die JSON-RPC-Request-ID gehört nicht zum Fingerprint und darf sich beim Retry ändern.

Der Schutz gilt, solange der zugehörige Task gespeichert ist: regulär bis zu einer Stunde, beim Überschreiten des Limits oder bei Betriebsarbeiten gegebenenfalls kürzer. Danach muss dein Client davon ausgehen, dass der Server die frühere messageId nicht mehr kennt.

Credits und Limits

A2A ruft intern dieselben geprüften Funktionen auf wie MCP und die REST API. Deshalb gelten dieselben Regeln:

Credit-Kosten pro Tool-Aufruf
Erstattungen bei fehlgeschlagenen Live-Abfragen
Schema- und Eingabeprüfungen
Rate-Limits deines gebuchten Plans

Ein A2A-Request umgeht weder dein Guthaben noch die Tarifgrenzen.

Für einen technischen Retry verwendest du dieselbe messageId und denselben Request-Inhalt. So löst ein Netzwerk-Retry keinen zweiten Tool-Aufruf und keine zweite Credit-Belastung aus.

Häufige Fehler

Problem	Ursache	Lösung
`401` bei jedem Request	API-Key fehlt oder ist ungültig	`Authorization: Bearer klaz_live_...` setzen oder Key im Dashboard rotieren
`REQUEST_MALFORMED`	Nachrichtenformat falsch, Request über 64 KiB oder `messageId` mit verändertem Inhalt wiederverwendet	Aufbau des Data-Parts prüfen, Request verkleinern oder neue `messageId` verwenden
Task endet als `REJECTED`	Unbekannter Tool-Name oder ungültige Hülle	Tool-Namen aus der Tabelle oben verwenden
Task endet als `FAILED`	Live-Abfrage oder Argumentprüfung fehlgeschlagen	Fehler-Artefakt am Task auswerten
`402 INSUFFICIENT_CREDITS`	Zu wenig Guthaben	Credits kaufen oder Plan upgraden unter /app/abrechnung
`ACCOUNT_SUBSCRIPTION_REQUIRED` oder `ACCOUNT_RECONNECT` im Fehler-Artefakt	Konto-API nicht gebucht oder Konto nicht verbunden	Einrichtung unter /app/konto-api abschließen
`TASK_NOT_CANCELABLE`	Live-Abfrage läuft bereits	Ergebnis abwarten und per `GetTask` abholen
`TASK_NOT_FOUND`	Task abgelaufen oder gehört einem anderen Konto	Auftrag mit neuer `messageId` erneut senden

Grenzen

A2A interpretiert keine frei formulierten Prompts.
Es wird kein zusätzlicher LLM-Anbieter aufgerufen und kein Prompt an ein Modell übertragen.
Streaming, Push Notifications und Extended Agent Cards sind nicht aktiv.
Bereits gestartete Live-Abfragen lassen sich nicht zuverlässig abbrechen; CancelTask liefert deshalb TASK_NOT_CANCELABLE.
Der Endpoint implementiert A2A 1.0. Einen Kompatibilitätsmodus für A2A 0.3 gibt es nicht.

Für interaktive Recherche, bei der dein KI-Client Tools selbst entdeckt und während einer Unterhaltung flexibel aufruft, bleibt MCP die passende Wahl. A2A ist für Agentensysteme gedacht, die standardisierte Tasks, Status und Ergebnis-Artefakte erwarten.

Webhooks

Lass dir neue Inserate automatisch an deinen Server schicken, sobald sie auf Kleinanzeigen erscheinen — passend zu deinen Filtern, im gewählten Intervall.

Jedes Inserat erreicht dich genau einmal pro Webhook. Auch wenn ein Inserat noch tagelang in der Suche steht, schicken wir es nicht erneut.

Tarife

Webhooks haben ihr eigenes Abo. Dein API-Guthaben und dein Rate-Limit bleiben davon unberührt.

Tarif	Intervall	Preis netto
Webhook Pulse	60 Sekunden	39 EUR / Monat
Webhook Flow	30 Sekunden	79 EUR / Monat
Webhook Stream	10 Sekunden	229 EUR / Monat
Webhook Realtime	3 Sekunden	749 EUR / Monat

Ein Abo entspricht einem aktiven Webhook mit einem Suchfilter und einer Ziel-URL.

Filter

Webhooks nutzen genau die Filter, die du auch von der Live-Suche kennst:

GET /api/v2/kleinanzeigen/search

Verfügbar sind unter anderem q, category_id, location_id, distance, min_price, max_price, picture_required, buy_now_only, shippable, ad_type, poster_type, latitude, longitude sowie kategoriespezifische attr[...]-Werte. ad_type=OFFER ist die normale Angebotssuche und wird nicht extra an Kleinanzeigen gesendet. Nur ad_type=WANTED wird als Gesuch-Filter weitergereicht.

Sortierung und Suchumfang

Die Suche liefert standardmäßig „Neueste zuerst“, ohne Sortierparameter. Der Webhook prüft pro Lauf nur die erste Ergebnisseite mit standardmäßig 100 Treffern (maximal 100); weitere Seiten ruft er nicht automatisch ab.

Für die Erfassung neuer Anzeigen ist daher entscheidend, ob sie zwischen zwei Prüfungen aus diesem Ergebnisfenster rutschen, nicht allein die Zahl bereits bestehender Treffer. Kürzere Intervalle verringern dieses Risiko, garantieren aber keine lückenlose Erfassung.

Lieferung

Sobald wir ein neues Inserat finden, schicken wir dir einen POST an deine Ziel-URL.

Header:

X-Klaz-Webhook-Id: <webhook_id>
X-Klaz-Delivery-Id: <delivery_id>
X-Klaz-Timestamp: 2026-05-09T12:00:00.000Z
X-Klaz-Signature: v1=<hex_hmac>

Payload:

{
  "event": "kleinanzeigen.search.ads_found",
  "webhook_id": "uuid",
  "delivery_id": "uuid",
  "created_at": "2026-05-09T12:00:00.000Z",
  "query": {
    "q": "sofa",
    "location_id": "3331",
    "distance": "25"
  },
  "data": {
    "meta": {
      "source": "live",
      "interval_seconds": 30,
      "dedupe": "new_ad_ids_only"
    },
    "ads": []
  }
}

data.ads hat dasselbe Format wie die Antwort der Live-Such-API.

Signatur prüfen

So weißt du, dass eine Lieferung wirklich von uns stammt: Wir hängen jeder Anfrage einen HMAC-SHA256 als Header an, gebildet aus

timestamp + "." + raw_body

mit deinem Webhook-Signing-Secret als Schlüssel. Das Secret findest du jederzeit im Dashboard und kannst es bei Bedarf rotieren.

Beispiel in Node.js:

import crypto from "node:crypto";

function verifyKlazWebhook({
  rawBody,
  timestamp,
  signature,
  secret,
}: {
  rawBody: string;
  timestamp: string;
  signature: string;
  secret: string;
}) {
  const expected =
    "v1=" +
    crypto
      .createHmac("sha256", secret)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Test schicken

Im Dashboard kannst du jederzeit eine Testlieferung auslösen. Sie ist signiert wie eine echte Lieferung und enthält keine Inserate, damit du deinen Endpunkt und die Signaturprüfung in Ruhe einspielen kannst.

Suchagenten

Ein Suchagent speichert eine Kleinanzeigen-Suche und meldet neue Treffer automatisch per E-Mail, Telegram oder Discord. Er ist für alle gedacht, die keine eigene Software anbinden wollen. Eingerichtet wird alles im Dashboard unter /app/suchagenten, ganz ohne API-Key.

Einrichtung

Suche zusammenstellen. Suchbegriff, Kategorie, Ort mit Umkreis, Preisspanne, Inserats- und Anbietertyp. Kategorien und Orte wählst du per Auswahlliste; die Live-Vorschau zeigt dir vor dem Abo, wie viele Inserate aktuell passen und wie die neuesten Treffer aussehen.
Kanal wählen. E-Mail geht an die verifizierte Adresse deines Kontos. Für Telegram öffnen wir unseren Bot: dort einmal auf „Start“ drücken, und dein privater Chat ist verbunden. Für Discord fügst du die Webhook-URL eines Textkanals auf deinem Server ein und sendest eine Testnachricht.
Abo abschließen. Ein Suchagent kostet 14,90 € netto pro Monat, zzgl. gesetzlicher MwSt., monatlich kündbar. Die Zahlung läuft über Stripe; Rabattcodes kannst du im letzten Schritt einlösen.

Direkt nach der Einrichtung läuft die erste Prüfung. Du bekommst eine erste Übersicht mit bis zu 20 aktuellen Treffern, damit du siehst, dass alles funktioniert.

Die zugrunde liegende Live-Suche liefert standardmäßig „Neueste zuerst“. Die Vorschau und die erste Übersicht zeigen dir daher die neuesten Treffer.

Lieferung

Dein Suchagent prüft alle 2 Minuten.
Nach der ersten Übersicht melden wir nur noch neue Inserate. Jedes Inserat erreicht dich genau einmal, auch wenn es tagelang in der Suche sichtbar bleibt.
Eine Nachricht bündelt bis zu 20 Inserate mit Titel, Preis, Ort und Link zum Original-Inserat.
Läufe ohne neue Treffer verschicken nichts, dein Postfach bleibt ruhig.

Kanäle verwalten

Deine Benachrichtigungskanäle findest du in den Einstellungen. Dort verbindest oder trennst du Telegram und Discord. Wichtig: Wenn du eine Verbindung trennst, werden Suchagenten deaktiviert, die dorthin liefern. Nach dem erneuten Verbinden kannst du sie mit einem Klick fortsetzen.

Der Kanal eines Suchagenten lässt sich jederzeit ändern, ohne den Agenten neu anzulegen.

Discord einrichten

Öffne in Discord die Einstellungen deines Textkanals und gehe zu Integrationen → Webhooks. Erstelle einen Webhook und kopiere dessen URL. Dafür brauchst du die Berechtigung „Webhooks verwalten“. Füge die URL im Suchagenten oder in den Benachrichtigungseinstellungen ein und wähle Verbinden & testen. Die Verbindung wird nach erfolgreicher Testnachricht gespeichert. Discord ist ohne Aufpreis im Suchagent-Abo enthalten.

Alle Mitglieder mit Zugriff auf den Kanal können die Suchtreffer und den Suchbegriff sehen. Pro Konto gibt es eine Discord-Verbindung; ein Wechsel betrifft alle deine Discord-Suchagenten. Persönliche Direktnachrichten, Forenkanäle und Threads werden nicht unterstützt. Die geheime Webhook-URL wird nach dem Speichern nicht angezeigt und beim Trennen entfernt.

Pausieren, testen, kündigen

Pausieren stoppt die Zustellung, das Abo läuft weiter, praktisch für Urlaub oder ruhige Phasen. Beim Fortsetzen prüft der Agent sofort wieder.
Test senden schickt eine Testnachricht an deinen Kanal, damit du die Zustellung prüfen kannst.
Kündigen beendet das Abo zum Ende des bezahlten Zeitraums. Bis dahin läuft dein Suchagent normal weiter, und du kannst die Kündigung jederzeit zurücknehmen.

Schlägt die Zustellung wiederholt fehl (zum Beispiel nach einem getrennten Telegram-Chat oder einem gelöschten Discord-Webhook), deaktivieren wir den Agenten automatisch und zeigen dir das im Dashboard an. Nach dem Beheben reicht ein Klick auf „Reaktivieren“.

Abgrenzung zu Webhooks und API

Suchagenten sind ein eigenes Produkt mit eigenem Abo. Sie verbrauchen keine API-Credits und belasten kein Rate-Limit.

Produkt	Am besten für
Suchagent	Benachrichtigungen per E-Mail, Telegram oder Discord, ohne eigenen Code
Webhooks	Neue Inserate per HTTPS-POST an deine eigene Software, Intervalle ab 3 Sekunden
API	Eigene Abfragen, Analysen und Integrationen

Wenn du mehrere Suchen parallel beobachten willst, legst du einfach mehrere Suchagenten an, jeder mit eigenem Filter, Kanal und Abo.

Fehler, Credits und Limits

Die API soll für deine Anwendung vorhersehbar sein: ungültige Requests verbrauchen keine Credits, erfolgreiche Requests werden nach Aktion berechnet, und fehlgeschlagene Live-Anfragen werden automatisch erstattet.

Fehlerantwort

Jede Fehlerantwort enthält ein maschinenlesbares error_code und eine message für Menschen. Bei Validierungsfehlern listet errors die betroffenen Felder. Bei manchen Fehlern liefert data zusätzliche Hinweise (z. B. fehlende Credits oder weiterführende Links).

{
  "success": false,
  "error_code": "INVALID_PARAMETERS",
  "message": "Invalid request parameters",
  "errors": {
    "min_price": ["min_price must be less than or equal to max_price"]
  },
  "request_id": "req_..."
}

Statuscodes

400: Ungültige Parameter, ungültige Pfad-ID oder ein vom Upstream zurückgewiesener Request.
401: klaz_key fehlt oder ist ungültig.
402: Nicht genug Credits.
404: Ressource wurde upstream nicht gefunden.
429: Planlimit erreicht oder Kleinanzeigen selbst hat das Limit ausgelöst.
500: Unerwarteter Serverfehler.
502: Kleinanzeigen hat abgelehnt oder ist temporär nicht verfügbar.
504: Timeout bei der Live-Anfrage.

Error Codes

Diskriminiere im Client auf error_code — die Codes sind stabil, während sich die message-Texte ändern können.

`error_code`	Status	Bedeutung
`INVALID_PARAMETERS`	400	Validierung fehlgeschlagen. `errors` enthält die Feldfehler.
`INVALID_AUTH_CONTEXT`	400	Auth-Header technisch fehlerhaft. Prüfe `klaz_key`.
`API_KEY_MISSING`	401	Kein `klaz_key` Header gesetzt. `data.signup_url` führt zur Anmeldung.
`API_KEY_INVALID`	401	Schlüssel unbekannt oder Account inaktiv. Neuen Schlüssel im Dashboard erzeugen.
`INSUFFICIENT_CREDITS`	402	Aktion zu teuer. `data.required_credits` und `data.available_credits` sind gesetzt; `data.buy_credits_url` und `data.upgrade_url` führen zur Abrechnung.
`UPSTREAM_BAD_REQUEST`	400	Kleinanzeigen hat den Request zurückgewiesen.
`UPSTREAM_NOT_FOUND`	404	Inserat, Verkäufer, Kategorie oder Standort existiert dort nicht (mehr).
`UPSTREAM_RATE_LIMITED`	429	Kleinanzeigen drosselt. Kurz warten und erneut versuchen — kein Plan-Upgrade nötig.
`PLAN_RATE_LIMIT_EXCEEDED`	429	Dein per-Minute-Limit ist erreicht. `data.upgrade_url` zeigt auf die Abrechnung.
`INGRESS_RATE_LIMIT_EXCEEDED`	429	Globales IP-Limit erreicht (sehr hoch angesetzt, normalerweise nur bei sehr aggressivem Traffic).
`UPSTREAM_UNAVAILABLE`	502	Kleinanzeigen ist gerade nicht erreichbar. Wird automatisch retryed.
`UPSTREAM_TIMEOUT`	504	Antwort kam nicht rechtzeitig. Erneut versuchen.
`INTERNAL_ERROR`	500	Unerwarteter Fehler bei uns. `request_id` mitsenden, wenn du Support kontaktierst.

Bei INSUFFICIENT_CREDITS enthält data die Credit-Zähler (required_credits, available_credits) plus buy_credits_url, upgrade_url, plans_url. Wer noch nie bezahlt hat, bekommt zusätzlich welcome_offer mit code, percent_off und checkout_url für den Rabatt auf die erste Zahlung eines Tarifs. Bei API_KEY_MISSING, API_KEY_INVALID und PLAN_RATE_LIMIT_EXCEEDED enthält data weiterführende URLs (signup_url, api_keys_url, docs_url, upgrade_url, plans_url), damit du Endnutzer:innen direkt zum richtigen Schritt schicken kannst.

Credit-Kosten

Kosten:

Live-Suche: 1 Credit.
Treffer pro Kategorie: 1 Credit.
Verkäuferprofil: 1 Credit.
Verkäufer-Inserate: 2 Credits.
Inseratdetails: 1 Credit.
Inseratstatus: 1 Credit.
Ähnliche Inserate: 1 Credit.
Weitere Inserate des Verkäufers ab Inserat-ID: 1 Credit.
Views zusätzlich laden: 1 Credit.
Kategorien: 1 Credit.
Kategorie-Metadaten: 1 Credit.
Standorte: 1 Credit.
Kleinanzeigen Historie (Archivsuche): 20 Credits pro angefangene 30 Tage des abgefragten Zeitraums, also 20 für die letzten 30 Tage und 260 für ein ganzes Jahr. Jede Folgeseite mit cursor kostet 20 Credits.

include_views=true addiert den Views-Credit zur jeweiligen Anfrage. Ein Detailabruf mit Views kostet also 2 Credits, ein Statusabruf mit Views kostet 2 Credits.

Mit dem Konto-API-Zugang kommen diese Aktionen dazu:

Chats auflisten: 5 Credits.
Chat öffnen: 10 Credits.
Nachricht senden: 25 Credits.
Neuen Chat starten: 50 Credits.

Live-Daten und Historie

Alle Endpunkte außer GET /api/v2/kleinanzeigen/history liefern aktuelle Daten aus der Live-Abfrage. Die Kleinanzeigen Historie ist das Archiv: Sie enthält die Inserate, die seit dem Start der Erfassung im Oktober 2026 neu erschienen oder hochgeschoben wurden. Ältere Daten gibt es nicht.

Verbindung und Stabilität

Du musst keine Proxy-Daten, Cookies oder Kleinanzeigen-spezifische Verbindungseinstellungen konfigurieren. Wir kümmern uns um Routing, Timeouts, Normalisierung und retryfähige Verbindungsfehler.

Aktuelle Einschränkungen

Raw-Antworten von Kleinanzeigen sind nicht Teil dieser API. Die Historie enthält keine Beschreibungen, Bilder oder Verkäuferdaten und kein Enddatum eines Inserats.

Die Standardsortierung der Suche ist „Neueste zuerst“ und benötigt keinen Sortierparameter. Nur die freie Wahl der Sortierung ist aktuell nicht verfügbar: Die REST API lehnt sort_type mit INVALID_PARAMETERS ab, das MCP-Tool bewirbt den Parameter nicht und entfernt ihn defensiv, falls ein Client ihn trotzdem mitsendet.

Entwicklerdokumentation

Schnellstart

Was du brauchst

Basis-URL

Erste Suche

Beispiel in JavaScript

Antwort lesen

Defaults

Authentifizierung

API-Key verwalten

Sicherer Einsatz

Typische Auth-Fehler

API Referenz

Inserate suchen

Treffer pro Kategorie

Inseratdetails abrufen

Inseratstatus prüfen

Ähnliche Inserate

Weitere Inserate zum Verkäufer eines Inserats

Verkäuferprofil abrufen

Weitere Inserate eines Verkäufers

Kategorien

Standorte

Kleinanzeigen Historie

Parameter

Kosten

Beispiel

So liest du die Treffer

Alle Seiten laden

Was die Historie nicht enthält

Fehler

Konto-API

Was du heute schon machen kannst

Hinweis zur Beta

Einrichtung

So bleibt dein Konto geschützt

Kosten

Verbindungsstatus

Chats auflisten

Chat öffnen

Nachricht senden

Neuen Chat starten

Sicher wiederholen mit request_id

Inserate erstellen

Fehlercodes

MCP Server

Wann du MCP verwenden solltest

Server-URL

Automatische Discovery

Authentifizierung

Tools

Konto-API-Tools

Beispiel für ältere Clients mit API-Key

Codex CLI

Claude Code CLI

Beispiel-Fragen an den Client

Sicherheit und Grenzen

Was dein MCP Client können muss

Häufige Fehler

A2A 1.0

Wann du A2A verwenden solltest

Verbindung

Authentifizierung

Aufbau eines Auftrags

Verfügbare Tools

Tasks und Ergebnisse

Wiederholte Anfragen

Credits und Limits

Häufige Fehler

Grenzen

Webhooks

Tarife

Filter

Sortierung und Suchumfang

Lieferung

Signatur prüfen

Test schicken

Suchagenten

Einrichtung

Lieferung