Kleinanzeigen Agent v2 ist live

Willkommen bei Kleinanzeigen Agent v2.

v2 ist nicht einfach ein größeres Update der alten API. Wir haben den Kern neu gebaut, weil v1 an eine Grenze gekommen ist: zu viele interne Zwischenschichten, zu viel Mapping, zu wenig Klarheit für moderne Integrationen.

Das Ziel von v2 ist einfach: Kleinanzeigen-Daten sollen schneller, näher an der Quelle und verlässlicher in deinen Anwendungen ankommen.

Das Problem mit v1

v1 hat lange funktioniert. Aber die Architektur war nicht mehr die richtige Basis für das, was viele inzwischen bauen wollen: Preis-Tracker, Marktanalysen, Matching-Tools, Benachrichtigungen, interne Dashboards oder eigene Agenten mit KI-Logik.

Vor allem drei Dinge haben gestört:

• Requests liefen durch unnötige interne Ebenen.
• Daten wurden in ein eigenes Zwischenformat übersetzt.
• Änderungen auf Kleinanzeigen mussten erst durch unser Mapping, bevor sie bei dir sichtbar wurden.

Das war okay für einfache Abfragen. Für echte Produktintegrationen war es zu schwerfällig.

Das Ziel von v2

v2 soll eine saubere Entwicklerplattform sein: direkt, gut dokumentiert und planbar im Betrieb.

Die API soll nicht im Weg stehen. Sie soll Live-Daten liefern, mit einer klaren Antwortstruktur, nachvollziehbarer Abrechnung und Endpunkten, die sich gut in bestehende Systeme integrieren lassen.

Die Lösung

Näher an der Quelle

v2 reicht Daten so weiter, wie Kleinanzeigen sie liefert. Es gibt kein eigenes Zwischenformat mehr, das Felder versteckt, umbenennt oder verzögert. Wenn Kleinanzeigen neue Informationen bereitstellt, können sie schneller in deiner Integration ankommen.

Spürbar schneller

Wir haben den Request-Pfad deutlich verkürzt. Weniger interne Logik zwischen deinem Aufruf und der Plattform bedeutet schnellere Antworten und weniger Reibung im laufenden Betrieb.

Einheitliche Antworten

Jeder Endpunkt folgt demselben Muster:

{
  "success": true,
  "data": {},
  "request_id": "req_..."
}

Fehler sind ebenfalls berechenbar. Bei fehlendem Guthaben bekommst du zum Beispiel einen error_code, den du direkt im Frontend oder in deiner Job-Logik behandeln kannst:

{
  "success": false,
  "message": "Insufficient credits",
  "error_code": "INSUFFICIENT_CREDITS",
  "data": {
    "required_credits": 2,
    "available_credits": 0
  },
  "request_id": "req_..."
}

Validierungsfehler kommen feldgenau im errors-Objekt zurück. Jede Antwort enthält außerdem eine request_id, damit Logs, Support-Anfragen und Debugging nachvollziehbarer werden.

Was neu ist

Basis-URL: https://v2-api.kleinanzeigen-agent.de/api/v2/kleinanzeigen. Auth-Header: klaz_key: klaz_live_....

Zum Start sind diese Bereiche live:

• GET /search - Live-Suche mit Filtern für Kategorie, Standort, Preis, Bilder, Versand, Inserattyp und kategoriespezifische Attribute.
• GET /ads/:ad_id - Vollständige Inseratdetails, optional inklusive Aufrufzahl (include_views=true).
• GET /ads/:ad_id/status - Leichtgewichtiger Statuscheck für aktive oder gelöschte Inserate.
• GET /sellers/:seller_id/ads - Weitere Inserate desselben Verkäufers.
• GET /categories, /categories/:id/metadata, /categories/:id/search-metadata - Kategoriebaum und Filterattribute.
• GET /locations, GET /locations/:id - Standortsuche nach Name, Postleitzahl oder Koordinaten.

Die vollständige Parameterliste mit Beispielantworten steht in der Dokumentation.

Was sich geändert hat

Neuer Auth-Header

Der Auth-Header heißt in v2 klaz_key. Alte v1-Keys funktionieren nicht mehr. Nach dem ersten Login erstellst du im Dashboard einen neuen API-Key und nutzt ihn direkt für v2.

Credits statt unklarer Nutzung

Du zahlst pro tatsächlicher Aktion, meistens ein bis zwei Credits je nach Aufwand. Pläne liefern monatliches Guthaben, Credit-Pakete kannst du unabhängig vom Abo dazukaufen und nutzen, wann du sie brauchst. Rate Limits hängen direkt am Plan und greifen sofort, sobald du upgradest.

Ungültige Requests verbrennen keine Credits. Wenn ein Live-Call wegen eines Upstream-Problems fehlschlägt, bekommst du den Credit automatisch zurück. Du sollst genau wissen, wofür du zahlst.

Keine automatische Migration alter Suchagenten

Suchagenten aus v1 werden nicht migriert. Der Grund ist bewusst: v2 ist als API-Plattform gebaut, nicht als starres Agenten-Produkt. Wenn du Agenten brauchst, kannst du sie mit v2 flexibler aufbauen - mit eigener Logik, eigenen Triggern, eigenen Filtern und der KI deiner Wahl.

Migration von v1

Dein v2-Account existiert bereits. Du loggst dich mit derselben E-Mail-Adresse ein, die du auf der alten Plattform genutzt hast, durchläufst ein kurzes Onboarding und erstellst deinen neuen API-Key.

Wenn du auf v1 ein aktives Abo hattest, haben wir dir Migrations-Credits gutgeschrieben. Du kannst direkt weiterarbeiten, ohne dass dir Guthaben fehlt.

Für den Umstieg sind drei Punkte wichtig:

• Erstelle einen neuen klaz_key im v2-Dashboard.
• Passe deine Requests an die v2-Endpunkte und die neue Antwortstruktur an.
• Plane den Wechsel vor dem 1. Juni 2026 ein.

Bis zum 1. Juni 2026 läuft die alte v1-API unter api.kleinanzeigen-agent.de parallel weiter. Danach schalten wir v1 ab.

Für wen v2 gedacht ist

v2 ist für alle, die Kleinanzeigen-Daten nicht nur anschauen, sondern in eigene Produkte und Workflows einbauen wollen.

Das können Marktanalysen, Preis-Tracker, Deal-Monitoring, Matching-Tools, Benachrichtigungs-Bots oder interne Recherche-Systeme sein.

Mehr Sichtbarkeit für API-Produkte

Mit v2 haben wir uns auch entschieden, vollständig zur Entwicklerplattform zu werden. Dazu gehört für uns nicht nur die API selbst, sondern auch eine öffentliche Bühne für das, was darauf entsteht.

Unter /apps möchten wir Projekte aus der Community sichtbar machen: Tools, Agenten, Dashboards, Bots, interne Workflows oder ganze Produkte, die Kleinanzeigen-Daten sinnvoll nutzen.

Wenn du etwas mit v2 baust, melde dich bei uns. Wir schauen es uns an und nehmen passende Projekte dort auf.

Jetzt loslegen

Account, Plan und Guthaben verwaltest du über /app/abrechnung. Schnellstart, Endpunkte und Beispielantworten findest du in der Dokumentation.

Wenn du Feedback hast, migrierst, Fragen stellst oder uns zeigen willst, was du mit v2 baust: melde dich unter [email protected].