AthausDocs

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

RouteWhat you get
GET /v1/methe key and its office
GET /v1/healthok 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}/unpublishput a listing online and take it off the market (Listings)
POST /v1/mediasupload 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}/messagesthe 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}/contentphotos, floor plans and documents (Downloading files)
POST /v1/inquiries/{id}/messages, POST /v1/inquiries/{id}/followUpsreply 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 testaddresses 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 Range and no HEAD. The length is known up front from sizeBytes in 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 read on files and counts against the read limits.

Keep reading

On this page