openapi: 3.1.0
info:
  title: Vehicle API (Edmunds) Inventory Models API
  description: The Edmunds Vehicle API provides comprehensive automotive data including vehicle makes, models, trims, configurations, specifications, media assets, True Market Value (TMV) pricing, dealer inventories, incentives, and consumer reviews. All responses are in JSON format. Authentication is via API key.
  version: '2.0'
  contact:
    name: Edmunds Developer Support
    url: https://developer.edmunds.com/support/
  license:
    name: Edmunds API Terms of Service
    url: https://developer.edmunds.com/terms/
  x-generated-from: documentation
servers:
- url: https://api.edmunds.com/api
  description: Edmunds API
security:
- ApiKey: []
tags:
- name: Models
  description: Vehicle model information
paths:
  /vehicle/v2/makes/{makeNiceName}/models:
    get:
      operationId: listModels
      summary: Vehicle API List Models
      description: Returns all models for a given vehicle make. Supports filtering by publication state and year. Returns model ID, name, nice name, and the parent make.
      tags:
      - Models
      parameters:
      - name: makeNiceName
        in: path
        required: true
        description: URL-friendly make name (e.g. toyota, ford, chevrolet)
        schema:
          type: string
        example: toyota
      - name: state
        in: query
        description: 'Publication state: new, used, or future'
        schema:
          type: string
          enum:
          - new
          - used
          - future
      - name: year
        in: query
        description: Filter by model year
        schema:
          type: integer
      - name: api_key
        in: query
        required: true
        description: Edmunds API key
        schema:
          type: string
      responses:
        '200':
          description: List of vehicle models for the make
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelListResponse'
              examples:
                ListModels200Example:
                  summary: Default listModels 200 response
                  x-microcks-default: true
                  value:
                    models:
                    - id: Toyota_Camry
                      name: Camry
                      niceName: camry
                      make:
                        id: 200001444
                        name: Toyota
                        niceName: toyota
                    modelsCount: 1
        '404':
          description: Make not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ModelYear:
      type: object
      description: A specific model year with available styles
      properties:
        id:
          type: integer
          description: Model year ID
          example: 100538647
        year:
          type: integer
          description: Model year (4-digit)
          example: 2025
        states:
          type: array
          description: 'Availability states: new, used, future'
          items:
            type: string
        styles:
          type: array
          description: Available trim styles for this year
          items:
            $ref: '#/components/schemas/StyleSummary'
    MakeSummary:
      type: object
      description: Summary representation of a vehicle make
      properties:
        id:
          type: integer
          example: 200001444
        name:
          type: string
          example: Toyota
        niceName:
          type: string
          example: toyota
    StyleSummary:
      type: object
      description: Summary of a vehicle style (trim)
      properties:
        id:
          type: integer
          description: Style ID
          example: 401890697
        name:
          type: string
          description: Full style name (trim + body style)
          example: LE 4dr Sedan
        submodel:
          type: object
          properties:
            body:
              type: string
              example: Sedan
            fuel:
              type: string
              example: Gas
            tuner:
              type: string
              example: Standard
    ModelListResponse:
      type: object
      properties:
        models:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        modelsCount:
          type: integer
    Model:
      type: object
      description: Detailed vehicle model information
      properties:
        id:
          type: string
          description: Model identifier
          example: Toyota_Camry
        name:
          type: string
          description: Model display name
          example: Camry
        niceName:
          type: string
          description: URL-friendly model name
          example: camry
        make:
          $ref: '#/components/schemas/MakeSummary'
        years:
          type: array
          items:
            $ref: '#/components/schemas/ModelYear'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: query
      name: api_key
      description: Edmunds API key obtained from developer.edmunds.com