Pulse Python SDK API

The Pulse SDK (pulse-api) is a Python client library that wraps the Pulse REST endpoints used by the admin pages. It is session-based: you authenticate once, with an API key or with a username and password, and every subsequent call is carried by the session cookie, with CSRF handled automatically. Each PulseApi object owns its own cookie jar and cached CSRF token, so one client instance is one Pulse session. Every call raises a PulseApiError (with .message, .status, and .body) on failure.

The SDK uses the Python standard library only, so it has no third party dependencies and installs on a machine with no internet access. It requires Python 3.8 or later.

The previous browser-side JavaScript client (pulse.api.js) has been discontinued. Python is now the only supported client SDK.

Download

The SDK is distributed by Cubewise as a zip package. It is not published on GitHub or on PyPI.

pulse-python-sdk.8.0.1.zip

The package contains:

Item	Description

Item	Description
`pulse_api-8.0.1-py3-none-any.whl`	The SDK, installable with `pip`.
`samples/`	Ready to run sample applications covering environments, users, groups, alerts, instance settings, migration packages and approvals.
`README.md`	Install instructions, configuration, and the full usage guide.

Install

Unzip the package, then install the wheel with pip. Using a virtual environment is recommended.

python -m venv .venv
.venv\Scripts\activate
pip install pulse_api-8.0.1-py3-none-any.whl

On Linux or macOS, use python3 -m venv .venv and source .venv/bin/activate.

Verify the install:

python -c "from pulse_api import PulseApi; print(PulseApi.VERSION)"

If you see ModuleNotFoundError: No module named 'pulse_api', the wheel was installed into a different Python than the one running the script. Use python -m pip install ... so that pip and python are the same interpreter.

Getting started

Create a client against your Pulse Server URL, then log in before making any other calls. Unlike the old browser client, the Python client connects to a full URL, so it can run from any machine that can reach the Pulse Server.

from pulse_api import PulseApi, PulseApiError

client = PulseApi('https://pulse.example.com')   # base_url='/pulse/' when Pulse is served under a sub-path

client.login.login_with_api_key('pulse_xxxxxxxx')
try:
    for env in client.system.get_system_servers():
        print(env['serverName'], env.get('RESTURL'))
finally:
    client.login.logout()

Method names are snake_case. Payload keys are the server's own JSON and stay camelCase (serverName, RESTURL, emailGroupId).

Follow the instructions in this article to Create a Pulse API key.

Full reference: This page is a summary only. The complete details of every SDK call (parameters, object shapes, sample flows, and return values) are covered by the README.md and the sample applications shipped in the SDK package.

Authentication (`login`)

Function	Purpose

Function	Purpose
`login.login(user_name, password)`	Log in with a username and password.
`login.login_with_api_key(api_key)`	Log in with a personal API key minted from the API Keys screen.
`login.logout()`	Log out and end the session.
`login.get_csrf_token(force=False)`	Advanced: fetch or refresh the cached CSRF token (normally handled for you).

Environments (`system`)

Manage Pulse environments (TM1 servers) shown on the Environments admin page.

Function	Purpose

Function	Purpose
`system.get_system_servers(server_name=None, include_deleted=False, agents=False)`	List environments (optionally include soft-deleted, or return workspace agents).
`system.get_authorised_system_servers(server_name=None)`	List environments the current non-admin user may see.
`system.test_server(server)`	Test an environment connection without saving.
`system.save_server(server)`	Create, update, activate, or deactivate an environment.
`system.delete_server(server)`	Soft-delete an environment.

Instance settings (`system`)

Manage the TM1 instances (services) within an environment.

Function	Purpose

Function	Purpose
`system.get_system_instances(servername=None)`	List instances plus notification email groups for an environment.
`system.save_instances(instances, servername=None)`	Save, activate, or deactivate instances (re-validates active ones).
`system.upgrade_instance(instance, target_version, servername=None)`	Request a TM1 instance upgrade (PAoC / managed environments only).

Users (`system_users`)

Function	Purpose

Function	Purpose
`system_users.list()`	List users, groups, and a dummy-password placeholder.
`system_users.save(user)`	Create (`id: 0`) or update a user.
`system_users.remove(user_id)`	Delete a user (built-in admin and SYNC-source users are protected).

Groups (`system_groups`)

Function	Purpose

Function	Purpose
`system_groups.list()`	List security groups with their permission flags.
`system_groups.get_new()`	Get a blank group template (starting point for a create).
`system_groups.save(group)`	Create (`id: 0`) or update a group.
`system_groups.remove(group_id)`	Delete a group (the built-in PUBLIC group cannot be deleted).
`system_groups.list_importable()`	List Windows / Active Directory groups available to import.
`system_groups.import_groups(groups)`	Import the named AD groups.

Alerts (`settings`)

Create, update, and delete Pulse system alerts and alert templates.

Function	Purpose

Function	Purpose
`settings.get_system_alerts(servername=None, view=None)`	List alerts, alert types, and email groups for an environment.
`settings.save_system_alert(alert)`	Create, update, or delete an alert (set `delete: true` to remove).
`settings.get_system_alert_templates(servername=None)`	List alert templates for the environment's TM1 version.
`settings.save_system_alert_template(template)`	Create or update an alert template.
`settings.delete_system_alert_template(template)`	Delete an alert template.
`settings.restore_system_alert_templates(templates)`	Restore built-in templates by id.
`settings.upload_system_alert_template(template)`	Upload a `.json` template file (multipart).
`settings.get_pulse_alerts(servername=None)` / `settings.save_pulse_alerts(alerts)`	Read / save monitor-connectivity alerts.
`settings.get_notification_groups()`	List email groups selectable for alerts.

Credentials (`credentials`)

Function	Purpose

Function	Purpose
`credentials.one(servername, servicename)`	Read a masked environment or instance credential.
`credentials.list_allowed(servername)`	List credentials the current user may see for an environment.
`credentials.save(credential, credential_id=None, reload=None)`	Save a TM1 or workspace credential.

API keys (`api_keys`)

Function	Purpose

Function	Purpose
`api_keys.list(all=False)`	List API keys for the current user (or all users, for an administrator).
`api_keys.mint(label, expires_in_days=None)`	Create a new API key. The key value is returned once, at creation.
`api_keys.revoke(key_id)`	Revoke a key without deleting it.
`api_keys.remove(key_id)`	Delete a key.

Migration: create a package (`packages`)

The Create Package wizard threads a mutable state object through several calls, then saves asynchronously (poll the status until it resolves).

Function	Purpose

Function	Purpose
`packages.start_package_create(server=None, service=None)`	Initial wizard state: available services plus a default date range.
`packages.get_package_create_items(server=None, service=None)`	Pre-selected items for a manual source-to-target create.
`packages.get_package_create_authors(state)`	Change authors within the source / date range.
`packages.get_package_create_changes(state)`	Detected changes for the selection.
`packages.get_package_create_dependencies(request)`	Dependencies for the included changes.
`packages.save_package_create(request, request_id)`	Start the create asynchronously.
`packages.get_package_create_status(request_id)`	Poll create status; returns the created package(s) once done.

Migration: execute a package (`packages`)

Executing a package updates the target TM1 instance. Test against a non-production environment first.

Function	Purpose

Function	Purpose
`packages.start_package_execution(package_id, server_name=None)`	Prepare: candidate target service plus package metadata.
`packages.compute_package_execute_changes(package_id, state)`	Compute the operations to apply for the prepared target.
`packages.get_package_execute_changes(package_id)`	Re-read the previously computed operation list.
`packages.run_package_execution(package_id, request)`	Start the execution asynchronously.
`packages.get_package_execution_run_status(package_id)`	Poll overall run status until it succeeds.
`packages.get_package_execution_status(package_id, last=0)`	Stream per-item progress log lines (incremental).

Migration: list, view & import packages (`packages`)

Function	Purpose

Function	Purpose
`packages.get_packages(archived=False)`	List packages, newest first (no execution history).
`packages.get_package_execute_history(archived=False, start=None, end=None)`	List packages with their per-package execution history (date-filterable).
`packages.view_package(package_id)`	Full package details: contents, execution, and approval history.
`packages.recreate_package(package_id)`	Recreate a new package from an existing one.
`packages.import_package(file)`	Upload a previously exported package file (multipart).

Migration: approvals (`packages`)

Function	Purpose

Function	Purpose
`packages.list_approvals(archived=False)`	List migration approval requests.
`packages.submit_approval(package_id, server_name=None, service_name=None, approver_email_group_id=None, description=None)`	Submit a package for approval.
`packages.action_approval(approval_id, status, action_remarks=None)`	Approve or deny an approval request.
`packages.archive_approval(approval_id)`	Archive an approval request.

Other namespaces

The same client also exposes the remaining Pulse REST areas, following the same naming rules: system_account, system_sync, reserved_credentials, permissions, vcs, metadata, process_history, monitoring, live_monitor, object_locking, web_artifacts and reports.

Any endpoint that has no dedicated method yet is still reachable through the underlying request helper, with the same CSRF and error handling:

client.request('GET', 'api/system/status', csrf=False)
client.request('POST', 'api/system/alert', body=alert)

Error handling

Every call raises a PulseApiError on failure. Note that .status may be 200 for envelope-style errors, where .body holds the parsed { Message, Success: false, Failed: true } response.

from pulse_api import PulseApi, PulseApiError

try:
    client.system_users.save(user)
except PulseApiError as e:
    print(e.message, e.status, e.body)

Pulse Python SDK API

Download

Install

Getting started

Authentication (login)

Environments (system)

Instance settings (system)

Users (system_users)

Groups (system_groups)

Alerts (settings)

Credentials (credentials)

API keys (api_keys)

Migration: create a package (packages)

Migration: execute a package (packages)

Migration: list, view & import packages (packages)

Migration: approvals (packages)