openapi: 3.1.0
info:
  title: Visteon Phoenix API
  description: >-
    The Phoenix API is an automotive-oriented JavaScript interface for building HTML5
    applications on Visteon's Phoenix infotainment platform. The API provides access to
    vehicle cockpit domains including audio playback and volume control, phone call
    management, media library browsing, navigation routing, screen and display management,
    remote UI rendering, and vehicle data such as speed, fuel level, and HVAC status.
    Applications written with the Phoenix API run across Visteon SmartCore and display
    audio infotainment hardware platforms.
  version: '2.0'
  contact:
    name: Visteon Developer Network
    url: https://developer.visteon.com/phoenix/
  license:
    name: Visteon Developer License
    url: https://developer.visteon.com/phoenix/
  termsOfService: https://www.visteon.com/legal/
externalDocs:
  description: Visteon Phoenix API Documentation
  url: https://developer.visteon.com/phoenix/api.html
servers:
  - url: https://developer.visteon.com/phoenix/api
    description: Visteon Phoenix Platform API
tags:
  - name: Audio
    description: Audio playback, volume, and source management
  - name: Phone
    description: Phone call management, contacts, and call history
  - name: Media
    description: Media library browsing, playback, and device management
  - name: Navigation
    description: Route planning, turn-by-turn guidance, and POI search
  - name: Screen Management
    description: Display and screen configuration for multi-screen cockpit
  - name: Vehicle
    description: Vehicle data including speed, fuel, HVAC, and door status
  - name: Remote UI
    description: Remote user interface rendering and interaction
security:
  - ApiKeyAuth: []
paths:
  /audio/status:
    get:
      operationId: getAudioStatus
      summary: Get Audio Status
      description: >-
        Returns the current audio status including playback state, active audio source,
        volume level, and mute state.
      tags:
        - Audio
      responses:
        '200':
          description: Current audio status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioStatus'
        '500':
          description: Internal server error
  /audio/volume:
    get:
      operationId: getVolume
      summary: Get Volume
      description: Returns the current master volume level and mute status.
      tags:
        - Audio
      responses:
        '200':
          description: Current volume settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeSettings'
        '500':
          description: Internal server error
    put:
      operationId: setVolume
      summary: Set Volume
      description: Sets the master volume level for the infotainment system.
      tags:
        - Audio
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VolumeUpdate'
      responses:
        '200':
          description: Updated volume settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VolumeSettings'
        '400':
          description: Invalid volume value
        '500':
          description: Internal server error
  /audio/sources:
    get:
      operationId: listAudioSources
      summary: List Audio Sources
      description: >-
        Returns all available audio sources such as FM radio, AM radio, Bluetooth audio,
        USB media, and auxiliary input.
      tags:
        - Audio
      responses:
        '200':
          description: List of audio sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioSourceList'
        '500':
          description: Internal server error
  /audio/sources/{sourceId}/activate:
    post:
      operationId: activateAudioSource
      summary: Activate Audio Source
      description: Switches the active audio source to the specified source.
      tags:
        - Audio
      parameters:
        - name: sourceId
          in: path
          required: true
          description: Identifier of the audio source to activate
          schema:
            type: string
      responses:
        '200':
          description: Audio source activated
        '404':
          description: Audio source not found
        '500':
          description: Internal server error
  /phone/status:
    get:
      operationId: getPhoneStatus
      summary: Get Phone Status
      description: >-
        Returns the current phone connection status including Bluetooth pairing state,
        signal strength, and active call status.
      tags:
        - Phone
      responses:
        '200':
          description: Phone connection status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneStatus'
        '500':
          description: Internal server error
  /phone/calls:
    get:
      operationId: listCalls
      summary: List Active Calls
      description: Returns a list of current active or on-hold phone calls.
      tags:
        - Phone
      responses:
        '200':
          description: List of active calls
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallList'
        '500':
          description: Internal server error
    post:
      operationId: makeCall
      summary: Make Call
      description: Initiates an outgoing phone call to the specified number.
      tags:
        - Phone
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallRequest'
      responses:
        '201':
          description: Call initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
        '400':
          description: Invalid phone number
        '500':
          description: Internal server error
  /phone/calls/{callId}:
    delete:
      operationId: endCall
      summary: End Call
      description: Terminates an active phone call.
      tags:
        - Phone
      parameters:
        - name: callId
          in: path
          required: true
          description: Identifier of the call to terminate
          schema:
            type: string
      responses:
        '204':
          description: Call ended
        '404':
          description: Call not found
        '500':
          description: Internal server error
  /media/library:
    get:
      operationId: browseMediaLibrary
      summary: Browse Media Library
      description: >-
        Browses the media library returning available media items from connected devices.
        Supports pagination and filtering by media type.
      tags:
        - Media
      parameters:
        - name: type
          in: query
          required: false
          description: Filter by media type (music, video, photos)
          schema:
            type: string
            enum: [music, video, photos]
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          required: false
          description: Number of items per page
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Media library items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaLibrary'
        '500':
          description: Internal server error
  /media/nowplaying:
    get:
      operationId: getNowPlaying
      summary: Get Now Playing
      description: Returns information about the currently playing media track.
      tags:
        - Media
      responses:
        '200':
          description: Currently playing track
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaTrack'
        '404':
          description: No media currently playing
        '500':
          description: Internal server error
  /navigation/route:
    get:
      operationId: getActiveRoute
      summary: Get Active Route
      description: Returns the currently active navigation route including waypoints and ETA.
      tags:
        - Navigation
      responses:
        '200':
          description: Active navigation route
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavigationRoute'
        '404':
          description: No active route
        '500':
          description: Internal server error
    post:
      operationId: startNavigation
      summary: Start Navigation
      description: Starts navigation to a specified destination address or coordinates.
      tags:
        - Navigation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NavigationRequest'
      responses:
        '201':
          description: Navigation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavigationRoute'
        '400':
          description: Invalid destination
        '500':
          description: Internal server error
    delete:
      operationId: cancelNavigation
      summary: Cancel Navigation
      description: Cancels the currently active navigation route.
      tags:
        - Navigation
      responses:
        '204':
          description: Navigation cancelled
        '404':
          description: No active route
        '500':
          description: Internal server error
  /navigation/search:
    get:
      operationId: searchPOI
      summary: Search Points of Interest
      description: Searches for points of interest near the current vehicle location or a specified coordinate.
      tags:
        - Navigation
      parameters:
        - name: query
          in: query
          required: true
          description: Search query string (e.g. "gas station", "restaurant")
          schema:
            type: string
        - name: lat
          in: query
          required: false
          description: Latitude for search center
          schema:
            type: number
        - name: lon
          in: query
          required: false
          description: Longitude for search center
          schema:
            type: number
        - name: radius
          in: query
          required: false
          description: Search radius in meters
          schema:
            type: integer
            default: 5000
      responses:
        '200':
          description: Points of interest results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/POIResults'
        '400':
          description: Invalid search parameters
        '500':
          description: Internal server error
  /vehicle/data:
    get:
      operationId: getVehicleData
      summary: Get Vehicle Data
      description: >-
        Returns current vehicle telemetry data including speed, fuel level, odometer,
        engine status, and HVAC settings.
      tags:
        - Vehicle
      responses:
        '200':
          description: Vehicle data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleData'
        '500':
          description: Internal server error
  /screen/displays:
    get:
      operationId: listDisplays
      summary: List Displays
      description: >-
        Returns all display screens available in the vehicle cockpit including
        instrument cluster, center stack, and passenger displays.
      tags:
        - Screen Management
      responses:
        '200':
          description: List of displays
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayList'
        '500':
          description: Internal server error
  /screen/displays/{displayId}:
    get:
      operationId: getDisplay
      summary: Get Display
      description: Returns configuration and state of a specific display screen.
      tags:
        - Screen Management
      parameters:
        - name: displayId
          in: path
          required: true
          description: Identifier of the display
          schema:
            type: string
      responses:
        '200':
          description: Display configuration and state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Display'
        '404':
          description: Display not found
        '500':
          description: Internal server error
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Phoenix-API-Key
  schemas:
    AudioStatus:
      type: object
      description: Current audio system status
      properties:
        isPlaying:
          type: boolean
        activeSource:
          type: string
        volume:
          type: integer
          minimum: 0
          maximum: 100
        isMuted:
          type: boolean
    VolumeSettings:
      type: object
      description: Volume configuration
      properties:
        level:
          type: integer
          minimum: 0
          maximum: 100
        isMuted:
          type: boolean
    VolumeUpdate:
      type: object
      description: Volume update request
      properties:
        level:
          type: integer
          minimum: 0
          maximum: 100
        mute:
          type: boolean
    AudioSourceList:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              type:
                type: string
                enum: [fm, am, bluetooth, usb, aux, streaming]
              isActive:
                type: boolean
    PhoneStatus:
      type: object
      description: Phone connection and call status
      properties:
        isConnected:
          type: boolean
        deviceName:
          type: string
        signalStrength:
          type: integer
          minimum: 0
          maximum: 5
        hasActiveCall:
          type: boolean
        batteryLevel:
          type: integer
          minimum: 0
          maximum: 100
    CallList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Call'
    Call:
      type: object
      description: A phone call
      properties:
        id:
          type: string
        number:
          type: string
        contactName:
          type: string
        status:
          type: string
          enum: [active, on-hold, incoming, outgoing]
        duration:
          type: integer
          description: Call duration in seconds
    CallRequest:
      type: object
      required: [number]
      properties:
        number:
          type: string
          description: Phone number to call
    MediaLibrary:
      type: object
      properties:
        total:
          type: integer
        offset:
          type: integer
        limit:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/MediaTrack'
    MediaTrack:
      type: object
      description: A media track or item
      properties:
        id:
          type: string
        title:
          type: string
        artist:
          type: string
        album:
          type: string
        duration:
          type: integer
          description: Duration in seconds
        type:
          type: string
          enum: [music, video, photo]
        uri:
          type: string
    NavigationRoute:
      type: object
      description: A navigation route
      properties:
        id:
          type: string
        destination:
          $ref: '#/components/schemas/Location'
        eta:
          type: string
          format: date-time
        distanceRemaining:
          type: number
          description: Distance remaining in meters
        timeRemaining:
          type: integer
          description: Time remaining in seconds
        isActive:
          type: boolean
    NavigationRequest:
      type: object
      description: Navigation start request
      required: [destination]
      properties:
        destination:
          $ref: '#/components/schemas/Location'
        avoidTolls:
          type: boolean
        avoidHighways:
          type: boolean
    Location:
      type: object
      description: A geographic location
      properties:
        address:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        name:
          type: string
    POIResults:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              address:
                type: string
              latitude:
                type: number
              longitude:
                type: number
              distance:
                type: number
                description: Distance from search center in meters
              category:
                type: string
    VehicleData:
      type: object
      description: Vehicle telemetry and status data
      properties:
        speed:
          type: number
          description: Current vehicle speed in km/h
        fuelLevel:
          type: integer
          description: Fuel level as percentage 0-100
        odometer:
          type: number
          description: Odometer reading in kilometers
        engineRunning:
          type: boolean
        gearPosition:
          type: string
          enum: [P, R, N, D, 1, 2, 3, 4, 5, 6]
        hvac:
          type: object
          properties:
            temperature:
              type: number
              description: Set temperature in Celsius
            fanSpeed:
              type: integer
              minimum: 0
              maximum: 7
            isAcOn:
              type: boolean
    DisplayList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Display'
    Display:
      type: object
      description: A cockpit display screen
      properties:
        id:
          type: string
        name:
          type: string
          description: Display name (e.g. Center Stack, Instrument Cluster)
        resolution:
          type: object
          properties:
            width:
              type: integer
            height:
              type: integer
        orientation:
          type: string
          enum: [landscape, portrait]
        isOn:
          type: boolean
        brightness:
          type: integer
          minimum: 0
          maximum: 100