HTTP

The HTTP integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] serves the Home Assistant frontend and APIs. You can manage the HTTP server settings from the UI under Settings > System > Network.

The integration supports these entity types:

• Binary sensor
• Sensor

HTTP server settings

To change how Home Assistant serves its web interface, go to Settings > System > Network, then find the HTTP server section.

Options in the UI

Saving HTTP server settings restarts Home Assistant. After Home Assistant restarts, an administrator is asked to confirm the new settings. If the settings are not confirmed within 5 minutes, Home Assistant automatically returns to the previous settings.

Migrating from YAML

Before Home Assistant 2026.8, the HTTP integration was configured in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]. The first time Home Assistant starts after you upgrade, your existing http: block is imported into the UI, and a repair issue is raised under Settings > System > Repairs to remind you to remove it.

To complete the migration:

1. Go to Settings > System > Network.
2. In the HTTP server section, check that your imported values are correct. If Home Assistant asks you to confirm the settings, confirm them.
3. Remove the http: block from configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more].
4. Restart Home Assistant.

The repair issue clears once the http: block is gone. For the repair issues that can appear during or after migration, see Troubleshooting.

Reverse proxies

When using a reverse proxy, turn on Trust X-Forwarded-For and add the proxy to Trusted proxies. Requests from reverse proxies are blocked if these options are not set.

APIs

On top of the http integration is a REST API, Python API and WebSocket API available.

The http platforms are not real platforms within the meaning of the terminology used around Home Assistant. Home Assistant’s REST API sends and receives messages over HTTP.

HTTP sensors

To use an HTTP sensor or binary sensor, you do not need to configure anything in Home Assistant. All configuration is done on the devices themselves. This means that you must be able to edit the target URL or endpoint and the payload. The entity is created after the first message arrives.

If you want to use an HTTP sensor, create a Long-Lived Access Token in the Home Assistant UI in the Security section of your User profile page.

All requests need to be sent to the endpoint of the device and use POST.

IP filtering and banning

If you want to apply additional IP filtering and automatically ban brute force attempts, turn on Enable IP banning and set Login attempts before ban to the maximum number of attempts before a ban is activated. After the first ban, an ip_bans.yaml file is created in the root configuration folder. It contains the banned IP address and the time in UTC when it was added:

127.0.0.1:
  banned_at: "2016-11-16T19:20:03"

After a ban is added, a persistent notification appears in the Home Assistant frontend.

To clear an IP ban, you can either:

• Remove the specific IP entry from ip_bans.yaml.
• Delete the entire ip_bans.yaml file. It will be recreated automatically the next time a ban occurs.

After making changes, restart Home Assistant to apply them.

Hosting files

If you want to use Home Assistant to host or serve static files then create a directory called www under the configuration path (/config). The static files in www/ can be accessed by the following URL http://your.domain:8123/local/, for example audio.mp3 would be accessed as http://your.domain:8123/local/audio.mp3.

Binary sensor

The HTTP binary sensor is dynamically created with the first request that is made to its URL. You don’t have to define it in the configuration first.

The sensor will then exist as long as Home Assistant is running. After a restart of Home Assistant the sensor will be gone until it is triggered again.

The URL for a binary sensor looks like the example below:

http://IP_ADDRESS:8123/api/states/binary_sensor.DEVICE_NAME

The JSON payload must contain the new state and can have a friendly name. The friendly name is used in the frontend to name the sensor.

{"state": "on", "attributes": {"friendly_name": "Radio"}}

For a quick test curl can be useful to “simulate” a device.

$ curl -X POST -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"state": "off", "attributes": {"friendly_name": "Radio"}}' \
    http://localhost:8123/api/states/binary_sensor.radio

To check if the sensor is working, use again curl to retrieve the current state.

$ curl -X GET -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
       -H "Content-Type: application/json" \
       http://localhost:8123/api/states/binary_sensor.radio
{
    "attributes": {
        "friendly_name": "Radio"
    },
    "entity_id": "binary_sensor.radio",
    "last_changed": "16:45:51 05-02-2016",
    "last_updated": "16:45:51 05-02-2016",
    "state": "off"
}

To delete the sensor, send DELETE request with curl

$ curl -X DELETE -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
       http://localhost:8123/api/states/binary_sensor.radio

Examples

In this section you’ll find some real-life examples of how to use this sensor, besides curl, which was shown earlier.

Using Python request module

As already shown on the API page, it’s very simple to use Python and the Requests module for the interaction with Home Assistant.

response = requests.post(
    "http://localhost:8123/api/states/binary_sensor.radio",
    headers={
        "Authorization": "Bearer LONG_LIVED_ACCESS_TOKEN",
        "content-type": "application/json",
    },
    data=json.dumps({"state": "on", "attributes": {"friendly_name": "Radio"}}),
)
print(response.text)

Using httpie

httpie is a user-friendly CLI HTTP client.

$ http -v POST http://localhost:8123/api/states/binary_sensor.radio \
      'Authorization:Bearer LONG_LIVED_ACCESS_TOKEN' content-type:application/json state=off \
      attributes:='{"friendly_name": "Radio"}'

Sensor

The HTTP sensor is dynamically created with the first request that is made to its URL. You don’t have to define it in the configuration first.

The sensor will then exist as long as Home Assistant is running. After a restart of Home Assistant the sensor will be gone until it is triggered again.

The URL for a sensor looks like the example below:

http://IP_ADDRESS:8123/api/states/sensor.DEVICE_NAME

The JSON payload must contain the new state and should include the unit of measurement and a friendly name. The friendly name is used in the frontend to name the sensor.

{"state": "20", "attributes": {"unit_of_measurement": "°C", "friendly_name": "Bathroom Temperature"}}

For a quick test, curl can be useful to “simulate” a device.

$ curl -X POST -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
       -H "Content-Type: application/json" \
       -d '{"state": "20", "attributes": {"unit_of_measurement": "°C", "friendly_name": "Bathroom Temp"}}' \
       http://localhost:8123/api/states/sensor.bathroom_temperature

You can then use curl again to retrieve the current sensor state and verify the sensor is working.

$ curl -X GET -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
       -H "Content-Type: application/json" \
       http://localhost:8123/api/states/sensor.bathroom_temperature
{
    "attributes": {
        "friendly_name": "Bathroom Temp",
        "unit_of_measurement": "\u00b0C"
    },
    "entity_id": "sensor.bathroom_temperature",
    "last_changed": "09:46:17 06-02-2016",
    "last_updated": "09:48:46 06-02-2016",
    "state": "20"
}

For more examples please visit the HTTP binary sensor page.

Troubleshooting

The HTTP server fails to start

If a saved setting prevents the HTTP server from starting, for example if an SSL certificate file is missing or the configured port is already in use, Home Assistant falls back to the last known-good configuration so you can regain access. If no working configuration is available, Home Assistant starts with the default HTTP settings for your installation method, without SSL.

To fix this, check the logs for the underlying error. Then, open the HTTP server section under Settings > System > Network, correct the values, and save.

Repair issues about YAML configuration

After the migration to UI configuration, Home Assistant raises a repair issue if an http: block remains in configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

• The HTTP YAML configuration is deprecated appears right after your configuration is imported.
• HTTP YAML configuration is ignored after migration appears on later starts if the http: block is still there.
• Failed to import HTTP YAML configuration appears if a value could not be imported. Home Assistant starts with the default HTTP settings; check the logs for the cause.

To clear the first two issues, remove the http: block from configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] and restart Home Assistant. For a failed import, correct the values under Settings > System > Network and save.