Dieser Quickstart bringt dich in unter fünf Minuten von null zu einem erfolgreichen API-Call. Du erstellst einen API-Key in deinem Dashboard und liest damit deine Inserate über https://wohno.de/api/v1.

Bevor du startest

Du brauchst ein WOHNO-Konto und eine Organisation. Falls du noch keine hast, erstelle zuerst ein Konto — jeder API-Key gehört zu einer Organisation, und jeder Call läuft im Kontext dieser Organisation.

Zwei Voraussetzungen gaten den API-Zugriff aktuell:

Closed Beta — die API ist in einer geschlossenen Beta. Deine Organisation muss dafür freigeschaltet sein, bevor ein Key erstellt werden kann (sonst liefert die Key-Erstellung BETA_NOT_ENABLED).
Integrations-Add-on — API-Zugriff auf professional kommt seit dem Zwei-Tarif-Modell nicht mehr aus dem Plan, sondern aus dem Add-on „Integrationen" (89 €/Monat, nur zusammen mit professional buchbar); ohne Add-on hat professional 0 API-Keys und 0 Requests/Monat, professional mit Add-on gewährt 3 Keys und 25.000 Requests/Monat. Der enterprise-Plan sowie bestehende business-Konten (Legacy-Plan) behalten API-Zugriff auch ohne Add-on.

Schritt 1 — API-Key erstellen

Öffne Dashboard → Einstellungen → API unter https://wohno.de/dashboard/settings.
Klicke auf API-Key erstellen.
Wähle den Key-Typ:
- Secret Key (sk_…) — für die Server-zu-Server-Nutzung. Er kann jeden Scope tragen (read, write, delete). Nimm diesen für den Quickstart.
- Publishable Key (pk_…) — für die Browser-/Embed-Nutzung. Nur lesend und mit zwingend erforderlicher Origin-Allowlist. Im Authentifizierungs-Guide erfährst du, welcher zu deinem Use Case passt.
Vergib den Scope listings:read (reicht für diesen Quickstart).
Kopiere den Secret-Wert jetzt — ein Secret Key wird genau einmal angezeigt und nur als Hash gespeichert. Wenn du ihn verlierst, erstelle einen neuen Key.

Dein Key sieht so aus: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx. Behandle ihn wie ein Passwort: niemals in Git committen und niemals in ein Browser-Bundle ausliefern.

Schritt 2 — Deinen ersten Call machen

Schicke einen GET-Request an /api/v1/listings mit deinem Key im X-API-Key-Header:

curl https://wohno.de/api/v1/listings \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Du solltest einen HTTP 200 mit einem JSON-Body erhalten. Eine erfolgreiche Antwort sieht so aus (gekürzt):

{
  "data": [
    {
      "id": "9f1c2a3b-...",
      "title": "Bright 2-room apartment",
      "status": "published"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6...",
    "has_more": true,
    "limit": 20
  }
}

Das war's — du hast deinen ersten authentifizierten WOHNO-API-Call gemacht.

Schritt 3 — Die Antwort verstehen

Envelope — Listen-Endpoints verpacken Ergebnisse in data. GET /api/v1/listings nutzt Cursor-Pagination: Reiche pagination.next_cursor als nächstes ?cursor= weiter, solange pagination.has_more true ist. (Manche Endpoints wie GET /api/v1/organizations nutzen stattdessen Offset-Pagination mit einem meta-Objekt — siehe die Konventions-Referenz.)
Rate-Limit-Header — jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Das Limit liegt bei 1000 Requests pro Stunde pro Key.
Quota-Header — X-Quota-Limit, X-Quota-Used, X-Quota-Reset und X-Quota-Status melden den monatlichen Verbrauch deiner Organisation. Quotas werden erzwungen: Ein Überschreiten des Plan-Monatslimits liefert 429 QUOTA_EXCEEDED.
Vor dem Marktplatz-Launch — die marktplatz-bezogenen Daten-Endpoints (Listings-Reads, Discovery, Applications, Termin-Anlegen/-Ändern/-Stornieren/-Buchen, Matching) liefern bis zum öffentlichen Launch 403 LAUNCH_PENDING. Die nicht-marktplatz-bezogenen Endpoints (Webhooks, Members, Usage, WBS, Listings-Write sowie das Lesen und Löschen der eigenen Keys) sind nicht launch-gegatet — die Key-Erstellung braucht weiterhin die oben genannte Closed-Beta-Freischaltung — der obige GET /api/v1/listings-Aufruf kann in der Pre-Launch-Phase also 403 LAUNCH_PENDING liefern.
Fehler — im Fehlerfall lautet der Body { "error": { "code", "message", "status" } }. Verzweige immer über den stabilen code, nicht über den message-Text.

Probier einen anderen Endpoint

Deine Organisationen aufzulisten funktioniert genauso (hier Offset-Pagination):

curl "https://wohno.de/api/v1/organizations?page=1&per_page=20" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Nächste Schritte

Authentifizierungs-Guide — Key-Typen, Scopes, Origin-Allowlists, Rotation und Auth-Fehler.
API-Referenz — die vollständige, interaktive Endpoint-Referenz.
Use-Case-Guides — End-to-End-Anleitungen für typische Integrationen.

Bevor du startest#

Schritt 1 — API-Key erstellen#

Schritt 2 — Deinen ersten Call machen#

Schritt 3 — Die Antwort verstehen#

Probier einen anderen Endpoint#