# REST API: the first call

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

> The REST API reads and writes the listings, contacts, inquiries, viewings and files of your office. One key, one call, JSON back.

Type: Guide
Last updated: 2026-11-16

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](/en/api/v1/inserate). Everything else is JSON with camelCase names.

## The first call [#the-first-call]

You create an API key under [Settings, API-Keys](https://app.athaus.ai/einstellungen/api-keys) ([Authentication](/en/api/v1/anmeldung)). Then:

```bash
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:

```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 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](/en/api/v1/fehler).

## What you can do [#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](/en/api/v1/inserate))                                   |
| `POST /v1/listings`, `PUT`, `PATCH` and `DELETE` on `/v1/listings/{externalListingId}`             | create, replace, change and delete ([Writing](/en/api/v1/schreiben))                                                      |
| `GET /v1/projects`, `GET /v1/projects/{externalProjectId}`                                         | the ids of the new-build projects in pages, and one project ([Projects](/en/api/v1/projekte))                             |
| `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](/en/api/v1/inserate#status))                                  |
| `POST /v1/medias`                                                                                  | upload a photo, a floor plan or a document, which a listing then names in `media` ([Listings](/en/api/v1/inserate#media)) |
| `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](#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](/en/api/v1/hinausgehen))                        |
| `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](/en/api/v1/ereignisse))                                                |
| `/v1/webhookEndpoints`, with `rotateSecret` and `test`                                             | addresses Athaus sends events to ([Webhooks](/en/api/v1/webhooks))                                                        |
| `GET /v1/automations`, `GET /v1/automations/{id}`                                                  | the automation levels of the office ([What leaves the office](/en/api/v1/hinausgehen#read-the-level))                     |
| `GET /v1/apiKeys`, `GET` and `DELETE` on `/v1/apiKeys/{id}`                                        | list, read and revoke the keys of the office ([Manage keys](/en/api/v1/anmeldung#keys-verwalten))                         |

Every operation has its own page in the [reference](/en/api/v1/referenz) with parameters, response fields and a curl example. Operations for new-build projects are in the document and marked as planned.

## Downloading files [#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`.

```bash
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](/en/api/v1/fehler) like everywhere else; only success is bytes.
* The call needs the level `read` on `files` and counts against the read [limits](/en/api/v1/limits).

<Cards>
  <Card title="Authentication" href="/en/api/v1/anmeldung" description="API keys, scopes and levels." />

  <Card title="Listings" href="/en/api/v1/inserate" description="The OpenImmo 2.0 shape." />

  <Card title="Country profiles" href="/en/api/v1/laenderprofile" description="One core, one profile per country." />

  <Card title="What leaves the office" href="/en/api/v1/hinausgehen" description="Replies, 202 and proposals." />

  <Card title="Errors" href="/en/api/v1/fehler" description="Problem details, the code, the request id." />

  <Card title="Pagination" href="/en/api/v1/blaettern" description="Page token, cursor and updatedSince." />

  <Card title="Webhooks" href="/en/api/v1/webhooks" description="Events to your address, signed." />

  <Card title="Events" href="/en/api/v1/ereignisse" description="What happened, for 30 days." />

  <Card title="Reference" href="/en/api/v1/referenz" description="Every operation on its own page." />
</Cards>
