Simple HTTP Client for Home Assistant

⚠️ IMPORTANT: Integration Renamed

This integration was previously called "Simple cURL" (domain: simple_curl). It has been renamed to "Simple HTTP Client" (domain: simple_http_client).

If you're upgrading from version v1.0.0:

For HACS users:

1. Remove from configuration.yaml: simple_curl: (if present)
2. Restart Home Assistant to disable the old integration
3. In HACS → Integrations, find "Simple cURL" and remove it
4. Remove old repository: https://github.com/storm1er/ha-simple-curl
5. Add repository: https://github.com/storm1er/ha-simple-http-client
6. Download "Simple HTTP Client"
7. Restart Home Assistant
8. Go to Settings → Devices & Services → Add Integration → search for "Simple HTTP Client"
9. Update all service calls: simple_curl.fetch → simple_http_client.fetch

For manual installation users:

1. Delete custom_components/simple_curl/ folder
2. Download and extract to custom_components/simple_http_client/
3. Remove from configuration.yaml: simple_curl: (if present)
4. Restart Home Assistant
5. Go to Settings → Devices & Services → Add Integration → search for "Simple HTTP Client"
6. Update all service calls: simple_curl.fetch → simple_http_client.fetch

A lightweight Home Assistant integration that provides a simple service to fetch URLs with custom HTTP methods and headers. The response is returned as a variable that can be used directly in your automations and scripts.

Why Use This?

Unlike the built-in rest integration which requires YAML configuration and creates sensors, Simple HTTP Client provides a callable service that:

• Works directly in automations and scripts without any configuration
• Returns data as variables using Home Assistant's response_variable feature
• Supports all HTTP methods (GET, POST, PUT, PATCH, DELETE, etc.)
• Handles custom headers and request bodies
• Provides complete response data (status, content, headers)

Perfect for one-off API calls, webhooks, or dynamic URL fetching where you don't need persistent sensors.

Installation

HACS (Recommended)

1. Open HACS in Home Assistant
2. Click the three dots (⋮) in the top right → Custom repositories
3. Add this repository URL: https://github.com/storm1er/ha-simple-http-client
4. Select category: Integration
5. Click Add
6. Find "Simple HTTP Client" in HACS and click Download
7. Restart Home Assistant
8. Go to Settings → Devices & Services
9. Click Add Integration (bottom right)
10. Search for "Simple HTTP Client" and add it

Manual Installation

1. Download the latest release from the releases page
2. Extract and copy the custom_components/simple_http_client folder to your Home Assistant custom_components directory
3. Restart Home Assistant
4. Go to Settings → Devices & Services
5. Click Add Integration (bottom right)
6. Search for "Simple HTTP Client" and add it

Note: No configuration.yaml entry is required. The integration is added through the UI.

Verify Installation

After adding the integration through the UI:

1. Go to Settings → Devices & Services
2. Verify "Simple HTTP Client" appears in your integrations list
3. Go to Developer Tools → Services
4. Search for simple_http_client.fetch
5. If the service appears, installation was successful!

Alternatively, check the logs at Settings → System → Logs for:

Simple HTTP Client integration loaded successfully

Service: simple_http_client.fetch

Parameters

Parameter	Required	Default	Description
url	Yes	-	The URL to fetch
method	No	GET	HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
headers	No	{}	HTTP headers as key-value pairs
body	No	-	Request body content (for POST, PUT, PATCH)
timeout	No	10	Request timeout in seconds

Response Data

The service returns a dictionary with the following fields:

• status: HTTP status code (integer)
• content: Response body as text (string)
• headers: Response headers (dictionary)
• error: Error message if request failed (string, only present on error)

Use the response_variable parameter to capture the response data in your automations.

Usage Examples

Basic GET Request

automation:
  - alias: "Fetch API Data"
    trigger:
      - platform: time
        at: "09:00:00"
    action:
      - service: simple_http_client.fetch
        data:
          url: "https://api.example.com/data"
        response_variable: api_response

      - service: notify.notify
        data:
          message: "API returned: {{ api_response.content }}"

POST Request with Authentication

script:
  post_to_api:
    sequence:
      - service: simple_http_client.fetch
        data:
          url: "https://api.example.com/endpoint"
          method: "POST"
          headers:
            Authorization: "Bearer {{ states('input_text.api_token') }}"
            Content-Type: "application/json"
          body: '{"temperature": {{ states("sensor.temperature") }}}'
        response_variable: result

      - service: persistent_notification.create
        data:
          title: "API Response"
          message: "Status: {{ result.status }}, Response: {{ result.content }}"

Parsing JSON Response

automation:
  - alias: "Fetch Weather Data"
    trigger:
      - platform: time_pattern
        hours: "/1"
    action:
      - service: simple_http_client.fetch
        data:
          url: "https://api.weather.example.com/current"
          headers:
            Accept: "application/json"
        response_variable: weather

      - variables:
          weather_data: "{{ weather.content | from_json }}"

      - service: input_text.set_value
        target:
          entity_id: input_text.current_temp
        data:
          value: "{{ weather_data.temperature }}"

Conditional Actions Based on Response

automation:
  - alias: "Check API Status"
    trigger:
      - platform: state
        entity_id: input_boolean.check_api
        to: "on"
    action:
      - service: simple_http_client.fetch
        data:
          url: "https://api.example.com/status"
          timeout: 5
        response_variable: api_status

      - if:
          - condition: template
            value_template: "{{ api_status.status == 200 }}"
        then:
          - service: light.turn_on
            target:
              entity_id: light.status_indicator
            data:
              rgb_color: [0, 255, 0]
        else:
          - service: light.turn_on
            target:
              entity_id: light.status_indicator
            data:
              rgb_color: [255, 0, 0]

Error Handling

automation:
  - alias: "Fetch with Error Handling"
    trigger:
      - platform: time_pattern
        minutes: "/15"
    action:
      - service: simple_http_client.fetch
        data:
          url: "https://api.example.com/data"
          timeout: 10
        response_variable: response

      - if:
          - condition: template
            value_template: "{{ 'error' in response }}"
        then:
          - service: persistent_notification.create
            data:
              title: "API Error"
              message: "Failed to fetch data: {{ response.error }}"
        else:
          - service: logbook.log
            data:
              name: "API Success"
              message: "Fetched successfully with status {{ response.status }}"

Dynamic URL with Template

script:
  fetch_device_status:
    sequence:
      - service: simple_http_client.fetch
        data:
          url: "http://{{ states('input_text.device_ip') }}/api/status"
          headers:
            X-API-Key: "{{ states('input_text.device_api_key') }}"
        response_variable: device_data

      - service: notify.notify
        data:
          message: "Device status: {{ device_data.content }}"

Important Notes

• Response Content Format: The response content is always returned as text. For JSON APIs, use the from_json filter to parse it.
• Error Handling: Network errors, timeouts, and connection failures are caught and returned in the error field instead of raising exceptions.
• Status Code 0: Indicates a network or connection error (not a valid HTTP response).
• Timeout: Default is 10 seconds. Adjust based on your API's expected response time.
• Security: Be careful not to log sensitive data like API keys or tokens. Use secrets for sensitive information.

Troubleshooting

Service not found

If the simple_http_client.fetch service doesn't appear:

1. Verify integration is added: Go to Settings → Devices & Services and check if "Simple HTTP Client" is listed
2. Add the integration: If not listed, click Add Integration and search for "Simple HTTP Client"
3. Verify installation: Confirm the integration files are in custom_components/simple_http_client/
4. Check logs: Go to Settings → System → Logs and search for "simple_http_client" errors
5. Restart Home Assistant: Sometimes a restart is needed after adding the integration

Common issues:

• Integration not added through UI - Make sure to add it via Settings → Devices & Services → Add Integration
• Files not in correct location - Must be in custom_components/simple_http_client/
• Cache issues - Try clearing your browser cache and restarting Home Assistant

Request fails with error

• Check the URL is accessible from your Home Assistant instance
• Verify headers and authentication are correct
• Increase the timeout if the API is slow to respond
• Check Home Assistant logs for detailed error messages

Response is empty

• Some APIs return empty bodies for certain status codes (204, 304, etc.)
• Check response.status to understand what the server returned
• Verify the API endpoint is correct

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on submitting pull requests, reporting issues, or publishing this integration to HACS.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you find this integration useful, consider:

• Starring the repository on GitHub
• Reporting issues or suggesting features via GitHub Issues
• Contributing improvements via pull requests

Credits

Built for Home Assistant 2026.* and later, using the modern response_variable service pattern.