2.VS Code asks you to confirm the server before it starts.
Needs: BOREALHOST_API_KEY
Pinned to v0.4.2 · cf06f10e844f
Tools it offers
As the server describes them. This text comes from the publisher and is shown as-is.
set_api_key
Set your BorealHost API key for this session.
Call this if you already have an API key (from checkout completion,
the BorealHost panel, or a container claim). All subsequent tool calls
will use this key for authentication.
Args:
api_key: Your BorealHost API key (format: bh_<48 hex chars>)
Returns:
{"success": true, "message": "API key set for this session",
"key_prefix": "bh_..."}
whoami
Check the current API key's account info, scopes, and site count.
Requires: BOREALHOST_API_KEY env var (read scope).
Returns:
{"user": {"id": "uuid", "email": "...", "date_joined": "iso8601"},
"api_key": {"id": "uuid", "name": "...", "prefix": "bh_...",
"scopes": ["read", "write"], "created_at": "iso8601"},
"account": {"sites": 2, "active_subscriptions": 1}}
Errors:
UNAUTHORIZED: Missing or invalid API key
request_api_key
Request an API key for a site YOU ARE RUNNING ON (challenge-response).
⚠ ONLY USE THIS IF YOU ARE EXECUTING INSIDE THAT SITE'S OWN CONTAINER. If
you bought or ordered the site from somewhere else, this is the wrong tool:
it returns "pending" and the pending never resolves, because the proof it
asks for is a file you cannot reach. Use `get_checkout_status(checkout_id)`
on the checkout that paid for the site — that hands over the site-scoped key
over plain HTTP with no container access. The refusal and the pending
response both name it under `alternative` when one is available.
Two-step verification flow:
1. A claim token is written into that site's container, at the per-site path
the response gives you in `claim_path` (mode 600, owner admin — readable
only from on the container). Do not hardcode the path.
2. Read that file and call claim_api_key(token) within 1 hour
Refused for sites on SHARED containers. One container there serves up to 40
customers behind one agent, so reading a file proves you are on the machine,
not which customer you are — the token would authenticate the wrong thing.
No authentication needed — the proof is reading the file from the container.
Args:
site_slug: The site identifier (your BorealHost site slug)
Returns:
{"status": "pending", "site_slug": "my-site", "expires_in_seconds": 3600,
"claim_path": "/home/admin/.borealhost/.claim_token_my-site",
"requires_container_access": true,
"instructions": "Read the claim token and call claim_api_key()...",
"alternative": {"checkout_id": "...", "command": "bh checkout status ..."}}
Errors:
VALIDATION_ERROR: Unknown site slug, no active subscription, shared
container, or a key already exists (rotate it, never revoke it to
reach this route). Carries `alternative` when another route works.
RATE_LIMITED: Too many pending claim tokens
Versions
v0.4.2· Sep 6, 2026
Signals
Installs through us
0
Agent reports
none yet
Publisher
ai.borealhost · unclaimed
Found via
registry
critical
tool:list_files.description
criticalPairs a secret with an instruction to send data.tool:upload_file.description
criticalPairs a secret with an instruction to send data.tool:create_directory.description
criticalPairs a secret with an instruction to send data.tool:create_alert_rule.description
criticalPairs a secret with an instruction to send data.tool:add_port_forward.description
criticalPairs a secret with an instruction to send data.tool:remove_port_forward.description
criticalPairs a secret with an instruction to send data.tool:register_domain.description
criticalPairs a secret with an instruction to send data.tool:get_site_nginx_snippet.description
criticalPairs a secret with an instruction to send data.tool:set_site_nginx_snippet.description
criticalPairs a secret with an instruction to send data.tool:set_domain_usage.description
criticalPairs a secret with an instruction to send data.tool:resend_registrant_verification.description
criticalPairs a secret with an instruction to send data.tool:list_compute_types.description
criticalPairs a secret with an instruction to send data.tool:snapshot_compute_volume.description
criticalPairs a secret with an instruction to send data.tool:container_action.description
criticalPairs a secret with an instruction to send data.tool:create_webhook.description
criticalPairs a secret with an instruction to send data.tool:test_webhook.description
criticalPairs a secret with an instruction to send data.tool:enable_smtp_relay.description
claim_api_key
Claim an API key using a claim token from the container.
After calling request_api_key(), read the claim token from the path that
call returned in `claim_path`, on that site's container, and pass it here.
The token is single-use — once claimed, it cannot be used again.
The API key is automatically activated for this MCP session.
Args:
claim_token: The claim token string read from the container file
Returns:
{"api_key": "bh_...", "key_prefix": "bh_...",
"site_slug": "my-site", "scopes": ["read", "write"],
"message": "API key created and activated..."}
Errors:
VALIDATION_ERROR: Invalid, expired, or already-claimed token
list_plans
List available hosting plans with pricing and resources.
No authentication needed.
Args:
track: Filter by plan track. Valid values: "single_site", "agency".
⚠ The track is not the site count — most plans on BOTH tracks
include several sites (site_starter 5, site_plus 8, site_pro 12).
Read `max_sites` on the plan, and use add_site() to fill a slot.
Leave empty to list all tracks.
include_deprecated: Include deprecated plans (default: false)
Returns:
[{"slug": "site_starter", "name": "Starter", "track": "single_site",
"hosting_type": "shared", "price": {"monthly": 5, "annual": 2, "currency": "CAD"},
"resources": null, "features": {"max_sites": 1, "ai_modules": [...],
"ai_agents": [], "free_domain_annual": false}}, ...]
create_checkout
Start a new checkout session to purchase a hosting plan.
No authentication needed. After creating, call update_checkout to set
buyer info, then complete_checkout to pay.
The response carries a `checkout_secret`, returned ONCE, that every later
step of this checkout requires. It is held in memory for this MCP session
and sent automatically — but it is gone if the server restarts. If a session
key is set, the checkout is owned by that account and the API key authorizes
the later steps on its own, which is the durable path.
Args:
sku: Plan SKU in format bh_{plan_slug}_{monthly|annual}.
Examples: "bh_site_starter_monthly", "bh_site_pro_annual",
"bh_site_managed_monthly", "bh_site_business_annual".
Call list_plans() to discover all available plan slugs.
Returns:
{"id": "uuid", "sku": "bh_site_starter_monthly",
"plan_slug": "site_starter", "billing_period": "monthly",
"status": "not_ready", "buyer_email": "", "requested_slug": "",
"created_at": "iso8601", "checkout_secret": "base64-token"}
Errors:
VALIDATION_ERROR: Invalid SKU format or unknown plan
RATE_LIMITED: Max 10 checkouts per IP per hour
update_checkout
Set buyer email and desired site slug on a checkout session.
The checkout must be in "not_ready" status. Setting requested_slug
transitions status to "ready" (required before completing).
Args:
checkout_id: Checkout session ID from create_checkout
buyer_email: Optional email — if omitted, a synthetic agent identity
(agent-{uuid}@api.borealhost.ai) is created at completion
requested_slug: Desired site identifier. Must be 3-50 chars, lowercase
alphanumeric + hyphens, cannot start/end with hyphen.
Must be globally unique.
site_type: What the docroot should serve — wordpress (default), php,
php-nodb or static-site. ⚠ Set it HERE: the checkout locks once
buyer info is set, so choosing later means provisioning a
WordPress you then convert away from, abandoning its tree in the
docroot and paying a minute of provisioning for nothing.
Returns:
{"id": "uuid", "sku": "...", "plan_slug": "...",
"billing_period": "monthly", "status": "ready",
"buyer_email": "...", "requested_slug": "my-site",
"created_at": "iso8601"}
Errors:
VALIDATION_ERROR: Invalid slug format or slug already taken
FORBIDDEN: Missing checkout_secret
NOT_FOUND: Unknown checkout_id
complete_checkout
Complete checkout with payment and start site provisioning.
The checkout must be in "ready" status.
Two payment methods:
- "stripe_checkout" (default): Returns a short, chat-safe payment URL.
**Present `payment_url` to the human — NOT `stripe_checkout_url`.**
The raw Stripe URL has a required `#fragment` that chat UIs routinely
strip when rendering markdown links, which causes Stripe to show
"page not found". `payment_url` is a short BorealHost redirect that
preserves the fragment via HTTP 302. After paying, the human lands on a
confirmation page (`confirmation_url`) — not on raw JSON. Then poll
get_checkout_status() until status becomes "completed". The API key
appears in the first poll after payment (shown once, then cleared).
Payment provisions the site; nothing else has to be called to create it.
- "stripe_payment_method": Charges a Stripe PaymentMethod directly.
Requires payment_method_id. On success, returns the API key immediately.
Args:
checkout_id: Checkout session ID
payment_method: "stripe_checkout" (returns a payment_url for a human),
"stripe_payment_method" (card on file), or "wallet" — pay from the
account's prepaid balance against THIS key's allowance. Check
get_wallet() first: `spendable_cents` is what you may actually
spend, and a wallet payment is refused for plans that order
dedicated hardware, which are authorised against a verified card
payment instead.
payment_method_id: Stripe PaymentMethod ID (pm_...). Required only
for "stripe_payment_method".
Returns (stripe_checkout):
{"id": "uuid", "status": "awaiting_payment",
"payment_url": "https://borealhost.ai/pay/<id>/?s=<secret>",
"confirmation_url": "https://borealhost.ai/pay/<id>/confirmation/?s=...",
"stripe_checkout_url": "https://checkout.stripe.com/c/pay/...",
"message": "Present payment_url to the human..."}
Returns (stripe_payment_method):
{"id": "uuid", "status": "completed", "api_key": "bh_...",
"api_key_message": "Store this API key securely...",
"subscription_id": "uuid", "provisioning_job_id": "uuid"}
Errors:
VALIDATION_ERROR: Missing payment_method_id for stripe_payment_method
FORBIDDEN: Checkout not in "ready" status
get_checkout_status
Poll a checkout session for status updates.
Call this after complete_checkout to track payment and provisioning.
Polling strategy:
- First 60 seconds: every 5 seconds
- After 60 seconds: every 15 seconds
- Stop after 10 minutes if not completed
Checkout statuses (in order):
- "not_ready": Missing required fields (slug)
- "ready": All fields set, awaiting payment
- "awaiting_payment": Stripe checkout page opened, waiting for human
- "in_progress": Payment received, site being provisioned
- "completed": Site ready — API key included (shown once, then cleared)
- "canceled": Checkout was abandoned
- "failed": Payment or provisioning failed
Terminal statuses: "completed", "canceled", "failed".
Args:
checkout_id: Checkout session ID
Returns (when completed):
{"id": "uuid", "status": "completed", "api_key": "bh_...",
"api_key_message": "Store this API key securely...",
"api_key_pending": false,
"subscription_id": "uuid", "subscription_status": "active",
"site": {"slug": "my-site", "status": "active",
"url": "https://my-site.borealhost.ai"},
"completed_at": "iso8601"}
Immediately after payment `site` may be null with a `provisioning_message`
— the site is being built. Poll again in a few seconds.
Note: The api_key field appears ONCE in the first poll after completion,
then is permanently cleared. `api_key_pending` tells you whether it is still
waiting to be collected. Store it immediately.
list_checkouts
List checkouts belonging to the authenticated account.
Requires: API key. Only checkouts with a recorded owner appear — every
checkout created while authenticated, plus every checkout that reached
payment. An anonymous checkout whose one-shot secret was lost cannot be
listed; create checkouts authenticated to keep them addressable.
Args:
status: Optional filter — "not_ready", "ready", "awaiting_payment",
"completed", "canceled", "failed".
Returns:
{"checkouts": [{...same shape as get_checkout_status...}], "note": "..."}
cancel_checkout
Abandon an unpaid checkout and expire its Stripe payment link.
Use this to clean up abandoned attempts rather than leaving them to sit.
A completed checkout is never cancelled here — that would be a refund, and
it is refused.
Args:
checkout_id: Checkout session ID
Returns:
The checkout, with status "canceled".
Errors:
VALIDATION_ERROR: Checkout was already paid — cancel the subscription
from the panel instead
FORBIDDEN: Missing checkout_secret and no owning API key
add_site
Provision a site into a slot a plan you ALREADY PAY FOR includes.
Two different things can be meant by "create a site". Buying one is the
checkout flow (create_checkout → update → complete). This is the other: most
plans include several sites, and this uses one of them at no extra cost.
site_starter includes 5, site_plus 8, site_pro 12, and the agency plans
more. `whoami` and `list_sites` show what the account already holds.
⚠ Prefer this over buying a second subscription when a slot is free. Sites
under ONE subscription share one CPU pool, one disk quota and one
rate-limit bucket — that shared budget is what the plan sells. Two
subscriptions split it, so the customer pays twice for capacity they had.
Requires: API key with write scope, on the account that owns the plan.
Args:
slug: Sub-domain for the new site (lowercase, digits, hyphens)
subscription_id: The subscription whose slot to use
client_name: Display name for the site (optional)
domain: Custom domain; defaults to <slug>.borealhost.ai
site_type: wordpress (default) | php | php-nodb | static-site. Choose
here rather than provisioning WordPress and calling set_site_type
afterwards — that installs a WordPress you then abandon in the
docroot, and it costs a minute of provisioning.
Returns:
{"subscription_id": "uuid", "provisioning_job_id": "uuid",
"slug": "my-second-site", "domain": "my-second-site.borealhost.ai",
"status": "provisioning"}
Poll get_site_status(slug) until it reports active.
Errors:
VALIDATION_ERROR: Plan includes a single site, slug taken, or every
slot is in use (the message reports used/total)
NOT_FOUND: Unknown subscription, or it belongs to another account
set_site_type
Change what a site's docroot IS, without deleting anything.
Types:
wordpress WordPress, PHP and a database (the default)
php PHP and a database, no WordPress
php-nodb PHP, no database
static-site HTML/CSS/JS only, no PHP and no database
⚠ NON-DESTRUCTIVE. Existing files stay on disk and existing databases are
not dropped. They remain the customer's data and keep counting against
their plan's quota — this changes how the site is SERVED, not what it
holds. Converting back later finds everything where it was.
⚠ Moving to a type without PHP does not merely stop executing .php — it
stops serving them. The vhost returns 404 for php/phtml, because falling
through to the static handler would return the file's SOURCE, and a
docroot converted from WordPress still contains wp-config.php with the
database password in it.
Shared hosting only. On a VPS the whole container is the customer's and
they reconfigure it with the tools inside it.
Requires: API key with write scope.
Args:
slug: Site identifier
site_type: One of the four values above
Returns:
{"from": "wordpress", "to": "static-site", "database_created": false,
"placeholder_seeded": false, "pool_removed": true}
`placeholder_seeded` is true only when the docroot was EMPTY — an
existing site's content is never overwritten.
Errors:
VALIDATION_ERROR: Unknown type, or the site is not on shared hosting
NOT_FOUND: Unknown slug or not reachable by this account
get_wallet
The account's prepaid balance, and what THIS key may spend from it.
Two ceilings, and both apply: the balance bounds the ACCOUNT, the allowance
bounds this KEY within it. Plan against `spendable_cents`, which is the
lower of the two — a $50 balance behind a $5 allowance means $5, and
planning against the balance is planning a purchase that gets refused.
`can_spend: false` with a non-zero balance is normal and means this key has
no budget allocated. That is not a bug: a key with no allowance may not
spend the account's money, which is the whole reason allowances exist. Ask
the human to allocate one in the panel (Compte → Clés API).
Read-only. Money goes in through a human — an agent able to top up its own
budget does not have one.
Requires: API key with read scope.
Returns:
{"currency": "CAD", "balance_cents": 5000, "spendable_cents": 500,
"can_spend": true,
"key_allowance": {"limit_cents": 2000, "spent_cents": 1500,
"remaining_cents": 500}}
To spend it: complete_checkout(..., payment_method="wallet").
get_site_status
Get detailed status of a hosted site including resources, domains, and modules.
Requires: API key with read scope.
Args:
slug: Site identifier (the slug chosen during checkout)
Returns:
{"slug": "my-site", "plan": "site_starter", "status": "active",
"domains": ["my-site.borealhost.ai"], "modules": {...},
"resources": {"memory_mb": 512, "cpu_cores": 1, "disk_gb": 10},
"created_at": "iso8601"}
Errors:
NOT_FOUND: Unknown slug or not owned by this account
manage_dns
Create or delete DNS records for a site.
Requires: API key with write scope.
Args:
slug: Site identifier
action: "create" or "delete"
record_type: "A", "AAAA", "CNAME", "MX", "TXT", or "SRV"
subdomain: Subdomain part (e.g. "www", "mail"). Leave empty for
the apex/root domain.
value: Record value. Required for "create". Examples:
A: "1.2.3.4", CNAME: "example.com", MX: "mail.example.com",
TXT: "v=spf1 include:_spf.google.com ~all"
The DNS provider manages the effective TTL and does not expose a
per-record value through this service.
Returns:
{"success": true, "record": {"type": "A", "subdomain": "www",
"value": "1.2.3.4"}}
Errors:
VALIDATION_ERROR: Missing value for create, invalid record type
NOT_FOUND: Unknown slug
install_app
Install an app template on a VPS/Cloud site.
Starts a background installation. Poll get_app_status() for progress.
Requires: API key with write scope. VPS or Cloud plan only.
Args:
slug: Site identifier
template: App template slug. Available: django, laravel, nextjs, nodejs,
nuxtjs, rails, static, wordpress
app_name: Short name for the app (2-50 chars, lowercase alphanumeric + hyphens).
Used as subdomain: {app_name}.{site_domain}
db_type: Database type. "none", "mysql", or "postgresql" (depends on template)
domain: Custom domain override (default: {app_name}.{site_domain})
display_name: Human-friendly name (default: derived from app_name)
Returns:
{"id": "uuid", "app_name": "myapp", "status": "installing",
"message": "Installation started. Poll for progress."}
Errors:
FORBIDDEN: Plan does not support apps (shared plans)
VALIDATION_ERROR: Invalid template, app_name, or duplicate name
get_app_status
Get app installation status and log.
Poll this after install_app() to track progress.
Requires: API key with read scope.
Args:
slug: Site identifier
app_id: App ID from install_app() response
Returns:
{"id": "uuid", "app_name": "myapp", "status": "running"|"installing"|"failed",
"install_log": "..."}
Statuses: "installing", "running", "stopped", "failed", "uninstalled"
list_apps
List installed apps on a site.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"apps": [{"id": "uuid", "app_name": "myapp", "template_slug": "django",
"status": "running", "domain": "myapp.mysite.borealhost.ai"}]}
list_snapshots
List all snapshots and scheduled snapshots for a site.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"snapshots": [{"id": "uuid", "name": "snap-...", "status": "completed",
"storage_type": "local"|"b2", "size_bytes": 1234, "size_display": "1.2 Mo",
"created_at": "iso8601"}], "scheduled": [...]}
create_snapshot
Create a local container snapshot (async).
Runs in background — returns immediately with status "creating".
Poll list_snapshots() to check when status becomes "completed" or "failed".
Available for VPS, dedicated, and cloud plans (any plan with max_snapshots > 0).
Local snapshots are stored on the host disk and count against disk quota.
Requires: API key with write scope.
Args:
slug: Site identifier
description: Optional description (max 200 chars)
Returns:
{"id": "uuid", "name": "snap-...", "status": "creating",
"storage_type": "local",
"message": "Snapshot started. Poll list_snapshots() to check status."}
Errors:
VALIDATION_ERROR: Max snapshots reached or insufficient disk quota
create_b2_snapshot
Create a B2 cloud-backed snapshot (zero local disk, async).
Streams container data directly to Backblaze B2 via restic.
No local disk impact — billed separately at cost+5%.
Runs in background — returns immediately with status "creating".
Poll list_snapshots() to check when status becomes "completed".
Only available for VPS plans.
Requires: API key with write scope.
Args:
slug: Site identifier
description: Optional description (max 200 chars)
Returns:
{"id": "uuid", "name": "...", "status": "creating",
"storage_type": "b2",
"message": "B2 cloud snapshot started. Poll list_snapshots()..."}
Errors:
VALIDATION_ERROR: Not a VPS plan or max snapshots reached
delete_snapshot
Delete a snapshot (local or B2).
Requires: API key with write scope.
Args:
slug: Site identifier
snapshot_id: UUID of the snapshot to delete
Returns:
{"success": true, "message": "Snapshot deleted"}
Errors:
NOT_FOUND: Snapshot not found
rollback_snapshot
Rollback a site to a previous snapshot.
WARNING: This is destructive. The current state of the container will be
replaced with the snapshot contents.
Requires: API key with admin scope.
Args:
slug: Site identifier
snapshot_id: UUID of the snapshot to rollback to
Returns:
{"success": true, "message": "Rolled back to snapshot ..."}
Errors:
NOT_FOUND: Snapshot not found or not in completed state
get_snapshot_usage
Get snapshot disk usage and quota info for a site.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"disk_quota_gb": 200, "max_snapshots": 5, "snapshot_count": 2,
"local_snapshot_bytes": 1234, "b2_snapshot_bytes": 5678,
"can_create": true}
schedule_snapshot
Schedule a snapshot for future execution.
Requires: API key with write scope. Max 3 pending schedules per site.
Args:
slug: Site identifier
scheduled_at: ISO 8601 datetime (must be in the future)
description: Optional description (max 200 chars)
Returns:
{"id": "uuid", "scheduled_at": "iso8601", "status": "scheduled"}
Errors:
VALIDATION_ERROR: Invalid datetime, not in future, or too many pending
cancel_scheduled_snapshot
Cancel a scheduled snapshot.
Requires: API key with write scope.
Args:
slug: Site identifier
schedule_id: UUID of the scheduled snapshot to cancel
Returns:
{"success": true, "message": "Scheduled snapshot cancelled"}
Errors:
NOT_FOUND: Schedule not found or already executed
list_backups
List all backups for a site (automatic and manual).
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
[{"id": "uuid", "backup_type": "auto"|"manual", "status": "completed",
"size_bytes": 1234, "size_display": "1.2 Mo",
"timestamp": "iso8601", "notes": "..."}]
create_backup
Create a manual backup (runs asynchronously).
The backup starts in the background. Poll list_backups() to check status.
Requires: API key with write scope.
Args:
slug: Site identifier
Returns:
{"id": "uuid", "status": "pending",
"message": "Backup started. Poll list_backups() to check status."}
browse_backup
List one bounded page of immediate children in a backup directory.
This returns names and metadata only, never file contents. Use
``next_cursor`` from the response as ``cursor`` to request the next page.
Requires: API key with read scope.
Args:
slug: Site identifier
backup_id: UUID of a completed backup
path: Absolute directory path as it existed in the backup
cursor: Resume after this entry name (optional)
limit: Maximum entries, from 1 through 100
Errors:
SNAPSHOT_SCOPE_CHANGED: The path is allowed by today's schedule but was
not included when this backup was created; choose an included path
or a newer backup.
recover_backup_files
Start a selected-file recovery and return its durable ID immediately.
Existing destination paths are never replaced. The operation is
asynchronous; poll ``get_file_recovery`` with the returned ID.
Requires: API key with write scope.
Args:
slug: Site identifier
backup_id: UUID of a completed backup
paths: One or more absolute paths from that backup
Returns:
{"id": "uuid", "backup_id": "uuid", "status": "running",
"paths": ["/absolute/path"], ...}
get_file_recovery
Poll one selected-file recovery without waiting for it to finish.
Requires: API key with read scope.
Args:
slug: Site identifier
backup_id: UUID of the source backup
recovery_id: UUID returned by ``recover_backup_files``
Returns:
{"id": "uuid", "backup_id": "uuid",
"status": "running"|"completed"|"failed", "paths": [...],
"error": "", ...}
recover_backup_database
Recover exactly one absent database from a completed backup.
The operation refuses an existing database and can never select ``all``.
It returns immediately; poll ``get_database_recovery`` with its durable ID.
Requires: API key with write scope.
Args:
slug: Site identifier
backup_id: UUID of a completed backup
database: One database name, never ``all``
get_database_recovery
Poll one database recovery without waiting for completion.
Requires: API key with read scope.
Args:
slug: Site identifier
backup_id: UUID of the source backup
recovery_id: UUID returned by ``recover_backup_database``
restore_backup
Restore a site from a backup.
WARNING: This is destructive. The current state of the site will be
replaced. Runs asynchronously — may take several minutes.
Requires: API key with admin scope.
Args:
slug: Site identifier
backup_id: UUID of the backup to restore from
Returns:
{"success": true, "message": "Restore started..."}
Errors:
VALIDATION_ERROR: Backup not found or not in completed state
get_metrics
Get traffic and performance metrics for a site.
Requires: API key with read scope.
Args:
slug: Site identifier
days: Number of days of history (1–90, default: 7)
Returns:
{"requests": [...], "bandwidth": [...], "errors": [...],
"period": {"start": "iso8601", "end": "iso8601"}}
Errors:
NOT_FOUND: Unknown slug
VALIDATION_ERROR: days out of range
scale
Change a site's hosting plan (upgrade or downgrade).
Requires: API key with admin scope. Best practice: create a snapshot
before downgrading.
Args:
slug: Site identifier
new_plan: Target plan slug (e.g. "site_pro", "site_managed").
Call list_plans() to see available plans.
Returns:
{"success": true, "old_plan": "site_starter", "new_plan": "site_pro",
"message": "Plan changed successfully"}
Errors:
NOT_FOUND: Unknown slug
VALIDATION_ERROR: Invalid plan slug or same plan
decommission
Delete a site and schedule resource cleanup (7-day grace period).
WARNING: This is destructive. The site will be inaccessible immediately.
After the grace period, its active service data is deleted. A final backup
remains recoverable for 30 days; immutable copies may remain until their
retention locks expire.
Best practice: create a snapshot before decommissioning.
Requires: API key with admin scope.
Args:
slug: Site identifier
Returns:
{"success": true, "message": "Site scheduled for deletion",
"grace_period_days": 7}
Errors:
NOT_FOUND: Unknown slug
update_account
Update account profile fields (email, language, name).
Requires: API key with write scope.
Only provided (non-empty) fields are updated.
Args:
email: New email address
language: Language preference — "fr" (French) or "en" (English)
first_name: First name
last_name: Last name
Returns:
{"success": true, "account": {"email": "...", "language": "fr",
"first_name": "...", "last_name": "..."}}
Errors:
VALIDATION_ERROR: Invalid email format or language code
delete_account
Permanently anonymize the account. Cancels subscriptions, deactivates keys.
WARNING: This is irreversible. The account will be soft-deleted and all
personal data anonymized. All sites will be decommissioned.
Requires: API key with admin scope.
Returns:
{"success": true, "message": "Account anonymized"}
list_subscriptions
List all subscriptions with plan details, pricing, status, and site slug.
Requires: API key with read scope.
Returns:
[{"id": "uuid", "plan_slug": "site_starter", "plan_name": "Starter",
"status": "active", "billing_period": "monthly",
"price": {"amount": 500, "currency": "cad"},
"site_slug": "my-site", "created_at": "iso8601"}]
get_billing_portal
Get a Stripe billing portal URL for managing payment methods and invoices.
Returns a URL (not a redirect) that the human can open in a browser.
Requires: API key with read scope.
Args:
flow: Optional. Set to "payment_method_update" to go directly
to the payment method update page.
Returns:
{"url": "https://billing.stripe.com/p/session/..."}
rotate_key
Rotate an API key, optionally keeping the old key valid for up to 1,440 minutes.
Creates a new key with the same name, scopes, and rate limits.
The new key is returned once — store it immediately.
Requires: API key with write scope.
Args:
key_id: UUID of the API key to rotate (get from whoami())
Returns:
{"api_key": "bh_...", "key_id": "uuid", "prefix": "bh_...",
"scopes": ["read", "write"], "message": "Key rotated. Store securely."}
Expiry and all restrictions are preserved. Without a grace period the old
key stops working immediately.
create_api_key
Create a new API key with specified scopes.
Cannot create keys with higher scopes than the current key.
Site-scoped keys restrict access to a single site.
email_domains restricts the key to email tools on the named domains; use
email:read, email:write and optionally email:signon scopes. expires_at is
an ISO timestamp; ip_allowlist accepts IP addresses and CIDR networks.
Requires: API key with write scope.
Args:
name: Human-readable name for the key (1-100 chars)
scopes: Comma-separated scopes. Options: "read", "read,write",
"read,write,admin". Default: "read"
site_slug: Optional — restrict the key to a single site.
Omit for account-wide access.
Returns:
{"api_key": "bh_...", "key_id": "uuid", "prefix": "bh_...",
"name": "My Key", "scopes": ["read", "write"],
"message": "Store this API key securely — it will not be shown again."}
Errors:
VALIDATION_ERROR: Invalid name, scopes, or max 25 active keys
FORBIDDEN: Cannot create keys with higher scopes than current key
list_api_keys
List all API keys for the account.
Shows key metadata (name, prefix, scopes, last used) but never the
full key value.
Requires: API key with read scope.
Returns:
[{"id": "uuid", "name": "My Key", "prefix": "bh_a2...",
"scopes": ["read", "write"], "is_active": true,
"created_at": "iso8601", "last_used_at": "iso8601"|null,
"site_slug": null|"my-site"}]
revoke_api_key
Revoke (deactivate) an API key. The key stops working immediately.
Requires: API key with write scope.
Args:
key_id: UUID of the key to revoke (from list_api_keys or whoami)
Returns:
{"success": true, "message": "API key revoked"}
Errors:
NOT_FOUND: Key not found or already revoked
get_ssh_info
Get SSH connection info for a VPS/dedicated site.
Only available for VPS/dedicated plans (not shared hosting).
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"host": "184.107.x.x", "port": 22, "username": "admin",
"ssh_command": "ssh admin@184.107.x.x"}
Errors:
NOT_FOUND: Unknown slug
FORBIDDEN: Plan does not support SSH (shared plans)
add_ssh_key
Inject your SSH public key into a site's container for direct SSH access.
The key is appended to /home/admin/.ssh/authorized_keys.
Only available for VPS/dedicated plans.
Requires: API key with write scope.
Args:
slug: Site identifier
public_key: SSH public key string. Supported types:
ssh-ed25519, ssh-rsa, ecdsa-sha2-nistp256/384/521
Returns:
{"success": true, "message": "SSH key added",
"ssh_command": "ssh admin@184.107.x.x"}
Errors:
VALIDATION_ERROR: Invalid or unsupported key format
FORBIDDEN: Plan does not support SSH
list_files
List files and directories in a site's container.
Path scoping depends on the plan:
- Shared plans: rooted at wp-content/ (WordPress content directory)
- VPS/dedicated plans: full filesystem access
Requires: API key with read scope.
Args:
slug: Site identifier
path: Relative path to list (empty for root of accessible area)
Returns:
{"path": "/", "entries": [{"name": "index.php", "type": "file",
"size": 1234, "modified": "iso8601"}, {"name": "uploads",
"type": "directory", "modified": "iso8601"}]}
Errors:
NOT_FOUND: Unknown slug or path doesn't exist
read_file
Read the contents of a file from a site's container.
Max file size: 512KB. Binary files are rejected — use the site's
file manager or SSH for binary files.
Requires: API key with read scope.
Args:
slug: Site identifier
path: Relative path to the file
Returns:
{"path": "wp-config.php", "content": "<?php ...",
"size": 1234, "encoding": "utf-8"}
Errors:
NOT_FOUND: File doesn't exist
VALIDATION_ERROR: File is binary or exceeds 512KB
write_file
Write or overwrite a text file in a site's container.
Creates parent directories if they don't exist.
Requires: API key with write scope.
Args:
slug: Site identifier
path: Relative path to the file
content: File content as a UTF-8 string
Returns:
{"success": true, "path": "...", "size": 1234}
Errors:
NOT_FOUND: Unknown slug
FORBIDDEN: Protected system path
upload_file
Upload a base64-encoded file to a site's container.
Use this for binary files (images, archives, fonts, etc.).
For text files, prefer write_file().
Requires: API key with write scope.
Args:
slug: Site identifier
path: Relative path including filename (e.g. "images/logo.png")
content_b64: Base64-encoded file content
Returns:
{"success": true, "path": "images/logo.png", "size": 45678}
Errors:
VALIDATION_ERROR: Invalid base64 encoding
FORBIDDEN: Protected system path
delete_file
Delete a file or directory from a site's container.
Directories are deleted recursively. Protected system paths
(e.g. /etc, /usr) cannot be deleted.
Requires: API key with write scope.
Args:
slug: Site identifier
path: Relative path to delete
Returns:
{"success": true, "path": "...", "message": "Deleted"}
Errors:
NOT_FOUND: Path doesn't exist
FORBIDDEN: Protected system path
create_directory
Create a directory in a site's container.
Creates parent directories if they don't exist.
Requires: API key with write scope.
Args:
slug: Site identifier
path: Relative path of the directory to create
Returns:
{"success": true, "path": "uploads/2024", "message": "Directory created"}
Errors:
NOT_FOUND: Unknown slug
FORBIDDEN: Protected system path
list_plugins
List installed WordPress plugins with status.
Requires: API key with read scope. WordPress sites only.
Args:
slug: Site identifier
Returns:
{"plugins": [{"name": "akismet", "status": "active", "version": "5.3",
"update_available": false}, ...]}
list_themes
List installed WordPress themes with status.
Requires: API key with read scope. WordPress sites only.
Args:
slug: Site identifier
Returns:
{"themes": [{"name": "twentytwentyfour", "status": "active",
"version": "1.0", "update_available": false}, ...]}
manage_plugin
Install, activate, deactivate, or delete a WordPress plugin.
Requires: API key with write scope.
Args:
slug: Site identifier
action: "install", "activate", "deactivate", or "delete"
plugin: Plugin slug (e.g. "akismet", "jetpack", "woocommerce")
Returns:
{"action": "install", "plugin": "jetpack", "result": {...}}
manage_theme
Install, activate, or delete a WordPress theme.
Requires: API key with write scope.
Args:
slug: Site identifier
action: "install", "activate", or "delete"
theme: Theme slug (e.g. "twentytwentyfour", "astra")
Returns:
{"action": "install", "theme": "astra", "result": {...}}
wp_check_updates
Check for available WordPress core, plugin, and theme updates.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"core": {"current": "6.5", "update": "6.6"},
"plugins": [{"name": "...", "current": "1.0", "new": "1.1"}],
"themes": [...]}
wp_update_all
Update WordPress core, all plugins, and all themes.
Runs all updates in sequence. May take up to 2 minutes.
Requires: API key with write scope.
Args:
slug: Site identifier
Returns:
{"core": {...}, "plugins": [...], "themes": [...]}
list_cron
List cron jobs on a site.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"jobs": [{"line": 1, "schedule": "*/5 * * * *",
"command": "/usr/bin/php /var/www/html/wp-cron.php"}, ...]}
add_cron
Add a cron job to a site.
Requires: API key with write scope.
Args:
slug: Site identifier
schedule: Cron schedule (e.g. "*/5 * * * *", "0 2 * * *")
command: Command to execute
Returns:
{"added": true, "result": {...}}
delete_cron
Delete a cron job by line number.
Get line numbers from list_cron().
Requires: API key with write scope.
Args:
slug: Site identifier
line_number: Line number of the cron entry to delete
Returns:
{"deleted": true}
ssl_info
Get SSL certificate information for a site.
Returns certificate details, expiry date, and issuer.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"issuer": "Let's Encrypt", "domain": "example.com",
"expires_at": "iso8601", "days_remaining": 60,
"force_https": true}
ssl_renew
Force SSL certificate renewal via certbot.
Requires: API key with write scope.
Args:
slug: Site identifier
Returns:
{"renewed": true, "expires_at": "iso8601"}
list_php_versions
List available PHP versions and the currently active one.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"versions": [{"version": "8.1", "active": false},
{"version": "8.2", "active": false},
{"version": "8.3", "active": true}]}
switch_php
Switch the active PHP version for a site.
Requires: API key with write scope.
Args:
slug: Site identifier
version: Target PHP version (e.g. "8.3", "8.2", "8.1")
Returns:
{"version": "8.3", "result": {...}}
cache_status
Get cache status (Redis, WP object cache, hit rates).
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"redis_running": true, "object_cache_enabled": true,
"hit_rate": 0.95, "memory_used_mb": 12}
cache_flush
Flush all caches (Redis + WP object cache).
Requires: API key with write scope.
Args:
slug: Site identifier
Returns:
{"flushed": true}
cache_toggle
Enable or disable the WordPress object cache.
Requires: API key with write scope.
Args:
slug: Site identifier
enable: true to enable, false to disable
Returns:
{"enabled": true}
get_database_info
Get WordPress database information (size, tables, row counts).
Requires: API key with read scope. WordPress sites only.
Args:
slug: Site identifier
Returns:
{"database": "wp_mysite", "size_mb": 45.2,
"tables": 12, "total_rows": 15432}
optimize_database
Optimize WordPress database tables (reduces bloat).
Requires: API key with write scope.
Args:
slug: Site identifier
Returns:
{"optimized": true, "tables_optimized": 12}
database_search_replace
Search and replace in WordPress database (e.g. URL migration).
Handles serialized data safely. Use dry_run=true first to preview changes.
Requires: API key with write scope.
Args:
slug: Site identifier
old: String to search for (e.g. "http://old-domain.com")
new: Replacement string (e.g. "https://new-domain.com")
dry_run: Preview only without making changes (default: true)
Returns:
{"replacements": 42, "tables_affected": 5, "dry_run": true}
list_databases
List all databases on a site's container.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"databases": ["wordpress", "app_db", ...]}
list_tables
List tables in a database.
Requires: API key with read scope.
Args:
slug: Site identifier
database: Database name
Returns:
{"tables": [{"name": "wp_posts", "rows": 1234, "size_mb": 5.2}, ...]}
execute_query
Run ONE bounded read against a site's database.
One statement, beginning with SELECT, SHOW, DESCRIBE or EXPLAIN, with no
second statement and no data-modifying clause anywhere in it. The container
proves the statement is a read before running it and caps the result: 200
rows by default, 1000 maximum, 2 MB of cell data. `truncated` in the
response says whether a cap was reached.
⚠ THIS TOOL CANNOT CHANGE ANYTHING, AND RETRYING WITH DIFFERENT WORDING WILL
NOT MAKE IT. Anything that is not a single bounded read is refused with
READ_ONLY and nothing runs. To change data or schema, use the tool for the
job: optimize_database, database_search_replace, manage_db_user,
list_databases, list_tables — and for creating, altering, dropping,
importing or exporting tables, the database manager in the control panel,
which has no tool here.
Requires: API key with write scope (unchanged — the scope is the customer's
published permission for this operation, not a claim about what it does).
Args:
slug: Site identifier
database: Database name
query: One read statement
Returns:
{"columns": ["id", "user_email"], "rows": [[1, "a@example.com"], ...],
"row_count": 1, "truncated": false, "execution_time_ms": 12.0}
Errors:
READ_ONLY: Not a single bounded read. The error text carries the
explanation and names the operation to use instead.
get_stack_info
Get detailed system stack information (OS, PHP, DB, web server versions).
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"os": "Debian 12", "kernel": "6.1.0",
"php": "8.3.4", "mysql": "10.11.6-MariaDB",
"nginx": "1.24.0", "wordpress": "6.5"}
get_resource_snapshot
Get current resource usage (CPU, memory, disk, load average).
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"cpu_percent": 12.5, "memory_mb": 384, "memory_total_mb": 512,
"disk_used_gb": 3.2, "disk_total_gb": 10,
"load_1m": 0.5, "load_5m": 0.3, "load_15m": 0.2}
cloudflare_proxy_status
Get Cloudflare proxy (CDN) status for a site.
Shows whether traffic is routed through Cloudflare's CDN (orange cloud)
or goes direct to origin (grey cloud / DNS-only).
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"domain": "my-site.borealhost.ai", "has_record": true,
"proxied": true, "ip": "1.2.3.4"}
cloudflare_set_proxy
Enable or disable Cloudflare CDN proxy for a site.
When enabled (orange cloud): traffic goes through Cloudflare's CDN,
gets caching, DDoS protection, and SSL termination at the edge.
When disabled (grey cloud): traffic goes directly to origin server.
Requires: API key with write scope.
Args:
slug: Site identifier
proxied: true to enable CDN proxy, false to disable
Returns:
{"domain": "my-site.borealhost.ai", "proxied": true, "ip": "1.2.3.4"}
cloudflare_purge_cache
Purge Cloudflare CDN cache for a site.
Without urls: purges all cached content for the site's subdomain.
With urls: purges only the specified URLs (max 30 per call).
Requires: API key with write scope.
Args:
slug: Site identifier
urls: Optional list of specific URLs to purge
(e.g. ["https://my-site.borealhost.ai/style.css"])
Returns:
{"purged": true, "scope": "host", "domain": "my-site.borealhost.ai"}
list_ftp_accounts
List SFTP accounts on a site.
Also returns the host and port to connect to. Do not use the site's domain
for SFTP: it is Cloudflare-proxied and only carries HTTP(S).
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"accounts": [{"username": "sftpuser", "home": "/wordpress", "uid": 1001}],
"configured": true,
"connection": {"host": "1.2.3.4", "port": 9312, "protocol": "SFTP"}}
create_ftp_account
Create an SFTP account on a site.
The account is chrooted to /var/www and lands in home_dir. Password must be
at least 8 characters. Username must be lowercase alphanumeric.
Requires: API key with write scope.
Args:
slug: Site identifier
username: SFTP username (lowercase, max 32 chars)
password: Password (min 8 chars)
home_dir: Landing directory inside /var/www. Leave empty to land at
/var/www itself, which lists every site directory.
Returns:
{"success": true, "username": "sftpuser", "home_dir": "/wordpress",
"protocol": "sftp"}
remove_ftp_account
Remove an SFTP account from a site.
Requires: API key with write scope.
Args:
slug: Site identifier
username: SFTP username to remove
Returns:
{"removed": true, "username": "sftpuser"}
list_alert_rules
List user-configurable alert rules for a site.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
[{"id": "uuid", "metric": "disk", "operator": "gt",
"threshold": 90, "severity": "warning", "enabled": true,
"cooldown_minutes": 30, "notify_email": true}]
create_alert_rule
Create an alert rule to monitor CPU, memory, or disk usage.
When the metric crosses the threshold, a notification is sent via
email and/or webhook. Max 10 rules per site.
Requires: API key with write scope.
Args:
slug: Site identifier
metric: "cpu", "memory", or "disk" (percentage-based)
threshold: Threshold value 0-100 (e.g. 90 for 90%)
operator: "gt" (greater than) or "lt" (less than). Default: "gt"
severity: "warning" or "critical". Default: "warning"
cooldown_minutes: Min minutes between repeated alerts. Default: 30
notify_email: Send email notification. Default: true
notify_webhook: Optional webhook URL for POST notifications
Returns:
{"id": "uuid", "metric": "disk", "threshold": 90, ...}
delete_alert_rule
Delete an alert rule.
Requires: API key with write scope.
Args:
slug: Site identifier
rule_id: UUID of the alert rule to delete
Returns:
{"deleted": true, "id": "uuid"}
run_malware_scan
Run a ClamAV malware scan on a site's container.
Scans the web root (or specified path) for malware, viruses, and trojans.
ClamAV is installed automatically if not present. Excludes node_modules,
vendor, .git, and cache directories.
May take up to 5 minutes for large sites.
Requires: API key with write scope.
Args:
slug: Site identifier
path: Directory to scan (default: /var/www/html)
Returns:
{"infected_files": [{"path": "/var/www/html/shell.php", "threat": "Php.Malware.Agent"}],
"scanned_count": 1234, "infected_count": 1, "scan_time_s": 45.2}
list_firewall_rules
List IP allow/deny firewall rules for a site.
Rules are implemented as Nginx allow/deny directives per container.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"rules": [{"ip": "1.2.3.4", "action": "deny"},
{"ip": "10.0.0.0/8", "action": "allow"}]}
add_firewall_rule
Add an IP firewall rule (allow or deny) and reload Nginx.
Supports IPv4, IPv6, and CIDR notation. Max 100 rules per site.
If a rule already exists for the IP, the action is updated.
Requires: API key with write scope.
Args:
slug: Site identifier
ip: IP address or CIDR (e.g. "1.2.3.4", "10.0.0.0/8", "2001:db8::/32")
action: "deny" (block) or "allow" (whitelist). Default: "deny"
Returns:
{"added": true, "ip": "1.2.3.4", "action": "deny"}
remove_firewall_rule
Remove an IP firewall rule and reload Nginx.
Requires: API key with write scope.
Args:
slug: Site identifier
ip: IP address or CIDR to remove (must match exactly)
Returns:
{"removed": true, "ip": "1.2.3.4"}
list_port_forwards
List ports published from this site's container to the public internet.
These are iptables DNAT rules on the node, NOT the IP allow/deny rules that
add_firewall_rule manages — those two tools do unrelated things and neither
substitutes for the other.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"port_forwards": [{"id": "...", "external_port": 3478,
"internal_port": 3478, "protocol": "udp", "status": "active",
"public_address": "203.0.113.5:3478", "port_preserved": true}],
"limit": 15, "port_budget": 7680, "ports_used": 1,
"max_range_ports": 1024, "public_ip": "203.0.113.5"}
add_port_forward
Publish a container port on the node's public IP (TCP or UDP).
This is how inbound UDP reaches a container. There is no other way: the
container's own address is private, and the IP allow/deny rules of
add_firewall_rule cannot route anything.
PORT PRESERVATION MATTERS. Leave external_port at 0 and a port is allocated
from 10000-19999 — your service becomes reachable, but on a DIFFERENT
number. That is fine for HTTP or ssh and broken for every protocol that
carries its own port inside the payload: STUN, TURN, RTP/WebRTC, SIP,
WireGuard, QUIC. For those, pass external_port equal to internal_port.
A media server needs a contiguous span, not one port — pass
internal_port_end. A span is always published unchanged and counts as ONE
rule against your limit.
Some ports are refused because the host or its neighbours already answer on
them: 22, 80, 443, 2222, 9201, 51820, and the bands 9210-9250, 9310-9350
and 20000-20099. The last one is why the "forward UDP 20000-20999 for
Janus" recipe printed in most Nextcloud Talk guides will not work here —
pick a span above it, e.g. 20100-20599.
Requires: API key with write scope.
Args:
slug: Site identifier
internal_port: Port your service listens on inside the container
protocol: "tcp" or "udp". Default: "tcp"
label: Free-text note shown in the panel
external_port: Publish on this exact port; 0 allocates one from the pool
internal_port_end: End of a contiguous range (inclusive); 0 means one port
Returns:
{"id": "...", "external_port": 3478, "internal_port": 3478,
"protocol": "udp", "status": "active",
"public_address": "203.0.113.5:3478", "port_preserved": true}
remove_port_forward
Stop publishing a port, by the rule id from list_port_forwards.
Requires: API key with write scope.
Args:
slug: Site identifier
forward_id: Rule id (uuid) from list_port_forwards
Returns:
{"removed": true, "forward_id": "..."}
get_logs
Retrieve container logs (error, access, or PHP).
Requires: API key with read scope.
Args:
slug: Site identifier
log_type: "error" (Nginx/Apache errors), "access" (HTTP request log),
or "php" (PHP-FPM errors, WordPress sites only)
lines: Number of lines to retrieve (1–500, default: 100)
search: Optional keyword filter — only lines containing this string
Returns:
{"log_type": "error", "lines": ["2024-01-15 ... error ...", ...],
"count": 42, "truncated": false}
Errors:
NOT_FOUND: Unknown slug
VALIDATION_ERROR: Invalid log_type or lines out of range
list_domains
List all domains owned by the authenticated user.
Requires: API key with read scope.
Returns:
[{"domain": "example.com", "status": "active",
"expires_at": "iso8601", "auto_renew": true,
"linked_site": "my-site"}]
search_domain
Check domain availability and get pricing.
Requires: API key with read scope.
Args:
domain: Full domain name (e.g. "example.com", "mybiz.ca")
Returns:
{"domain": "example.com", "available": true,
"registration_estimate_cad": "15.99", "currency": "CAD",
"price_cad_includes_privacy": false, "total_cad": null,
"quote_required": true}
Note: .ca domains require ca_legal_type when registering.
register_domain
Register a new domain with WHOIS contact info and Stripe billing.
First request a quote (quote_only=True), present registration_cad,
privacy_cad, total_cad, term and privacy choice, and obtain customer consent.
Then repeat the same input with quote_only=False and the quote_token.
Never automatically accept a replacement token after a price change.
Included annual registration covers registration only; selected privacy
uses the same BoC daily USD/CAD rate, rounded to CAD cents, no markup.
Registration/renewal convert their actual operation-specific USD cost first,
then apply 10% and round up to CAD .95. Rates older than four days refuse.
Requires: API key with write scope.
Args:
whois_privacy: Explicit privacy choice; defaults selected only for supported paid TLDs.
quote_only: True returns a quote without registration or payment.
quote_token: Signed five-minute quote accepted by the customer.
domain: Full domain name (e.g. "example.ca", "mybusiness.com")
first_name: Registrant first name
last_name: Registrant last name
email: Registrant email address
phone: Phone number in E.164 format: "+1.5145551234"
address1: Street address (e.g. "123 Rue Principale")
city: City (e.g. "Montreal")
state: Province/state code (e.g. "QC", "ON", "BC")
postal_code: Postal/ZIP code (e.g. "H2X 1Y4")
country: ISO 3166-1 alpha-2 country code (default: "CA")
period: Registration period in years (1–10, default: 1)
usage_mode: What the domain points at.
"site" (default) links it to the billing subscription's
site with automatic DNS + Nginx + SSL.
"external_ns" delegates it to `nameservers` — the domain is
registered here but hosted elsewhere; we manage no DNS.
"dns_only" keeps it on our DNS with no site behind it.
"forward" redirects visitors to `forward_url`.
nameservers: Ordered list of 2–6 nameserver hostnames. Required when
usage_mode="external_ns" (e.g. ["ns1.other.com", "ns2.other.com"])
forward_url: Redirect target, required when usage_mode="forward"
(e.g. "https://example.org")
forward_type: "301" permanent (default) or "302" temporary
forward_include_path: Append the visitor's path to the target (default: True)
ca_legal_type: Required for .ca domains. CIRA legal types:
"CCT" (Canadian citizen), "RES" (permanent resident),
"CCO" (corporation), "GOV" (government), "EDU" (education),
"ASS" (association), "HOP" (hospital), "PRT" (partnership),
"TDM" (trademark), "TRD" (trade union), "PLT" (political party),
"LAM" (library/archive/museum), "MAJ" (Her Majesty),
"INB" (Indian band), "ABO" (Aboriginal peoples),
"LGR" (legal representative)
Returns:
Quote request: {"quote": {"registration_cad": "...",
"privacy_cad": "...", "total_cad": "...", "currency": "CAD",
"period": 1, "whois_privacy": false, "expires_at": "iso8601"},
"quote_token": "...", "privacy_explanation": "..."}
Purchase: {"name": "example.ca", "status": "registered",
"last_pricing_quote": {...}, ...}
Errors:
VALIDATION_ERROR: Missing required fields, invalid phone format,
missing ca_legal_type for .ca domains
NOT_FOUND: Domain not available (already registered by someone else)
domain_detail
Get full domain details including DNS and infrastructure status.
Requires: API key with read scope.
Args:
domain_name: Full domain name (e.g. "example.com")
Returns:
{"domain": "example.com", "status": "active",
"expires_at": "iso8601", "auto_renew": true,
"nameservers": ["ns1.borealhost.ai", "ns2.borealhost.ai"],
"dns_records": [...], "linked_site": "my-site"}
Errors:
NOT_FOUND: Domain not owned by this account
list_subdomains
List subdomain DNS records for a domain you own.
Requires: API key with read scope.
Args:
domain_name: Registrable domain (e.g. "example.com")
Returns:
[{"fqdn": "blog.example.com", "subdomain": "blog",
"record_type": "A", "value": "1.2.3.4", "is_auto": true}, ...]
Errors:
NOT_FOUND: Domain not found
add_subdomain
Create and route a subdomain of a site-linked domain.
Creates the DNS A record (if absent) pointing at the site's server,
then configures the nginx vhost and SSL certificate on that server.
The domain must already be linked to a site (see link_domain).
Idempotent: if the DNS record already exists and points at the site's
server, the nginx/SSL steps are (re)applied — safe to re-call, e.g. to
retry SSL after DNS propagation. May take up to 3 minutes when a
certificate is issued.
Requires: API key with write scope.
Args:
domain_name: Registrable domain linked to a site (e.g. "example.com")
subdomain: Subdomain label only, no dots (e.g. "blog")
Returns:
{"fqdn": "blog.example.com", "domain": "example.com",
"site": "my-site", "message": "..."}
Errors:
NOT_FOUND: Domain not found
VALIDATION_ERROR: Domain not linked to a site, invalid label, or
an existing record points at a different server
delete_subdomain
Remove a subdomain: its DNS record, nginx vhost and certificate.
The inverse of add_subdomain. Removes the DNS record AND the server-side
vhost and cert, so the name stops resolving and stops being served. Nothing
else on the domain is touched.
Requires: API key with write scope.
Args:
domain_name: Registrable domain linked to a site (e.g. "example.com")
subdomain: Subdomain label only, no dots (e.g. "blog")
Returns:
{"fqdn": "blog.example.com", "domain": "example.com",
"removed": ["dns", "vhost", "cert"], "message": "..."}
Errors:
NOT_FOUND: Domain or subdomain not found
VALIDATION_ERROR: Domain not linked to a site, or invalid label
link_domain
Link a domain to a hosted site.
Attaches the domain to the specified site and triggers automatic
DNS configuration and SSL provisioning.
WARNING: Regenerates this site's nginx vhost on the host from scratch. Any config applied to that vhost by hand is lost, silently — the site keeps serving and only the hand-added behaviour disappears. Config set via the nginx-snippet endpoint is NOT affected: it lives in a separate file the regenerated vhost re-includes, which is what that endpoint is for.
Requires: API key with write scope.
Args:
domain_name: Full domain name (e.g. "example.com")
site_slug: Site identifier to link the domain to
Returns:
{"success": true, "domain": "example.com",
"linked_site": "my-site", "message": "Domain linked"}
Errors:
NOT_FOUND: Domain or site not found
VALIDATION_ERROR: Domain already linked to another site
get_site_nginx_snippet
Read the custom nginx config for a domain on the BorealHost host proxy.
Your site sits behind a BorealHost reverse proxy that terminates TLS and
forwards to your container. This returns the custom nginx block applied to
that proxy for this domain (empty if you have not set one).
Requires: API key with read scope.
Args:
domain_name: Full domain name (e.g. "example.com")
Returns:
{"domain": "example.com", "content": "location ...", "exists": true}
Errors:
NOT_FOUND: Domain not found
VALIDATION_ERROR: Domain is not linked to a site
set_site_nginx_snippet
Set custom nginx config on the BorealHost host proxy — WebSocket, timeouts, headers.
Use this when configuring your container's own nginx is not enough because
something in front of it is interfering. The host proxy sits between the
internet and your container, and by default its catch-all `location /` does
not do anything special per-site.
WEBSOCKETS: if your WebSocket endpoint returns 400 through your domain but
upgrades correctly (101) when tested inside your container, the Upgrade
header is being dropped in front of you. Add a location block that relays it:
location ^~ /your/ws/path/ {
proxy_pass <your site's existing upstream>;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600;
proxy_send_timeout 3600;
error_page 502 503 504 =502;
}
When testing with curl, force HTTP/1.1 (curl --http1.1). A WebSocket handshake uses the Upgrade header, which is invalid in HTTP/2 —
curl negotiates h2 with a CDN by default and the edge answers 400, which looks exactly like the bug you are trying to fix.
This config lives OUTSIDE the generated vhost, so it survives domain
re-linking, autoconfig, plan changes and reprovisioning. Sending "" clears it.
Bounds — the file is parsed by a root process on a machine shared with
BorealHost infrastructure, so only per-site proxy directives are accepted:
location, proxy_pass, proxy_set_header, proxy_http_version, proxy_*_timeout,
proxy_buffering, client_max_body_size, add_header, error_page, expires, gzip.
`root`, `alias`, `include`, `access_log`, `error_log`, `server` and `upstream`
are refused, and proxy_pass must target your own site's existing upstream.
A rejection names the directive and why.
The config is validated with `nginx -t` before it is applied and rolled back
automatically if it does not pass, so a mistake cannot take your site down.
Requires: API key with write scope.
Args:
domain_name: Full domain name (e.g. "example.com")
content: nginx config, or "" to clear it
Returns:
{"domain": "example.com", "bytes": 214, "replaced": false}
Errors:
NOT_FOUND: Domain not found
VALIDATION_ERROR: Domain not linked to a site, a directive is not
permitted, proxy_pass targets something other than your own
upstream, or nginx rejected the config (the message says which)
set_domain_usage
Set what a registered domain points at — a site, someone else's
nameservers, our DNS with no site, or a redirect to another URL.
Use this to park a domain, hand it to an external host, or forward it.
Switching modes tears down the previous one (a forwarded domain that
becomes a site domain loses its redirect, and vice versa).
Requires: API key with write scope.
Args:
domain_name: Full domain name (e.g. "example.com")
usage_mode: "site" — link it to a hosted site (needs site_slug);
"external_ns" — delegate to the customer's own nameservers
(needs nameservers), we stop managing its DNS entirely;
"dns_only" — our nameservers, records edited by hand,
nothing served;
"forward" — our nameservers plus an HTTP redirect to
forward_url (needs forward_url)
site_slug: Site to link to, when usage_mode="site"
nameservers: Ordered list of 2–6 nameserver hostnames, when
usage_mode="external_ns"
forward_url: Redirect target, when usage_mode="forward"
forward_type: "301" permanent (default) or "302" temporary
forward_include_path: Append the visitor's path to the target (default: True)
Returns:
{"domain": "example.com", "usage_mode": "forward",
"forward_url": "https://example.org",
"configuration": {"dns": true, "nginx": true, "ssl": false, ...}}
For forward mode, ssl=false usually just means DNS has not propagated
yet — call this tool again a few minutes later to finish the cert.
Errors:
NOT_FOUND: Domain or site not found
VALIDATION_ERROR: Bad nameserver hostname, bad redirect URL,
missing site_slug, or a self-referential redirect
domain_settings
Update domain settings (auto-renew, WHOIS privacy, registrar lock).
Only provided (non-None) fields are updated.
Requires: API key with write scope.
Args:
domain_name: Full domain name (e.g. "example.com")
auto_renew: Optional bool enabling/disabling automatic renewal
whois_privacy: Optional bool. False disables saved proxy service. Paid activation via True is refused; request an activation quote through Support.
locked: Optional bool enabling/disabling registrar lock (prevents unauthorized transfers)
Returns:
{"success": true, "domain": "example.com",
"auto_renew": true, "whois_privacy": true, "locked": true}
Errors:
NOT_FOUND: Domain not found or not owned by account
resend_registrant_verification
Request OpenSRS verification email to its existing owner contact.
Requires a write-scope API key and an owned registered/transferred domain.
Call only when the customer requests a resend. No recipient override.
Returns domain, send_acknowledged, inbox_delivery_confirmed (always false),
registrant_verified, and the refreshed registrant_verification snapshot.
A send acknowledgement confirms neither inbox delivery nor verification;
status can remain unknown if the subsequent status refresh fails.
PROVIDER_REFUSED (502) means no email should be assumed sent. CONFLICT (409)
means another resend is in progress; RATE_LIMITED (429) has Retry-After 3600.
Never automatically retry a refused, busy or throttled resend.
list_domain_dns
List all DNS records for a domain.
Returns DNS records at the domain level (independent of site-level
manage_dns). Use this for domains that may not be linked to a site.
Requires: API key with read scope.
Args:
domain_name: Full domain name (e.g. "example.com")
Returns:
[{"id": "record-id", "type": "A", "subdomain": "www",
"value": "1.2.3.4"}]
The DNS provider manages the effective TTL and does not expose a
per-record value through this service.
Errors:
NOT_FOUND: Domain not found or not owned by account
add_domain_dns
Add a DNS record to a domain.
Requires: API key with write scope.
Args:
domain_name: Full domain name (e.g. "example.com")
record_type: "A", "AAAA", "CNAME", "MX", "TXT", or "SRV"
value: Record value (e.g. "1.2.3.4" for A, "mail.example.com" for MX)
subdomain: Subdomain part (e.g. "www", "mail"). Empty for apex domain.
priority: MX priority (required for MX records)
The DNS provider manages the effective TTL and does not expose a
per-record value through this service.
Returns:
{"success": true, "record": {"id": "...", "type": "A",
"subdomain": "www", "value": "1.2.3.4"}}
Errors:
VALIDATION_ERROR: Missing value, invalid record type
NOT_FOUND: Domain not found
delete_domain_dns
Delete a DNS record from a domain.
Requires: API key with write scope.
Args:
domain_name: Full domain name (e.g. "example.com")
record_id: ID of the DNS record to delete (from list_domain_dns)
Returns:
{"success": true, "message": "DNS record deleted"}
Errors:
NOT_FOUND: Domain or record not found
list_modules
List AI modules and their enabled/disabled state for a site.
Also returns the list of modules available for the site's plan.
Requires: API key with read scope.
Args:
slug: Site identifier
Returns:
{"modules": {"chatbot": true, "seo": false, "translation": false,
"content": false}, "available": ["chatbot", "seo", "translation", "content"]}
Errors:
NOT_FOUND: Unknown slug
toggle_module
Enable or disable an AI module on a site.
The module must be in the plan's available module list.
Requires: API key with write scope.
Args:
slug: Site identifier
module_name: Module to toggle. Available modules:
"chatbot" (AI chat widget), "seo" (SEO optimization),
"translation" (content translation), "content" (AI content generation)
Returns:
{"module": "chatbot", "enabled": true, "message": "Module enabled"}
Errors:
NOT_FOUND: Unknown slug or module not in plan
VALIDATION_ERROR: Invalid module name
list_compute_types
List on-demand compute instance types with hourly CAD prices.
On-demand instances are real cloud VMs in Canada (Montreal region),
billed per minute (1-hour minimum) post-paid onto your existing
BorealHost subscription. Use them for short-lived extra compute
(builds, batch jobs, experiments).
Requires: API key with read scope.
Returns:
{"region": "ca-central-1", "currency": "CAD",
"billing": "hourly, post-paid; billing runs until the instance is terminated",
"types": [{"type": "lsw.c3.large", "vcpu": 2, "memory_gb": 3,
"hourly_price_cad": 0.08, "min_disk_gb": 5,
"storage_types": ["CENTRAL", "LOCAL"]}, ...]}
list_compute_images
List OS images available for on-demand compute instances.
Requires: API key with read scope.
Returns:
{"images": [{"id": "UBUNTU_24_04_64BIT", "name": "Ubuntu 24.04 LTS (x86_64)",
"family": "linux", "flavour": "ubuntu"}, ...]}
launch_compute_instance
Launch an on-demand hourly compute instance (Canada, CAD).
Billing starts at launch (per minute, 1-hour minimum) and runs until
terminate_compute_instance — stopping does NOT stop the charge. Every
instance has a hard TTL
(max_lifetime_hours, default 72h) after which it is auto-terminated.
Usage is metered onto your existing BorealHost subscription; an active
subscription is required.
Requires: API key with write scope.
Args:
instance_type: From list_compute_types, e.g. "lsw.c3.large"
image_id: From list_compute_images, e.g. "UBUNTU_24_04_64BIT"
name: Optional label for the instance
ssh_public_key: Public key installed as root access. Mutually exclusive
with user_data (provider limitation) — provide exactly one.
user_data: cloud-init config (plain text #cloud-config). Use
ssh_authorized_keys inside it if you need a key AND user data.
root_disk_size: GB (default max(min_disk, 25))
storage_type: "CENTRAL" (redundant) or "LOCAL" (faster I/O)
max_lifetime_hours: Hard TTL, 1-336 (default 72)
Returns:
Instance dict: {"id", "state": "launching", "public_ip", "instance_type",
"hourly_price_cad", "terminate_after", ...}. Poll get_compute_instance
until state is "running" and public_ip is set (~1-3 min).
Errors:
PAYMENT_REQUIRED: No active subscription to bill against
LIMIT_EXCEEDED: Concurrent instance cap reached
SPEND_CAP_EXCEEDED: Monthly compute spend cap reached
VALIDATION_ERROR: Bad type/image/disk/TTL, or both/neither of
ssh_public_key and user_data
list_compute_instances
List your on-demand compute instances with month-to-date spend.
Requires: API key with read scope.
Returns:
{"instances": [...], "month_to_date_spend_cad": 12.34,
"monthly_spend_cap_cad": 500.0}
get_compute_instance
Get live details for a compute instance (state, public IP, accrued cost).
State is synced from the cloud provider on each call. SSH as root once
state is "running" and public_ip is set.
Requires: API key with read scope.
Args:
instance_id: Instance UUID from launch_compute_instance / list
Returns:
{"id", "state", "public_ip", "hourly_price_cad", "accrued_cad",
"terminate_after", ...}
start_compute_instance
Start a stopped compute instance.
Requires: API key with write scope.
stop_compute_instance
Stop a compute instance. WARNING: hourly billing continues while stopped.
Use terminate_compute_instance to stop the charges permanently.
Requires: API key with write scope.
reboot_compute_instance
Reboot a running compute instance.
Requires: API key with write scope.
terminate_compute_instance
Permanently terminate a compute instance — this stops hourly billing.
The instance and its disk are destroyed and cannot be recovered. Copy any
results off the instance before terminating.
Requires: API key with write scope.
Returns:
Final instance dict with state "terminated" and total accrued_cad.
list_compute_volumes
List your compute volumes — machines that survive instance termination.
A volume is a whole machine (packages, drivers, services, users, data)
stored in Canada. Detaching destroys the instance but keeps the machine;
attaching restores it onto a fresh instance, optionally of a DIFFERENT
type. That is how you move a workload from a small CPU box to a big GPU
box without rebuilding it.
Requires: API key with read scope.
Returns:
{"volumes": [{"id", "name", "state", "instance_type", "stored_gb",
"has_snapshot", "instance": {...} or null}, ...],
"price_cad_per_gb_month": 0.03}
state is one of: creating, attached, detaching, detached, attaching,
error. Only "attached" has a running instance you can log into.
get_compute_volume
Get a volume's live state, its instance, and its monthly storage cost.
Requires: API key with read scope.
Returns:
Volume dict plus "monthly_storage_cad". After attach, poll this until
instance.state is "running" — then allow a few more minutes for the
restore to finish and the machine to reboot into itself.
create_compute_volume
Create a persistent machine and boot its first instance.
Start here, then set the machine up however you like (install packages,
drivers, models). Everything you do becomes part of the volume the first
time you detach or snapshot it.
While attached you pay hourly compute; while detached you pay only for
stored bytes (CA$0.03/GB/month). Stopping an instance does NOT save money
on this provider — detaching is what stops the compute charge.
Requires: API key with write scope, and an active subscription.
Args:
name: Label for the volume, e.g. "trainer"
image_id: From list_compute_images, e.g. "UBUNTU_24_04_64BIT".
Cannot change later — restores must land on the same OS.
instance_type: From list_compute_types, e.g. "lsw.g6.xlarge".
CAN change on every later attach.
ssh_public_key: Required. Volume instances always boot via cloud-init,
so this is the only way in.
root_disk_size: GB. Defaults to the type's minimum (or 25).
Returns:
Volume dict with state "attached". Poll get_compute_volume until
instance.state is "running" (~1-3 min).
Errors:
PAYMENT_REQUIRED: No active subscription
LIMIT_EXCEEDED: Volume cap reached
NOT_AVAILABLE: Volumes not enabled on this deployment
adopt_compute_instance
Turn an instance you are ALREADY running into a persistent volume.
Use this when you launched something, set it up, and then decided you want
to keep it. Nothing reboots and no data moves — the machine you have
becomes the volume, and you can detach it afterwards to stop paying for
compute while keeping the machine. Beats creating a volume and rebuilding.
Only instances launched with an ssh_public_key qualify. One launched with
your own user_data carries only your key, and a key cannot be added to a
machine we cannot already log into — check "managed_ssh" on the instance.
Requires: API key with write scope, and an active subscription.
Args:
instance_id: A running lsw.* instance you own
name: Label for the volume (defaults to the instance name)
Returns:
Volume dict with state "attached", wrapping that same instance. No
snapshot exists yet — the first one is taken on detach or snapshot.
Errors:
CONFLICT: Not running, already a volume, BorealHost Metal, or launched
without BorealHost management access
detach_compute_volume
Queue: snapshot the machine, verify it, then destroy the instance.
This is how you stop paying for compute while keeping your work.
ASYNCHRONOUS. Returns immediately with state "detaching" — it does NOT mean
the detach finished. The capture takes minutes (roughly 1 min per 10 GB plus
verification), so it runs in a background worker. Poll get_compute_volume
until state is "detached" (done) or "error" (failed).
Safety: if the snapshot or its verification fails, the instance is left
RUNNING and the volume goes to state "error". Your data is never traded
for a tidy state machine. Retry the detach once you have fixed the cause.
Requires: API key with write scope.
Returns:
Volume dict with state "detaching". Poll for the outcome.
attach_compute_volume
Restore a detached volume onto a fresh instance — optionally a new type.
Pass a different instance_type to move the same machine to different
hardware: this is the closest thing to changing instance type that the
provider allows, since it has no resize API at all.
The restore runs at first boot and the machine reboots into itself, so the
instance answers SSH BEFORE it is ready. Poll get_compute_volume and give
it a few minutes (measured: ~6 min for a 10 GB GPU machine end to end).
The machine keeps its SSH host keys, so your client will not warn about a
changed host identity.
Requires: API key with write scope.
Args:
volume_id: A volume in state "detached"
ssh_public_key: Required — installed via cloud-init at boot
instance_type: Defaults to the type it last ran on
root_disk_size: GB. May grow, never shrink below the volume's size.
Returns:
Volume dict with state "attached" and a new instance.
Errors:
CONFLICT: Volume is not detached, or has no snapshot yet
snapshot_compute_volume
Queue a checkpoint snapshot without detaching — before a risky change.
ASYNCHRONOUS. Returns immediately with state "snapshotting"; poll
get_compute_volume until it is back to "attached" (done) or "error".
Named systemd units are stopped for the capture so the snapshot is
application-consistent (a live database directory copied mid-write is not
reliably restorable). The worker restarts nothing — reboot or start them
yourself afterwards.
Requires: API key with write scope.
Args:
volume_id: A volume in state "attached"
quiesce_units: Services to stop during capture,
e.g. ["ollama.service", "postgresql.service"]
Returns:
Volume dict with state "snapshotting". Poll for the outcome.
delete_compute_volume
Permanently delete a volume and everything stored in it.
Irreversible: the instance is released AND the stored data is purged from
object storage, so billing genuinely stops. Refuses while an instance is
live unless force=True, so a running machine's only copy cannot be
destroyed by reflex.
Requires: API key with admin scope.
Returns:
{"id", "state": "deleted"}
container_action
Start, stop, or restart a site's container.
Only for plans with a dedicated container (VPS / split-VPS / dedicated).
Shared-hosting sites share a container and cannot restart it. The
response reports the observed container state after the action.
Requires: API key with write scope.
Args:
slug: Site identifier
action: "start", "stop", or "restart"
Returns:
{"site", "action", "status": "running|stopped", "observed": true}
Errors:
VALIDATION_ERROR: Shared-hosting plan or unknown action
list_support_tickets
List the account's support tickets.
Requires: API key with read scope.
Args:
status: Optional filter (e.g. "open", "closed")
Returns:
[{"id", "subject", "status", "category", "created_at", ...}, ...]
get_support_ticket
Get a support ticket with its full message thread.
Requires: API key with read scope.
Args:
ticket_id: Ticket UUID from list_support_tickets
Returns:
{"id", "subject", "status", "messages": [...]}
create_support_ticket
Open a support ticket with the BorealHost team.
Use this to escalate platform-side problems you cannot fix with the
available tools (billing issues, infrastructure faults, API bugs).
A human answers every ticket — poll get_support_ticket for updates.
Requires: API key with write scope.
Args:
subject: Short summary (max 200 chars)
message: Full description (max 20000 chars)
category: Optional (e.g. "technical", "billing")
site: Optional site slug the ticket concerns
Returns:
{"id", "subject", "status", "message": "Ticket created..."}
reply_support_ticket
Add a message to an existing support ticket.
Requires: API key with write scope.
Args:
ticket_id: Ticket UUID
message: Reply text
Returns:
{"id", "status", ...}
get_backup_retention
Get the backup retention policy for a VPS site.
Requires: API key with read scope.
Returns:
{"site", "retention": {"keep_daily", "keep_weekly", "keep_monthly"}}
set_backup_retention
Set the backup retention policy for a VPS site.
Storage is billed on real stored bytes, so deeper history costs the
customer, not the platform. Values are clamped to platform bounds; the
response reports what was actually stored. Pass -1 to leave a knob
unchanged, or reset=true to restore defaults.
Requires: API key with write scope.
Returns:
{"site", "retention": {...}}
delete_backup
Permanently delete a single backup (metadata + stored snapshot).
Irreversible. Requires: API key with admin scope.
Returns:
{"site", "backup_id", "deleted": true}
list_redirects
List HTTP redirect rules for a site.
Requires: API key with read scope.
Returns:
[{"id", "source_path", "target_url", "redirect_type"}, ...]
add_redirect
Add an HTTP redirect rule to a site.
Requires: API key with write scope.
Args:
slug: Site identifier
source_path: Path to redirect, must start with "/" (e.g. "/old-page")
target_url: Destination URL
redirect_type: 301 (permanent, default) or 302 (temporary)
Returns:
{"id", "source_path", "target_url", "redirect_type"}
delete_redirect
Delete a redirect rule by source path or id.
Requires: API key with write scope.
Returns:
{"site", "deleted": true}
set_force_https
Enable or disable the HTTP→HTTPS redirect for a site.
Requires: API key with write scope.
Returns:
{"site", "force_https": true|false, "message"}
list_db_users
List database users for a site.
Requires: API key with read scope.
Returns:
{"engine", "users": [{"user", "host", ...}, ...]}
manage_db_user
Manage a database user on a site.
Actions: "create" (user+password), "drop" (user),
"set_password" (user+password), "grants" (list a user's grants),
"grant" / "revoke" (user+database, optional privileges e.g. "ALL"
or "SELECT,INSERT").
Requires: API key with write scope.
Returns:
{"engine", "action", "result": {...}}
transfer_out_domain
Prepare a domain to transfer to another registrar.
Unlocks the domain and emails the EPP/auth code to the registrant
contact on file (BorealHost never sees the code). The domain keeps
working here until the transfer completes.
Requires: API key with write scope.
Returns:
{"domain", "unlocked": true, "auth_code_emailed": true, "message"}
enable_wildcard
Route *.domain (every subdomain) to the domain's linked site.
Creates a wildcard DNS record and issues a wildcard certificate via
ACME DNS-01. SLOW — DNS propagation is part of the challenge, expect
2-5 minutes. Requires the domain to be linked to a site and its DNS
hosted by BorealHost.
Requires: API key with write scope.
Returns:
{"domain", "wildcard", "site", "ssl_active", "not_after"}
upload_ssl_cert
Install your own SSL certificate for a site's domain.
The certificate must be a PEM fullchain (leaf + intermediates) and the
key unencrypted PEM. Validated (parse, key match, domain coverage,
expiry) before nginx is touched; nginx config is tested before reload.
Requires: API key with write scope.
Returns:
{"site", "domain", "server_names", "installed": true,
"ssl_active": true, "not_after"}
rotate_email_key
Rotate the current email-only key with overlap, preserving scope and expiry.
enable_email_domain
Enable an independent email domain; preserve all other email domains.
Requires a verified owned domain and email:write scope. site_slug selects
billing when ambiguous. Defaults request 2,000 users and 50,000 aliases.
list_email_domains
List email domains visible to this key, with cluster connection settings.
get_email_domain
Read effective OpenSRS limits, counts, connections and public DNS health.
update_email_domain
Set mailbox_limit, alias_limit, quota_gb, smtp_sent_limit, services or language.
configure_email_dns
Configure OpenSRS DKIM and merge email DNS, preserving other senders and subdomains.
disable_email_domain
Disable an empty email domain; refuses active or recoverable accounts.
list_mailboxes
Page through a domain's mailboxes, optionally filtering by organisation label.
get_mailbox
Inspect usage, services, aliases count, forwarding/Sieve, autoresponder and label.
create_email_mailbox
Create a domain-addressed billable mailbox. Password returned once; retries omit it.
update_mailbox
Set display_name, quota_gb, smtp_sent_limit, label, services or suspended.
Suspension disables client access and outbound SMTP while preserving receipt.
delete_email_mailbox
Soft-delete a mailbox. confirm must equal email. Provider recovery window: 30 days.
restore_mailbox
Restore a uniquely identifiable soft-deleted mailbox under its original address.
reset_email_mailbox_password
Reset password and terminate IMAP/POP sessions. Requires email:signon.
logout_mailbox_sessions
Terminate established IMAP and POP sessions through OpenSRS logout_user.
clear_mailbox_forwarding
Clear forwarding; when Sieve exists, requires explicit clear_all_filters=true.
create_mailbox_token
Issue a temporary mail-services token with no OMA access. Requires email:signon.
Use 60, 120, ... 1440 minutes. OpenSRS rejects fractional hours; no rounding up.
get_email_webmail_url
Issue a one-use BorealHost link expiring in 60 seconds. Redemption mints provider SSO. Requires email:signon.
find_address
Look up mailbox/alias/forward/free in an authorized email domain.
list_mailbox_aliases
List a mailbox's aliases with pagination.
add_mailbox_alias
Add an alias on the same domain, preserving existing aliases.
remove_mailbox_alias
Remove one alias, preserving the mailbox and other aliases.
set_mailbox_aliases
Replace the complete alias list idempotently (maximum 2,000).
list_email_audit
List email API mutation/credential issuance attempts, actor, reason and outcome.
get_email_status
Email addon status and mailboxes for a site.
Requires: API key with read scope.
Returns:
{"configured": bool, "domain", "mailboxes", "mailbox_list": [...]}
setup_email
Enable business email (hosted mailboxes + webmail) on a domain.
Creates the hosted-email domain, sets up outbound authentication
(DKIM/SPF), and auto-configures MX/SPF DNS when the zone is hosted by
BorealHost. Mailboxes are billed per-mailbox on the site subscription.
Requires: API key with write scope.
Returns:
{"configured": true, "domain", "dns_auto_configured", "message"}
create_mailbox
Create a mailbox on the site's email domain.
Password is generated when omitted and returned ONCE — store it.
Each mailbox adds to the subscription's email billing.
Requires: API key with write scope.
Args:
slug: Site identifier
local_part: Part before the @ (e.g. "info")
display_name: Optional display name
password: Optional password (generated if empty)
Returns:
{"email", "password", "message"}
delete_mailbox
Delete a mailbox (its mail is destroyed).
Requires: API key with write scope.
Returns:
{"email", "deleted": true}
reset_mailbox_password
Reset a mailbox password (generated when omitted, returned ONCE).
Requires: API key with write scope.
Returns:
{"email", "password", "message"}
get_webmail_url
One-time webmail single-sign-on URL for a mailbox.
Requires: API key with write scope.
Returns:
{"email", "url"}
list_webhooks
List webhook endpoints registered on the account.
Requires: API key with read scope.
Returns:
[{"id", "url", "events", "is_active", "last_status",
"failure_count"}, ...]
create_webhook
Register a webhook endpoint for platform events.
Events (backup failures, security notices, hosting incidents, billing)
are POSTed as JSON, signed with X-BH-Signature (HMAC-SHA256 of the raw
body). The signing secret is returned ONCE. Categories: billing,
security, hosting, decommission, general — empty list means all.
Endpoints auto-disable after 20 consecutive failures.
Requires: API key with write scope.
Returns:
{"id", "url", "events", "secret", "message"}
delete_webhook
Remove a webhook endpoint.
Requires: API key with write scope.
Returns:
{"id", "deleted": true}
test_webhook
Send a test event to a webhook endpoint (async).
Poll list_webhooks afterwards for last_status.
Requires: API key with write scope.
Returns:
{"id", "message"}
get_smtp_relay
List SMTP relay credentials for a site, with domain-auth status.
Requires: API key with read scope.
Returns:
{"relays": [{"relay_id", "domain", "status",
"domain_authenticated"}, ...]}
enable_smtp_relay
Enable an SMTP relay for a site's outbound transactional mail.
Provisions a mail-send-only credential on the platform relay and
configures SPF/DKIM DNS when the domain zone is hosted here. The SMTP
password is returned ONCE. Use TLS on port 587, username "apikey".
Requires: API key with write scope.
Returns:
{"relay_id", "domain", "smtp_host", "smtp_ports", "smtp_username",
"smtp_password", "dns_auto_configured", "message"}
revoke_smtp_relay
Revoke an SMTP relay credential (immediate at the relay).
Requires: API key with write scope.
Returns:
{"relay_id", "revoked": true}
prompt:purchase_hosting
Step-by-step guide to purchase a BorealHost hosting plan, from plan discovery through payment to site provisioning
prompt:setup_site
Post-purchase site setup guide: configure DNS, enable AI modules
prompt:manage_dns
Guide for common DNS operations: A records, CNAME, MX, TXT/SPF, with examples
prompt:register_domain
Domain registration guide with required WHOIS contact fields and .ca specifics
prompt:claim_site_key
Get an API key by proving you're running on a BorealHost container (challenge-response flow)