# Upload a file

Adresse: https://docs.athaus.ai/api/v1/referenz/create-media

> Aufruf, Parameter, Antwort und Fehler von POST /v1/medias.

Typ: Referenz
Zuletzt aktualisiert: 2026-11-14

Stores one photo, floor plan or document and returns its id. The body is the file itself, not JSON: `Content-Type` is its type (image/jpeg, image/png, image/webp, application/pdf), at most 25 MB. The query says what the file is: `kind` (`photo`, `floor_plan`, `document`), `documentType` for a document, `fileName`, and your own `externalMediaId`. The file belongs to no listing yet: name its `externalMediaId` in `media` when you create or change a listing, in the order you want. A file no listing names is removed after 7 days. The content must be of the type the header names (415 otherwise). Send `Idempotency-Key` to make a retry safe. Needs write access to `files`.

Braucht den Scope [`propose`](/api/v1/anmeldung#scopes) und mindestens die Stufe `write` auf `files`.

## Aufruf [#aufruf]

```http
POST https://api.athaus.ai/v1/medias
```

### Parameter [#parameter]

**Abfrage**

| Name              | Typ      | Pflicht | Beschreibung                                                                                                                                                                                                                                                                                |
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fileName`        | `string` | nein    | The name the file keeps in the app and in downloads. Without it the file is named `file` plus its type's ending.                                                                                                                                                                            |
| `kind`            | `string` | nein    | What the file is. Without it an image is a `photo` and a PDF a `document`. A `photo` must be an image; a `floor_plan` may be an image or a PDF. Eines von `photo`, `floor_plan`, `document`.                                                                                                |
| `documentType`    | `string` | nein    | For a `document`, which paper it is, in the keys the app uses: `energy_certificate`, `floor_plan`, `living_area`, `land_registry`, `declaration_of_division`, `budget_plan`, `logs`, `utilities`, `lease`, `property_tax`, `expose`, `modernization`, `other`. Not allowed for other kinds. |
| `externalMediaId` | `string` | nein    | Your id of the file, which a listing names in `media[].externalMediaId`. Unique in the office. Without it Athaus uses the `id` it returns. 1 to 200 characters: letters, digits, `.`, `_`, `:` and `-`, starting with a letter or digit.                                                    |

**Kopf**

| Name              | Typ      | Pflicht | Beschreibung                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Athaus-Version`  | `string` | nein    | Optional and carries nothing a client needs: the version is the path. Accepted when it says `v1` or `1`. Any other value is a 400 `api_version_unsupported`.                                                                                                                                                                                                                                                                         |
| `Idempotency-Key` | `string` | nein    | Makes a retry safe: the same key with the same body returns the first answer and writes nothing twice. A random value of at least 128 bits, for example a UUID, 1 to 255 characters. The key is kept for 24 hours and scoped to the API key and this operation. The same key with a different body is a 422; while the first request still runs it is a 409. Only successful answers are kept: after an error the key is free again. |

### Beispiel [#beispiel]

```bash
curl -X POST "https://api.athaus.ai/v1/medias" \
  -H "Authorization: Bearer ath_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: image/jpeg" \
  --data-binary @file
```

## Antwort [#antwort]

Bei Erfolg kommt `201` mit `Media`.

### Media [#media]

| Feld              | Typ                  | Beschreibung                                                                           |
| ----------------- | -------------------- | -------------------------------------------------------------------------------------- |
| `object`          | `string`             | Immer `media`.                                                                         |
| `id`              | `string (uuid)`      | UUID of the file. It stays the id of the file in `/files` once a listing has taken it. |
| `externalMediaId` | `string`             | The id a listing names in `media[].externalMediaId`.                                   |
| `kind`            | `string`             | Eines von `photo`, `floor_plan`, `document`.                                           |
| `documentType`    | `string \| null`     |                                                                                        |
| `fileName`        | `string`             |                                                                                        |
| `mimeType`        | `string`             |                                                                                        |
| `sizeBytes`       | `integer`            |                                                                                        |
| `width`           | `integer \| null`    | In pixels, for an image where it is known.                                             |
| `height`          | `integer \| null`    | In pixels, for an image where it is known.                                             |
| `createdAt`       | `string (date-time)` |                                                                                        |

### Köpfe der Antwort [#köpfe-der-antwort]

| Kopf                  | Beschreibung                                                                                                    |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `Request-Id`          | Identifies this request. Quote it in a support request.                                                         |
| `Athaus-Version`      | The API version of this response: v1.                                                                           |
| `Athaus-Release`      | The release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it. |
| `RateLimit-Policy`    | The quota policy of the bucket that applies.                                                                    |
| `RateLimit`           | Remaining quota and seconds until the bucket is full again.                                                     |
| `Idempotent-Replayed` | `true` when this is the stored answer to an earlier request with the same Idempotency-Key.                      |

## Fehler [#fehler]

Jeder Fehler kommt als [Problem Details](/api/v1/fehler). Verzweige auf `code`, nicht auf `title` oder `detail`.

| Status | Codes                                                                                                                                                                                                        | Bedeutung                                                                                                                             |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | [`invalid_query`](/api/errors#invalid_query), [`api_version_unsupported`](/api/errors#api_version_unsupported), [`invalid_body`](/api/errors#invalid_body)                                                   | Invalid request.                                                                                                                      |
| `401`  | [`unauthorized`](/api/errors#unauthorized)                                                                                                                                                                   | Missing or invalid API key.                                                                                                           |
| `403`  | [`insufficient_permissions`](/api/errors#insufficient_permissions), [`plan_required`](/api/errors#plan_required)                                                                                             | The key lacks a right, or the plan does not include API access.                                                                       |
| `404`  | [`not_found`](/api/errors#not_found)                                                                                                                                                                         | Nothing under this ID.                                                                                                                |
| `409`  | [`reference_already_exists`](/api/errors#reference_already_exists), [`idempotency_key_in_use`](/api/errors#idempotency_key_in_use), [`idempotency_outcome_unknown`](/api/errors#idempotency_outcome_unknown) | The request conflicts with the state of the resource (for example a duplicate), or with an idempotency key.                           |
| `413`  | [`payload_too_large`](/api/errors#payload_too_large)                                                                                                                                                         | The file is larger than 25 MB.                                                                                                        |
| `415`  | [`invalid_input`](/api/errors#invalid_input)                                                                                                                                                                 | The Content-Type is not one of image/jpeg, image/png, image/webp, application/pdf, or the bytes are not of the type the header names. |
| `422`  | [`idempotency_key_reused`](/api/errors#idempotency_key_reused)                                                                                                                                               | The idempotency key was already used with a different request body.                                                                   |
| `429`  | [`rate_limited`](/api/errors#rate_limited)                                                                                                                                                                   | Rate limit exceeded.                                                                                                                  |
| `500`  | [`internal_error`](/api/errors#internal_error)                                                                                                                                                               | Server error.                                                                                                                         |
