selenium.webdriver.common.api_request_context#

APIRequestContext for making HTTP requests with browser cookie synchronization.

Classes

APIRequestContext(driver[, base_url, ...])

Makes HTTP requests with automatic browser cookie synchronization.

APIResponse(status, status_text, headers, ...)

Represents an HTTP response from an API request.

Exceptions

APIRequestFailure(response)

Raised when an API request returns a non-2xx status and fail_on_status_code is True.
exception APIRequestFailure(response)[source]#

Bases: Exception

Raised when an API request returns a non-2xx status and fail_on_status_code is True.

Parameters:

response (APIResponse)

Return type:

None

response#

The APIResponse that triggered the failure.

args#
with_traceback()#

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class APIResponse(status, status_text, headers, url, body)[source]#

Bases: object

Represents an HTTP response from an API request.

Parameters:

  • status (int)

  • status_text (str)

  • headers (dict[str, str])

  • url (str)

  • body (bytes)

status#

HTTP status code.

status_text#

HTTP status text.

headers#

Response headers as a dict.

url#

The request URL.

property ok: bool#

Whether the response status is in the 200-299 range.

json()[source]#

Parse the response body as JSON.

Returns:

The parsed JSON object.

Return type:

Any

text()[source]#

Decode the response body as UTF-8 text.

Returns:

The response body as a string.

Return type:

str

body()[source]#

Return the raw response body bytes.

Returns:

The response body as bytes.

Return type:

bytes

dispose()[source]#

Free the response body memory.

Return type:

None

class APIRequestContext(driver, base_url='', extra_headers=None, timeout=30.0, max_redirects=10, fail_on_status_code=False)[source]#

Bases: _BaseRequestContext

Makes HTTP requests with automatic browser cookie synchronization.

Cookies from the browser session are sent with API requests, and cookies from API responses are synced back to the browser.

Parameters:

  • driver (WebDriver) – The WebDriver instance to sync cookies with.

  • base_url (str) – Optional base URL prepended to relative request paths.

  • extra_headers (dict[str, str] | None) – Optional headers included in every request.

  • timeout (float) – Default request timeout in seconds.

  • max_redirects (int) – Maximum number of redirects to follow.

  • fail_on_status_code (bool) – If True, raise APIRequestFailure for non-2xx responses.

new_context(base_url='', extra_headers=None, storage_state=None, fail_on_status_code=False)[source]#

Create an isolated API request context that does not sync with the browser.

Parameters:

  • base_url (str) – Optional base URL for this context.

  • extra_headers (dict[str, str] | None) – Optional headers for this context.

  • storage_state (dict | str | Path | None) – Optional cookies to pre-load, as a dict, JSON file path, or Path.

  • fail_on_status_code (bool) – If True, raise APIRequestFailure for non-2xx responses.

Returns:

An _IsolatedAPIRequestContext instance.

Return type:

_IsolatedAPIRequestContext

get_storage_state(path=None)[source]#

Export the current browser cookies as a storage state dict.

Parameters:

path (str | Path | None) – Optional file path to save the storage state as JSON.

Returns:

A dict with a “cookies” key containing the browser cookies.

Return type:

dict[str, Any]

delete(url, **kwargs)#

Send a DELETE request.

Parameters:

  • url (str) – The request URL (absolute or relative to base_url).

  • **kwargs (Any) – Optional arguments: headers, params, data, form, json_data, timeout, max_redirects, fail_on_status_code.

Returns:

An APIResponse object.

Return type:

APIResponse

dispose()#

Close the underlying connection pool.

Return type:

None

fetch(url, method='GET', **kwargs)#

Send an HTTP request with a custom method.

Parameters:

  • url (str) – The request URL (absolute or relative to base_url).

  • method (str) – The HTTP method to use.

  • **kwargs (Any) – Optional arguments: headers, params, data, form, json_data, timeout, max_redirects, fail_on_status_code.

Returns:

An APIResponse object.

Return type:

APIResponse

get(url, **kwargs)#

Send a GET request.

Parameters:

  • url (str) – The request URL (absolute or relative to base_url).

  • **kwargs (Any) – Optional arguments: headers, params, timeout, max_redirects, fail_on_status_code.

Returns:

An APIResponse object.

Return type:

APIResponse

head(url, **kwargs)#

Send a HEAD request.

Parameters:

  • url (str) – The request URL (absolute or relative to base_url).

  • **kwargs (Any) – Optional arguments: headers, params, timeout, max_redirects, fail_on_status_code.

Returns:

An APIResponse object.

Return type:

APIResponse

patch(url, **kwargs)#

Send a PATCH request.

Parameters:

  • url (str) – The request URL (absolute or relative to base_url).

  • **kwargs (Any) – Optional arguments: headers, params, data, form, json_data, timeout, max_redirects, fail_on_status_code.

Returns:

An APIResponse object.

Return type:

APIResponse

post(url, **kwargs)#

Send a POST request.

Parameters:

  • url (str) – The request URL (absolute or relative to base_url).

  • **kwargs (Any) – Optional arguments: headers, params, data, form, json_data, timeout, max_redirects, fail_on_status_code.

Returns:

An APIResponse object.

Return type:

APIResponse

put(url, **kwargs)#

Send a PUT request.

Parameters:

  • url (str) – The request URL (absolute or relative to base_url).

  • **kwargs (Any) – Optional arguments: headers, params, data, form, json_data, timeout, max_redirects, fail_on_status_code.

Returns:

An APIResponse object.

Return type:

APIResponse