openapi: 3.1.0
info:
  title: CarDossier Market API
  version: 1.0.0
  description: Real-time Polish used car market data. Valuation, price history, liquidity, and regional pricing.
servers:
  - url: https://car-dossier.com/api/v1
    description: Production Server
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
security:
  - ApiKeyAuth: []
paths:
  /market/valuation:
    get:
      summary: Get Market Valuation
      description: Returns average, median, P25, and P75 prices for a specific make/model/year.
      parameters:
        - name: make
          in: query
          required: true
          schema: { type: string }
        - name: model
          in: query
          required: true
          schema: { type: string }
        - name: year
          in: query
          required: true
          schema: { type: integer }
        - name: fuel_type
          in: query
          required: false
          schema: { type: string, enum: [Benzyna, Diesel, Hybryda, Elektryczny] }
        - name: gearbox
          in: query
          required: false
          schema: { type: string, enum: [Manualna, Automatyczna] }
        - name: mileage
          in: query
          required: false
          schema: { type: integer }
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: "success" }
                  data:
                    type: object
                    properties:
                      valuation:
                        type: object
                        properties:
                          average: { type: number }
                          median: { type: number }
                          p25: { type: number }
                          p75: { type: number }
                      sample_size: { type: integer }
                      credits_remaining: { type: integer }

  /market/price-history:
    get:
      summary: Get Price History
      parameters:
        - name: make
          in: query
          required: true
          schema: { type: string }
        - name: model
          in: query
          required: true
          schema: { type: string }
        - name: year
          in: query
          required: true
          schema: { type: integer }
        - name: months
          in: query
          required: false
          schema: { type: integer, default: 6 }
      responses:
        '200':
          description: Successful response

  /market/liquidity:
    get:
      summary: Get Market Liquidity (Days on Market)
      parameters:
        - name: make
          in: query
          required: true
          schema: { type: string }
        - name: model
          in: query
          required: true
          schema: { type: string }
        - name: year
          in: query
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Successful response

  /market/valuation-factors:
    get:
      summary: Get Valuation Factors
      parameters:
        - name: make
          in: query
          required: true
          schema: { type: string }
        - name: model
          in: query
          required: true
          schema: { type: string }
        - name: year
          in: query
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Successful response

  /market/regional:
    get:
      summary: Get Regional Pricing
      parameters:
        - name: make
          in: query
          required: true
          schema: { type: string }
        - name: model
          in: query
          required: true
          schema: { type: string }
        - name: year
          in: query
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Successful response