HomeAssistant OpenAPI Specifications

HomeAssistantOpenAPISpecs.json

{
    "openapi": "3.1.0",
    "info": {
        "title": "Home Assistant",
        "description": "Integrates Home Assistant",
        "version": "v1.0.0",
        "contact": {
            "name": "Lars (ScorchChamp) Cornelissen",
            "url": "https://gist.github.com/ScorchChamp/f10d30459eef5b70253a70a14f2dff1c",
            "email": "opensource@datastudy.nl"
        }
    },
    "servers": [
        {
            "url": "YOUR BASE URL HERE"
        }
    ],
    "paths": {
        "/api/": {
            "get": {
                "description": "Returns a message if the API is up and running.",
                "operationId": "APIStatus",
                "responses": {
                    "200": {
                        "description": "API is available"
                    }
                },
                "deprecated": false,
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/config": {
            "get": {
                "description": "Returns the current configuration as JSON.",
                "operationId": "APIConfig",
                "deprecated": false,
                "responses": {
                    "200": {
                        "description": "Config data"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/events": {
            "get": {
                "description": "Returns an array of event objects. Each event object contains event name and listener count.",
                "operationId": "Events",
                "deprecated": false,
                "responses": {
                    "200": {
                        "description": "Events Objects"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/services": {
            "get": {
                "description": "Returns an array of service objects. Each object contains the domain and which services it contains.",
                "operationId": "Services",
                "deprecated": false,
                "responses": {
                    "200": {
                        "description": "Events Objects"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/history/period/{timestamp}": {
            "get": {
                "description": "Returns an array of state changes in the past. Each object contains further details for the entities.",
                "operationId": "HistoryPeriod",
                "parameters": [
                    {
                        "name": "timestamp",
                        "in": "path",
                        "required": true,
                        "description": "The beginning of the period in YYYY-MM-DDThh:mm:ssTZD format.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "filter_entity_id",
                        "in": "query",
                        "required": true,
                        "description": "One or more entity IDs to filter on, comma separated.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_time",
                        "in": "query",
                        "required": false,
                        "description": "The end of the period in URL encoded format. Defaults to 1 day.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "minimal_response",
                        "in": "query",
                        "required": false,
                        "description": "Only return last_changed and state for states other than the first and last state.",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "no_attributes",
                        "in": "query",
                        "required": false,
                        "description": "Skip returning attributes from the database.",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "significant_changes_only",
                        "in": "query",
                        "required": false,
                        "description": "Only return significant state changes.",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "deprecated": false,
                "responses": {
                    "200": {
                        "description": "Array of state changes in the past."
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/logbook/{timestamp}": {
            "get": {
                "description": "Returns an array of logbook entries.",
                "operationId": "LogbookEntries",
                "parameters": [
                    {
                        "name": "timestamp",
                        "in": "path",
                        "required": true,
                        "description": "The beginning of the period in YYYY-MM-DDThh:mm:ssTZD format. Defaults to 1 day before the time of the request.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "entity",
                        "in": "query",
                        "required": false,
                        "description": "Filter on one entity.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "end_time",
                        "in": "query",
                        "required": false,
                        "description": "Choose the end of the period starting from the timestamp in URL encoded format.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "deprecated": false,
                "responses": {
                    "200": {
                        "description": "Array of logbook entries."
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/states": {
            "get": {
                "description": "Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes.",
                "operationId": "AllEntityStates",
                "deprecated": false,
                "responses": {
                    "200": {
                        "description": "All entity state Objects"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/states/{entityId}": {
            "get": {
                "description": "Check entity state",
                "operationId": "CheckEntity",
                "parameters": [
                    {
                        "name": "entityId",
                        "in": "path",
                        "required": true,
                        "description": "ID of the entity to check",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "deprecated": false,
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/error_log": {
            "get": {
                "description": "Retrieve all errors logged during the current session of Home Assistant as a plaintext response.",
                "operationId": "GetErrorLog",
                "deprecated": false,
                "responses": {
                    "200": {
                        "description": "Plaintext response containing all logged errors."
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/camera_proxy/{cameraEntityId}": {
            "get": {
                "description": "Returns the data (image) from the specified camera entity_id.",
                "operationId": "GetCameraData",
                "parameters": [
                    {
                        "name": "cameraEntityId",
                        "in": "path",
                        "required": true,
                        "description": "ID of the camera entity",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "deprecated": false,
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/api/calendars": {
            "get": {
                "description": "Returns the list of calendar entities",
                "operationId": "GetCalendars",
                "deprecated": false,
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of calendar entities"
                    }
                }
            }
        },
        "/api/calendars/{calendarEntityId}": {
            "get": {
                "description": "Returns the list of calendar events for the specified calendar entity_id between the start and end times (exclusive).",
                "operationId": "GetCalendarEvents",
                "parameters": [
                    {
                        "name": "calendarEntityId",
                        "in": "path",
                        "required": true,
                        "description": "ID of the calendar entity",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "start",
                        "in": "query",
                        "required": true,
                        "description": "Start time of the events",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "name": "end",
                        "in": "query",
                        "required": true,
                        "description": "End time of the events",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    }
                ],
                "deprecated": false,
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of calendar events"
                    }
                }
            }
        },
        "/api/states/{entity_id}": {
            "post": {
                "description": "Updates or creates a state",
                "operationId": "UpdateOrCreateState",
                "parameters": [
                    {
                        "name": "entity_id",
                        "in": "path",
                        "required": true,
                        "description": "ID of the entity",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "state": {
                                        "type": "string"
                                    },
                                    "attributes": {
                                        "type": "object",
                                        "properties": {
                                            "next_rising": {
                                                "type": "string",
                                                "format": "date-time"
                                            },
                                            "next_setting": {
                                                "type": "string",
                                                "format": "date-time"
                                            }
                                        }
                                    }
                                },
                                "required": [
                                    "state"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Entity existed"
                    },
                    "201": {
                        "description": "State of a new entity was set",
                        "headers": {
                            "Location": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/events/{event_type}": {
            "post": {
                "description": "Fires an event with event_type",
                "operationId": "FireEvent",
                "parameters": [
                    {
                        "name": "event_type",
                        "in": "path",
                        "required": true,
                        "description": "Type of the event",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "next_rising": {
                                        "type": "string",
                                        "format": "date-time"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Event fired",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/services/{domain}/{service}": {
            "post": {
                "description": "Calls a service within a specific domain. Will return when the service has been executed.",
                "operationId": "CallService",
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "description": "Domain of the service",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "service",
                        "in": "path",
                        "required": true,
                        "description": "Name of the service",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "entity_id": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "List of states that have changed while the service was being executed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "attributes": {
                                                "type": "object"
                                            },
                                            "entity_id": {
                                                "type": "string"
                                            },
                                            "last_changed": {
                                                "type": "string",
                                                "format": "date-time"
                                            },
                                            "state": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/template": {
            "post": {
                "description": "Render a Home Assistant template. See template docs for more information.",
                "operationId": "RenderTemplate",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "template": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "template"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Returns the rendered template in plain text.",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/config/core/check_config": {
            "post": {
                "description": "Trigger a check of configuration.yaml. No additional data needs to be passed in with this request. Needs config integration enabled.",
                "operationId": "CheckConfig",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "If the check is successful, the following will be returned:",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "errors": {
                                            "type": "null"
                                        },
                                        "result": {
                                            "type": "string",
                                            "enum": [
                                                "valid",
                                                "invalid"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/intent/handle": {
            "post": {
                "description": "Handle an intent.",
                "operationId": "HandleIntent",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "intent": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "intent"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Returns the response for the handled intent.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "response": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {},
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT"
            }
        }
    }
}