Upload a file
Aufruf, Parameter, Antwort und Fehler von POST /v1/medias.
Zuletzt aktualisiert:
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 und mindestens die Stufe write auf files.
Aufruf
POST https://api.athaus.ai/v1/mediasParameter
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
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 @fileAntwort
Bei Erfolg kommt 201 mit 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
| 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
Jeder Fehler kommt als Problem Details. Verzweige auf code, nicht auf title oder detail.
| Status | Codes | Bedeutung |
|---|---|---|
400 | invalid_query, api_version_unsupported, invalid_body | Invalid request. |
401 | unauthorized | Missing or invalid API key. |
403 | insufficient_permissions, plan_required | The key lacks a right, or the plan does not include API access. |
404 | not_found | Nothing under this ID. |
409 | reference_already_exists, idempotency_key_in_use, 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 | The file is larger than 25 MB. |
415 | 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 | The idempotency key was already used with a different request body. |
429 | rate_limited | Rate limit exceeded. |
500 | internal_error | Server error. |
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: 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.