title: ESP32HTTPClient Class Reference - C++ Methods & Signatures description: Complete API documentation for the ESP32HTTPClient class: constructor, HTTP verb methods, persistent headers, authentication, and timeouts. keywords: ESP32HTTPClient class, ESP32HTTPClient constructor, C++ ESP32 HTTP library reference, ESP32 HTTP client methods tags: - api - client - class

ESP32HTTPClient¶

The main entry point for the library. Create one instance per server base URL and reuse it across all requests.

Header: #include "ESP32HTTPClient.h"

Constructor¶

`ESP32HTTPClient(baseUrl)`¶

Creates a client with automatic port selection (80 for HTTP, 443 for HTTPS).

ESP32HTTPClient(const char* baseUrl);

Parameters:

Parameter	Type	Description
`baseUrl`	`const char*`	The base URL including protocol (e.g., `"https://api.example.com"`). Do not include a trailing slash.

Example:

ESP32HTTPClient client("https://api.example.com");

`ESP32HTTPClient(baseUrl, port)`¶

Creates a client targeting a specific port.

ESP32HTTPClient(const char* baseUrl, int port);

Parameters:

Parameter	Type	Description
`baseUrl`	`const char*`	The base URL including protocol.
`port`	`int`	The target TCP port (e.g., `8080`, `443`).

Example:

ESP32HTTPClient client("http://192.168.1.100", 8080);

HTTP Request Methods¶

Each method returns a RestRequest that can be chained with .query(), .body(), and .getBody(). The HTTP request is dispatched when the RestRequest object goes out of scope or when the first .getBody() is added.

`get(path)`¶

Sends a GET request to baseUrl + path.

RestRequest get(const char* path);

Example:

client.get("/todos/1").getBody("title", title, sizeof(title));

`post(path)`¶

Sends a POST request to baseUrl + path.

RestRequest post(const char* path);

Example:

client.post("/users").body("name", "Pedro").body("age", 21).getBody("id", &newId);

`put(path)`¶

Sends a PUT request to baseUrl + path.

RestRequest put(const char* path);

Example:

client.put("/posts/1").body("title", "new title");

`update(path)`¶

Semantic alias for put(). Sends an identical HTTP PUT request.

RestRequest update(const char* path);

Example:

client.update("/lights/1").body("state", "OFF");

`patch(path)`¶

Sends a PATCH request to baseUrl + path for partial updates.

RestRequest patch(const char* path);

Example:

client.patch("/config").body("timeout", 30);

`del(path)`¶

Sends a DELETE request to baseUrl + path.

RestRequest del(const char* path);

Example:

client.del("/users/15");

`soap(path)`¶

Initiates a SOAP request targeting baseUrl + path, returning a SoapRequest builder.

SoapRequest soap(const char* path = "");

Example:

client.soap("/ws")
      .soapAction("http://example.org/GetPrice")
      .body("<m:GetPrice xmlns:m=\"http://example.org\"><m:Item>Widget</m:Item></m:GetPrice>")
      .getBody("Price", &price);

`graphql(path)` / `graphqlPost(path)`¶

Initiates a GraphQL request targeting baseUrl + path (defaults to POST), returning a GraphQLRequest builder.

GraphQLRequest graphql(const char* path = "/graphql");
GraphQLRequest graphqlPost(const char* path = "/graphql");

Example:

client.graphql("/graphql")
      .query("query { user { id name } }")
      .getData("user.name", &name);

`graphqlGet(path)`¶

Initiates a GraphQL query targeting baseUrl + path via HTTP GET, formatting the query and variables as URL query parameters.

GraphQLRequest graphqlGet(const char* path = "/graphql");

Example:

client.graphqlGet("/graphql")
      .query("{ systemStatus }")
      .getData("systemStatus", &status);

`graphqlBatch(path)`¶

Initiates a batch of multiple GraphQL operations targeting baseUrl + path sent in a single HTTP POST request, returning a GraphQLBatchRequest builder.

GraphQLBatchRequest graphqlBatch(const char* path = "/graphql");

Example:

auto batch = client.graphqlBatch("/graphql");
batch.addQuery("query { user { name } }").getData("user.name", &name);
batch.addQuery("query { config { theme } }").getData("config.theme", &theme);
batch.execute();

Configuration Methods¶

`setHeader(name, value)`¶

Registers a custom HTTP header that is sent with every subsequent request.

void setHeader(const char* name, const char* value);

Parameter	Limit
`name`	Up to 63 characters
`value`	Up to 255 characters

Example:

client.setHeader("Authorization", "Bearer my-token");
client.setHeader("X-Device-ID",   "ESP32-001");

Note

Headers persist for the lifetime of the client instance. Call setHeader() again with the same name to overwrite.

Reading response headers

setHeader() sets headers to be sent in the request. To read headers returned by the server in the response, use RestRequest::getHeader.

`bearer(token)`¶

Sets the Authorization: Bearer <token> header sent with every subsequent request.

void bearer(const char* token);

Parameter	Type	Description
`token`	`const char*`	The Bearer / JWT token string.

Example:

client.bearer("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...");

`basic(user, password)`¶

Encodes credentials into Base64 and sets the Authorization: Basic <base64> header sent with every subsequent request.

void basic(const char* user, const char* password);

Parameter	Type	Description
`user`	`const char*`	Username.
`password`	`const char*`	Password.

Example:

client.basic("admin", "secret123");

`apiKey(name, key)`¶

Sets an API key header (e.g. X-API-Key) sent with every subsequent request.

void apiKey(const char* name, const char* key);

Parameter	Type	Description
`name`	`const char*`	Header name (e.g., `"X-API-Key"` or `"x-api-key"`).
`key`	`const char*`	API key string.

Example:

client.apiKey("x-api-key", "my-secret-api-key");

`cookie(name, value)`¶

Appends or creates a Cookie header on the client. Returns a reference to ESP32HTTPClient, allowing you to chain .get(), .post(), or even other .cookie() calls directly on the client.

ESP32HTTPClient& cookie(const char* name, const char* value);

Parameters: * name: The name of the cookie (e.g., "session_id"). * value: The value of the cookie (e.g., "abc1234").

Example:

client.cookie("session_id", "abc1234")
      .cookie("device_id", "esp32-01")
      .get("/profile");

`setBaseUrl(baseUrl, port)`¶

Changes the base URL and target port at runtime for subsequent requests.

void setBaseUrl(const char* baseUrl, int port = 0);

Example:

client.setBaseUrl("https://api.v2.example.com", 443);

`setUrl(baseUrl)`¶

Convenience alias for updating only the base URL at runtime.

void setUrl(const char* baseUrl);

`setPort(port)`¶

Updates the target TCP port at runtime.

void setPort(int port);

`getBaseUrl()`¶

Returns the current base URL string.

const char* getBaseUrl() const;

`getPort()`¶

Returns the current target TCP port (or 0 if default).

int getPort() const;

`setTimeout(timeoutMs)`¶

Configures the default network timeout in milliseconds for all requests made by this client. Default is 60000 ms (1 minute).

void setTimeout(uint16_t timeoutMs);

Example:

client.setTimeout(10000); // 10 seconds

`getTimeout()`¶

Returns the configured default timeout in milliseconds.

uint16_t getTimeout() const;

`setMaxRetry(maxRetry)`¶

Configures the default maximum number of automatic retries on network failures. Default is 1 retry.

void setMaxRetry(int maxRetry);

Example:

client.setMaxRetry(3); // Up to 3 retries

`getMaxRetry()`¶

Returns the configured default max retry count.

int getMaxRetry() const;

`setContentType(contentType)`¶

Overrides the Content-Type header used for request bodies. Defaults to application/json.

void setContentType(const char* contentType);

Example:

client.setContentType("application/x-www-form-urlencoded");

Response & Error Inspection¶

`getStatusCode()`¶

Returns the HTTP status code of the last completed request.

int getStatusCode() const;

Return values:

Value	Meaning
`> 0`	Standard HTTP status code (200, 201, 404, 500…)
`< 0`	Network-level error (no connection, timeout, etc.)
`0`	No request has been made yet

`isSuccess()`¶

Returns true if the last request completed with a 2xx HTTP status code (200 <= code < 300).

bool isSuccess() const;

Example:

client.get("/data").getBody("val", &val);
if (client.isSuccess()) {
    Serial.println("Request succeeded!");
}

`hasError()`¶

Returns true if the last request failed due to a network error (code < 0) or an HTTP client/server error (code >= 400).

bool hasError() const;

Example:

client.get("/data").getBody("val", &val);
if (client.hasError()) {
    Serial.printf("Error (%d): %s\n", client.getStatusCode(), client.getErrorMessage().c_str());
}

`getErrorMessage()`¶

Returns a human-readable description of the last status or error code.

String getErrorMessage() const;

`errorToString(code)`¶

Static helper that converts any HTTP status code or client negative error code into a descriptive string.

static String errorToString(int code);

Struct Serialization & Deserialization¶

Static utility methods to convert mapped C++ structs to and from JSON strings.

`toJson(struct)`¶

Serializes a struct mapped with REST_JSON_MAP into a JSON string.

template <typename T>
static String toJson(const T& obj);

Example:

User user = {15, "Pedro", 9.5f, true};
String json = ESP32HTTPClient::toJson(user);

`fromJson(json, struct)`¶

Deserializes a JSON string into a target struct mapped with REST_JSON_MAP.

template <typename T>
static void fromJson(const String& json, T* target);
template <typename T>
static void fromJson(const char* json, T* target);

Example:

User user;
ESP32HTTPClient::fromJson("{\"id\":15,\"name\":\"Pedro\"}", &user);

Callbacks¶

You can register global callbacks on the client instance that are executed whenever any request completes.

`onSuccess(callback)`¶

Registers a callback executed when any request finishes with a 2xx HTTP status code (200 <= code < 300).

void onSuccess(HttpResponseCallback cb);

Example:

client.onSuccess([](int code) {
    Serial.printf("Client request succeeded with status %d\n", code);
});

`onError(callback)`¶

Registers a callback executed when any request fails with an error (code < 200 || code >= 400).

void onError(HttpErrorCallback cb);
void onError(HttpResponseCallback cb);

Example:

client.onError([](int code, const char* message) {
    Serial.printf("Client request failed (%d): %s\n", code, message);
---

### `onResponse(cb)`

Registers a global callback that is invoked after any request finishes, providing the HTTP status code.

```cpp
void onResponse(HttpResponseCallback cb);

Example:

client.onResponse([](int code) {
    Serial.printf("Request completed with status: %d\n", code);
});

`onObservability(cb)`¶

Registers a global callback that is invoked at the end of each request, providing performance metrics (timings, payload sizes, heap usage).

void onObservability(ObservabilityCallback cb);

Struct Definition (ObservabilityMetrics):

struct ObservabilityMetrics {
    unsigned long totalTimeMs;
    unsigned long ttfbMs;
    size_t txBytes;
    size_t rxBytes;
    int retries;
    uint32_t freeHeapBefore;
    uint32_t freeHeapAfter;
};

Example:

client.onObservability([](const ObservabilityMetrics& m) {
    Serial.printf("TTFB: %lu ms | TX: %d | RX: %d\n", m.ttfbMs, m.txBytes, m.rxBytes);
});

Connection Management¶

`end()`¶

Closes the persistent TCP/TLS Keep-Alive connection and frees its memory buffers.

void end();

Call this after a burst of requests to reclaim ~45KB of TLS memory during a long idle period. The next request will automatically re-establish the connection.

Example:

client.get("/data1").getBody("v", &v1);
client.get("/data2").getBody("v", &v2);

client.end(); // free TLS memory
delay(60000);

client.get("/data3").getBody("v", &v3); // reconnects automatically

Error Codes and HTTP Status Codes¶

Code	Meaning	Category
`-1`	Connection Refused	Client error
`-2`	Send Header Failed	Client error
`-3`	Send Payload Failed	Client error
`-4`	Not Connected	Client error
`-5`	Connection Lost	Client error
`-6`	No Stream	Client error
`-7`	No HTTP Server	Client error
`-8`	Too Less RAM	Client error
`-9`	Encoding Error	Client error
`-10`	Stream Write Error	Client error
`-11`	Read Timeout	Client error
`200`	OK	HTTP success
`201`	Created	HTTP success
`202`	Accepted	HTTP success
`204`	No Content	HTTP success
`400`	Bad Request	HTTP client error
`401`	Unauthorized	HTTP client error
`403`	Forbidden	HTTP client error
`404`	Not Found	HTTP client error
`405`	Method Not Allowed	HTTP client error
`408`	Request Timeout	HTTP client error
`409`	Conflict	HTTP client error
`429`	Too Many Requests	HTTP client error
`500`	Internal Server Error	HTTP server error
`501`	Not Implemented	HTTP server error
`502`	Bad Gateway	HTTP server error
`503`	Service Unavailable	HTTP server error
`504`	Gateway Timeout	HTTP server error
`0`	Not Executed	Internal state

Generic Fallback Behavior¶

Negative unknown codes → Unknown Client Error
200–299 → Success
300–399 → Redirection
400–499 → Client Error
500–599 → Server Error
Other values → Unknown HTTP Status

Example¶

A short usage example showing how applications can handle both transport errors and HTTP errors:

int status = client.get("/api/data").getStatusCode();

if (client.isSuccess()) {
    // Handle successful response
} else {
    Serial.println(client.getErrorMessage());
}

ESP32HTTPClient¶

Constructor¶

ESP32HTTPClient(baseUrl)¶

ESP32HTTPClient(baseUrl, port)¶

HTTP Request Methods¶

get(path)¶

post(path)¶

put(path)¶

update(path)¶

patch(path)¶

del(path)¶

soap(path)¶

graphql(path) / graphqlPost(path)¶

graphqlGet(path)¶

graphqlBatch(path)¶

Configuration Methods¶

setHeader(name, value)¶

bearer(token)¶

basic(user, password)¶

apiKey(name, key)¶

cookie(name, value)¶

setBaseUrl(baseUrl, port)¶

setUrl(baseUrl)¶

setPort(port)¶

getBaseUrl()¶

getPort()¶

setTimeout(timeoutMs)¶

getTimeout()¶

setMaxRetry(maxRetry)¶

getMaxRetry()¶

setContentType(contentType)¶

Response & Error Inspection¶

getStatusCode()¶

isSuccess()¶

hasError()¶

getErrorMessage()¶

errorToString(code)¶

Struct Serialization & Deserialization¶

toJson(struct)¶

fromJson(json, struct)¶

Callbacks¶

onSuccess(callback)¶

onError(callback)¶

onObservability(cb)¶

Connection Management¶

end()¶

Error Codes and HTTP Status Codes¶

Generic Fallback Behavior¶

Example¶

`ESP32HTTPClient(baseUrl)`¶

`ESP32HTTPClient(baseUrl, port)`¶

`get(path)`¶

`post(path)`¶

`put(path)`¶

`update(path)`¶

`patch(path)`¶

`del(path)`¶

`soap(path)`¶

`graphql(path)` / `graphqlPost(path)`¶

`graphqlGet(path)`¶

`graphqlBatch(path)`¶

`setHeader(name, value)`¶

`bearer(token)`¶

`basic(user, password)`¶

`apiKey(name, key)`¶

`cookie(name, value)`¶

`setBaseUrl(baseUrl, port)`¶

`setUrl(baseUrl)`¶

`setPort(port)`¶

`getBaseUrl()`¶

`getPort()`¶

`setTimeout(timeoutMs)`¶

`getTimeout()`¶

`setMaxRetry(maxRetry)`¶

`getMaxRetry()`¶

`setContentType(contentType)`¶

`getStatusCode()`¶

`isSuccess()`¶

`hasError()`¶

`getErrorMessage()`¶

`errorToString(code)`¶

`toJson(struct)`¶

`fromJson(json, struct)`¶

`onSuccess(callback)`¶

`onError(callback)`¶

`onObservability(cb)`¶

`end()`¶