python

Pulse REST API — Python sample SDK

A sample SDK over the Pulse REST API: pulse_api.py is a dependency-free client for those endpoints, and the sample apps drive it from the command line. It is the Python counterpart to ../js/ — the same apps, at feature parity.

Important

The documentation and examples are not yet final and may be subject to change from time to time. At this stage, they primarily reflect the APIs currently being used by Pulse for this release version. Should there be any updates or changes, we will communicate them accordingly.

Pulse is session-based: you authenticate once (API key, or username/password) and every subsequent call rides the session cookie. Where the Node.js samples load the browser bundle pulse.api.js in a vm sandbox, Python can't evaluate JavaScript — so pulse_api.py is a faithful port of that bundle: same endpoints, same query keys, same CSRF handling, same error/envelope semantics. Only the naming convention differs.

pulse.api.js (JS)	pulse_api.py (Python)
PulseApi.configure({ baseUrl: '/' })	PulseApi(url, base_url='/')
PulseApi.login.loginWithApiKey(key)	client.login.login_with_api_key(key)
PulseApi.system.getSystemServers()	client.system.get_system_servers()
PulseApi.settings.getSystemAlerts({servername})	client.settings.get_system_alerts(servername=...)
PulseApi.systemGroups.getNew()	client.system_groups.get_new()
PulseApiError (.message/.status/.body)	PulseApiError (.message/.status/.body)

Namespaces map one-to-one (camelCase → snake_case): api_keys, system_users, system_account, system_groups, credentials, reserved_credentials, system_sync, permissions, login, vcs, metadata, process_history, monitoring, live_monitor, object_locking, web_artifacts, system, settings, packages, reports.

Unlike the JS module (a browser singleton), the Python client is an instance — it owns the cookie jar and the cached CSRF token, so one PulseApi object is one Pulse session.

Requirements

• Python 3.7+ — standard library only, nothing to pip install.
• Network access to a Pulse Server.

Configuration

Connection settings live in pulse_config.py — not committed, and created for you on first run:

import os

URL      = os.environ.get('PULSE_URL')      or 'http://localhost:8099'  # Pulse Server base URL
API_KEY  = os.environ.get('PULSE_API_KEY')  or ''                       # personal API key
USER     = os.environ.get('PULSE_USER')     or ''                       # username (if no API_KEY)
PASSWORD = os.environ.get('PULSE_PASSWORD') or ''                       # password (if no API_KEY)

Authentication precedence: API_KEY is used if set; otherwise USER/PASSWORD; otherwise the call is attempted unauthenticated. Environment variables always override the file values, so you can keep secrets out of the file:

PULSE_URL=https://pulse.example.com PULSE_API_KEY=pulse_xxxxx python3 pulse_sample_app.py

Mint an API key from the Pulse UI under API Keys.

First-run config bootstrap

You don't have to create pulse_config.py by hand. pulse_config_init.py ensures it exists, scaffolding a template with empty credential values if it's missing — this runs automatically at the top of each sample, so a first run creates the file instead of crashing on a missing import. Fill in the generated file (or set the env vars) and run again.

You can also scaffold it explicitly:

python3 pulse_config_init.py

An existing pulse_config.py is never overwritten.

Scripts

File	Description
pulse_api.py	The Pulse client API, ported from pulse.api.js (imported by the samples; not run directly).
pulse_config_init.py	Ensures pulse_config.py exists; can also be run standalone to scaffold it.
pulse_harness.py	Shared plumbing (client, login, console reader, UTF-8 stdout) used by the interactive apps; not run directly.
pulse_sample_app.py	Minimal example: logs in and lists the environments (TM1 servers) served by Pulse.
pulse_interactive_groups.py	Manage security groups (list / view / create / update / delete).
pulse_interactive_users.py	Manage system users (list / view / create / update / delete + membership).
pulse_interactive_environments.py	Manage environments / TM1 servers (list / view / test / create / update / delete / connectivity alert).
pulse_interactive_instances.py	Manage instance settings (list / view / update / request upgrade) per environment.
pulse_interactive_alerts.py	Manage system alerts (list / view / create / update / delete) per environment.
pulse_interactive_packages.py	Migration packages: list / view / execution history / recreate / import.
pulse_interactive_package_create.py	Create Package wizard (detect changes → dependencies → async save + poll).
pulse_interactive_package_execute.py	Execute Package (prepare → compute → run + poll). ⚠ mutates the target TM1.
pulse_interactive_approvals.py	Migration approvals: list / view / submit / approve-deny / archive.

Your connection settings (pulse_config.py) also live here once created; it is not committed.

pulse_sample_app.py

python3 pulse_sample_app.py

Connects using pulse_config.py, prints the server URL and API version, then lists each environment with its status and REST URL. It keeps its own plumbing (rather than using pulse_harness.py) so it reads top-to-bottom as a standalone example.

Interactive apps

Each interactive app is menu-driven, shares the pulse_config.py connection via pulse_harness.py, and maps directly onto one API namespace. Run any of them with python3 <file>:

python3 pulse_interactive_groups.py           # system_groups  — security groups
python3 pulse_interactive_users.py            # system_users   — system users
python3 pulse_interactive_environments.py     # system         — environments (TM1 servers)
python3 pulse_interactive_instances.py        # system         — instance settings
python3 pulse_interactive_alerts.py           # settings       — system alerts
python3 pulse_interactive_packages.py         # packages       — view / import / recreate
python3 pulse_interactive_package_create.py   # packages       — create-package wizard
python3 pulse_interactive_package_execute.py  # packages       — execute a package
python3 pulse_interactive_approvals.py        # packages       — migration approval workflow

Blank input cancels a prompt; 0 (or q / EOF / Ctrl-D) quits. Every app logs out on exit.

The alerts and instances apps target a specific environment — set it from the menu (they default to the first environment the server reports). Executing a package mutates the target TM1 instance, so package_execute gates every run behind an explicit confirmation — test against a disposable environment.

The apps print the same UTF-8 output as their Node.js twins (→, ⚠️, •, …). Node writes UTF-8 regardless of the console code page; Python follows the locale, so pulse_harness.py switches stdout/stderr to UTF-8 — otherwise a Windows cp1252 console raises UnicodeEncodeError mid-print.

Using the client directly

The samples are thin console front-ends; the client is usable on its own:

from pulse_api import PulseApi, PulseApiError

client = PulseApi('https://pulse.example.com')      # base_url='/pulse/' if 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'))

    alerts = client.settings.get_system_alerts(servername='PROD')
    for alert in alerts['alerts']:
        print(alert['id'], alert['alertType'], alert['severity'])
except PulseApiError as e:
    print(e.message, e.status, e.body)
finally:
    client.login.logout()

Payload keys are the server's own JSON, so they stay camelCase (serverName, RESTURL, emailGroupId, ...) exactly as documented.

Anything not wrapped in a namespace method 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)

The paths, query keys and body shapes those take are documented in ../rest-api-public.md — the pure-HTTP reference for the same API, with a runnable Postman version in ../pulse-rest-api-public.postman_collection.json.