REST API: the first call
The REST API reads and writes the listings, contacts, inquiries, viewings and files of your office. One key, one call, JSON back.
Last updated:
The REST API gives your system access to the listings, contacts, inquiries, viewings and files of your office: reading for all of them, writing for listings and contacts, replying and following up on inquiries, plus events and webhooks. The base address is https://api.athaus.ai/v1. Listings use the OpenImmo 2.0 shape. Everything else is JSON with camelCase names.
The first call
You create an API key under Settings, API-Keys (Authentication). Then:
curl https://api.athaus.ai/v1/me \
-H "Authorization: Bearer ath_live_..."The response tells you which office the key belongs to, what it may do and which version of the API answered:
{
"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 to 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"]
}A 401 means the key is wrong. A 403 means the key lacks a scope or the office lacks the plan. Both are covered under Errors.
What you can do
| Route | What you get |
|---|---|
GET /v1/me | the key and its office |
GET /v1/health | ok when the API is up and the key is valid |
GET /v1/listings, GET /v1/listings/{externalListingId} | the ids of the listings page by page, and one listing (Listings) |
POST /v1/listings, PUT, PATCH and DELETE on /v1/listings/{externalListingId} | create, replace, change and delete (Writing) |
GET /v1/projects, GET /v1/projects/{externalProjectId} | the ids of the new-build projects in pages, and one project (Projects) |
POST /v1/projects and PUT /v1/projects/{externalProjectId} | create and change a project |
POST /v1/listings/{externalListingId}/publish, POST /v1/listings/{externalListingId}/unpublish | put a listing online and take it off the market (Listings) |
POST /v1/medias | upload a photo, a floor plan or a document, which a listing then names in media (Listings) |
GET /v1/contacts, GET /v1/contacts/{id} | the contacts of the office |
POST /v1/contacts, PATCH and DELETE on /v1/contacts/{id} | create, change and delete a contact |
GET /v1/inquiries, GET /v1/inquiries/{id}, GET /v1/inquiries/{id}/messages | the inquiries and their conversations |
GET /v1/viewings, GET /v1/viewings/{id} | the viewing appointments with their guests |
GET /v1/files, GET /v1/files/{id}, GET /v1/files/{id}/content | photos, floor plans and documents (Downloading files) |
POST /v1/inquiries/{id}/messages, POST /v1/inquiries/{id}/followUps | reply to and follow up with people who inquired (What leaves the office) |
GET /v1/proposals, GET /v1/proposals/{id} | what became of a 202 |
GET /v1/events, GET /v1/events/{id} | what happened in the office, for 30 days (Events) |
/v1/webhookEndpoints, with rotateSecret and test | addresses Athaus sends events to (Webhooks) |
GET /v1/automations, GET /v1/automations/{id} | the automation levels of the office (What leaves the office) |
GET /v1/apiKeys, GET and DELETE on /v1/apiKeys/{id} | list, read and revoke the keys of the office (Manage keys) |
Every operation has its own page in the reference with parameters, response fields and a curl example. Operations for new-build projects are in the document and marked as planned.
Downloading files
GET /v1/files/{id} returns the details of a file, GET /v1/files/{id}/content the file itself. The response is the bytes of the original, as a download (Content-Disposition: attachment) and with the media type Athaus stored. If none is stored, you get application/octet-stream.
curl -H "Authorization: Bearer $ATHAUS_KEY" \
-o photo.jpg \
https://api.athaus.ai/v1/files/<id>/content- The file comes whole, in one response. There are no variants such as thumbnails, no
Rangeand noHEAD. The length is known up front fromsizeBytesin the details. - The details of a file carry no address for the content. Build it from the
id. - A file of another office and a file that no longer exists both answer
404. An error arrives as JSON in the problem format like everywhere else; only success is bytes. - The call needs the level
readonfilesand counts against the read limits.
Authentication
API keys, scopes and levels.
Listings
The OpenImmo 2.0 shape.
Country profiles
One core, one profile per country.
What leaves the office
Replies, 202 and proposals.
Errors
Problem details, the code, the request id.
Pagination
Page token, cursor and updatedSince.
Webhooks
Events to your address, signed.
Events
What happened, for 30 days.
Reference
Every operation on its own page.
Keep reading
REST API: authentication with an API key
Every call to /v1 carries an API key as a bearer token. Where to get one, which scopes it carries and what does not work.
REST API: listings in the OpenImmo 2.0 shape
Read and write listings in the shape of OpenImmo 2.0. Two ids, drafts, receipts, warnings, and every member of a listing.
REST API: errors as problem details
Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.
REST API reference
Every operation of /v1 with parameters, response and example, generated from the contract of the API.