# REST-API: Ereignisse

Adresse: https://docs.athaus.ai/api/v1/ereignisse

> Was im Büro geschah, 30 Tage lang abrufbar. Dieselben Ereignisse, die an Webhooks gehen, gefiltert nach Typ und Zeit.

Typ: Anleitung
Zuletzt aktualisiert: 2026-11-14

`GET /v1/events` liefert, was im Büro geschah: neue Anfragen und Nachrichten, gebuchte, abgesagte und anstehende Besichtigungen, Dateien, die gelesen wurden. Das sind dieselben Ereignisse, die ein [Webhook](/api/v1/webhooks) bekommt, mit derselben Id. Nutze die Liste, wenn du keine Adresse hast, einen Webhook verpasst hast oder nach einem Ausfall aufholen willst.

```bash
curl "https://api.athaus.ai/v1/events?type=inquiry.received&limit=2" \
  -H "Authorization: Bearer ath_live_..."
```

```json
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "0190f3c1-22aa-7d10-9b3e-0f8e5c6a1d44",
      "type": "inquiry.received",
      "createdAt": "2026-11-12T08:14:03.512Z",
      "apiVersion": "v1",
      "livemode": true,
      "data": {
        "object": {
          "object": "inquiry",
          "id": "0190f3c1-2217-7a02-8c4b-5e1d7a9b3f10",
          "listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
          "status": "new",
          "source": "athaus",
          "answered": false,
          "replyable": true,
          "name": "Mia K.",
          "email": null,
          "phone": null,
          "contactId": null,
          "contactConsent": "not_requested",
          "seeker": null,
          "createdAt": "2026-11-12T08:14:03Z",
          "updatedAt": "2026-11-12T08:14:03Z"
        }
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJzIjoiLWNyZWF0ZWRBdCIsLi4ufQ"
}
```

## Was ein Ereignis ist [#was-ein-ereignis-ist]

`{ object: "event", id, type, createdAt, apiVersion, livemode, data: { object } }`.

* `type` ist einer der Namen aus der [Webhook-Tabelle](/api/v1/webhooks#events). Neue Typen kommen ohne neue Version: Überlies, was du nicht kennst.
* `data.object` ist die Ressource, um die es im Ereignis geht, in der Form, in der `/v1` sie liest. Sie hat den Stand von jetzt, nicht den des Ereignisses: Brauchst du den Stand von damals, musst du ihn beim Zustellen festhalten. Gibt es die Ressource nicht mehr, kommt stattdessen `{ "object": "viewing", "id": "...", "deleted": true }`.
* Was ein `GET` nicht liefert, steht auch hier nicht. Name, E-Mail und Telefon einer suchenden Person erscheinen nur, solange sie sie dem Büro freigegeben hat.
* `apiVersion` ist die Version, in der `data` geformt ist.
* `livemode` ist `false` bei einem Ereignis des [Testbüros](/api/v1/testmodus).

## Wie lange, und wer was sieht [#wie-lange-und-wer-was-sieht]

Ein Ereignis ist 30 Tage abrufbar; danach antwortet `GET /v1/events/{id}` mit `404`, und die Liste zeigt es nicht mehr.

Ein Key sieht nur die Ereignisse der Ressourcen, die er lesen darf: Ohne `read` auf `viewings` fehlen ihm die drei Besichtigungs-Typen. `proposal.pending` sieht er nur für Vorschläge, die er selbst angelegt hat. Einen `type` außerhalb davon zu verlangen ist `403` (`insufficient_permissions`). Ein einzelnes Ereignis außerhalb davon ist `404`. Die Liste braucht den Scope `read`, aber keine Stufe auf einer eigenen Ressource.

## Filtern und blättern [#filtern-und-blättern]

| Parameter         | Wirkung                                                       |
| ----------------- | ------------------------------------------------------------- |
| `type`            | nur Ereignisse dieses Typs                                    |
| `createdSince`    | nur Ereignisse ab diesem Zeitpunkt (ISO 8601, einschließlich) |
| `createdBefore`   | nur Ereignisse vor diesem Zeitpunkt                           |
| `limit`, `cursor` | wie überall, siehe [Blättern](/api/v1/blaettern)              |

Die Liste ist nach `createdAt` absteigend sortiert, das Neueste zuerst, und die Reihenfolge ist fest. Es gibt kein `sort` und kein `updatedSince`: Ein Ereignis ändert sich nie.

## Nach einem Ausfall aufholen [#nach-einem-ausfall-aufholen]

Behalte die `id` des neuesten Ereignisses, das du verarbeitet hast, und die Zeit seines `createdAt`. Lies mit `createdSince` ab dieser Zeit, blättere bis zum Ende und überspring, was du schon hast. Ereignisse mit derselben Zeit kommen genau einmal, auch über Seitengrenzen.

```bash
curl "https://api.athaus.ai/v1/events/0190f3c1-22aa-7d10-9b3e-0f8e5c6a1d44" \
  -H "Authorization: Bearer ath_live_..."
```

Beide Operationen stehen in der [Referenz](/api/v1/referenz/list-events).
