API

Référence de l'API

Base : /api/v1. Spécification complète au format OpenAPI 3.1 : openapi.json (importable dans Postman, Insomnia ou un générateur de client).

Console d'essai

La clé reste dans cette page (jamais enregistrée) et n'est envoyée qu'à notre API. Les appels comptent dans vos quotas et peuvent consommer des crédits : préférez une clé dédiée, limitée aux droits de lecture.

Clé d'APIOpération

La console envoie seulement des requêtes GET. Pour POST et DELETE, utilisez curl ou votre client HTTP depuis un serveur.

Endpoints

GET/me

Clé utilisée, droits, limites, usage du mois et solde de crédits

toute clé valide

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

GET/sources

Sources renvoyées par l'API (redistribution autorisée)

toute clé valide

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

GET/listings/search

Recherche synchrone de voitures

Réponses des sites en cache et des sites rapides, 8 s au plus. « q » est analysé sans IA ; les paramètres explicites sont prioritaires. Au moins « make » ou « q ».

droit : search:read1 crédit(s)

Paramètres
Paramètre	Où	Type
q	requête	string · 200 car. maxTexte libre (ex. « golf diesel automatique moins de 80000 km »)
make	requête	string · 40 car. max
model	requête	string · 40 car. max
price_min	requête	integer · ≥ 0, ≤ 10000000
price_max	requête	integer · ≥ 0, ≤ 10000000
year_min	requête	integer · ≥ 1950, ≤ 2100
year_max	requête	integer · ≥ 1950, ≤ 2100
km_max	requête	integer · ≥ 0, ≤ 2000000
fuel	requête	petrol \| diesel \| hybrid \| plugin_hybrid \| electric \| lpg \| cng \| hydrogen
gearbox	requête	manual \| automatic
body_type	requête	string
canton	requête	string
mode	requête	achat \| leasing \| abonnement \| encheres
sort	requête	price_asc \| price_desc \| km_asc \| year_desc
limit	requête	integer · ≥ 1, ≤ 50 · défaut 20
cursor	requête	string · 300 car. maxCurseur de la page suivante

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
402 Crédits insuffisants
403 Droit (scope), adresse IP ou origine navigateur non autorisés
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

GET/parts/search

Recherche synchrone de pièces

droit : parts:read1 crédit(s)

Paramètres
Paramètre	Où	Type
q	requête	string · 200 car. max
part	requête	string
oem	requête	string · 40 car. maxRéférence d'origine (ex. 5G0941005A)
make	requête	string · 40 car. max
model	requête	string · 40 car. max
year	requête	integer · ≥ 1950, ≤ 2049
side	requête	left \| right
position	requête	front \| rear
condition	requête	new \| used
price_max	requête	integer · ≥ 1, ≤ 1000000
sort	requête	total_asc \| relevance
limit	requête	integer · ≥ 1, ≤ 50 · défaut 20
cursor	requête	string · 300 car. max

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
402 Crédits insuffisants
403 Droit (scope), adresse IP ou origine navigateur non autorisés
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

POST/searches

Lancer une recherche asynchrone (tous les sites autorisés)

Répond 202 avec l'identifiant. Suivi par GET /searches/{id} ou par le webhook « search.completed ». Scope search:read (voitures) ou parts:read (mode « pieces »).

droit : search:read1 crédit(s)

Corps JSON (schéma)

{
  "type": "object",
  "properties": {
    "mode": {
      "default": "achat",
      "type": "string",
      "enum": [
        "achat",
        "leasing",
        "abonnement",
        "encheres",
        "pieces"
      ]
    },
    "ask": {
      "type": "string",
      "maxLength": 200
    },
    "criteria": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          {
            "type": "number"
          }
        ]
      }
    }
  },
  "additionalProperties": false
}

202 Recherche acceptée
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
402 Crédits insuffisants
403 Droit (scope), adresse IP ou origine navigateur non autorisés
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

GET/searches/{id}

Statut, progression par site et offres d'une recherche asynchrone

droit : search:read

Paramètres
Paramètre	Où	Type
id *	chemin	stringIdentifiant « srch_… »
page	requête	integer · ≥ 1 · défaut 1
per_page	requête	integer · ≥ 1, ≤ 100 · défaut 50

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
404 Ressource introuvable (ou appartenant à un autre compte)
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

DELETE/searches/{id}

Annuler une recherche en attente ou en cours

droit : search:read

Paramètres
Paramètre	Où	Type
id *	chemin	stringIdentifiant « srch_… »

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
404 Ressource introuvable (ou appartenant à un autre compte)
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

GET/market/models/{marque}/{modele}

Statistiques agrégées d'un modèle (prix médian, fourchette, par année et km)

droit : market:read1 crédit(s)

Paramètres
Paramètre	Où	Type
marque *	chemin	stringIdentifiant en minuscules (ex. volkswagen)
modele *	chemin	stringIdentifiant en minuscules (ex. golf)

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
402 Crédits insuffisants
403 Droit (scope), adresse IP ou origine navigateur non autorisés
404 Ressource introuvable (ou appartenant à un autre compte)
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

GET/market/price-position

Fourchette du marché en direct et position d'un prix

Interroge les sites en direct : jusqu'à ~40 s.

droit : market:read2 crédit(s)

Paramètres
Paramètre	Où	Type
make *	requête	string · 40 car. max
model *	requête	string · 40 car. max
year *	requête	integer · ≥ 1950
km *	requête	integer · ≥ 0, ≤ 1500000
fuel	requête	petrol \| diesel \| hybrid \| plugin_hybrid \| electric \| lpg \| cng \| hydrogen
gearbox	requête	manual \| automatic
price_chf	requête	integer · ≥ 500, ≤ 5000000

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
402 Crédits insuffisants
403 Droit (scope), adresse IP ou origine navigateur non autorisés
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

GET/alerts

Alertes du compte

droit : alerts:write

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

POST/alerts

Créer une alerte

Quota de l'offre, puis crédits au-delà. Événement webhook « alert.match » à chaque nouvelle offre.

droit : alerts:write3 crédit(s)

Corps JSON (schéma)

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "mode": {
      "default": "achat",
      "type": "string",
      "enum": [
        "achat",
        "leasing",
        "abonnement",
        "encheres",
        "pieces"
      ]
    },
    "criteria": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          {
            "type": "number"
          }
        ]
      }
    },
    "kind": {
      "default": "new_match",
      "type": "string",
      "enum": [
        "new_match",
        "price_below"
      ]
    },
    "threshold_chf": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000
    },
    "frequency": {
      "default": "immediate",
      "type": "string",
      "enum": [
        "immediate",
        "daily",
        "weekly"
      ]
    }
  },
  "required": [
    "name",
    "criteria"
  ],
  "additionalProperties": false
}

201 Alerte créée
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
402 Crédits insuffisants
403 Droit (scope), adresse IP ou origine navigateur non autorisés
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

DELETE/alerts/{id}

Supprimer une alerte

droit : alerts:write

Paramètres
Paramètre	Où	Type
id *	chemin	stringIdentifiant numérique de l'alerte

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
404 Ressource introuvable (ou appartenant à un autre compte)
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

GET/webhooks

Webhooks du compte (sans secret)

droit : webhooks:write

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

POST/webhooks

Créer un webhook (le secret de signature n'est renvoyé qu'une fois)

droit : webhooks:write

Corps JSON (schéma)

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "url",
    "events"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "https, adresse publique, sans redirection"
    },
    "events": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "enum": [
          "search.completed",
          "alert.match",
          "price.drop"
        ]
      }
    },
    "description": {
      "type": "string",
      "maxLength": 100
    }
  }
}

201 Webhook créé
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

GET/webhooks/{id}

Journal des 50 dernières livraisons

droit : webhooks:write

Paramètres
Paramètre	Où	Type
id *	chemin	stringIdentifiant « wh_… »

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
404 Ressource introuvable (ou appartenant à un autre compte)
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

DELETE/webhooks/{id}

Supprimer un webhook

droit : webhooks:write

Paramètres
Paramètre	Où	Type
id *	chemin	stringIdentifiant « wh_… »

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
404 Ressource introuvable (ou appartenant à un autre compte)
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

POST/webhooks/{id}/test

Envoyer un événement de test signé (5 par minute)

droit : webhooks:write

Paramètres
Paramètre	Où	Type
id *	chemin	stringIdentifiant « wh_… »

200 Succès
400 Requête invalide (paramètre inconnu ou répété, valeur refusée, clé dans l'URL)
401 Clé absente, invalide, révoquée ou expirée
403 Droit (scope), adresse IP ou origine navigateur non autorisés
404 Ressource introuvable (ou appartenant à un autre compte)
429 Limite de débit ou quota mensuel atteints (voir Retry-After)
503 API momentanément indisponible ou désactivée

Voir aussi : webhooks et conditions d'utilisation.