| Name | mistapi JSON |
| Version |
0.57.2
JSON |
| download |
| home_page | None |
| Summary | Python package to simplify the Mist System APIs usage |
| upload_time | 2025-09-01 16:26:18 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License |
| keywords |
api
juniper
mist
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MISTAPI - Python Package for Mist API
[](https://pypi.org/project/mistapi/)
[](https://pypi.org/project/mistapi/)
[](https://opensource.org/licenses/MIT)
A comprehensive Python package to interact with the Mist Cloud APIs, built from the official [Mist OpenAPI specifications](https://www.juniper.net/documentation/us/en/software/mist/api/http/getting-started/how-to-get-started).
## MIT LICENSE
Copyright (c) 2023 Thomas Munzer
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
## Links
- **Documentation**: [Mist API Documentation](https://doc.mist-lab.fr)
- **Source Code**: [GitHub Repository](https://github.com/tmunzer/mistapi_python)
- **PyPI Package**: [mistapi on PyPI](https://pypi.org/project/mistapi/)
- **Examples**: [Mist Library Examples](https://github.com/tmunzer/mist_library)
- **Bug Reports**: [GitHub Issues](https://github.com/tmunzer/mistapi_python/issues)
## Features
This package provides a complete Python interface to the Mist Cloud APIs:
### Core Features
* **Authentication Management**: Support for API tokens and login/password (with 2FA)
* **Interactive CLI**: Built-in functions for organization and site selection
* **Comprehensive API Coverage**: Auto-generated from OpenAPI specs covering all endpoints
* **HashiCorp Vault Integration**: Secure credential storage support
* **Pagination Support**: Automatic handling of paginated responses
* **Robust Error Handling**: Detailed error responses and logging
* **Proxy Support**: HTTP/HTTPS proxy configuration
### API Coverage
The package includes complete coverage of Mist APIs:
#### Organization Level APIs
* Organizations, Sites, Site Groups, Site Templates
* Devices (APs, Switches, Gateways), Device Profiles, Device Templates
* Network configurations (WLANs, VPNs, Networks, EVPN Topologies)
* User management (Admins, API Tokens, Guests, PSKs)
* Monitoring (Alarms, Events, Insights, Statistics, SLE)
* Assets, Licenses, Subscriptions, Webhooks
* Security (NAC, Policies, Certificates)
* MSP and Multi-tenant management
#### Site Level APIs
* Site-specific device management and configuration
* RF diagnostics and optimization (RRM, Channel Planning)
* Location services (Maps, Zones, Beacons, Asset tracking)
* Client management and analytics
* Synthetic testing and performance monitoring
* Anomaly detection and troubleshooting
#### Constants and Utilities
* Device models, AP channels, Application categories
* Country codes, Alarm definitions, Event types
* Webhook topics, License types, and more
#### Additional Services
* Two-factor authentication, OAuth, Login/Logout
* Account recovery, Registration, Invitations
* Mobile device management, Installer workflows
## Requirements
* Python 3.10 or higher
* Dependencies: `requests`, `python-dotenv`, `tabulate`, `deprecation`, `hvac`
## Installation
Install the package using pip:
```bash
# Linux/macOS
python3 -m pip install mistapi
# Windows
py -m pip install mistapi
# Install with development dependencies (for contributors)
pip install mistapi[dev]
```
## Upgrade
```bash
# Linux/macOS
python3 -m pip install --upgrade mistapi
# Windows
py -m pip install --upgrade mistapi
```
## Configuration
Configuration is optional. All required information can be passed as `APISession` parameters.
However, you can set them in an `.env` file. The location of this file must be provided when calling the `APISession` class with the `env_file` parameter:
```python
import mistapi
apisession = mistapi.APISession(env_file="path/to/the/.env")
```
### Environment Variables
| Variable Name | Type | Default | Comment |
|-----------------------|--------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| MIST_HOST | string | None | The Mist Cloud to use. It must be the "api" one (e.g. `api.mist.com`, `api.eu.mist.com`, ...) |
| MIST_APITOKEN | string | None | The API Token to use. |
| MIST_USER | string | None | The login to use if no API Token is provided (apitoken use is preferred) |
| MIST_PASSWORD | string | None | The password to use if no API Token is provided (apitoken use is preferred) |
| MIST_VAULT_URL | string | https://127.0.0.1:8200 | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, URL of the Vault instance |
| MIST_VAULT_PATH | string | None | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Path to the secret in Vault |
| MIST_VAULT_MOUNT_POINT| string | secret | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Mount point for the secrets engine |
| MIST_VAULT_TOKEN | string | None | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Token for authenticating with Vault |
| CONSOLE_LOG_LEVEL | int | 20 | The minimum log level to display on the console, using `logging` schema (0 = Disabled, 10 = Debug, 20 = Info, 30 = Warning, 40 = Error, 50 = Critical) |
| LOGGING_LOG_LEVEL | int | 10 | The minimum log level to log on the file, using `logging` schema (0 = Disabled, 10 = Debug, 20 = Info, 30 = Warning, 40 = Error, 50 = Critical). This is only used when the script calling `mistapi` is using Python `logging` package and is configured to log to a file |
| HTTPS_PROXY | string | None | Configure the package to use an HTTP/HTTPS proxy (e.g. http://user:password@myproxy.com:3128) |
Example `.env` file:
```bash
MIST_HOST=api.mist.com
MIST_APITOKEN=your_api_token_here
```
## Quick Start
```python
import mistapi
# Initialize session
apisession = mistapi.APISession()
# Authenticate
apisession.login()
# Use the API
device_models = mistapi.api.v1.const.device_models.getDeviceModels(apisession)
print(f"Found {len(device_models.data)} device models")
# Interactive org selection
org_id = mistapi.cli.select_org(apisession)[0]
# Get organization information
org_info = mistapi.api.v1.orgs.orgs.getOrg(apisession, org_id)
print(f"Organization: {org_info.data['name']}")
```
## Usage
Detailed usage examples are available in the [mist_library repository](https://github.com/tmunzer/mist_library).
### 1. Initialize APISession
```python
import mistapi
apisession = mistapi.APISession()
```
This class accepts different parameters, all optionals:
| Parameter Name | Type | Default | Comment |
|-------------------|--------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| email | str | None | used if login/password is used. Can be defined later |
| password | str | None | used if login/password is used. Can be defined later |
| apitoken | str | None | used if API Token is used. Can be defined later |
| host | str | None | Mist Cloud to reach (e.g. "api.mist.com"). Can be defined later |
| vault_url | string | https://127.0.0.1:8200 | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, URL of the Vault instance |
| vault_path | string | None | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Path to the secret in Vault |
| vault_mount_point | string | secret | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Mount point for the secrets engine |
| vault_token | string | None | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Token for authenticating with Vault |
| env_file | str | None | path to the env file to load. See README.md for allowed variables |
| console_log_level | int | 20 | The minimum log level to display on the console, using `logging` schema (0 = Disabled, 10 = Debug, 20 = Info, 30 = Warning, 40 = Error, 50 = Critical) |
| logging_log_level | int | 10 | The minimum log level to log on the file, using `logging` schema (0 = Disabled, 10 = Debug, 20 = Info, 30 = Warning, 40 = Error, 50 = Critical). This is only used when the script calling `mistapi` is using Python `logging` package and is configured to log to a file |
| https_proxy | string | None | Configure the package to use an HTTP/HTTPS proxy (e.g. http://user:password@myproxy.com:3128) |
### 2. Authenticate
The `login()` function must be called to validate authentication:
#### 2.1. Automatic Authentication (with env file)
If the env file contains valid credentials, authentication is automatic:
```python
import mistapi
apisession = mistapi.APISession(env_file="~/.mist_env")
apisession.login()
# Output:
# -------------------------------- Authenticated ---------------------------------
# Welcome Thomas Munzer!
print(apisession.get_authentication_status()) # True
```
#### 2.2. Interactive Authentication
If credentials are missing, the package will prompt for them interactively:
**Cloud Selection:**
If no `host` is configured, you'll be prompted to select a Mist cloud:
```
----------------------------- Mist Cloud Selection -----------------------------
0) APAC 01 (host: api.ac5.mist.com)
1) APAC 03 (host: api.gc7.mist.com)
2) EMEA 01 (host: api.eu.mist.com)
3) EMEA 02 (host: api.gc3.mist.com)
4) EMEA 03 (host: api.ac6.mist.com)
5) EMEA 04 (host: api.gc6.mist.com)
6) Global 01 (host: api.mist.com)
7) Global 02 (host: api.gc1.mist.com)
8) Global 03 (host: api.ac2.mist.com)
9) Global 04 (host: api.gc2.mist.com)
10) Global 05 (host: api.gc4.mist.com)
Select a Cloud (0 to 10, or q to exit):
```
**Authentication:**
If no authentication is configured, you'll be prompted for credentials:
```
--------------------------- Login/Pwd authentication ---------------------------
Login: user@example.com
Password:
[ INFO ] Authentication successful!
Two Factor Authentication code required: 123456
[ INFO ] 2FA authentication succeeded
-------------------------------- Authenticated ---------------------------------
Welcome Thomas Munzer!
```
### 3. Using the APIs
Once authenticated, you can access all Mist API endpoints:
```python
# Get device models (constants)
device_models = mistapi.api.v1.const.device_models.getDeviceModels(apisession)
print(f"Status: {device_models.status_code}")
print(f"URL: {device_models.url}")
print(f"Data: {len(device_models.data)} models")
# Get organization statistics
org_stats = mistapi.api.v1.orgs.stats.getOrgStats(apisession, org_id)
print(f"Organization has {org_stats.data['num_sites']} sites")
# Search for devices
devices = mistapi.api.v1.orgs.devices.searchOrgDevices(apisession, org_id, type="ap")
print(f"Found {len(devices.data['results'])} access points")
```
```
## CLI Helper Functions
The package includes helpful CLI functions for interactive use:
### Organization Selection
```python
# Select single organization
org_ids = mistapi.cli.select_org(apisession)
print(f"Selected org: {org_ids[0]}")
# Select multiple organizations
org_ids = mistapi.cli.select_org(apisession, allow_many=True)
print(f"Selected {len(org_ids)} organizations")
```
Output:
```
Available organizations:
0) Acme Corp (id: 203d3d02-xxxx-xxxx-xxxx-76896a3330f4)
1) Demo Lab (id: 6374a757-xxxx-xxxx-xxxx-361e45b2d4ac)
...
Select an Org (0 to 2, or q to exit): 0
```
### Site Selection
```python
# Select site within an organization
site_ids = mistapi.cli.select_site(apisession, org_id="203d3d02-xxxx-xxxx-xxxx-76896a3330f4")
print(f"Selected site: {site_ids[0]}")
```
Output:
```
Available sites:
0) Headquarters (id: f5fcbee5-xxxx-xxxx-xxxx-1619ede87879)
1) Branch Office (id: a8b2c3d4-xxxx-xxxx-xxxx-987654321abc)
...
Select a Site (0 to 1, or q to exit): 0
```
## Pagination Support
For APIs that return paginated results, the package provides convenient methods:
### Get Next Page
```python
# Get first page
response = mistapi.api.v1.orgs.clients.searchOrgClientsEvents(apisession, org_id, duration="1d")
print(f"First page: {len(response.data['results'])} results")
print(f"Next page URL: {response.next}")
# Get next page
response_2 = mistapi.get_next(apisession, response)
print(f"Second page: {len(response_2.data['results'])} results")
```
### Get All Pages
```python
# Get all pages automatically
response = mistapi.api.v1.orgs.clients.searchOrgClientsEvents(apisession, org_id, duration="1d")
print(f"First page: {len(response.data['results'])} results")
all_data = mistapi.get_all(apisession, response)
print(f"Total results across all pages: {len(all_data)}")
```
## API Help and Documentation
Get help on any API function:
```python
help(mistapi.api.v1.orgs.stats.getOrgStats)
```
This displays detailed information about parameters, return values, and usage examples.
## Error Handling
The package provides structured error handling:
```python
try:
org_info = mistapi.api.v1.orgs.orgs.getOrg(apisession, "invalid-org-id")
except Exception as e:
print(f"API Error: {e}")
# Check response status
response = mistapi.api.v1.orgs.orgs.listOrgs(apisession)
if response.status_code == 200:
print(f"Success: {len(response.data)} organizations")
else:
print(f"Error {response.status_code}: {response.data}")
```
## Development and Testing
For contributors and advanced users:
### Development Setup
```bash
# Clone the repository
git clone https://github.com/tmunzer/mistapi_python.git
cd mistapi_python
# Install with development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run tests with coverage
pytest --cov=src/mistapi --cov-report=html
# Run linting
ruff check src/
```
### Package Structure
```
src/mistapi/
├── __init__.py # Main package exports
├── __api_session.py # Session management and authentication
├── __api_request.py # HTTP request handling
├── __api_response.py # Response parsing and pagination
├── __logger.py # Logging configuration
├── __pagination.py # Pagination utilities
├── cli.py # Interactive CLI functions
├── __models/ # Data models (privileges, etc.)
└── api/v1/ # Auto-generated API endpoints
├── const/ # Constants and enums
├── orgs/ # Organization-level APIs
├── sites/ # Site-level APIs
├── login/ # Authentication APIs
└── utils/ # Utility functions
```
## Supported Mist Clouds
The package supports all Mist cloud instances:
- **APAC 01**: api.ac5.mist.com
- **APAC 03**: api.gc7.mist.com
- **EMEA 01**: api.eu.mist.com
- **EMEA 02**: api.gc3.mist.com
- **EMEA 03**: api.ac6.mist.com
- **EMEA 04**: api.gc6.mist.com
- **Global 01**: api.mist.com
- **Global 02**: api.gc1.mist.com
- **Global 03**: api.ac2.mist.com
- **Global 04**: api.gc2.mist.com
- **Global 05**: api.gc4.mist.com
## Examples and Use Cases
### Device Management
```python
# List all devices in an organization
devices = mistapi.api.v1.orgs.devices.listOrgDevices(apisession, org_id)
# Get specific device details
device = mistapi.api.v1.orgs.devices.getOrgDevice(apisession, org_id, device_id)
# Update device configuration
update_data = {"name": "New Device Name"}
result = mistapi.api.v1.orgs.devices.updateOrgDevice(apisession, org_id, device_id, body=update_data)
```
### Site Management
```python
# Create a new site
site_data = {
"name": "New Branch Office",
"country_code": "US",
"timezone": "America/New_York"
}
new_site = mistapi.api.v1.orgs.sites.createOrgSite(apisession, org_id, body=site_data)
# Get site statistics
site_stats = mistapi.api.v1.sites.stats.getSiteStats(apisession, site_id)
```
### Client Analytics
```python
# Search for wireless clients
clients = mistapi.api.v1.orgs.clients.searchOrgWirelessClients(
apisession, org_id,
duration="1d",
limit=100
)
# Get client events
events = mistapi.api.v1.orgs.clients.searchOrgClientsEvents(
apisession, org_id,
duration="1h",
client_mac="aa:bb:cc:dd:ee:ff"
)
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
### Guidelines
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
Raw data
{
"_id": null,
"home_page": null,
"name": "mistapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "API, Juniper, Mist",
"author": null,
"author_email": "Thomas Munzer <tmunzer@juniper.net>",
"download_url": "https://files.pythonhosted.org/packages/f2/47/75bb054dc8e42dff901b361603993297d5618d2581f3e370b66553980d56/mistapi-0.57.2.tar.gz",
"platform": null,
"description": "# MISTAPI - Python Package for Mist API\n\n[](https://pypi.org/project/mistapi/)\n[](https://pypi.org/project/mistapi/)\n[](https://opensource.org/licenses/MIT)\n\nA comprehensive Python package to interact with the Mist Cloud APIs, built from the official [Mist OpenAPI specifications](https://www.juniper.net/documentation/us/en/software/mist/api/http/getting-started/how-to-get-started).\n\n## MIT LICENSE\n\nCopyright (c) 2023 Thomas Munzer\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n\n## Links\n\n- **Documentation**: [Mist API Documentation](https://doc.mist-lab.fr)\n- **Source Code**: [GitHub Repository](https://github.com/tmunzer/mistapi_python)\n- **PyPI Package**: [mistapi on PyPI](https://pypi.org/project/mistapi/)\n- **Examples**: [Mist Library Examples](https://github.com/tmunzer/mist_library)\n- **Bug Reports**: [GitHub Issues](https://github.com/tmunzer/mistapi_python/issues)\n\n\n## Features\n\nThis package provides a complete Python interface to the Mist Cloud APIs:\n\n### Core Features\n* **Authentication Management**: Support for API tokens and login/password (with 2FA)\n* **Interactive CLI**: Built-in functions for organization and site selection\n* **Comprehensive API Coverage**: Auto-generated from OpenAPI specs covering all endpoints\n* **HashiCorp Vault Integration**: Secure credential storage support\n* **Pagination Support**: Automatic handling of paginated responses\n* **Robust Error Handling**: Detailed error responses and logging\n* **Proxy Support**: HTTP/HTTPS proxy configuration\n\n### API Coverage\nThe package includes complete coverage of Mist APIs:\n\n#### Organization Level APIs\n* Organizations, Sites, Site Groups, Site Templates\n* Devices (APs, Switches, Gateways), Device Profiles, Device Templates\n* Network configurations (WLANs, VPNs, Networks, EVPN Topologies)\n* User management (Admins, API Tokens, Guests, PSKs)\n* Monitoring (Alarms, Events, Insights, Statistics, SLE)\n* Assets, Licenses, Subscriptions, Webhooks\n* Security (NAC, Policies, Certificates)\n* MSP and Multi-tenant management\n\n#### Site Level APIs \n* Site-specific device management and configuration\n* RF diagnostics and optimization (RRM, Channel Planning)\n* Location services (Maps, Zones, Beacons, Asset tracking)\n* Client management and analytics\n* Synthetic testing and performance monitoring\n* Anomaly detection and troubleshooting\n\n#### Constants and Utilities\n* Device models, AP channels, Application categories\n* Country codes, Alarm definitions, Event types\n* Webhook topics, License types, and more\n\n#### Additional Services\n* Two-factor authentication, OAuth, Login/Logout\n* Account recovery, Registration, Invitations\n* Mobile device management, Installer workflows\n\n## Requirements\n\n* Python 3.10 or higher\n* Dependencies: `requests`, `python-dotenv`, `tabulate`, `deprecation`, `hvac`\n\n## Installation\n\nInstall the package using pip:\n\n```bash\n# Linux/macOS\npython3 -m pip install mistapi\n\n# Windows\npy -m pip install mistapi\n\n# Install with development dependencies (for contributors)\npip install mistapi[dev]\n```\n\n## Upgrade\n\n```bash\n# Linux/macOS\npython3 -m pip install --upgrade mistapi\n\n# Windows\npy -m pip install --upgrade mistapi\n```\n\n## Configuration\n\nConfiguration is optional. All required information can be passed as `APISession` parameters.\nHowever, you can set them in an `.env` file. The location of this file must be provided when calling the `APISession` class with the `env_file` parameter:\n\n```python\nimport mistapi\napisession = mistapi.APISession(env_file=\"path/to/the/.env\")\n```\n\n### Environment Variables\n| Variable Name | Type | Default | Comment |\n|-----------------------|--------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| MIST_HOST | string | None | The Mist Cloud to use. It must be the \"api\" one (e.g. `api.mist.com`, `api.eu.mist.com`, ...) |\n| MIST_APITOKEN | string | None | The API Token to use. |\n| MIST_USER | string | None | The login to use if no API Token is provided (apitoken use is preferred) |\n| MIST_PASSWORD | string | None | The password to use if no API Token is provided (apitoken use is preferred) |\n| MIST_VAULT_URL | string | https://127.0.0.1:8200 | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, URL of the Vault instance |\n| MIST_VAULT_PATH | string | None | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Path to the secret in Vault |\n| MIST_VAULT_MOUNT_POINT| string | secret | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Mount point for the secrets engine |\n| MIST_VAULT_TOKEN | string | None | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Token for authenticating with Vault |\n| CONSOLE_LOG_LEVEL | int | 20 | The minimum log level to display on the console, using `logging` schema (0 = Disabled, 10 = Debug, 20 = Info, 30 = Warning, 40 = Error, 50 = Critical) |\n| LOGGING_LOG_LEVEL | int | 10 | The minimum log level to log on the file, using `logging` schema (0 = Disabled, 10 = Debug, 20 = Info, 30 = Warning, 40 = Error, 50 = Critical). This is only used when the script calling `mistapi` is using Python `logging` package and is configured to log to a file |\n| HTTPS_PROXY | string | None | Configure the package to use an HTTP/HTTPS proxy (e.g. http://user:password@myproxy.com:3128) |\n\nExample `.env` file:\n```bash\nMIST_HOST=api.mist.com\nMIST_APITOKEN=your_api_token_here\n```\n\n## Quick Start\n\n```python\nimport mistapi\n\n# Initialize session\napisession = mistapi.APISession()\n\n# Authenticate\napisession.login()\n\n# Use the API\ndevice_models = mistapi.api.v1.const.device_models.getDeviceModels(apisession)\nprint(f\"Found {len(device_models.data)} device models\")\n\n# Interactive org selection\norg_id = mistapi.cli.select_org(apisession)[0]\n\n# Get organization information \norg_info = mistapi.api.v1.orgs.orgs.getOrg(apisession, org_id)\nprint(f\"Organization: {org_info.data['name']}\")\n```\n\n## Usage\n\nDetailed usage examples are available in the [mist_library repository](https://github.com/tmunzer/mist_library).\n\n### 1. Initialize APISession\n\n```python\nimport mistapi\napisession = mistapi.APISession()\n```\nThis class accepts different parameters, all optionals:\n\n| Parameter Name | Type | Default | Comment |\n|-------------------|--------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| email | str | None | used if login/password is used. Can be defined later |\n| password | str | None | used if login/password is used. Can be defined later |\n| apitoken | str | None | used if API Token is used. Can be defined later |\n| host | str | None | Mist Cloud to reach (e.g. \"api.mist.com\"). Can be defined later |\n| vault_url | string | https://127.0.0.1:8200 | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, URL of the Vault instance |\n| vault_path | string | None | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Path to the secret in Vault |\n| vault_mount_point | string | secret | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Mount point for the secrets engine |\n| vault_token | string | None | If the Mist MIST_HOST, MIST_APITOKEN, MIST_USER, MIST_PASSWORD are stored in an HashiCorp Vault, Token for authenticating with Vault |\n| env_file | str | None | path to the env file to load. See README.md for allowed variables |\n| console_log_level | int | 20 | The minimum log level to display on the console, using `logging` schema (0 = Disabled, 10 = Debug, 20 = Info, 30 = Warning, 40 = Error, 50 = Critical) |\n| logging_log_level | int | 10 | The minimum log level to log on the file, using `logging` schema (0 = Disabled, 10 = Debug, 20 = Info, 30 = Warning, 40 = Error, 50 = Critical). This is only used when the script calling `mistapi` is using Python `logging` package and is configured to log to a file |\n| https_proxy | string | None | Configure the package to use an HTTP/HTTPS proxy (e.g. http://user:password@myproxy.com:3128) |\n\n### 2. Authenticate\n\nThe `login()` function must be called to validate authentication:\n\n#### 2.1. Automatic Authentication (with env file)\n\nIf the env file contains valid credentials, authentication is automatic:\n\n```python\nimport mistapi\napisession = mistapi.APISession(env_file=\"~/.mist_env\")\napisession.login()\n\n# Output:\n# -------------------------------- Authenticated ---------------------------------\n# Welcome Thomas Munzer!\n\nprint(apisession.get_authentication_status()) # True\n```\n\n#### 2.2. Interactive Authentication\n\nIf credentials are missing, the package will prompt for them interactively:\n\n**Cloud Selection:**\nIf no `host` is configured, you'll be prompted to select a Mist cloud:\n\n```\n----------------------------- Mist Cloud Selection -----------------------------\n\n0) APAC 01 (host: api.ac5.mist.com)\n1) APAC 03 (host: api.gc7.mist.com) \n2) EMEA 01 (host: api.eu.mist.com)\n3) EMEA 02 (host: api.gc3.mist.com)\n4) EMEA 03 (host: api.ac6.mist.com)\n5) EMEA 04 (host: api.gc6.mist.com)\n6) Global 01 (host: api.mist.com)\n7) Global 02 (host: api.gc1.mist.com)\n8) Global 03 (host: api.ac2.mist.com)\n9) Global 04 (host: api.gc2.mist.com)\n10) Global 05 (host: api.gc4.mist.com)\n\nSelect a Cloud (0 to 10, or q to exit):\n```\n\n**Authentication:**\nIf no authentication is configured, you'll be prompted for credentials:\n\n```\n--------------------------- Login/Pwd authentication ---------------------------\n\nLogin: user@example.com\nPassword: \n[ INFO ] Authentication successful!\n\nTwo Factor Authentication code required: 123456\n[ INFO ] 2FA authentication succeeded\n\n-------------------------------- Authenticated ---------------------------------\n\nWelcome Thomas Munzer!\n```\n\n### 3. Using the APIs\n\nOnce authenticated, you can access all Mist API endpoints:\n\n```python\n# Get device models (constants)\ndevice_models = mistapi.api.v1.const.device_models.getDeviceModels(apisession)\nprint(f\"Status: {device_models.status_code}\")\nprint(f\"URL: {device_models.url}\")\nprint(f\"Data: {len(device_models.data)} models\")\n\n# Get organization statistics\norg_stats = mistapi.api.v1.orgs.stats.getOrgStats(apisession, org_id)\nprint(f\"Organization has {org_stats.data['num_sites']} sites\")\n\n# Search for devices\ndevices = mistapi.api.v1.orgs.devices.searchOrgDevices(apisession, org_id, type=\"ap\")\nprint(f\"Found {len(devices.data['results'])} access points\")\n```\n```\n\n## CLI Helper Functions\n\nThe package includes helpful CLI functions for interactive use:\n\n### Organization Selection\n\n```python\n# Select single organization\norg_ids = mistapi.cli.select_org(apisession)\nprint(f\"Selected org: {org_ids[0]}\")\n\n# Select multiple organizations\norg_ids = mistapi.cli.select_org(apisession, allow_many=True)\nprint(f\"Selected {len(org_ids)} organizations\")\n```\n\nOutput:\n```\nAvailable organizations:\n0) Acme Corp (id: 203d3d02-xxxx-xxxx-xxxx-76896a3330f4)\n1) Demo Lab (id: 6374a757-xxxx-xxxx-xxxx-361e45b2d4ac)\n...\n\nSelect an Org (0 to 2, or q to exit): 0\n```\n\n### Site Selection \n\n```python\n# Select site within an organization\nsite_ids = mistapi.cli.select_site(apisession, org_id=\"203d3d02-xxxx-xxxx-xxxx-76896a3330f4\")\nprint(f\"Selected site: {site_ids[0]}\")\n```\n\nOutput:\n```\nAvailable sites:\n0) Headquarters (id: f5fcbee5-xxxx-xxxx-xxxx-1619ede87879)\n1) Branch Office (id: a8b2c3d4-xxxx-xxxx-xxxx-987654321abc)\n...\n\nSelect a Site (0 to 1, or q to exit): 0\n```\n\n## Pagination Support\n\nFor APIs that return paginated results, the package provides convenient methods:\n\n### Get Next Page\n\n```python\n# Get first page\nresponse = mistapi.api.v1.orgs.clients.searchOrgClientsEvents(apisession, org_id, duration=\"1d\")\nprint(f\"First page: {len(response.data['results'])} results\")\nprint(f\"Next page URL: {response.next}\")\n\n# Get next page\nresponse_2 = mistapi.get_next(apisession, response)\nprint(f\"Second page: {len(response_2.data['results'])} results\")\n```\n\n### Get All Pages\n\n```python\n# Get all pages automatically\nresponse = mistapi.api.v1.orgs.clients.searchOrgClientsEvents(apisession, org_id, duration=\"1d\")\nprint(f\"First page: {len(response.data['results'])} results\")\n\nall_data = mistapi.get_all(apisession, response)\nprint(f\"Total results across all pages: {len(all_data)}\")\n```\n\n## API Help and Documentation\n\nGet help on any API function:\n\n```python\nhelp(mistapi.api.v1.orgs.stats.getOrgStats)\n```\n\nThis displays detailed information about parameters, return values, and usage examples.\n\n## Error Handling\n\nThe package provides structured error handling:\n\n```python\ntry:\n org_info = mistapi.api.v1.orgs.orgs.getOrg(apisession, \"invalid-org-id\")\nexcept Exception as e:\n print(f\"API Error: {e}\")\n \n# Check response status\nresponse = mistapi.api.v1.orgs.orgs.listOrgs(apisession)\nif response.status_code == 200:\n print(f\"Success: {len(response.data)} organizations\")\nelse:\n print(f\"Error {response.status_code}: {response.data}\")\n```\n\n## Development and Testing\n\nFor contributors and advanced users:\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/tmunzer/mistapi_python.git\ncd mistapi_python\n\n# Install with development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=src/mistapi --cov-report=html\n\n# Run linting\nruff check src/\n```\n\n### Package Structure\n\n```\nsrc/mistapi/\n\u251c\u2500\u2500 __init__.py # Main package exports\n\u251c\u2500\u2500 __api_session.py # Session management and authentication \n\u251c\u2500\u2500 __api_request.py # HTTP request handling\n\u251c\u2500\u2500 __api_response.py # Response parsing and pagination\n\u251c\u2500\u2500 __logger.py # Logging configuration\n\u251c\u2500\u2500 __pagination.py # Pagination utilities\n\u251c\u2500\u2500 cli.py # Interactive CLI functions\n\u251c\u2500\u2500 __models/ # Data models (privileges, etc.)\n\u2514\u2500\u2500 api/v1/ # Auto-generated API endpoints\n \u251c\u2500\u2500 const/ # Constants and enums\n \u251c\u2500\u2500 orgs/ # Organization-level APIs\n \u251c\u2500\u2500 sites/ # Site-level APIs \n \u251c\u2500\u2500 login/ # Authentication APIs\n \u2514\u2500\u2500 utils/ # Utility functions\n```\n\n## Supported Mist Clouds\n\nThe package supports all Mist cloud instances:\n\n- **APAC 01**: api.ac5.mist.com\n- **APAC 03**: api.gc7.mist.com \n- **EMEA 01**: api.eu.mist.com\n- **EMEA 02**: api.gc3.mist.com\n- **EMEA 03**: api.ac6.mist.com\n- **EMEA 04**: api.gc6.mist.com\n- **Global 01**: api.mist.com\n- **Global 02**: api.gc1.mist.com\n- **Global 03**: api.ac2.mist.com\n- **Global 04**: api.gc2.mist.com\n- **Global 05**: api.gc4.mist.com\n\n## Examples and Use Cases\n\n### Device Management\n\n```python\n# List all devices in an organization\ndevices = mistapi.api.v1.orgs.devices.listOrgDevices(apisession, org_id)\n\n# Get specific device details\ndevice = mistapi.api.v1.orgs.devices.getOrgDevice(apisession, org_id, device_id)\n\n# Update device configuration\nupdate_data = {\"name\": \"New Device Name\"}\nresult = mistapi.api.v1.orgs.devices.updateOrgDevice(apisession, org_id, device_id, body=update_data)\n```\n\n### Site Management\n\n```python\n# Create a new site\nsite_data = {\n \"name\": \"New Branch Office\",\n \"country_code\": \"US\",\n \"timezone\": \"America/New_York\"\n}\nnew_site = mistapi.api.v1.orgs.sites.createOrgSite(apisession, org_id, body=site_data)\n\n# Get site statistics\nsite_stats = mistapi.api.v1.sites.stats.getSiteStats(apisession, site_id)\n```\n\n### Client Analytics\n\n```python\n# Search for wireless clients\nclients = mistapi.api.v1.orgs.clients.searchOrgWirelessClients(\n apisession, org_id, \n duration=\"1d\",\n limit=100\n)\n\n# Get client events\nevents = mistapi.api.v1.orgs.clients.searchOrgClientsEvents(\n apisession, org_id,\n duration=\"1h\",\n client_mac=\"aa:bb:cc:dd:ee:ff\"\n)\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n### Guidelines\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`) \n5. Open a Pull Request\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Python package to simplify the Mist System APIs usage",
"version": "0.57.2",
"project_urls": {
"Bug Tracker": "https://github.com/tmunzer/mistapi_python/issues",
"Source": "https://github.com/tmunzer/mistapi_python"
},
"split_keywords": [
"api",
" juniper",
" mist"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fa727f4f5ac38b6d9ebcf54f1064f1101a08aee5c1749d8c7ac713d8fa996f01",
"md5": "26c35007fc9e5bff2bec97254b2c128f",
"sha256": "f23f8b7739873c1f640ecb13c1119f9c24b72a14af63aac17a568e0688a67460"
},
"downloads": -1,
"filename": "mistapi-0.57.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "26c35007fc9e5bff2bec97254b2c128f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 256411,
"upload_time": "2025-09-01T16:26:15",
"upload_time_iso_8601": "2025-09-01T16:26:15.822799Z",
"url": "https://files.pythonhosted.org/packages/fa/72/7f4f5ac38b6d9ebcf54f1064f1101a08aee5c1749d8c7ac713d8fa996f01/mistapi-0.57.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f24775bb054dc8e42dff901b361603993297d5618d2581f3e370b66553980d56",
"md5": "8266de26bb1bffc9ba8aa4ca6f5a3507",
"sha256": "a5cd871d24ac1a70c2cb83dd0ec6442a189431ce5520aef4ab53b8b1d8f6399d"
},
"downloads": -1,
"filename": "mistapi-0.57.2.tar.gz",
"has_sig": false,
"md5_digest": "8266de26bb1bffc9ba8aa4ca6f5a3507",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 4718788,
"upload_time": "2025-09-01T16:26:18",
"upload_time_iso_8601": "2025-09-01T16:26:18.923903Z",
"url": "https://files.pythonhosted.org/packages/f2/47/75bb054dc8e42dff901b361603993297d5618d2581f3e370b66553980d56/mistapi-0.57.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 16:26:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tmunzer",
"github_project": "mistapi_python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mistapi"
}
