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
| 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) |
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}/unpublish | ein Inserat online stellen und vom Markt nehmen (Inserate) |
POST /v1/medias | ein 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}/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) |
POST /v1/inquiries/{id}/messages, POST /v1/inquiries/{id}/followUps | Anfragenden 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 test | Adressen, 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
Rangeund keinHEAD. Die Länge steht vorab insizeBytesbei 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
readauffilesund zählt gegen die Grenzen fürs Lesen.
Anmeldung
API-Keys, Scopes und Stufen.
Inserate
Die Form von OpenImmo 2.0.
Länderprofile
Ein Kern, ein Profil je Land.
Was das Büro verlässt
Antworten, 202 und Vorschläge.
Fehler
Problem Details, der Code, die Request-Id.
Blättern
Page Token, Cursor und updatedSince.
Webhooks
Ereignisse an deine Adresse, signiert.
Ereignisse
Was geschah, 30 Tage lang.
Referenz
Jede Operation auf einer eigenen Seite.
Weiter lesen
REST-API: Anmeldung mit einem API-Key
Jeder Aufruf von /v1 trägt einen API-Key als Bearer-Token. Wo du ihn bekommst, welche Scopes er trägt und was nicht geht.
REST-API: Inserate in der Form von OpenImmo 2.0
Inserate lesen und schreiben in der Form von OpenImmo 2.0. Zwei Ids, Entwürfe, Quittungen, Hinweise und jedes Mitglied eines Inserats.
REST-API: Fehler als Problem Details
Jeder Fehler von /v1 ist ein Problem nach RFC 9457 mit echtem HTTP-Status, einem Code zum Verzweigen und einer Request-Id für den Support.
REST-API Referenz
Jede Operation von /v1 mit Parametern, Antwort und Beispiel, aus dem Vertrag der API erzeugt.