swagger.yaml

swagger: '2.0'
info:
  title: Home Assistant
  description: Home Assistant REST API
  version: "1.0.1"
# the domain of the service
host: localhost:8123

# array of all schemes that your API supports
schemes:
  - http
  - https

securityDefinitions:
  #api_key:
  #  type: apiKey
  #  description: API password
  #  name: api_password
  #  in: query
  
   api_key:
    type: apiKey
    description: API password
    name: x-ha-access
    in: header

# will be prefixed to all paths
basePath: /api

consumes:
  - application/json
produces:
  - application/json
paths:
  /:
    get:
      summary: API alive message
      description: Returns message if API is up and running.
      tags:
        - Core
      security:
        - api_key: []
      responses:
        200:
          description: API is up and running
          schema:
            $ref: '#/definitions/Message'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /config:
    get:
      summary: API alive message
      description: Returns the current configuration as JSON.
      tags:
        - Core
      security:
        - api_key: []
      responses:
        200:
          description: Current configuration
          schema:
            $ref: '#/definitions/ApiConfig'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /discovery_info:
    get:
      summary: Basic information about Home Assistant instance
      tags:
        - Core
      responses:
        200:
          description: Basic information
          schema:
            $ref: '#/definitions/DiscoveryInfo'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /bootstrap:
    get:
      summary: Returns all data needed to bootstrap Home Assistant.
      tags:
        - Core
      security:
        - api_key: []
      responses:
        200:
          description: Bootstrap information
          schema:
            $ref: '#/definitions/BootstrapInfo'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /events:
    get:
      summary: Array of event objects.
      description: Returns an array of event objects. Each event object contain event name and listener count.
      tags:
        - Events
      security:
        - api_key: []
      responses:
        200:
          description: Events
          schema:
            type: array
            items:
              $ref: '#/definitions/Event'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /services:
    get:
      summary: Array of service objects.
      description: Returns an array of service objects. Each object contains the domain and which services it contains.
      tags:
        - Services
      security:
        - api_key: []
      responses:
        200:
          description: Services
          schema:
            type: array
            items:
              $ref: '#/definitions/Service'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /history:
    get:
      summary: Array of state changes in the past.
      description: Returns an array of state changes in the past. Each object contains further detail for the entities.
      tags:
        - State
      security:
        - api_key: []
      responses:
        200:
          description: State changes
          schema:
            type: array
            items:
              $ref: '#/definitions/History'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /states:
    get:
      summary: Array of state objects.
      description: |
        Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes.
      tags:
        - State
      security:
        - api_key: []
      responses:
        200:
          description: States
          schema:
            type: array
            items:
              $ref: '#/definitions/State'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /states/{entity_id}:
    get:
      summary: Specific state object.
      description: |
        Returns a state object for specified entity_id.
      tags:
        - State
      security:
        - api_key: []
      parameters:
      - name: entity_id
        in: path
        description: entity_id of the entity to query
        required: true
        type: string
      responses:
        200:
          description: State
          schema:
            $ref: '#/definitions/State'
        404:
          description: Not found
          schema:
            $ref: '#/definitions/Message'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
    post:
      description: |
        Updates or creates the current state of an entity.
      tags:
        - State
      consumes:
        - application/json
      parameters:
      - name: entity_id
        in: path
        description: entity_id to set the state of
        required: true
        type: string
      - $ref: '#/parameters/State'
      responses:
        200:
          description: State of existing entity was set
          schema:
            $ref: '#/definitions/State'
        201:
          description: State of new entity was set
          schema:
            $ref: '#/definitions/State'
          headers:
            location:
              type: string
              description: location of the new entity
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /error_log:
    get:
      summary: Error log
      description: |
        Retrieve all errors logged during the current session of Home Assistant as a plaintext response.
      tags:
        - Core
      security:
        - api_key: []
      produces:
        - text/plain
      responses:
        200:
          description: Plain text error log
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /camera_proxy/camera.{entity_id}:
    get:
      summary: Camera image.
      description: |
        Returns the data (image) from the specified camera entity_id.
      tags:
        - Camera
      security:
        - api_key: []
      produces:
        - image/jpeg
      parameters:
      - name: entity_id
        in: path
        description: entity_id of the camera to query
        required: true
        type: string
      responses:
        200:
          description: Camera image
          schema:
            type: file
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /events/{event_type}:
    post:
      description: |
        Fires an event with event_type
      tags:
        - Events
      security:
        - api_key: []
      consumes:
        - application/json
      parameters:
      - name: event_type
        in: path
        description: event_type to fire event with
        required: true
        type: string
      - $ref: '#/parameters/EventData'
      responses:
        200:
          description: Response message
          schema:
            $ref: '#/definitions/Message'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /services/{domain}/{service}:
    post:
      description: |
        Calls a service within a specific domain. Will return when the service has been executed or 10 seconds has past, whichever comes first.
      tags:
        - Services
      security:
        - api_key: []
      consumes:
        - application/json
      parameters:
      - name: domain
        in: path
        description: domain of the service
        required: true
        type: string
      - name: service
        in: path
        description: service to call
        required: true
        type: string
      - $ref: '#/parameters/ServiceData'
      responses:
        200:
          description: List of states that have changed while the service was being executed. The result will include any changed states that changed while the service was being executed, even if their change was the result of something else happening in the system.
          schema:
            type: array
            items:
              $ref: '#/definitions/State'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /template:
    post:
      description: |
        Render a Home Assistant template.
      tags:
        - Template
      security:
        - api_key: []
      consumes:
        - application/json
      produces:
        - text/plain
      parameters:
      - $ref: '#/parameters/Template'
      responses:
        200:
          description: Returns the rendered template in plain text.
          schema:
            type: string
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /event_forwarding:
    post:
      description: |
        Setup event forwarding to another Home Assistant instance.
      tags:
        - Core
      security:
        - api_key: []
      consumes:
        - application/json
      parameters:
      - $ref: '#/parameters/EventForwarding'
      responses:
        200:
          description: It will return a message if event forwarding was setup successful.
          schema:
            $ref: '#/definitions/Message'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
    delete:
      description: |
        Cancel event forwarding to another Home Assistant instance.
      tags:
        - Core
      consumes:
        - application/json
      parameters:
      - $ref: '#/parameters/EventForwarding'
      responses:
        200:
          description: It will return a message if event forwarding was cancelled successful.
          schema:
            $ref: '#/definitions/Message'
        default:
          description: Error
          schema:
            $ref: '#/definitions/Message'
  /stream:
    get:
      summary: Server-sent events
      description: The server-sent events feature is a one-way channel from your Home Assistant server to a client which is acting as a consumer.
      tags:
        - Core
        - Events
      security:
        - api_key: []
      produces:
        - text/event-stream
      parameters:
        - name: restrict
          in: query
          description: comma-separated list of event_types to filter
          required: false
          type: string
      responses:
        default:
          description: Stream of events
          schema:
            type: object
            x-events:
              state_changed:
                type: object
                properties:
                  entity_id:
                    type: string
                  old_state:
                    $ref: '#/definitions/State'
                  new_state:
                    $ref: '#/definitions/State'
definitions:
  ApiConfig:
    type: object
    properties:
      components:
        type: array
        description: List of component types
        items:
          type: string
          description: Component type
      latitude:
        type: number
        format: float
        description: Latitude of Home Assistant server
      longitude:
        type: number
        format: float
        description: Longitude of Home Assistant server
      location_name:
        type: string
      unit_system:
        type: object
        properties:
          length:
            type: string
          mass:
            type: string
          temperature: 
            type: string
          volume:
            type: string
      time_zone:
        type: string
      version:
        type: string
  DiscoveryInfo:
    type: object
    properties:
      base_url:
        type: string
      location_name:
        type: string
      requires_api_password:
        type: boolean
      version:
        type: string
  BootstrapInfo:
    type: object
    properties:
      config:
        $ref: '#/definitions/ApiConfig'
      events:
        type: array
        items:
          $ref: '#/definitions/Event'
      services:
        type: array
        items:
          $ref: '#/definitions/Service'
      states:
        type: array
        items:
          $ref: '#/definitions/State'
  Event:
    type: object
    properties:
      event:
        type: string
      listener_count:
        type: integer
  Service:
    type: object
    properties:
      domain:
        type: string
      services:
        type: object
        additionalProperties:
          $ref: '#/definitions/DomainService'
  DomainService:
    type: object
    properties:
      description:
        type: string
      fields:
        type: object
        description: Object with service fields that can be called
  State:
    type: object
    properties:
      attributes:
        $ref: '#/definitions/StateAttributes'
      state:
        type: string
      entity_id:
        type: string
      last_changed:
        type: string
        format: date-time
  StateAttributes:
    type: object
    additionalProperties:
      type: string
  History:
    allOf:
    - $ref: '#/definitions/State'
    - type: object
      properties:
        last_updated:
            type: string
            format: date-time
  Message:
    type: object
    properties:
      message:
        type: string
parameters:
  State:
    name: body
    in: body
    description: State parameter
    required: false
    schema:
      type: object
      required:
      - state
      properties:
        attributes:
          $ref: '#/definitions/StateAttributes'
        state:
          type: string
  EventData:
    name: body
    in: body
    description: event_data
    required: false
    schema:
      type: object
  ServiceData:
    name: body
    in: body
    description: service_data
    required: false
    schema:
      type: object
  Template:
    name: body
    in: body
    description: Template to render
    required: true
    schema:
      type: object
      required:
      - template
      properties:
        template:
          description: Jinja2 template string
          type: string
  EventForwarding:
    name: body
    in: body
    description: Event Forwarding parameter
    required: true
    schema:
      type: object
      required:
      - host
      - api_password
      properties:
        host:
          type: string
        api_password:
          type: string
        port:
          type: integer