AthausDoku

REST-API: der erste Aufruf

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

Zuletzt aktualisiert:

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. Alles andere ist JSON mit Namen in camelCase.

Der erste Aufruf

Den API-Key legst du unter Einstellungen, API-Keys an (Anmeldung). Dann:

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:

{
  "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.

Was du tun kannst

RouteWas du bekommst
GET /v1/meden Key und sein Büro
GET /v1/healthok, 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)
POST /v1/listings, PUT, PATCH und DELETE auf /v1/listings/{externalListingId}anlegen, ersetzen, ändern und löschen (Schreiben)
GET /v1/projects, GET /v1/projects/{externalProjectId}die Ids der Neubauprojekte seitenweise und ein Projekt (Projekte)
POST /v1/projects und PUT /v1/projects/{externalProjectId}ein Projekt anlegen und ändern
POST /v1/listings/{externalListingId}/publish, POST /v1/listings/{externalListingId}/unpublishein Inserat online stellen und vom Markt nehmen (Inserate)
POST /v1/mediasein Foto, einen Grundriss oder ein Dokument hochladen, das ein Inserat dann in media nennt (Inserate)
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}/messagesdie 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}/contentFotos, Grundrisse und Dokumente (Dateien herunterladen)
POST /v1/inquiries/{id}/messages, POST /v1/inquiries/{id}/followUpsAnfragenden antworten und bei ihnen nachfassen (Was das Büro verlässt)
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)
/v1/webhookEndpoints, mit rotateSecret und testAdressen, an die Athaus Ereignisse schickt (Webhooks)
GET /v1/automations, GET /v1/automations/{id}die Automatikstufen des Büros (Was das Büro verlässt)
GET /v1/apiKeys, GET und DELETE auf /v1/apiKeys/{id}die Keys des Büros auflisten, lesen und widerrufen (Keys verwalten)

Jede Operation hat in der Referenz eine eigene Seite mit Parametern, Antwortfeldern und einem curl-Beispiel.

Dateien herunterladen

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.

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 wie überall, nur der Erfolg sind Bytes.
  • Der Aufruf braucht die Stufe read auf files und zählt gegen die Grenzen fürs Lesen.

Weiter lesen

Auf dieser Seite