Documentation for ExCurlImpersonate.

Shared options

• :headers - a map of headers to include in the request, defaults to %{"user-agent" => "ex_curl_impersonate/0.1.0"} (not added when :impersonate is set)
• :body - a string to send as the request body, defaults to ""
• :follow_location - if redirects should be followed, defaults to true
• :ssl_verifyhost - if SSL certificates should be verified, defaults to true
• :ssl_verifypeer - if SSL certificates should be verified, defaults to true
• :return_metrics - if request timing metrics should be included in the returned results, defaults to false
• :verbose - if curl should output verbose logs to stdout, useful for debugging. Defaults to false
• :proxy - proxy to use for transfers. Can be hostname or IP address with optional port number. Supports various proxy types (http, https, socks4, socks5). Defaults to nil
• :timeout_ms - maximum time in milliseconds for the whole request (CURLOPT_TIMEOUT_MS); on expiry the call returns {:error, "OPERATION_TIMEDOUT"}. The call blocks its process (on a dirty IO scheduler) until curl returns, so set this for anything talking to untrusted servers. Defaults to nil (no limit)
• :connect_timeout_ms - maximum time in milliseconds for the connection phase, including DNS, TCP, TLS and proxy handshakes (CURLOPT_CONNECTTIMEOUT_MS). Defaults to nil (curl's default of 300 seconds)
• :interface - outgoing network interface, local IP address or hostname to bind to, like curl's --interface (e.g. "eth1", "192.0.2.10", "if!eth1", "host!192.0.2.10"). Returns {:error, "INTERFACE_FAILED"} if it can't be used. Defaults to nil
• :ip_resolve - which IP version names resolve to (CURLOPT_IPRESOLVE): :v4, :v6 or :any. It applies to every name curl resolves for the transfer, the proxy's included, so through a proxy reached over IPv4 :v6 fails to connect; use :resolve to choose the target's address family there. Defaults to nil (:any)
• :resolve - list of "host:port:address" entries that pin a name to an address, like curl's --resolve (e.g. ["www.example.com:443:[2001:db8::1]"]). With a socks5:// proxy (not socks5h://) the pinned address is what the proxy is asked to connect to, which is how to choose IPv4 or IPv6 for a target through a proxy. Defaults to nil
• :cainfo - path to a PEM CA bundle used to verify peers (curl-impersonate's built-in default is /etc/ssl/certs/ca-certificates.crt on Linux, /etc/ssl/cert.pem on macOS); set this on distros that keep it elsewhere, e.g. /etc/pki/tls/certs/ca-bundle.crt. Defaults to nil
• :capath - path to a directory of hashed CA certificates used to verify peers (built-in default is /etc/ssl/certs on Linux); set this on distros that keep it elsewhere. Defaults to nil
• :impersonate - browser to impersonate (TLS, HTTP/2 fingerprint and default headers), e.g. "chrome136", "safari18_0", "firefox135". See the curl-impersonate targets. When set, the default user-agent header is not added. Defaults to nil
• :impersonate_default_headers - whether :impersonate also sends the browser's default headers. Defaults to true
• :accept_encoding - encodings to request and transparently decode (CURLOPT_ACCEPT_ENCODING). "" means every encoding this build supports (gzip, deflate, br, zstd), like curl's --compressed; a value such as "gzip" limits it; false disables decoding and returns the raw body bytes (an impersonated browser still advertises its own accept-encoding, so the server may compress anyway). Defaults to ""
• :http_version - one of :http1_0, :http1_1, :http2, :http2_tls, :http2_prior_knowledge, :http3 (falls back if HTTP/3 fails) or :http3_only. Defaults to nil (curl's default, or the impersonated browser's)

Fingerprint options

Every option added by curl-impersonate is available, named after the lowercased CURLOPT_ constant (e.g. CURLOPT_TLS_GREASE → :tls_grease). They default to nil (not set) and are applied after :impersonate, so they override the preset.

• integer / boolean: :http2_no_priority, :http2_window_update, :http3_ssl_permute_extensions, :proxy_credential_no_reuse, :quic_initial_packet_number, :split_cookies, :ssl_enable_alps, :ssl_enable_ticket, :ssl_permute_extensions, :stream_exclusive, :tls_grease, :tls_key_shares_limit, :tls_key_usage_no_check, :tls_record_size_limit, :tls_signed_cert_timestamps, :tls_status_request, :tls_use_new_alps_codepoint, :ws_ssl_disable_ticket
• string: :form_boundary, :http2_pseudo_headers_order, :http2_settings, :http2_streams, :http3_httpheader_order, :http3_pseudo_headers_order, :http3_settings, :http3_sig_hash_algs, :http3_ssl_ec_curves, :http3_tls_extension_order, :httpheader_order, :quic_cid_length, :quic_transport_parameters, :ssl_cert_compression, :ssl_sig_hash_algs, :tls_delegated_credentials, :tls_extension_order, :tls_trust_anchors, :ws_httpheader_order, :ws_ssl_cert_compression
• list of "Name: value" strings: :httpbaseheader, :http3_httpheader, :ws_httpheader. httpbaseheader: [] removes the impersonated browser's default headers.

Error messages

Error messages refer to error codes on the libcurl error codes documentation page.

For example, when we try to send a request to an invalid url:

  iex> ExCurlImpersonate.get("https://")
  {:error, "URL_MALFORMAT"}

The returned error tuple includes the error message "URL_MALFORMAT". This corresponds to the CURLE_URL_MALFORMAT (error code 3) error listed in the libcurl error codes documentation.