CarHunt Watchlists API

openapi: 3.2.0
info:
  title: CarHunt Pro Watchlists API
  description: 'API de sourcing automobile CarHunt Pro : recherche multi-critères dans

    plus d’un million d''annonces actives agrégées depuis 6

    sources. Un cycle complet d''actualisation du catalogue est lancé toutes les

    4 heures. Chaque annonce dispose d''un score de

    sous-cote et de médianes de marché. Les critères des watchlists sont évalués toutes les

    10 minutes sur le catalogue déjà collecté, puis les

    webhooks sont notifiés après détection. ### Authentification

    Créez une clé API dans votre espace app.carhunt.fr

    (Réglages → API, offre Business ou API Analyste attribuée), puis transmettez-la sur chaque requête :


    Authorization: Bearer chp_live_…


    ### Quotas

    Le plan Business inclut un quota mensuel de **véhicules**. L''offre API Analyste,

    attribuée individuellement, inclut 1 000 **analyses** et 5 000 **véhicules**

    par mois calendaire UTC. `GET /v1/usage` expose les deux soldes. Chaque véhicule renvoyé par la recherche ou livré par webhook est décompté

    une fois. `POST /v1/estimate` et `GET /v1/listings/{listing_id}/analysis`

    consomment chacun une analyse si une réponse exploitable est produite ; les

    trois comparables inclus ne débitent pas de véhicules. Une cohorte de moins

    de cinq annonces rend 422 sans débit. Les crédits d''analyse prépayés prennent

    le relais après le quota mensuel et n''expirent pas. Pour proposer 3 à 5 alternatives, appelez `GET /v1/listings/search` avec

    `page_size=3` à `5`, budget (`price_max`) et critères du client ; le nombre

    de véhicules effectivement renvoyés est débité. Aucun classement personnalisé

    ni garantie de disponibilité chez l''annonceur n''est implicite. Rate-limit : 60 req/min par clé. ### Synchronisation des annonces importées

    `GET /v1/listings/changes` accepte jusqu''à 100 identifiants CarHunt dans `ids`. La recherche fournit `sync_until` pour initialiser le suivi sans nouvel import. Sans date, le flux peut réinitialiser un lot (véhicules décomptés). Transmettez

    `updated_since` avec le `sync_until` du dernier lot traité : seuls les véhicules

    réellement modifiés sont renvoyés et décomptés. Une réponse vide ne consomme rien. Chaque élément expose `last_modified_at`, `status` et la fiche `listing`. Les statuts `inactive` et `deleted` permettent de retirer les annonces du catalogue

    client ; `deleted` a une fiche nulle et ne signifie pas vendu. `unknown_ids` ne

    prouve pas un retrait. Revisites et recalculs de score ne déclenchent pas d''édition. Le suivi commence à `tracking_started_at` : une date antérieure rend 409 et exige

    une réinitialisation sans date. Un lot dépassant le solde rend 429 sans décompte. Le paramètre `since` de la recherche continue à servir aux **nouvelles** annonces. ### Estimation et historique

    `POST /v1/estimate` accepte marque, modèle, année, kilométrage et des filtres

    facultatifs (énergie, boîte, motorisation, finition), sans annonce à résoudre. Les quartiles et la médiane portent sur les **prix demandés** d''annonces actives

    comparables, pas sur les transactions. La cohorte est échantillonnée à 2 000

    annonces récentes au maximum ; `sample_truncated` le signale. Les repères de

    négociation sont statistiques : ils ne tiennent pas compte de l''état réel. L''historique et la volatilité de `GET /v1/listings/{listing_id}/analysis`

    concernent **cette annonce**, pas l''ensemble du marché. L''historique peut être vide. `history_status` distingue `unavailable` (aucune observation sur la période demandée),

    `no_change_recorded` (aucune variation enregistrée depuis la première observation)

    et `price_changed`. `source_url` et `current_price` concernent l''annonce analysée. La collecte d''historique ayant débuté en juin 2026, une absence de variation

    enregistrée ne permet pas de conclure sur les prix antérieurs. Exemple d''estimation (prix en euros, kilométrage en km) :


    ```json

    {"make":"RENAULT","model":"CLIO","year":2020,"mileage":50000,"energy":"Essence","asking_price":13500}

    ```


    ### Couverture

    Le catalogue cible les annonces automobiles d''occasion en France.'
  contact:
    name: CarHunt Pro
    url: https://app.carhunt.fr/
    email: contact@carhunt.fr
  version: 1.0.0
servers:
- url: /public-api
- url: https://api-pro.carhunt.fr
  description: Production
- url: https://api-pro-stage.carhunt.fr
  description: Staging
tags:
- name: Watchlists
paths:
  /v1/watchlists:
    get:
      tags:
      - Watchlists
      summary: Lister les watchlists de l'organisation
      operationId: list_watchlists_v1_watchlists_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/WatchlistOut'
                type: array
                title: Response List Watchlists V1 Watchlists Get
    post:
      tags:
      - Watchlists
      summary: Créer une watchlist (alerte push)
      description: 'La watchlist est **armée dès sa création**. Ses critères sont évalués toutes les 10 minutes sur le catalogue déjà collecté. Les annonces détectées depuis le passage précédent sont poussées en POST JSON sur `webhook_url` (payload : watchlist + liste d''annonces au format ListingOut). La première livraison est possible au passage suivant s''il y a de nouvelles annonces matchantes ; ce rythme ne constitue pas un délai garanti depuis la publication chez la source. Le stock existant n''est jamais renvoyé, seules les annonces découvertes APRÈS la création le sont. Chaque véhicule livré par webhook est décompté du quota mensuel, comme un véhicule renvoyé par l''API ; à quota épuisé les livraisons sont suspendues puis reprennent là où elles se sont arrêtées.'
      operationId: create_watchlist_v1_watchlists_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistIn'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/watchlists/{watchlist_id}:
    patch:
      tags:
      - Watchlists
      summary: Modifier une watchlist
      description: 'Modification partielle d''une watchlist : nom, critères de ciblage, webhook,

        mise en pause (`is_active`). Seuls les champs présents dans le corps sont

        appliqués ; un critère de filtre transmis à `null` est retiré.'
      operationId: update_watchlist_v1_watchlists__watchlist_id__patch
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
          title: Watchlist Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistPatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Watchlists
      summary: Supprimer une watchlist
      operationId: delete_watchlist_v1_watchlists__watchlist_id__delete
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
          title: Watchlist Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WatchlistIn:
      properties:
        name:
          type: string
          maxLength: 120
          title: Name
        make:
          anyOf:
          - type: string
          - type: 'null'
          title: Make
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        region:
          anyOf:
          - type: string
          - type: 'null'
          title: Region
        departments:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Departments
        year_min:
          anyOf:
          - type: integer
          - type: 'null'
          title: Year Min
        year_max:
          anyOf:
          - type: integer
          - type: 'null'
          title: Year Max
        mileage_max:
          anyOf:
          - type: integer
          - type: 'null'
          title: Mileage Max
        price_max:
          anyOf:
          - type: integer
          - type: 'null'
          title: Price Max
        energy:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Energy
        gearbox:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Gearbox
        motorization:
          anyOf:
          - type: string
          - type: 'null'
          title: Motorization
        finition:
          anyOf:
          - type: string
          - type: 'null'
          title: Finition
        seller_type:
          anyOf:
          - type: string
            pattern: ^(pro|private)$
          - type: 'null'
          title: Seller Type
        min_deal_score:
          anyOf:
          - type: number
            maximum: 100.0
            minimum: 0.0
          - type: 'null'
          title: Min Deal Score
        webhook_url:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Webhook Url
          description: URL POST JSON notifiée après détection d'une nouvelle annonce matchante ; les critères sont évalués toutes les 10 minutes sur le catalogue déjà collecté
      type: object
      required:
      - name
      title: WatchlistIn
    WatchlistOut:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        filters:
          type: object
          title: Filters
        webhook_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Url
        is_active:
          type: boolean
          title: Is Active
        last_alerted_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Alerted At
          description: 'Watermark du scheduler (UTC) : posé à la création, puis avancé à chaque passage ayant trouvé et livré de nouvelles annonces'
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
      type: object
      required:
      - id
      - name
      - filters
      - is_active
      title: WatchlistOut
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WatchlistPatch:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Name
        make:
          anyOf:
          - type: string
          - type: 'null'
          title: Make
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        region:
          anyOf:
          - type: string
          - type: 'null'
          title: Region
        departments:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Departments
        year_min:
          anyOf:
          - type: integer
          - type: 'null'
          title: Year Min
        year_max:
          anyOf:
          - type: integer
          - type: 'null'
          title: Year Max
        mileage_max:
          anyOf:
          - type: integer
          - type: 'null'
          title: Mileage Max
        price_max:
          anyOf:
          - type: integer
          - type: 'null'
          title: Price Max
        energy:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Energy
        gearbox:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Gearbox
        motorization:
          anyOf:
          - type: string
          - type: 'null'
          title: Motorization
        finition:
          anyOf:
          - type: string
          - type: 'null'
          title: Finition
        seller_type:
          anyOf:
          - type: string
            pattern: ^(pro|private)$
          - type: 'null'
          title: Seller Type
        min_deal_score:
          anyOf:
          - type: number
            maximum: 100.0
            minimum: 0.0
          - type: 'null'
          title: Min Deal Score
        webhook_url:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Webhook Url
        is_active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Active
          description: Mettre en pause (false) ou réactiver (true) la watchlist
      type: object
      title: WatchlistPatch
      description: 'Modification partielle : seuls les champs transmis sont appliqués.

        Un champ de filtre transmis à `null` retire ce critère. Impossible de vider

        entièrement les critères (422).'