API Reference

This section provides detailed documentation for all classes and methods in the AskPablos API client.

Core Classes

AskPablos

class askpablos_api.AskPablos(api_key: str, secret_key: str)

Bases: object

Simple interface for making GET requests through the AskPablos proxy API.

This class provides a clean interface for sending GET requests through the AskPablos proxy service. It handles authentication, request formatting, and error management automatically.

The AskPablos class is designed to be simple and focused - it only supports GET requests to keep the interface clean and easy to use.

client

The underlying client for making API requests.

Type:

ProxyClient

__init__(api_key: str, secret_key: str)

Initialize the AskPablos API client.

Creates a new instance of the AskPablos client with the provided authentication credentials. The client will use these credentials for all subsequent API requests.

Parameters:

• api_key (str) – Your unique API key from the AskPablos dashboard.

• secret_key (str) – Your private secret key used for HMAC signing.

Raises:

AuthenticationError – If any of the required credentials are missing or invalid.

get(url: str, params: Dict[str, str] | None = None, headers: Dict[str, str] | None = None, browser: bool = False, screenshot: bool = False, operations: list | None = None, timeout: int = 30, max_retries: int = 3, is_bulk: bool = False, **options) → ResponseData

Send a GET request through the AskPablos proxy.

This is the main method for fetching web pages and API endpoints through the AskPablos proxy service. It supports various options for customizing the request behavior.

Parameters:

• url (str) – The target URL to fetch. Must be a valid HTTP/HTTPS URL.

• params (Dict[str, str], optional) – URL query parameters to append. Example: {“page”: “1”, “limit”: “10”}

• headers (Dict[str, str], optional) – Custom headers for the request.

• browser (bool, optional) – Whether to use browser automation for JavaScript rendering. Defaults to False.

• screenshot (bool, optional) – Whether to take a screenshot of the page. Requires browser=True. Defaults to False.

• operations (list, optional) –

  List of browser operations to perform. Example: [{“task”: “waitForElement”,

  ”match”: {“on”: “xpath”, “rule”: “visible”,

  ”value”: “//*[@id=’element’]”}}]

• timeout (int, optional) – Request timeout in seconds. Defaults to 30.

• max_retries (int, optional) – Maximum number of retries on failure. Defaults to 3.

• **options – Additional proxy options.

• is_bulk (bool, optional) – Whether the request is part of a bulk operation.

Returns:

The response object from the API containing:

• status_code (int): HTTP status code from the target server

• headers (Dict[str, str]): Response headers from target server

• content (bytes): Response body/content

• url (str): Final URL after any redirects

• elapsed_time (str): Time taken to complete the request

• encoding (Optional[str]): Response text encoding

• json (Optional[Dict[str, Any]]): Parsed JSON data if available

• screenshot (Optional[bytes]): Screenshot data if requested

Return type:

ResponseData

Raises:

• APIConnectionError – If the client cannot connect to the AskPablos API.

• ResponseError – If the API returns an error status code.

• AuthenticationError – If authentication fails.

• ConfigurationError – If there is a configuration issue with the request.

The main client class for making requests through the AskPablos proxy service. This is the primary interface that most users will interact with.

ProxyClient

class askpablos_api.ProxyClient(api_key: str, secret_key: str, api_url: str = 'http://10.10.10.24')

Bases: object

High-level client for the AskPablos proxy service.

This class orchestrates the authentication, HTTP communication, and validation components to provide a clean interface for making proxy requests.

__init__(api_key: str, secret_key: str, api_url: str = 'http://10.10.10.24')

Initialize the proxy client.

Parameters:

• api_key – Your API key from the AskPablos dashboard

• secret_key – Your secret key for HMAC signing

• api_url – The proxy API base URL

request(url: str, method: str = 'GET', headers: Dict[str, str] | None = None, params: Dict[str, str] | None = None, options: Dict[str, Any] | None = None, timeout: int = 30, max_retries: int = 3, is_bulk: bool = False) → ResponseData

Send a request through the AskPablos proxy.

When browser mode is enabled (browser=True), all browser-specific parameters (wait_for_load, screenshot, js_strategy) are always sent to the API server with their explicit values, ensuring precise control over browser behavior.

Parameters:

• url – Target URL to fetch through the proxy

• method – HTTP method (GET, POST, PUT, DELETE, etc.)

• headers – Custom headers to send to the target URL

• params – Query parameters to append to the target URL

• options – Proxy-specific options for request processing. When browser=True is included, all browser-specific options are sent to the API.

• timeout – Request timeout in seconds

• max_retries – Maximum number of retries on failure

• is_bulk – Whether this is a bulk request

Returns:

Response object with all request results

Return type:

ResponseData

A lower-level client for direct proxy interactions and advanced use cases.

HTTPClient

class askpablos_api.HTTPClient(auth_manager: AuthManager, api_url: str)

Bases: object

Handles low-level HTTP communication with the AskPablos API.

This class manages the HTTP requests, response parsing, and error handling for the proxy service communication.

__init__(auth_manager: AuthManager, api_url: str)

Initialize the HTTP client.

Parameters:

• auth_manager – Authentication manager for request signing

• api_url – Base URL for the API service

send_request(url: str, method: str = 'GET', options: RequestOptions | None = None, is_bulk: bool = False) → ResponseData

Send an HTTP request through the proxy service.

Parameters:

• url – Target URL to fetch through the proxy

• method – HTTP method (GET, POST, etc.)

• options – Request options and proxy settings

• is_bulk – Whether this is a bulk request

Returns:

Parsed response from the API

Return type:

ResponseData

Raises:

• APIConnectionError – If connection to API fails

• ResponseError – If API returns an error response

Handles HTTP communication and request execution.

AuthManager

class askpablos_api.AuthManager(api_key: str, secret_key: str)

Bases: object

Handles authentication and request signing for the AskPablos API.

This class manages API credentials and provides methods for generating HMAC-SHA256 signatures required for API authentication.

__init__(api_key: str, secret_key: str)

Initialize the authentication manager.

Parameters:

• api_key – Your API key from the AskPablos dashboard

• secret_key – Your secret key for HMAC signing

Raises:

AuthenticationError – If credentials are missing or invalid

generate_signature(payload: str) → str

Generate a base64-encoded HMAC SHA256 signature.

Creates a cryptographic signature of the request payload using the client’s secret key. This signature is used by the API server to verify that the request came from an authorized client and hasn’t been tampered with.

Parameters:

payload – JSON string of the request body that will be signed. This should be the exact JSON that will be sent in the HTTP request body.

Returns:

Base64 encoded HMAC-SHA256 signature of the payload.

Return type:

str

Note

The signature is generated using HMAC-SHA256 with the client’s secret key. The resulting binary signature is then base64-encoded for transmission in HTTP headers.

build_auth_headers(payload: str) → Dict[str, str]

Construct authentication headers for API requests.

Builds the complete set of HTTP headers needed for API authentication, including the content type, API key, and request signature.

Parameters:

payload – JSON string of the request body. Used to generate the authentication signature.

Returns:

HTTP headers dictionary containing:

• Content-Type: Set to “application/json”

• X-API-Key: Your API key for identification

• X-Signature: HMAC-SHA256 signature of the payload

Return type:

Dict[str, str]

Manages authentication and HMAC signature generation.

ParameterValidator

class askpablos_api.ParameterValidator

Bases: object

Validates request parameters and options for API calls.

This class provides centralized validation logic to ensure that parameter combinations are valid and provide helpful error messages when invalid combinations are detected.

static validate_browser_dependencies(browser: bool, screenshot: bool = False) → None

Validate that browser-dependent features are only used with browser=True.

The following parameters require browser=True to function: - screenshot: Requires browser automation to capture page screenshots

Parameters:

• browser – Whether browser mode is enabled

• screenshot – Whether screenshot capture is requested

Raises:

ConfigurationError – If browser features are requested without browser=True

static validate_url(url: str) → None

Validate that the URL is properly formatted.

Parameters:

url – URL to validate

Raises:

ValueError – If URL is invalid

static validate_timeout(timeout: int) → None

Validate timeout parameter.

Parameters:

timeout – Timeout value in seconds

Raises:

ValueError – If timeout is invalid

static validate_headers(headers: Dict[str, str] | None) → None

Validate headers parameter.

Parameters:

headers – Headers dictionary to validate

Raises:

ValueError – If headers are invalid

classmethod validate_request_params(url: str, headers: Dict[str, str] | None = None, browser: bool = False, screenshot: bool = False, timeout: int = 30) → None

Validate all request parameters at once.

Parameters:

• url – Target URL

• headers – Custom headers

• browser – Browser mode flag

• screenshot – Screenshot capture flag

• timeout – Request timeout

Raises:

ValueError – If any parameter is invalid

Validates request parameters and enforces API requirements.

Data Models

ResponseData

class askpablos_api.ResponseData(status_code: int, headers: Mapping[str, str], content: bytes, url: str, elapsed_time: str, encoding: str | None, json_data: Dict[str, Any] | None = None, screenshot: bytes | None = None)

Bases: object

Response object that provides structured access to HTTP response data.

This class encapsulates all response information from a proxy request, including headers, content, timing, and optional screenshot data.

status_code

HTTP status code from the target server

Type:

int

headers

Response headers from target server

Type:

Dict[str, str]

content

Response body/content as bytes

Type:

bytes

url

Final URL after any redirects

Type:

str

elapsed_time

Time taken to complete the request (formatted string)

Type:

str

encoding

Response text encoding

Type:

Optional[str]

json

Parsed JSON data if available

Type:

Optional[Dict[str, Any]]

screenshot

Base64 decoded screenshot if requested

Type:

Optional[bytes]

__init__(status_code: int, headers: Mapping[str, str], content: bytes, url: str, elapsed_time: str, encoding: str | None, json_data: Dict[str, Any] | None = None, screenshot: bytes | None = None)

Initialize a ResponseData object.

property text: str

Get response content as text.

Returns:

Response content decoded as text using the response encoding

Return type:

str

property ok: bool

Check if the response was successful.

Returns:

True if status code is between 200-299

Return type:

bool

raise_for_status() → None

Raise an exception if the response was unsuccessful.

Raises:

HTTPError – If the status code indicates an error

RequestOptions

class askpablos_api.RequestOptions(browser: bool = False, screenshot: bool = False, timeout: int = 30, max_retries: int = 3, **additional_options)

Bases: object

Container for request options and parameters.

This class encapsulates all options that can be passed to a proxy request, providing validation and default values.

__init__(browser: bool = False, screenshot: bool = False, timeout: int = 30, max_retries: int = 3, **additional_options)

Initialize request options.

Parameters:

• browser – Enable browser automation

• screenshot – Take page screenshot

• timeout – Request timeout in seconds

• max_retries – Maximum number of retries on failure (default: 3)

• **additional_options – Additional proxy options (e.g., operations)

validate() → None

Validate the request options.

Raises:

ValueError – If invalid parameter combinations are detected

to_dict() → Dict[str, Any]

Convert options to dictionary format.

Returns:

Options as dictionary

Return type:

Dict[str, Any]

Exception Classes

AskPablosError

class askpablos_api.AskPablosError

Bases: Exception

Base exception for all AskPablos API errors.

This is the root exception class for all errors that can occur within the AskPablos API client. All other exceptions inherit from this base class.

AuthenticationError

class askpablos_api.AuthenticationError

Bases: AskPablosError

Raised when there is an authentication problem with the API.

This exception is raised when: - API key is missing or empty - Secret key is missing or empty - Authentication credentials are invalid - HMAC signature verification fails

APIConnectionError

class askpablos_api.APIConnectionError

Bases: AskPablosError

Raised when the client fails to connect to the API.

This exception is raised when: - Network connectivity issues prevent reaching the API - DNS resolution fails for the API URL - Connection timeouts occur - The API server is unreachable or down

ResponseError

class askpablos_api.ResponseError(status_code: int, message: str)

Bases: AskPablosError

Raised when there is an error in the API response.

This exception is raised when the AskPablos API returns an HTTP error status code (4xx or 5xx). It includes both the status code and the error message from the API response.

Common scenarios: - 400 Bad Request: Invalid request parameters - 401 Unauthorized: Authentication failed - 403 Forbidden: Access denied - 404 Not Found: Endpoint not found - 429 Too Many Requests: Rate limit exceeded - 500 Internal Server Error: Server error

status_code

The HTTP status code from the API response

Type:

int

message

The error message from the API response

Type:

str

__init__(status_code: int, message: str)

Initialize a ResponseError with status code and message.

Parameters:

• status_code (int) – The HTTP status code from the API response

• message (str) – The error message describing what went wrong