# REST-API: der erste Aufruf

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

> Die REST-API liest und schreibt Inserate, Kontakte, Anfragen, Besichtigungen und Dateien deines Büros. Ein Key, ein Aufruf, JSON zurück.

Typ: Anleitung
Zuletzt aktualisiert: 2026-11-16

Die REST-API gibt deinem System Zugriff auf die Inserate, Kontakte, Anfragen, Besichtigungen und Dateien deines Büros: Lesen für alle, Schreiben für Inserate und Kontakte, Antworten und Nachfassen bei Anfragen, dazu Ereignisse und Webhooks. Die Basisadresse ist `https://api.athaus.ai/v1`. Inserate haben die [Form von OpenImmo 2.0](/api/v1/inserate). Alles andere ist JSON mit Namen in camelCase.

## Der erste Aufruf [#der-erste-aufruf]

Den API-Key legst du unter [Einstellungen, API-Keys](https://app.athaus.ai/einstellungen/api-keys) an ([Anmeldung](/api/v1/anmeldung)). Dann:

```bash
curl https://api.athaus.ai/v1/me \
  -H "Authorization: Bearer ath_live_..."
```

Die Antwort sagt, zu welchem Büro der Key gehört, was er darf und welche Version der API geantwortet hat:

```json
{
  "object": "me",
  "office": { "object": "office", "id": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17", "name": "Muster Immobilien" },
  "key": {
    "object": "api_key",
    "id": "0190f3a4-1d2e-7a55-8c10-3b9e4f6a2d08",
    "name": "Export nach Excel",
    "prefix": "ath_live_Ab3d",
    "mode": "live",
    "scopes": ["read"],
    "permissions": {
      "listings": "read",
      "contacts": "read",
      "inquiries": "read",
      "viewings": "read",
      "files": "read",
      "webhookEndpoints": "read",
      "apiKeys": "none",
      "projects": "none"
    },
    "createdAt": "2026-11-11T09:30:00Z",
    "lastUsedAt": "2026-11-11T09:41:12Z"
  },
  "apiVersion": "v1",
  "profiles": ["de"]
}
```

Ein `401` heißt: Der Key stimmt nicht. Ein `403` heißt: Dem Key fehlt ein Scope, oder dem Büro fehlt der Tarif. Beides steht unter [Fehler](/api/v1/fehler).

## Was du tun kannst [#was-du-tun-kannst]

| Route                                                                                              | Was du bekommst                                                                                                                   |
| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/me`                                                                                       | den Key und sein Büro                                                                                                             |
| `GET /v1/health`                                                                                   | `ok`, wenn die API läuft und der Key stimmt                                                                                       |
| `GET /v1/listings`, `GET /v1/listings/{externalListingId}`                                         | die Ids der Inserate seitenweise und ein Inserat ([Inserate](/api/v1/inserate))                                                   |
| `POST /v1/listings`, `PUT`, `PATCH` und `DELETE` auf `/v1/listings/{externalListingId}`            | anlegen, ersetzen, ändern und löschen ([Schreiben](/api/v1/schreiben))                                                            |
| `GET /v1/projects`, `GET /v1/projects/{externalProjectId}`                                         | die Ids der Neubauprojekte seitenweise und ein Projekt ([Projekte](/api/v1/projekte))                                             |
| `POST /v1/projects` und `PUT /v1/projects/{externalProjectId}`                                     | ein Projekt anlegen und ändern                                                                                                    |
| `POST /v1/listings/{externalListingId}/publish`, `POST /v1/listings/{externalListingId}/unpublish` | ein Inserat online stellen und vom Markt nehmen ([Inserate](/api/v1/inserate#status))                                             |
| `POST /v1/medias`                                                                                  | ein Foto, einen Grundriss oder ein Dokument hochladen, das ein Inserat dann in `media` nennt ([Inserate](/api/v1/inserate#media)) |
| `GET /v1/contacts`, `GET /v1/contacts/{id}`                                                        | die Kontakte des Büros                                                                                                            |
| `POST /v1/contacts`, `PATCH` und `DELETE` auf `/v1/contacts/{id}`                                  | einen Kontakt anlegen, ändern und löschen                                                                                         |
| `GET /v1/inquiries`, `GET /v1/inquiries/{id}`, `GET /v1/inquiries/{id}/messages`                   | die Anfragen und ihre Gespräche                                                                                                   |
| `GET /v1/viewings`, `GET /v1/viewings/{id}`                                                        | die Besichtigungstermine mit ihren Gästen                                                                                         |
| `GET /v1/files`, `GET /v1/files/{id}`, `GET /v1/files/{id}/content`                                | Fotos, Grundrisse und Dokumente ([Dateien herunterladen](#downloading-files))                                                     |
| `POST /v1/inquiries/{id}/messages`, `POST /v1/inquiries/{id}/followUps`                            | Anfragenden antworten und bei ihnen nachfassen ([Was das Büro verlässt](/api/v1/hinausgehen))                                     |
| `GET /v1/proposals`, `GET /v1/proposals/{id}`                                                      | was aus einer `202` wurde                                                                                                         |
| `GET /v1/events`, `GET /v1/events/{id}`                                                            | was im Büro geschah, 30 Tage lang ([Ereignisse](/api/v1/ereignisse))                                                              |
| `/v1/webhookEndpoints`, mit `rotateSecret` und `test`                                              | Adressen, an die Athaus Ereignisse schickt ([Webhooks](/api/v1/webhooks))                                                         |
| `GET /v1/automations`, `GET /v1/automations/{id}`                                                  | die Automatikstufen des Büros ([Was das Büro verlässt](/api/v1/hinausgehen#die-stufe-lesen))                                      |
| `GET /v1/apiKeys`, `GET` und `DELETE` auf `/v1/apiKeys/{id}`                                       | die Keys des Büros auflisten, lesen und widerrufen ([Keys verwalten](/api/v1/anmeldung#keys-verwalten))                           |

Jede Operation hat in der [Referenz](/api/v1/referenz) eine eigene Seite mit Parametern, Antwortfeldern und einem curl-Beispiel.

## Dateien herunterladen [#downloading-files]

`GET /v1/files/{id}` liefert die Angaben zu einer Datei, `GET /v1/files/{id}/content` die Datei selbst. Die Antwort sind die Bytes des Originals, als Download (`Content-Disposition: attachment`) und mit dem Medientyp, den Athaus gespeichert hat. Ist keiner gespeichert, kommt `application/octet-stream`.

```bash
curl -H "Authorization: Bearer $ATHAUS_KEY" \
  -o foto.jpg \
  https://api.athaus.ai/v1/files/<id>/content
```

* Die Datei kommt ganz, in einer Antwort. Es gibt keine Varianten wie Vorschaubilder, kein `Range` und kein `HEAD`. Die Länge steht vorab in `sizeBytes` bei den Angaben.
* Die Angaben zu einer Datei tragen keine Adresse für den Inhalt. Bilde sie aus der `id`.
* Eine Datei eines anderen Büros und eine Datei, die es nicht mehr gibt, antworten beide mit `404`. Ein Fehler kommt als JSON im [Problem-Format](/api/v1/fehler) wie überall, nur der Erfolg sind Bytes.
* Der Aufruf braucht die Stufe `read` auf `files` und zählt gegen die [Grenzen](/api/v1/limits) fürs Lesen.

<Cards>
  <Card title="Anmeldung" href="/api/v1/anmeldung" description="API-Keys, Scopes und Stufen." />

  <Card title="Inserate" href="/api/v1/inserate" description="Die Form von OpenImmo 2.0." />

  <Card title="Länderprofile" href="/api/v1/laenderprofile" description="Ein Kern, ein Profil je Land." />

  <Card title="Was das Büro verlässt" href="/api/v1/hinausgehen" description="Antworten, 202 und Vorschläge." />

  <Card title="Fehler" href="/api/v1/fehler" description="Problem Details, der Code, die Request-Id." />

  <Card title="Blättern" href="/api/v1/blaettern" description="Page Token, Cursor und updatedSince." />

  <Card title="Webhooks" href="/api/v1/webhooks" description="Ereignisse an deine Adresse, signiert." />

  <Card title="Ereignisse" href="/api/v1/ereignisse" description="Was geschah, 30 Tage lang." />

  <Card title="Referenz" href="/api/v1/referenz" description="Jede Operation auf einer eigenen Seite." />
</Cards>
