Skip to main content
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.
⌘I