BorealHost Python SDK

Python SDK for the BorealHost.ai REST API.

BorealHost is an agent-native Quebec-based web hosting platform. This SDK wraps the full public REST API (/api/v1/*) — purchase hosting, deploy sites, manage DNS, register domains, run SSH commands, and scale infrastructure.

Install

pip install borealhost-sdk

0.5.3 release notes

Backup downloads now wait when the API returns 202 Accepted while preparing an export. download_backup() follows Retry-After for up to 30 minutes by default; use max_wait to change the timeout and on_wait to report progress. Only an exact HTTP 200 is accepted as the archive. Completed downloads replace the destination atomically from a private sibling temporary file (mode 0600 on Unix), so redirects, refusals, timeouts, and interrupted transfers leave an existing file unchanged and do not leave a new destination behind. Upgrade older clients before downloading backups: versions through 0.5.2 can save the pending JSON response instead of the archive.

Usage

from borealhost_sdk import Client

client = Client(api_key="bh_...")

# List plans (no auth needed)
plans = client.list_plans()

# Manage sites
sites = client.list_sites()
status = client.get_site("my-site")
client.deploy("my-site")

# DNS
client.add_domain_dns("example.com", record_type="A", value="1.2.3.4", subdomain="www")

Authentication

API keys are in the format bh_<48 hex chars>.

# Pass at construction
client = Client(api_key="bh_...")

# Or via environment variable
# export BOREALHOST_API_KEY="bh_..."
client = Client()

# Or set later
client = Client()
client.set_api_key("bh_...")

Custom base URL

client = Client(api_key="bh_...", base_url="https://staging.borealhost.ai")

Errors

All errors from the API raise ApiError:

from borealhost_sdk import Client, ApiError

try:
    client.deploy("unknown-site")
except ApiError as e:
    print(e.code)     # "NOT_FOUND"
    print(e.message)  # "Site 'unknown-site' not found"

Related packages

• borealhost — command-line tool (bh)
• borealhost-mcp — MCP server for AI agents

Links

• API docs: https://borealhost.ai/api/v1/docs/
• Homepage: https://borealhost.ai