* :cpp:func:`esp_http_client_init`: Creates an :cpp:type:`esp_http_client_handle_t` instance, i.e., an HTTP client handle based on the given :cpp:type:`esp_http_client_config_t` configuration. This function must be the first to be called; default values are assumed for the configuration values that are not explicitly defined by the user.
* :cpp:func:`esp_http_client_perform`: Performs all operations of the ``esp_http_client`` - opening the connection, exchanging data, and closing the connection (as required), while blocking the current task before its completion. All related events are invoked through the event handler (as specified in :cpp:type:`esp_http_client_config_t`).
* :cpp:func:`esp_http_client_cleanup`: Closes the connection (if any) and frees up all the memory allocated to the HTTP client instance. This must be the last function to be called after the completion of operations.

esp_http_client_config_t cfg = {
    /* other configurations options */
    .use_secure_element = true,
};

Use ECDSA Peripheral for TLS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The ECDSA peripheral can be used for the underlying TLS connection in the HTTP client connection. Please refer to the **ECDSA Peripheral with ESP-TLS** section in the :doc:`ESP-TLS documentation </api-reference/protocols/esp_tls>` for more details. The HTTP client can be configured to use ECDSA peripheral as follows:

.. code-block:: c

    esp_http_client_config_t cfg = {
        /* other configurations options */
        .use_ecdsa_peripheral = true,
        .ecdsa_key_efuse_blk = 4,    // Low eFuse block for ECDSA key
        .ecdsa_key_efuse_blk_high = 5,   // High eFuse block for ECDSA key (SECP384R1 only)
        .ecdsa_curve = ESP_TLS_ECDSA_CURVE_SECP384R1, // set this to ESP_TLS_ECDSA_CURVE_SECP256R1 for SECP256R1 curve
    };

While making HTTPS requests, if server verification is needed, an additional root certificate (in PEM format) needs to be provided to the ``cert_pem`` member in the ``esp_http_client_config_t`` configuration. Users can also use the ``ESP x509 Certificate Bundle`` for server verification using the ``crt_bundle_attach`` member of the ``esp_http_client_config_t`` configuration.

* :cpp:func:`esp_http_client_init`: Create a HTTP client handle.
* ``esp_http_client_set_*`` or ``esp_http_client_delete_*``: Modify the HTTP connection parameters (optional).
* :cpp:func:`esp_http_client_open`: Open the HTTP connection with ``write_len`` parameter (content length that needs to be written to server), set ``write_len=0`` for read-only connection.
* :cpp:func:`esp_http_client_write`: Write data to server with a maximum length equal to ``write_len`` of :cpp:func:`esp_http_client_open` function; no need to call this function for ``write_len=0``.
* :cpp:func:`esp_http_client_fetch_headers`: Read the HTTP Server response headers, after sending the request headers and server data (if any). Returns the ``content-length`` from the server and can be succeeded by :cpp:func:`esp_http_client_get_status_code` for getting the HTTP status of the connection.
* :cpp:func:`esp_http_client_read`: Read the HTTP stream.
* :cpp:func:`esp_http_client_close`: Close the connection.
* :cpp:func:`esp_http_client_cleanup`: Release allocated resources.

* Authentication with URI

    .. highlight:: c

    ::

        esp_http_client_config_t config = {
            .url = "http://user:[email protected]/basic-auth/user/passwd",
            .auth_type = HTTP_AUTH_TYPE_BASIC,
        };


* Authentication with username and password entry

    .. highlight:: c

    ::

        esp_http_client_config_t config = {
            .url = "http://httpbin.org/basic-auth/user/passwd",
            .username = "user",
            .password = "passwd",
            .auth_type = HTTP_AUTH_TYPE_BASIC,
        };

* :ref:`CONFIG_ESP_HTTP_CLIENT_SAVE_RESPONSE_HEADERS`: Enable saving of response headers (disabled by default to conserve memory).
* :ref:`CONFIG_ESP_HTTP_CLIENT_MAX_SAVED_RESPONSE_HEADERS`: Maximum number of response headers to save (default: 10).
* :ref:`CONFIG_ESP_HTTP_CLIENT_MAX_RESPONSE_HEADER_SIZE`: Maximum size in bytes for both header key and value (default: 128 bytes each).

#if CONFIG_ESP_HTTP_CLIENT_SAVE_RESPONSE_HEADERS
esp_http_client_handle_t client = esp_http_client_init(&config);
esp_err_t err = esp_http_client_perform(client);

if (err == ESP_OK) {
    char *content_type = NULL;
    err = esp_http_client_get_response_header(client, "Content-Type", &content_type);
    if (err == ESP_OK && content_type != NULL) {
        ESP_LOGI(TAG, "Content-Type: %s", content_type);
    } else if (err == ESP_ERR_NOT_FOUND) {
        ESP_LOGW(TAG, "Content-Type header not found");
    }

    char *date = NULL;
    err = esp_http_client_get_response_header(client, "Date", &date);
    if (err == ESP_OK && date != NULL) {
        ESP_LOGI(TAG, "Date: %s", date);
    }
}

esp_http_client_cleanup(client);
#endif

* **Header Count Limit**: Only the first ``CONFIG_ESP_HTTP_CLIENT_MAX_SAVED_RESPONSE_HEADERS`` headers are saved. Additional headers beyond this limit are discarded with a warning log.
* **Size Constraints**: Headers where either the key or value exceeds ``CONFIG_ESP_HTTP_CLIENT_MAX_RESPONSE_HEADER_SIZE`` bytes are discarded with a warning log showing the actual sizes.
* **Multi-Value Headers**: For headers that appear multiple times in the response (e.g., ``Set-Cookie``), only the last value is retained.
* **Case Sensitivity**: Header lookups are case-insensitive, but the original case is preserved in storage.
* **Memory Overhead**: Enabling this feature increases memory consumption. Calculate approximate memory usage as: ``(CONFIG_ESP_HTTP_CLIENT_MAX_SAVED_RESPONSE_HEADERS * CONFIG_ESP_HTTP_CLIENT_MAX_RESPONSE_HEADER_SIZE * 2)`` bytes per client instance.
* **Header Lifecycle**: Response headers are cleared when starting a new request with the same client handle via :cpp:func:`esp_http_client_perform` or :cpp:func:`esp_http_client_prepare`.

The returned header value pointer is managed internally by the HTTP client and must not be freed by the application. The pointer remains valid until the client handle is cleaned up or a new request is initiated.

- HTTP_EVENT_ERROR              : ``esp_http_client_handle_t``
- HTTP_EVENT_ON_CONNECTED       : ``esp_http_client_handle_t``
- HTTP_EVENT_HEADERS_SENT       : ``esp_http_client_handle_t``
- HTTP_EVENT_ON_HEADER          : ``esp_http_client_handle_t``
- HTTP_EVENT_ON_HEADERS_COMPLETE: ``esp_http_client_handle_t``
- HTTP_EVENT_ON_STATUS_CODE     : ``esp_http_client_handle_t``
- HTTP_EVENT_ON_DATA            : ``esp_http_client_on_data_t``
- HTTP_EVENT_ON_FINISH          : ``esp_http_client_handle_t``
- HTTP_EVENT_DISCONNECTED       : ``esp_http_client_handle_t``
- HTTP_EVENT_REDIRECT           : ``esp_http_client_redirect_event_data_t``

.. code-block:: c

    #include "esp_http_client.h"
    esp_http_client_config_t config = {
        .tls_version = ESP_HTTP_CLIENT_TLS_VER_TLS_1_2,
    };