Mage Pro offers two main APIs for managing your workflows and infrastructure:
- Mage Cloud API: Used to manage and update your Mage clusters from the Mage Cloud Portal.
- Mage Pro Cluster API: Runs on your Mage Pro cluster and is similar to the Mage OSS API, used to manage pipelines, runs, variables, and other resources.
Mage Cloud API
The Mage Cloud API is a private API used internally by the Mage Cloud Portal to manage Mage Pro clusters. It supports operations such as:
- Starting, stopping, and restarting clusters
- Updating cluster environment variables and configurations
Base URL
https://cloud.mage.ai/api/v1
Authentication
To interact with the Mage Cloud API, you must first authenticate with your Mage Cloud credentials and obtain a session token.
Example: Initialize session and get token
import requests
API_KEY = 'oMqz2m320NfVERFonfytPFVETfPTHyN5N7db9dLK'
BASE_API = 'https://cloud.mage.ai/api/v1'
SESSION_API = f'{BASE_API}/sessions'
def authenticate_session(username: str, password: str) -> requests.Session:
"""
Authenticate with the Mage Cloud API using credentials and return an authorized session.
Args:
username (str): Mage Cloud login email.
password (str): Mage Cloud login password.
Required ENV:
MAGE_CLOUD_API_KEY
Returns:
requests.Session: An authenticated session with token set in cookies.
"""
headers = {
"Content-Type": "application/json",
"X-API-KEY": API_KEY
}
payload = {
"session": {
"email": username,
"password": password
}
}
session = requests.Session()
session.headers = headers
response = session.post(SESSION_API, json=payload)
if response.json().get('error'):
raise ValueError(response.text)
token = response.json()['session']['token']
session.headers['Cookie'] = f'oauth_token={token}'
return session
Start or Stop a Cluster
Once authenticated, you can update the cluster status by modifying the replicaCount and status in the cluster’s config.
Example: Start or Stop a Cluster
def update_cluster_status(session: requests.Session, team_id: str, cluster_id: str, start: bool = True):
"""
Start or stop a Mage Pro cluster by updating replicaCount and status.
Args:
session (requests.Session): Authenticated Mage Cloud session.
team_id (str): Mage Cloud team ID.
cluster_id (str): Cluster ID.
start (bool): Set True to start, False to stop the cluster.
"""
cluster_url = f'{BASE_API}/teams/{team_id}/clusters/{cluster_id}'
response = session.get(cluster_url)
response.raise_for_status()
cluster = response.json()['cluster']
config = cluster.get('config', {})
config['replicaCount'] = 1 if start else 0
cluster['status'] = 'Active' if start else 'Stopped'
update_payload = {
"cluster": {
"config": config,
"status": cluster['status']
}
}
put_response = session.put(cluster_url, json=update_payload)
put_response.raise_for_status()
print(f"Cluster has been {'started' if start else 'stopped'}.")
Example usage
# Pass in credentials from your secret manager or CLI prompt
username = 'your_email@example.com'
password = 'your_password_here'
session = authenticate_session(username, password)
# Start the cluster
update_cluster_status(session, team_id='your_team_id', cluster_id='your_cluster_id', start=True)
# Stop the cluster
# update_cluster_status(session, team_id='your_team_id', cluster_id='your_cluster_id', start=False)
Update Cluster Environment Variables
To add or update environment variables in a Mage Pro cluster, modify the extraEnvs
field in the cluster config.
Example: Update Environment Variables
def update_cluster_env_vars(session, team_id, cluster_id, updates):
"""
Add or update environment variables in a Mage Pro cluster.
Args:
session (requests.Session): Authenticated session with Mage Cloud API.
team_id (str): Mage team ID.
cluster_id (str): Cluster ID.
updates (dict): Dictionary of environment variable key-value pairs to add or update.
"""
cluster_url = f'https://cloud.mage.ai/api/v1/teams/{team_id}/clusters/{cluster_id}'
# Fetch current cluster config
response = session.get(cluster_url)
response.raise_for_status()
cluster = response.json()['cluster']
config = cluster.get('config', {})
# Load existing environment variables
existing_envs = config.get('extraEnvs', [])
env_map = {env['name']: env['value'] for env in existing_envs}
# Apply updates
env_map.update(updates)
# Convert back to list format
config['extraEnvs'] = [{'name': k, 'value': v} for k, v in env_map.items()]
# Build payload and apply update
update_payload = {
"cluster": {
"config": config
}
}
put_response = session.put(cluster_url, json=update_payload)
put_response.raise_for_status()
print("Cluster environment variables updated successfully.")
Example usage
session = authenticate_session(username='your_email@example.com', password='your_password')
update_cluster_env_vars(
session=session,
team_id='your_team_id',
cluster_id='your_cluster_id',
updates={
'AI_SIDEKICK': '1',
'DEFAULT_EXECUTOR_TYPE': 'k8s',
'ENABLE_SOME_FEATURE': 'true'
}
)
Mage Pro cluster API
The Mage Pro Cluster API is the set of HTTP APIs available on your running Mage Pro cluster. It extends the Mage OSS API and allows:
- Create/Get/Update/Delete pipelines/blocks
- Trigger pipelines
- CRUD pipeline schedules/triggers
- CRUD pipeline runs
- CRUD workspaces
- Deploy git commits
- More APIs available in Mage Pro UI
Base URL
https://<your-cluster-hostname>/api
For the full list of cluster API endpoints, see the Mage Open Source API Reference.
Note: Mage Pro may expose additional admin or authentication APIs depending on your deployment and licensing tier.