Entwicklerdokumentation

Schnellstart

Mit der API rufst du aktuelle Kleinanzeigen-Daten direkt in deiner eigenen Anwendung ab: Suche, Inseratdetails, 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://v2-api.kleinanzeigen-agent.de/api/v2/kleinanzeigen

Ab dem 01.06.2026 funktioniert zusätzlich auch die neue API-Subdomain:

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

Bis zum 01.06.2026 ist v2-api.kleinanzeigen-agent.de die Übergangs-Subdomain für die API. Danach funktionieren beide Basis-URLs.

Erste Suche

curl "https://v2-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://v2-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.

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_...

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.
• 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.

sort_type ist aktuell nicht verfügbar. Die API antwortet mit 400, wenn der Parameter gesendet wird.

curl "https://v2-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:

{
  "ad_id": "1234567890",
  "title": "Sofa",
  "description": "Guter Zustand",
  "price": {
    "amount": 120,
    "currency_code": "EUR",
    "currency_label": "Euro",
    "price_type": "FIXED",
    "negotiable": false
  },
  "shipping_available": false,
  "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.

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.

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://v2-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 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://v2-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://v2-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.

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.

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.

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.

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.

Bei INSUFFICIENT_CREDITS enthält data die Credit-Zähler (required_credits, available_credits) plus buy_credits_url, upgrade_url, plans_url. 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.
• Verkäufer-Inserate: 2 Credits.
• Inseratdetails: 1 Credit.
• Inseratstatus: 1 Credit.
• Views zusätzlich laden: 1 Credit.
• Kategorien: 1 Credit.
• Kategorie-Metadaten: 1 Credit.
• Standorte: 1 Credit.

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.

Live-Daten

Die API liefert aktuelle Daten aus der Live-Abfrage. Sie ist nicht als historisches Archiv gedacht und liefert keine gespeicherten Suchergebnisse aus früheren Läufen.

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

Die erste v2-Version konzentriert sich auf Live-Abfragen. Gespeicherte Suchhistorie, Harvesting und Raw-Antworten sind nicht Teil dieser API. sort_type ist aktuell deaktiviert.