# BorealHost.ai — Full API Reference

> Complete reference for AI agents. For a summary, see /llms.txt

## Agent Self-Service Flow
Agents can register, pay, and provision sites without any human intervention:

1. Register: POST /api/v1/auth/register/ {"name": "My Agent"}
   → Returns an API key (shown once, store securely)
2. Browse plans: GET /api/v1/plans/
3. Create checkout: POST /api/v1/acp/checkouts/ {"sku": "bh_site_starter_monthly"}
4. Set buyer info: POST /api/v1/acp/checkouts/{id}/update/
   Body: {"buyer_email": "agent@example.com", "requested_slug": "my-site"}
5. Complete payment: POST /api/v1/acp/checkouts/{id}/complete/
   Body: {"payment_method": "stripe_checkout"} → returns Stripe Checkout URL
   OR: {"payment_method": "stripe_payment_method", "payment_method_id": "pm_..."}
6. Poll status: GET /api/v1/acp/checkouts/{id}/ until status is "completed"
   → Response includes API key and site provisioning info
7. Manage site: GET /api/v1/sites/{slug}/ with API key

## Authentication
All authenticated endpoints require a Bearer token:
  Authorization: Bearer bh_<48 hex chars>

API keys are account-scoped (one key = all sites).
Scopes: read, write, admin (hierarchical: admin > write > read).
Get a key via POST /api/v1/auth/register/ or POST /api/v1/keys/create/ or the panel UI.

## Response Format
All responses use this envelope:
  Success: {"ok": true, "data": {...}, "meta": {"request_id": "...", "timestamp": "..."}}
  Error:   {"ok": false, "error": {"code": "...", "message": "...", "param": "..."}}

## Rate Limits
Default: 60 req/min, 10,000 req/day per key.
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
429 responses include Retry-After header.

## Endpoints

### Discovery (no auth required)

#### GET /api/v1/plans/
List all available hosting plans.
Query: ?include_deprecated=true, ?track=single_site
Returns: array of plan objects with slug, name, price, resources, features.

#### GET /api/v1/plans/{slug}/
Get details for a specific plan.

#### GET /api/v1/status/
Platform health status.

### Registration (no auth required)

#### POST /api/v1/auth/register/
Register an agent account and get an API key. Rate-limited: 5/hour per IP.
Body: {"name": "My Agent Key"}
Creates a synthetic agent identity. Returns: api_key (shown once), key_id, scopes.

#### GET /api/v1/auth/whoami/
Verify API key and see account info. Auth required.
Returns: user info, key details, site count, active subscriptions.

### Sites (auth required)

#### POST /api/v1/sites/create/
Create a site from a completed ACP checkout. Scope: write.
Body: {"checkout_id": "uuid-from-completed-checkout"}
For agency plans, create managed sites: {"subscription_id": "uuid", "slug": "...", "client_name": "..."}

#### GET /api/v1/sites/
List all sites owned by the authenticated user. Scope: read.

#### GET /api/v1/sites/{slug}/
Get detailed site info including resources, modules, domains. Scope: read.

#### DELETE /api/v1/sites/{slug}/delete/
Schedule site decommissioning (7-day grace period). Scope: admin.

#### POST /api/v1/sites/{slug}/dns/
Create or delete DNS records. Scope: write.
Body: {"action": "create|delete", "type": "A|AAAA|CNAME|MX|TXT|SRV", "subdomain": "www", "value": "1.2.3.4"}
Optional: ttl (default 3600), priority (for MX).

#### POST /api/v1/sites/{slug}/deploy/
Trigger a deployment via bh-agent. Scope: write.

### Snapshots (auth required)

#### GET /api/v1/sites/{slug}/snapshots/
List all snapshots (local + B2 cloud) and scheduled snapshots. Scope: read.

#### POST /api/v1/sites/{slug}/snapshots/create/
Create a local container snapshot (async). Scope: write.
Body: {"description": "optional"} Returns immediately, poll list for status.

#### POST /api/v1/sites/{slug}/snapshots/b2/
Create a B2 cloud snapshot (async, zero local disk). VPS only. Scope: write.

#### DELETE /api/v1/sites/{slug}/snapshots/{id}/
Delete a snapshot (local or B2). Scope: write.

#### POST /api/v1/sites/{slug}/snapshots/{id}/rollback/
Rollback container to snapshot (destructive). Scope: admin.

#### GET /api/v1/sites/{slug}/snapshots/usage/
Get disk quota, snapshot count, local/B2 bytes. Scope: read.

#### POST /api/v1/sites/{slug}/snapshots/schedule/
Schedule a future snapshot. Body: {"scheduled_at": "ISO8601", "description": ""}. Max 3 pending. Scope: write.

#### DELETE /api/v1/sites/{slug}/snapshots/schedule/{id}/
Cancel a scheduled snapshot. Scope: write.

### Backups (auth required)

#### GET /api/v1/sites/{slug}/backups/
List all backups (automatic + manual). Scope: read.

#### POST /api/v1/sites/{slug}/backups/create/
Create a manual backup (async). Returns immediately, poll list for status. Scope: write.

#### POST /api/v1/sites/{slug}/backups/{id}/restore/
Restore from backup (destructive, async). Scope: admin.

#### GET /api/v1/sites/{slug}/metrics/
Get traffic metrics. Scope: read.
Query: ?days=7 (max 90)
Returns daily stats: requests, bandwidth, unique IPs, avg response time, error rate.

#### POST /api/v1/sites/{slug}/scale/
Change the site plan. Scope: admin.
Body: {"new_plan": "site_pro"}

### API Keys (auth required)

#### POST /api/v1/keys/create/
Create a new API key. Scope: write.
Body: {"name": "My Key", "scopes": ["read", "write"], "site_slug": "optional-site", "disabled_tools": ["deploy"]}
site_slug: restrict key to one site (omit for account-level).
disabled_tools: list of tool names to block (omit for all allowed).
Returns the full key once. Max 25 active keys per account.

### Key Claim — Challenge-Response (no auth required)

#### POST /api/v1/keys/claim/request/
Start challenge-response key provisioning. No auth.
Body: {"site_slug": "my-site"}
Writes a claim token to the container at ~/.borealhost/.claim_token (mode 600).
Returns instructions to read the token and call the claim endpoint.
Rate limited: 5 per IP per hour + 3 pending per site.

#### POST /api/v1/keys/claim/
Claim an API key using the token read from the container. No auth.
Body: {"claim_token": "<token-from-file>"}
Returns a site-scoped API key (read+write, scoped to the requested site).
Token is single-use, expires in 1 hour. Rate limited: 10 per IP per hour.

#### GET /api/v1/keys/
List all API keys. Scope: read.

#### POST /api/v1/keys/{id}/revoke/
Deactivate an API key. Scope: write.

#### POST /api/v1/keys/{id}/rotate/
Atomically rotate an API key. Creates a new key with same name/scopes, deactivates the old key. Scope: write.
Returns: new key (shown once), rotated_from (old key ID).

### Account Management (auth required)

#### POST /api/v1/account/update/
Update account profile. Scope: write.
Body: {"email": "...", "language": "en", "first_name": "...", "last_name": "..."}
All fields optional. Validates email format + uniqueness.

#### DELETE /api/v1/account/delete/
Soft-delete (anonymize) account. Scope: admin.
Body: {"confirm": "DELETE"}
Cancels Stripe subscriptions, deactivates all API keys, anonymizes user.

#### GET /api/v1/account/subscriptions/
List all subscriptions with plan details, pricing, and site slug. Scope: read.

#### GET /api/v1/account/billing-portal/
Get Stripe billing portal URL (not a redirect). Scope: read.
Query: ?flow=payment_method_update (optional)
Returns: {"url": "https://billing.stripe.com/..."}

### File Management (auth required)

#### GET /api/v1/sites/{slug}/files/
List directory contents. Scope: read.
Query: ?path=relative/path (empty = root)
Returns: {path, entries: [{name, type, size, modified}]}

#### GET /api/v1/sites/{slug}/files/read/
Read a file. Scope: read.
Query: ?path=relative/path/file.txt
Returns: {path, content, mime_type}. Max 512KB.

#### POST /api/v1/sites/{slug}/files/write/
Write/overwrite a file. Scope: write.
Body: {"path": "relative/path/file.txt", "content": "file contents"}

#### POST /api/v1/sites/{slug}/files/mkdir/
Create a directory. Scope: write.
Body: {"path": "relative/path/new-dir"}

#### POST /api/v1/sites/{slug}/files/upload/
Upload a file (base64-encoded). Scope: write.
Body: {"path": "relative/path/image.png", "content_b64": "base64data..."}

#### POST /api/v1/sites/{slug}/files/delete/
Delete a file or directory. Protected paths cannot be deleted. Scope: write.
Body: {"path": "relative/path/old-file.txt"}

### SSH Access (auth required, VPS/dedicated plans only)

#### GET /api/v1/sites/{slug}/ssh/
Get SSH connection info (host, port, username, command). Scope: read.
Returns: {host, port, username, command}

#### POST /api/v1/sites/{slug}/ssh/keys/
Inject an SSH public key into the container. Scope: write.
Body: {"public_key": "ssh-ed25519 AAAA... agent@host"}
The key is appended to /home/admin/.ssh/authorized_keys.
Returns connection info so the agent can SSH in immediately.

### Logs (auth required)

#### GET /api/v1/sites/{slug}/logs/
Retrieve container logs. Scope: read.
Query: ?type=error|access|php&lines=100&search=keyword
Default type: error. Max lines: 500. PHP type only for WordPress plans.
Returns: {type, lines_requested, content}

### Modules (auth required)

#### GET /api/v1/sites/{slug}/modules/
List modules and plan availability. Scope: read.
Returns: {modules: [{name, enabled}], available: [module_names]}

#### POST /api/v1/sites/{slug}/modules/{name}/toggle/
Enable/disable an AI module. Scope: write.
Module must be in plan's available list.
Returns: {module, enabled}

### Domain Management (auth required)

#### GET /api/v1/domains/
List all domains owned by the authenticated user. Scope: read.

#### GET /api/v1/domains/search/
Check domain availability and pricing. Scope: read.
Query: ?domain=example.com
Returns: {domain, available, status, price_cad, currency}

#### POST /api/v1/domains/register/
Register a domain with contact info and Stripe billing. Scope: write.
Body: {"domain": "example.com", "period": 1, "contact": {first_name, last_name, email, phone, address1, city, state, postal_code, country}, "ca_legal_type": "CCT"}
Free domain if plan has free_domain_annual + annual billing + no existing domains.

#### GET /api/v1/domains/{name}/
Get domain detail with infrastructure status. Scope: read.

#### GET /api/v1/domains/{name}/dns/
List DNS records for a domain. Scope: read.

#### POST /api/v1/domains/{name}/dns/add/
Add a DNS record. Scope: write.
Body: {"type": "A|AAAA|CNAME|MX|TXT|SRV", "subdomain": "www", "value": "1.2.3.4", "ttl": 3600}
Automatically pushed to OpenSRS for managed domains.

#### POST /api/v1/domains/{name}/dns/delete/
Delete a DNS record. Scope: write.
Body: {"record_id": "uuid"}. Auto-managed records cannot be deleted.

#### POST /api/v1/domains/{name}/link/
Link a domain to a tenant site. Scope: write.
Body: {"site_slug": "my-site"}

#### POST /api/v1/domains/{name}/settings/
Update domain settings. Scope: write.
Body: {"auto_renew": true, "whois_privacy": true, "locked": true}
All fields optional. Synced to OpenSRS.

### Stripe ACP (Agent Checkout Protocol)

#### GET /.well-known/acp.json
ACP discovery document with SKU catalog and payment methods.

#### POST /api/v1/acp/checkouts/
Create checkout session. Body: {"sku": "bh_site_starter_monthly"}
SKU format: bh_{plan_slug}_{monthly|annual}

#### GET /api/v1/acp/checkouts/{id}/
Get checkout session state.

#### POST /api/v1/acp/checkouts/{id}/update/
Update with buyer info. Body: {"buyer_email": "...", "requested_slug": "my-site"}

#### POST /api/v1/acp/checkouts/{id}/complete/
Complete with payment.
Option A: {"payment_method": "stripe_checkout"} → returns Stripe Checkout URL
Option B: {"payment_method": "stripe_payment_method", "payment_method_id": "pm_..."} → direct charge
On completion, returns an API key for managing the provisioned site.

## Complete Plan Catalog

### Mon Site (Single Business)

#### Starter (`site_starter`)
- Monthly: $5 CAD
- Annual: $2 CAD/mo
- Hosting: shared
- Max sites: 1
- Snapshots: N/A
- AI modules: chatbot, translate, seo, content
- AI agents: none
- Free domain (annual): no
- SKU: bh_site_starter_monthly / bh_site_starter_annual

#### Pro (`site_pro`)
- Monthly: $12 CAD
- Annual: $9 CAD/mo
- Hosting: shared
- Max sites: 1
- Snapshots: N/A
- AI modules: chatbot, translate, seo, content
- AI agents: wp_developer, site_assistant
- Free domain (annual): no
- SKU: bh_site_pro_monthly / bh_site_pro_annual

#### Managed (`site_managed`)
- Monthly: $32 CAD
- Annual: $25 CAD/mo
- Hosting: split_vps
- RAM: 2048 MB
- CPU: 1 cores
- Disk: 10 GB NVMe
- Max sites: 1
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): yes
- SKU: bh_site_managed_monthly / bh_site_managed_annual

#### Business (`site_business`)
- Monthly: $59 CAD
- Annual: $49 CAD/mo
- Hosting: split_vps
- RAM: 4096 MB
- CPU: 2 cores
- Disk: 25 GB NVMe
- Max sites: 1
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): yes
- SKU: bh_site_business_monthly / bh_site_business_annual

### Agence (Multi-Site)

#### Freelance (`agency_freelance`)
- Monthly: $35 CAD
- Annual: $29 CAD/mo
- Hosting: shared
- Max sites: 10
- Snapshots: N/A
- AI modules: chatbot, translate, seo, content
- AI agents: wp_developer, site_assistant
- Free domain (annual): yes
- SKU: bh_agency_freelance_monthly / bh_agency_freelance_annual

#### Agency (`agency_pro`)
- Monthly: $69 CAD
- Annual: $59 CAD/mo
- Hosting: shared
- Max sites: 25
- Snapshots: N/A
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): yes
- SKU: bh_agency_pro_monthly / bh_agency_pro_annual

#### Studio (`agency_studio`)
- Monthly: $119 CAD
- Annual: $99 CAD/mo
- Hosting: shared
- Max sites: 50
- Snapshots: N/A
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): yes
- SKU: bh_agency_studio_monthly / bh_agency_studio_annual

### Cloud VPS (Burstable)

#### Cloud 1 (`cloud_1`)
- Monthly: $5 CAD
- Annual: $3 CAD/mo
- Hosting: split_vps
- RAM: 1024 MB
- CPU: 1 cores
- Disk: 20 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): no
- SKU: bh_cloud_1_monthly / bh_cloud_1_annual

#### Cloud 2 (`cloud_2`)
- Monthly: $7 CAD
- Annual: $5 CAD/mo
- Hosting: split_vps
- RAM: 2048 MB
- CPU: 1 cores
- Disk: 40 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): no
- SKU: bh_cloud_2_monthly / bh_cloud_2_annual

#### Cloud 3 (`cloud_3`)
- Monthly: $9 CAD
- Annual: $7 CAD/mo
- Hosting: split_vps
- RAM: 4096 MB
- CPU: 2 cores
- Disk: 40 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): no
- SKU: bh_cloud_3_monthly / bh_cloud_3_annual

### VPS (Dedicated CPU)

#### VPS 1 (`vps_1`)
- Monthly: $12 CAD
- Annual: $9 CAD/mo
- Hosting: split_vps
- RAM: 6144 MB
- CPU: 4 cores
- Disk: 100 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): no
- SKU: bh_vps_1_monthly / bh_vps_1_annual

#### VPS 2 (`vps_2`)
- Monthly: $25 CAD
- Annual: $19 CAD/mo
- Hosting: split_vps
- RAM: 16384 MB
- CPU: 6 cores
- Disk: 200 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): yes
- SKU: bh_vps_2_monthly / bh_vps_2_annual

#### VPS 3 (`vps_3`)
- Monthly: $35 CAD
- Annual: $29 CAD/mo
- Hosting: split_vps
- RAM: 24576 MB
- CPU: 8 cores
- Disk: 300 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): yes
- SKU: bh_vps_3_monthly / bh_vps_3_annual

#### VPS 4 (`vps_4`)
- Monthly: $65 CAD
- Annual: $55 CAD/mo
- Hosting: split_vps
- RAM: 49152 MB
- CPU: 12 cores
- Disk: 400 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): yes
- SKU: bh_vps_4_monthly / bh_vps_4_annual

#### VPS 5 (`vps_5`)
- Monthly: $85 CAD
- Annual: $69 CAD/mo
- Hosting: split_vps
- RAM: 65536 MB
- CPU: 16 cores
- Disk: 500 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): yes
- SKU: bh_vps_5_monthly / bh_vps_5_annual

#### VPS 6 (`vps_6`)
- Monthly: $159 CAD
- Annual: $135 CAD/mo
- Hosting: split_vps
- RAM: 122880 MB
- CPU: 24 cores
- Disk: 600 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: chatbot, translate, seo, content
- AI agents: domain_advisor, wp_developer, site_assistant, claude_coder, openai_coder
- Free domain (annual): yes
- SKU: bh_vps_6_monthly / bh_vps_6_annual

### VibeCoding (AI Dev Environments)

#### Starter (`vibecoding_starter`)
- Monthly: $15 CAD
- Annual: $12 CAD/mo
- Hosting: split_vps
- RAM: 1024 MB
- CPU: 1 cores
- Disk: 25 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: none
- AI agents: none
- Free domain (annual): no
- SKU: bh_vibecoding_starter_monthly / bh_vibecoding_starter_annual

#### Pro (`vibecoding_pro`)
- Monthly: $25 CAD
- Annual: $20 CAD/mo
- Hosting: split_vps
- RAM: 2048 MB
- CPU: 2 cores
- Disk: 40 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: none
- AI agents: none
- Free domain (annual): no
- SKU: bh_vibecoding_pro_monthly / bh_vibecoding_pro_annual

#### Team (`vibecoding_team`)
- Monthly: $40 CAD
- Annual: $33 CAD/mo
- Hosting: split_vps
- RAM: 4096 MB
- CPU: 3 cores
- Disk: 80 GB NVMe
- Max sites: None
- Snapshots: 10
- AI modules: none
- AI agents: none
- Free domain (annual): no
- SKU: bh_vibecoding_team_monthly / bh_vibecoding_team_annual

## Quick Start — Full Agent Self-Service

1. Register and get API key:
   POST /api/v1/auth/register/ {"name": "My Agent"}
   → Store the returned api_key securely

2. Browse plans:
   GET /api/v1/plans/

3. Create checkout:
   POST /api/v1/acp/checkouts/ {"sku": "bh_site_starter_monthly"}

4. Set buyer info:
   POST /api/v1/acp/checkouts/{id}/update/
   {"buyer_email": "agent@example.com", "requested_slug": "my-site"}

5. Complete with payment:
   POST /api/v1/acp/checkouts/{id}/complete/ {"payment_method": "stripe_checkout"}
   → Returns stripe_checkout_url for human to pay
   → OR use "stripe_payment_method" + "payment_method_id" for direct charge

6. Poll until completed:
   GET /api/v1/acp/checkouts/{id}/ until status is "completed"
   → Returns API key for managing the provisioned site

7. Manage your site:
   GET /api/v1/sites/my-site/ (with API key from step 6)
   POST /api/v1/sites/my-site/deploy/

## Discovery Endpoints
- MCP discovery: GET https://borealhost.ai/.well-known/mcp.json
- AI plugin: GET https://borealhost.ai/.well-known/ai-plugin.json
- OpenAPI spec: GET https://borealhost.ai/api/v1/openapi.json
- Agent guide: GET https://borealhost.ai/for-agents

## MCP Server
Available at https://borealhost.ai/mcp/ (remote HTTP). 46 tools, 5 resources, 5 prompts.

Auth: set_api_key, register, request_api_key, claim_api_key
Core: whoami, list_plans, create_checkout, update_checkout,
      complete_checkout, get_checkout_status, get_site_status,
      manage_dns, deploy, get_metrics, scale, decommission
Snapshots: list_snapshots, create_snapshot, create_b2_snapshot, delete_snapshot,
           rollback_snapshot, get_snapshot_usage, schedule_snapshot, cancel_scheduled_snapshot
Backups: list_backups, create_backup, restore_backup
Account: update_account, delete_account, list_subscriptions, get_billing_portal, rotate_key
Files: list_files, read_file, write_file, upload_file, delete_file
SSH: get_ssh_info, add_ssh_key
Logs: get_logs
Domains: list_domains, search_domain, register_domain, domain_detail
Modules: list_modules, toggle_module

Key types: account-level (all sites) or site-scoped (one site, with per-tool permissions).
Challenge-response claim: request_api_key(slug) → read token from container → claim_api_key(token).

Config: set BOREALHOST_API_KEY env var, or call set_api_key()/register() at runtime.

## Contact
- Website: https://borealhost.ai
- API docs: https://borealhost.ai/api/
- Email: admin@borealhost.ai
- Location: Quebec, Canada