Client#

The main entry point for interacting with the Ionworks API.

Main client module for the Ionworks API.

This module provides the Ionworks client, which is the main entry point for interacting with the Ionworks API. It handles authentication, request/response processing, and provides access to all API resources through sub-clients.

class ionworks.client.Ionworks(api_key=None, api_url=None, dataframe_backend=None, timeout=None, max_retries=None)[source]#

Bases: object

Client for interacting with the Ionworks API.

Handles authentication, request/response processing, and provides access to all API resources through sub-clients.

Parameters:

api_key (str | None)
api_url (str | None)
dataframe_backend (str | None)
timeout (int | None)
max_retries (int | None)

__init__(api_key=None, api_url=None, dataframe_backend=None, timeout=None, max_retries=None)[source]#

Initialize Ionworks client.

Parameters:

api_key (str | None) – API key. If not provided, will look for IONWORKS_API_KEY env var.
api_url (str | None) – API URL. If not provided, will look for IONWORKS_API_URL env var.
dataframe_backend (str | None) – DataFrame backend for returned data: “polars” or “pandas”. If not provided, uses IONWORKS_DATAFRAME_BACKEND env var (defaults to “polars”).
timeout (int | None) – Request timeout in seconds. Defaults to 10 seconds if not provided.
max_retries (int | None) – Maximum number of retries for failed requests. Defaults to 5 if not provided. Retries occur on connection errors, timeouts, and 5xx server errors.

Return type:

None

request(method, endpoint, json_payload=None)[source]#

Make a request to the Ionworks API with standardized error handling.

Requests use the configured timeout and will retry up to the configured maximum number of times on connection errors, timeouts, and 5xx server errors.

Parameters:

method (str)
endpoint (str)
json_payload (dict[str, Any] | None)

Return type:

Any

get(endpoint)[source]#

Make a GET request using the request helper.

Parameters:: endpoint (str)
Return type:: Any

post(endpoint, json_payload)[source]#

Make a POST request using the request helper.

Parameters:

endpoint (str)
json_payload (dict[str, Any])

Return type:

Any

put(endpoint, json_payload)[source]#

Make a PUT request using the request helper.

Parameters:

endpoint (str)
json_payload (dict[str, Any])

Return type:

Any

delete(endpoint)[source]#

Make a DELETE request using the request helper.

Parameters:: endpoint (str)
Return type:: None

health_check()[source]#

Check the health of the Ionworks API.

Returns:: Health check response.
Return type:: dict[str, Any]

capabilities()[source]#

Fetch platform capabilities and domain context.

Returns domain knowledge (battery data hierarchy, key concepts), authentication info, and pointers to JSON Schema endpoints.

Returns:: Capabilities including domain_context, schemas, openapi_spec, and authentication.
Return type:: dict[str, Any]

schema(name)[source]#

Fetch a discovery schema by name.

Parameters:

name (str) –

Schema to fetch. Supported values:

"data" — cell data hierarchy (specifications, instances, measurements, steps, time_series).
"protocol" — Universal Cycler Protocol (UCP) JSON Schema.

Returns:

The requested schema.

Return type:

dict[str, Any]

Raises:

ValueError – If name is not a recognised schema.