Skip to content

Launching soon: search & applications go live on September 30, 2026. Set up your profile now.

WOHNO

API Changelog

Chronological, additive history of the WOHNO REST API: every new resource, endpoint and scope, wave by wave.

This changelog tracks every change to the WOHNO REST API (/api/v1). The API is versioned as v1 and evolves additively — new fields, endpoints and scopes never break existing integrations. For the rules behind this (deprecation windows, DTO versioning), see the Versioning & Deprecation Policy.

Each entry lists the date, the wave it shipped with, the new endpoints, and the new scopes. Unless noted, every change is purely additive.

Availability: Every operation below is generally available (GA) and visible in the API reference — no feature flag gates the API's data surface. Two enrollment gates still stand in front of it, though: (1) creating API keys (POST /api/v1/api-keys) is in closed beta — until your organization is enabled for it, key creation returns 403 BETA_NOT_ENABLED, and it additionally requires a paid plan (see the quickstart); (2) before the public marketplace launch, the marketplace-facing data endpoints (listings reads, discovery, applications, appointment create/update/cancel/book, matching) return 403 LAUNCH_PENDING. The remaining non-marketplace endpoints (webhooks, members, usage, analytics, WBS, listings write, and reading or deleting your own keys) are available now. Resource-specific gates still apply where noted (secret-key scopes, the applications consent gate, the Premium plan for matching).

2026-08 — Booking authorization: signed booking intent

Breaking (publishable keys only)

  • POST /api/v1/appointments/{id}/book: publishable (pk_) keys can no longer book via body user_id. Instead of the unauthenticated user id, a WOHNO-issued signed booking_intent is now required (bound to the logged-in seeker session and to exactly this slot, 10-minute TTL, single-use — best-effort; on a Redis outage it fails open, the primary protection remaining signature + TTL + aid bind). Without a valid intent → 403 BOOKING_INTENT_REQUIRED; invalid/expired/replayed → 403 BOOKING_INTENT_INVALID; intent verification not configured server-side → 503 BOOKING_INTENT_UNAVAILABLE.
  • Secret (sk_) keys: core flow unchanged, two detail changes. Server-to-server booking via user_id for your own organization's applicants keeps working unchanged (applicant gate + audit log remain active). New: (1) the validation error text for a missing user_id now reads "Required for secret keys without booking_intent"; (2) a booking_intent field sent alongside is now evaluated and wins over user_id (previously an unknown field was ignored).
  • The 200 response for pk bookings now returns notes: null (internal landlord notes are no longer delivered; the field is kept for schema stability); sk responses are byte-identical. Note: the read endpoints (GET list/detail with appointments:read) currently still return notes — a hardening of the pk read path will follow separately.

Notes

  • Intent issuance is first-party only (logged-in WOHNO session). Standalone issuance for third-party origins does not exist yet — until then the pk booking path is effectively inactive (roadmap: user authentication on the REST API).
  • Security-motivated exception to the additive-only rule (closes the documented impersonation gap P55-04). At the time of the change there was no known pk consumer (closed beta); the breaking decision visibly rests with the maintainer at merge time.

2026-06 — Listings owner override

Breaking

  • Quota enforcement is now GA (default-on, no more flag). Previously the request quota only ran in tracking mode (informative X-Quota-* headers, no blocking). Starting this wave, withApiAuth enforces the plan's monthly limit unconditionally: exceeding it returns a hard 429 QUOTA_EXCEEDED (with a Retry-After header); webhook_deliveries over the limit are blocked as well (delivery marked failed, webhook.failed event with error: "quota_exceeded"). Only successful requests are charged — a 4xx/5xx response automatically refunds the consumed unit. If the quota backend (Redis) is unreachable, the request still goes through (fail-open). embed_impressions are still counted informationally, with no enforcement (no 429). See Quotas for details.

Added

  • POST /api/v1/listings accepts an optional owner_email field. It assigns the new listing to that team member (instead of the API key's creator), as long as the email belongs to a member of the same organization (role owner, admin or member). Honored on create only; ignored on external_ref upsert and PATCH.

Notes

  • Purely additive — omitting owner_email keeps the previous behavior (the key creator owns the listing).
  • An unknown email and a non-member return the same 403 FORBIDDEN, so the field cannot be used to enumerate WOHNO accounts.
  • See Sync listings from your CRM for usage.

2026-05 — Analytics & Usage (Wave 5)

Added

  • GET /api/v1/usage — quota and usage self-service for your own organization. Scope usage:read (secret keys only). GA (own data only).
  • GET /api/v1/analytics/listings/{id} — aggregated listing analytics (org-isolated, no PII). Scope analytics:read (secret keys only). GA.

Notes

  • Both endpoints are secret-key (sk_) only and excluded from publishable keys.
  • Additive: no changes to existing endpoints or response shapes.

2026-04 — Utility & Discovery (Wave 4)

Added

  • POST /api/v1/wbs/check — stateless WBS (Wohnberechtigungsschein) eligibility quick-check. Scope wbs:check, publishable-key allowed (browser-safe). GA.
  • GET /api/v1/discovery/listings — discreet, cross-org listing discovery with ETag support. Scope discovery:read, publishable-key allowed. GA — returns 403 LAUNCH_PENDING until the public marketplace launch.
  • POST /api/v1/matching/score — matching score as a service (Premium). Scope matching:score (secret keys only), aggregate output only. GA — returns 403 LAUNCH_PENDING until the public marketplace launch.

Notes

  • Additive only. wbs:check and discovery:read are the first publishable (pk_) scopes added since the read endpoints; matching:score stays sk_-only.

2026-03 — Applications / Bewerbungen (Wave 3)

Status: GA · PII-critical. This resource handles applicant PII. It is generally available and in the public reference, but access is consent-gated: an organization's api_applicant_access_enabled consent must be set, or every call fails closed with 403 CONSENT_REQUIRED. Before the public marketplace launch these endpoints additionally return 403 LAUNCH_PENDING.

Added

  • GET /api/v1/listings/{id}/applications — list applications for a listing. Scope applications:read (secret keys only).
  • GET /api/v1/applications/{id} — read a single application (reduced, whitelisted DTO). Scope applications:read (secret keys only).
  • PATCH /api/v1/applications/{id} — update application status / tags. Scope applications:write (secret keys only).

Notes

  • Secret-key (sk_) only; access is consent-gated (403 CONSENT_REQUIRED when api_applicant_access_enabled is unset).
  • Reduced ApplicationPublicDto and per-read audit logging protect applicant PII.
  • Additive: no existing endpoint changes.

2026-02 — Listings Write & Syndication (Wave 2)

Added

  • POST /api/v1/listings — create / upsert a listing (supports external_ref and Idempotency-Key). Scope listings:write (secret keys only).
  • PATCH /api/v1/listings/{id} — update a listing. Scope listings:write.
  • DELETE /api/v1/listings/{id} — delete a listing. Scope listings:delete.
  • POST / DELETE /api/v1/listings/{id}/images — signed-URL image upload and removal. Scope listings:write.

Notes

  • The previously read-only Listings resource gained write operations — additive, the existing GET endpoints and listings:read scope are unchanged.
  • Write endpoints accept an Idempotency-Key header so retried bulk writes are safe. GA.

2026-01 — Webhooks, API Keys & Members (Wave 1)

Added

  • POST /api/v1/webhooks, GET/PATCH/DELETE /api/v1/webhooks/{id} — manage webhook subscriptions (the delivery pipeline, HMAC signing and event types already existed). Scopes webhooks:read / webhooks:write.
  • GET /api/v1/webhooks/{id}/deliveries and POST .../deliveries/{deliveryId}/redeliver — delivery log + re-delivery.
  • GET/POST /api/v1/api-keys, GET/DELETE /api/v1/api-keys/{id} — manage your own API keys programmatically. Scopes api-keys:read / api-keys:write.
  • GET/POST /api/v1/organizations/{id}/members and PATCH/DELETE /api/v1/organizations/{id}/members/{userId} — manage team members. Scopes members:read / members:write.

Notes

  • All Wave 1 endpoints are secret-key (sk_) only and excluded from publishable keys. GA.
  • These scopes (webhooks:*, api-keys:*, members:*) were previously defined but had no endpoints; this wave activated them. Additive only.