Biens
Le catalogue, et votre propre inventaire à l'intérieur. Les endpoints de lecture couvrent tout ce que nous détenons ; ceux d'écriture ne touchent jamais que les fiches publiées par votre organisation.
/v1/api/propertiesproperties:readLister les biens
Parcourez le catalogue page par page, avec des filtres.
L'endpoint de lecture du quotidien. Les filtres se combinent avec un ET. Ce qui est omis reste sans contrainte : un appel sans filtre renvoie donc tout le catalogue dans l'ordre du curseur.
Paramètres de requête
| Nom | Type | Description |
|---|---|---|
city | string | Ville à laquelle se restreindre, telle qu'elle figure dans l'adresse d'un bien. exemple : Berlin |
district | string | Quartier au sein de la ville. exemple : Kreuzberg |
postal_code | string | Code postal auquel se restreindre. exemple : 10999 |
type | enum | Nature du bien. apartment | house | studio | villa | penthouse | loft | townhouse | other exemple : apartment |
transaction_type | enum | Restreindre aux ventes ou aux locations. sale | rent exemple : sale |
status | enum | Statut de l'annonce. Omettez-le pour obtenir tous les statuts plutôt que les seuls actifs. active | archived | sold | flagged exemple : active |
external_id | string | Votre propre identifiant de fiche, pour retrouver ce qu'un import a créé. exemple : OBJ-10041 |
min_price | number | Borne inférieure incluse du prix affiché. exemple : 250000 |
max_price | number | Borne supérieure incluse du prix affiché. exemple : 750000 |
min_living_area | number | Borne inférieure incluse de la surface habitable, en mètres carrés. exemple : 60 |
min_bedrooms | integer | Borne inférieure incluse du nombre de chambres. exemple : 2 |
limit | integer | Fiches par page. par défaut : 50exemple : 50 |
cursor | string | Pointeur opaque issu de la réponse précédente. À omettre pour la première page. Les curseurs sont stables face aux insertions : la pagination ne saute donc jamais une fiche et n'en répète aucune, contrairement à un décalage. exemple : eyJpZCI6InByb3BfMWI3N2UwYTRmMiJ9 |
sort | string | Champ de tri. Préfixez d'un moins pour un ordre décroissant. exemple : -created_at |
expand | enum | Fiches liées à inclure directement plutôt qu'à récupérer séparément. images | price_history | market | translations exemple : images |
language | string | Répondre dans cette langue lorsque le bien la possède, sous forme de code ISO 639-1. Un bien qui ne possède pas la langue conserve son propre texte plutôt que d'être répondu dans une autre, et la réponse indique dans quelle langue elle est revenue. Ce sont les flux portant plusieurs langues qui alimentent ce champ. exemple : es |
Réponse
{
"data": [
{ "id": "prop_8f2a41c9d0", "title": "Top-floor apartment…", "price": 42900000 },
{ "id": "prop_1b77e0a4f2", "title": "Garden flat…", "price": 38500000 }
],
"meta": {
"has_more": true,
"next_cursor": "eyJpZCI6InByb3BfMWI3N2UwYTRmMiJ9",
"limit": 50
}
}https://api.skautik.com/v1/api/properties
GET /v1/api/properties?city=Berlin&district=Kreuzberg&postal_code=10999 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/properties/searchproperties:readRechercher des biens
Recherche sémantique et géographique trop complexe pour une chaîne de requête.
Accepte une requête en langage naturel, un polygone tracé, ou les deux. Les résultats reviennent classés par pertinence plutôt que par une colonne triable : cet endpoint ignore donc le paramètre sort. C'est un POST parce qu'un polygone n'a pas sa place dans une URL, pas parce qu'il modifie quoi que ce soit.
Champs du corps
| Nom | Type | Description |
|---|---|---|
query | string | Description en langage courant de ce qui est recherché. exemple : "quiet two bedroom near a park, needs a home office" |
polygon | array | Anneau fermé de paires [longitude, latitude], dans l'ordre GeoJSON. exemple : [[13.3702, 52.4812], [13.4791, 52.4812], [13.4791, 52.5401], [13.3702, 52.5401], [13.3702, 52.4812]] |
bounds | object | Rectangle avec sw_lat, sw_lng, ne_lat, ne_lng. Mutuellement exclusif avec polygon. exemple : {"north": 52.5401, "south": 52.4812, "east": 13.4791, "west": 13.3702} |
filters | object | Les mêmes clés que celles acceptées en paramètres de requête par l'endpoint de liste. exemple : {"property_type": "apartment", "price_max": 60000000} |
limit | integer | Résultats à renvoyer, de 1 à 200. par défaut : 50exemple : 50 |
Corps de la requête
{
"query": "quiet two bedroom near a park, needs a home office",
"filters": {
"market": "berlin-de",
"transaction_type": "sale",
"price_max": 50000000
},
"limit": 20
}Réponse
{
"data": [
{
"id": "prop_8f2a41c9d0",
"title": "Top-floor apartment…",
"relevance": 0.87,
"matched_on": ["quiet street", "park within 300m", "study alcove"]
}
],
"meta": { "has_more": false, "limit": 20 }
}https://api.skautik.com/v1/api/properties/search
POST /v1/api/properties/search HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"query": "quiet two bedroom near a park, needs a home office",
"filters": {
"market": "berlin-de",
"transaction_type": "sale",
"price_max": 50000000
},
"limit": 20
}/v1/api/properties/{property_id}properties:readRécupérer un bien
Un bien avec l'ensemble complet de ses attributs.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
property_idobligatoire | string | Identifiant renvoyé par n'importe quel endpoint de collection. exemple : prop_8f2a41c9d0 |
Paramètres de requête
| Nom | Type | Description |
|---|---|---|
expand | enum | Fiches liées à inclure directement plutôt qu'à récupérer séparément. images | price_history | market | translations exemple : images |
language | string | Répondre dans cette langue lorsque le bien la possède, sous forme de code ISO 639-1. Un bien qui ne possède pas la langue conserve son propre texte plutôt que d'être répondu dans une autre, et la réponse indique dans quelle langue elle est revenue. Ce sont les flux portant plusieurs langues qui alimentent ce champ. exemple : es |
Réponse
{
"data": {
"id": "prop_8f2a41c9d0",
"title": "Top-floor apartment with a south-facing balcony",
"property_type": "apartment",
"transaction_type": "sale",
"price": 42900000,
"currency": "EUR",
"price_period": null,
"price_per_area": 579700,
"bedrooms": 2,
"bathrooms": 1,
"rooms": 3,
"living_area": 74,
"floor": 4,
"total_floors": 4,
"year_built": 1908,
"energy_label": "C",
"address": {
"street": "Oranienstrasse",
"postal_code": "10999",
"district": "Kreuzberg",
"city": "Berlin",
"country": "DE"
},
"location": {
"latitude": 52.4993,
"longitude": 13.4184,
"precision": "street"
},
"status": "active",
"listed_at": "2026-07-28T09:12:04Z",
"last_verified_at": "2026-08-11T04:00:00Z",
"updated_at": "2026-08-11T04:00:00Z"
}
}Réponses notables
- 404
- Identifiant inconnu, ou fiche que votre clé ne peut pas voir. À traiter comme une absence.
https://api.skautik.com/v1/api/properties/{property_id}
GET /v1/api/properties/prop_8f2a41c9d0?expand=images&language=es HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/properties/{property_id}/price-historyproperties:readHistorique des prix
Tous les prix affichés observés pendant le suivi de l'annonce.
Ce sont des prix annoncés, pas des prix de transaction. Un bien peut très bien s'être vendu à un montant assez différent de son dernier prix affiché.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
property_idobligatoire | string | Identifiant du bien. exemple : prop_8f2a41c9d0 |
Réponse
{
"data": [
{ "price": 44900000, "currency": "EUR", "observed_at": "2026-07-28T09:12:04Z" },
{ "price": 42900000, "currency": "EUR", "observed_at": "2026-08-09T06:31:11Z" }
]
}https://api.skautik.com/v1/api/properties/{property_id}/price-history
GET /v1/api/properties/prop_8f2a41c9d0/price-history HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/properties/{property_id}/similarGrowth and aboveproperties:readBiens similaires
Fiches comparables, pour le contexte ou l'appui d'une estimation.
La similarité mêle emplacement, surface, type et état. C'est une commodité, pas une expertise, et les comparables se raréfient vite dans les secteurs peu fournis.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
property_idobligatoire | string | Bien de référence pour la comparaison. exemple : prop_8f2a41c9d0 |
Paramètres de requête
| Nom | Type | Description |
|---|---|---|
limit | integer | Comparables à renvoyer, de 1 à 50. exemple : 10 |
https://api.skautik.com/v1/api/properties/{property_id}/similar
GET /v1/api/properties/prop_8f2a41c9d0/similar?limit=10 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/propertiesproperties:writeCréer un bien
Publiez une fiche de votre propre inventaire.
Envoyez une Idempotency-Key pour qu'une requête réessayée ne puisse pas créer une annonce en double. Les fiches créées ainsi appartiennent à votre organisation et sont les seules que votre clé peut modifier.
Champs du corps
| Nom | Type | Description |
|---|---|---|
external_id | string | Votre identifiant pour ce bien. Facultatif, mais renseignez-le si la fiche risque d'arriver plus tard par un import : sans lui, l'import n'a rien pour faire le rapprochement et crée un doublon. exemple : AG-4471-0812 |
titleobligatoire | string | Titre de l'annonce. exemple : Top-floor apartment with a south-facing balcony |
property_typeobligatoire | enum | L'un des types de biens pris en charge. exemple : apartment |
transaction_typeobligatoire | enum | sale ou rent. exemple : sale |
priceobligatoire | integer | Montant en unités mineures. exemple : 48900000 |
currencyobligatoire | string | Code ISO 4217. exemple : EUR |
addressobligatoire | object | Au minimum une ville et un pays ; plus il y en a, meilleure est la précision du géocodage. exemple : {"street": "Oranienstrasse 12", "postal_code": "10999", "city": "Berlin", "country": "DE"} |
En-têtes
| Nom | Type | Description |
|---|---|---|
Idempotency-Key | string | Unique par création logique. Rejouer la même clé renvoie le résultat d'origine au lieu de créer une seconde fiche. exemple : a2f1c7e4-… |
Corps de la requête
{
"title": "Top-floor apartment with a south-facing balcony",
"property_type": "apartment",
"transaction_type": "sale",
"price": 42900000,
"currency": "EUR",
"living_area": 74,
"bedrooms": 2,
"address": {
"street": "Oranienstrasse",
"postal_code": "10999",
"city": "Berlin",
"country": "DE"
}
}Réponses notables
- 201
- Créé. L'en-tête Location porte l'URL de la nouvelle ressource.
- 409
- Une Idempotency-Key a été réutilisée avec un corps différent.
- 422
- Le corps a été analysé mais a échoué à la validation. Voir le tableau errors.
https://api.skautik.com/v1/api/properties
POST /v1/api/properties HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"title": "Top-floor apartment with a south-facing balcony",
"property_type": "apartment",
"transaction_type": "sale",
"price": 42900000,
"currency": "EUR",
"living_area": 74,
"bedrooms": 2,
"address": {
"street": "Oranienstrasse",
"postal_code": "10999",
"city": "Berlin",
"country": "DE"
}
}/v1/api/properties/{property_id}properties:writeMettre à jour un bien
Modifiez des champs d'une fiche que vous avez publiée.
C'est une mise à jour partielle : n'envoyez que ce qui change. Envoyez If-Match avec l'ETag de votre dernière lecture pour ne pas écraser une modification concurrente. Une fiche appartenant à une source d'import est refusée ici, parce que la prochaine exécution annulerait ce que vous auriez écrit : modifiez-la plutôt dans le système qui alimente l'import.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
property_idobligatoire | string | Bien à mettre à jour. exemple : prop_8f2a41c9d0 |
En-têtes
| Nom | Type | Description |
|---|---|---|
If-Match | string | ETag de votre dernière lecture. Rejeté avec un 412 si la fiche a changé entre-temps. exemple : "3f8a2c1d9b" |
Corps de la requête
{
"title": "Top-floor apartment with a south-facing balcony and new windows",
"listing": {
"price": 419000,
"status": "active"
}
}Réponses notables
- 403
- La fiche existe mais votre organisation ne l'a pas publiée.
- 409
- managed_by_import. La fiche appartient à une source d'import, qui fait autorité sur elle. Le corps nomme la source.
- 412
- Le If-Match n'a pas correspondu. Relisez et réappliquez votre modification.
https://api.skautik.com/v1/api/properties/{property_id}
PATCH /v1/api/properties/prop_8f2a41c9d0 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"title": "Top-floor apartment with a south-facing balcony and new windows",
"listing": {
"price": 419000,
"status": "active"
}
}/v1/api/properties/{property_id}properties:writeRetirer un bien
Retirez du marché l'une de vos fiches.
Un retrait n'est pas une suppression. La fiche passe en retiré, disparaît de la recherche et conserve son historique de prix pour que les analyses passées restent lisibles. Une fiche appartenant à une source d'import est refusée, parce que la prochaine exécution la ramènerait aussitôt : retirez-la à la source.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
property_idobligatoire | string | Bien à retirer. exemple : prop_8f2a41c9d0 |
Réponses notables
- 204
- Retiré. Pas de corps.
- 409
- managed_by_import. Retirez-le à la source, ou supprimez d'abord la source.
https://api.skautik.com/v1/api/properties/{property_id}
DELETE /v1/api/properties/prop_8f2a41c9d0 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/properties/{property_id}/imagesproperties:readLister les images
Les fiches d'image d'un bien, dans l'ordre d'affichage.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
property_idobligatoire | string | Identifiant du bien. exemple : prop_8f2a41c9d0 |
https://api.skautik.com/v1/api/properties/{property_id}/images
GET /v1/api/properties/prop_8f2a41c9d0/images HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/properties/{property_id}/imagesimages:writeEnvoyer une image
Attachez une image à une fiche que vous avez publiée.
Envoi multipart. JPEG, PNG ou WebP jusqu'à 12 Mo. N'envoyez que des images dont vous détenez les droits : la photographie immobilière est le plus souvent concédée sous licence à un agent plutôt que détenue en propre.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
property_idobligatoire | string | Bien auquel l'attacher. exemple : prop_8f2a41c9d0 |
Paramètres de requête
| Nom | Type | Description |
|---|---|---|
room_type | string | Ce que montre la photographie ; sert à regrouper les images et à choisir une source pour la mise en scène. exemple : living_room |
primary | boolean | Passez true pour en faire l'image principale, ce qui rétrograde l'actuelle. exemple : true |
Champs du corps
| Nom | Type | Description |
|---|---|---|
fileobligatoire | binary | Contenu de l'image. exemple : listings.csv |
position | integer | Ordre d'affichage. L'image en position 0 est l'image principale. exemple : 1 |
Réponses notables
- 413
- Le fichier dépasse la taille limite.
- 415
- Format d'image non pris en charge.
https://api.skautik.com/v1/api/properties/{property_id}/images
POST /v1/api/properties/prop_8f2a41c9d0/images?room_type=living_room&primary=true HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"file": "listings.csv",
"position": 1
}/v1/api/properties/{property_id}/images/{image_id}images:writeSupprimer une image
Retirez une image d'une fiche que vous avez publiée.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
property_idobligatoire | string | Identifiant du bien. exemple : prop_8f2a41c9d0 |
image_idobligatoire | string | Identifiant de l'image. exemple : img_2b7d4f1908 |
https://api.skautik.com/v1/api/properties/{property_id}/images/{image_id}
DELETE /v1/api/properties/prop_8f2a41c9d0/images/img_2b7d4f1908 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…