Reference

This is the complete API reference for the pd4castr-api-sdk Python package. It documents every public class, method, data model, and exception.

Client

The Client class is the main entry point for interacting with the pd4castr API.

Constructor

from pd4castr_api_sdk import Client
 
client = Client(
    *,
    client_id: str,
    client_secret: str,
    timeout: float = 30.0,
    base_url: str | None = None,
    auth0_domain: str | None = None,
    auth0_audience: str | None = None,
)

Parameter	Type	Default	Description
`client_id`	`str`	(required)	OAuth 2.0 client ID
`client_secret`	`str`	(required)	OAuth 2.0 client secret
`timeout`	`float`	`30.0`	HTTP request timeout in seconds
`base_url`	`str` or `None`	`https://api.v2.pd4castr.com.au`	API base URL override
`auth0_domain`	`str` or `None`	`pdview.au.auth0.com`	Auth0 tenant domain override
`auth0_audience`	`str` or `None`	`https://api.pd4castr.com.au`	Auth0 API audience override

All parameters are keyword-only.

The client supports the context manager protocol, so you can use it with a with statement to automatically close the connection:

with Client(client_id="...", client_secret="...") as client:
    models = client.get_models()

Methods

`get_models`

client.get_models(*, time_horizon: str | None = None) -> list[Model]

Returns a list of all models accessible to the authenticated user, including your organisation’s private models and any public models.

Parameter	Type	Default	Description
`time_horizon`	`str` or `None`	`None`	Filter models by time horizon

Valid time_horizon values:

"day_ahead"
"week_ahead"
"quarterly"
"historical"

When time_horizon is None, all models are returned regardless of their time horizon.

Returns: list[Model]

`get_model`

client.get_model(model_id: str) -> Model

Fetches a single model by its unique ID.

Parameter	Type	Description
`model_id`	`str`	The unique model ID

Returns: Model

Raises: NotFoundError if no model exists with the given ID.

`get_current_user`

client.get_current_user() -> User

Returns the profile and organisation details for the authenticated user.

Returns: User

`close`

client.close() -> None

Closes the underlying HTTP connection. After calling close(), the client can’t make further requests. If you use the client as a context manager, this is called automatically.

Data models

All data models use Pydantic and are returned as typed Python objects. Unknown fields from the API are ignored automatically.

`Model`

Represents a forecast model on the pd4castr platform.

Field	Type	Description
`id`	`str`	Unique model identifier
`modelGroupId`	`str`	ID of the model group this model belongs to
`name`	`str`	Internal model name
`displayName`	`str`	Human-readable display name
`notes`	`str`	Model notes or description
`revision`	`int`	Model revision number
`dockerImage`	`str`	Docker image used to run the model
`createdAt`	`str`	ISO 8601 creation timestamp
`displayTimezone`	`str`	Timezone for displaying forecast results
`horizon`	`TimeHorizon`	The model’s forecast time horizon
`modelMetadata`	`ModelMetadata`	Additional metadata about the model
`outputSpecification`	`list[ColumnSpecification]`	Schema of the model’s output columns
`tags`	`list[str]`	Tags associated with the model
`sensitivities`	`list[SensitivitySpecification]`	Sensitivity configurations
`outputFileFormat`	`FileFormat`	Output file format (`json`, `csv`, `parquet`)
`forecastVariable`	`ForecastVariableSpecification`	The variable being forecast

`TimeHorizon`

Describes the forecast time horizon for a model.

Field	Type	Description
`name`	`str`	Full name (for example, “Day Ahead”)
`shortName`	`str`	Abbreviated name (for example, “DA”)
`key`	`str`	Machine-readable key (for example, “day_ahead”)

`ModelMetadata`

Optional metadata associated with a model. All fields are optional and default to None.

Field	Type	Description
`description`	`str` or `None`	Extended model description
`releaseDate`	`str` or `None`	When the model was released
`resolution`	`str` or `None`	Forecast resolution (for example, “30min”)
`baseComparisonModel`	`str` or `None`	ID of the baseline comparison model

`ColumnSpecification`

Describes a single column in the model’s output data.

Field	Type	Description
`name`	`str`	Column name
`type`	`str`	Data type of the column
`ui`	`UISpecification` or `None`	Optional display configuration

`UISpecification`

Controls how a column is displayed in the pd4castr web app.

Field	Type	Description
`seriesKey`	`bool` or `None`	Whether the column is a series key
`colours`	`list[str]` or `None`	Hex color codes for chart rendering

`SensitivitySpecification`

Defines a sensitivity parameter and its available categories.

Field	Type	Description
`name`	`str`	Name of the sensitivity parameter
`categories`	`list[str]`	Available category values for this sensitivity

`ForecastVariableSpecification`

Describes the variable that a model forecasts.

Field	Type	Description
`name`	`str`	Full variable name (for example, “Price”)
`shortName`	`str`	Abbreviated name (for example, “price”)
`key`	`str`	Machine-readable key

`FileFormat`

A string enumeration of supported output file formats.

Value	Description
`"json"`	JSON format
`"csv"`	Comma-separated values
`"parquet"`	Apache Parquet format

FileFormat extends Python’s StrEnum, so you can compare it directly with strings:

if model.outputFileFormat == "parquet":
    print("This model outputs Parquet files")

`User`

Represents an authenticated user on the pd4castr platform.

Field	Type	Description
`id`	`str`	Unique user identifier
`email`	`str`	User’s email address
`organisation`	`Organisation` or `None`	The user’s organisation

`Organisation`

Represents an organisation on the pd4castr platform.

Field	Type	Description
`id`	`str`	Unique organisation identifier
`displayName`	`str`	Organisation display name
`slug`	`str`	URL-friendly organisation slug
`domains`	`list[str]`	Email domains for the organisation
`permissions`	`list[str]`	Granted permission strings

Exceptions

The SDK defines a small exception hierarchy for error handling.

`ApiError`

Raised when the API returns an HTTP 4xx or 5xx response (except 404, which raises NotFoundError instead).

Property	Type	Description
`status_code`	`int`	The HTTP status code
`message`	`str`	A human-readable error message
`body`	`Any` or `None`	The parsed response body, if available

`NotFoundError`

Raised when the API returns an HTTP 404 response.

Note: NotFoundError does not inherit from ApiError. If you need to catch both, use separate except clauses.

Error handling example

from pd4castr_api_sdk import Client, ApiError, NotFoundError
 
with Client(client_id="...", client_secret="...") as client:
    try:
        model = client.get_model("non-existent-id")
    except NotFoundError:
        print("Model not found")
    except ApiError as e:
        print(f"API error {e.status_code}: {e.message}")

Next steps

Quick start — install the SDK and make your first API call
Authentication — understand the OAuth 2.0 flow and credential management