The revision identifies this documentation snapshot, not the API version or a confirmation of what is deployed. API version information is in the OpenAPI reference.
Use the API to deploy a service from a Dockerfile or a prebuilt Linux container image, and manage services within your slice. You can also configure services in Portal without writing API requests.
- API base URL:
https://api.budgethost.io - Manage services and tokens in Portal
- Deploy a service
- Runtime operations and private database services
- Manage a slice through the API
- OpenAPI reference
- API changelog
Choose your setup#
For a one-command deployment, start with the Budgethost CLI guide:
The CLI uploads source, builds remotely and waits for the result. The deployment and slice guides offer Bash, PowerShell and Node.js versions of each API example. See the OS-specific prerequisites before using them.
Choose the right token#
A service token gives access to one service. Use it for deployments and service configuration. A slice token can manage services, storage and tokens within one slice, according to its permissions. Neither token can change your purchased allocation or another customer's resources.
In Portal, open Slice settings → API tokens → Create token. Give the token a recognizable name, choose its scope and permissions, and select its expiry. Download the credentials or copy them to a private file. The token is shown only once. Existing tokens can be renamed from their expanded details.
Tokens expire after 90 days by default; you can choose a shorter lifetime or no expiry. They do not renew automatically. In Portal, Renew creates a replacement with the same name, permissions and lifetime policy. Update your clients, verify the replacement, then Revoke the old token. Renewal does not revoke it automatically. Revoked tokens can be deleted from the list.
A service token cannot manage tokens. A slice token with tokens:manage can list
and revoke slice tokens and issue service tokens. With tokens:renew, it can
renew itself through the API. See slice token operations.
Revoking a slice token normally leaves its previously issued service tokens valid;
API cascade revocation is an explicit separate option.
Finish active deployments before rotating credentials. Retry keys are token-scoped, and revocation may prevent further deployment stages. Expiry does not stop the running service.
Credentials and shell setup#
Choose one language below and use that version throughout the guides:
- Linux / macOS: Bash, curl 7.76+ (
--fail-with-body), jq, tar and Python 3. On macOS, open Terminal and runbashfirst; do not assume the default zsh shell. - Windows: PowerShell 7.4+ with its built-in HTTP and JSON commands. No WSL, curl, jq or Python is needed for the PowerShell examples.
- Node.js: Node.js 22+ on Windows, macOS or Linux. Save the setup and selected
example steps together in a
.mjsfile and run it withnode your-script.mjs. These examples use built-in modules andfetch; no npm packages are required. Source packaging uses a localtarexecutable.
Docker is needed only when building an image locally. See the OS prerequisites. Use the selector at the top right of each code panel to choose a language. Your choice carries across the guide. In downloaded Markdown, expand the matching language section. The API request and response are the same.
For a service token, Portal's downloaded .service.env contains:
SERVICE_ID='your-service-id'
SERVICE_TOKEN='your-service-token'
Keep that file outside your source directory and exclude it from Git. Load only a credentials file you trust. Change the example credentials path to your file. Run the setup once for a new operation. Keep its state directory: when recovering, reuse it and its saved keys instead of running a fresh setup.
The PowerShell and Node.js setups define reusable request, JSON and retry-key helpers. Keep these definitions with the later examples. If starting from a slice, use the slice setup instead; it defines the same helpers and lets you issue a service token before continuing to deployment.
Linux / macOS - Bash
set -euo pipefail
set +x
umask 077
# Change this path to your downloaded credentials file.
chmod 600 ~/.service.env
source ~/.service.env
API_URL=https://api.budgethost.io
BASE="$API_URL/v1/deploy/services/$SERVICE_ID"
# Save requests, responses and retry keys outside your source directory.
STATE=$(mktemp -d)
printf 'Deployment state: %s\n' "$STATE"
api() {
curl --fail-with-body --silent --show-error \
--header "Authorization: Bearer $SERVICE_TOKEN" "$@"
}
uuid() {
python3 -c 'import uuid; print(uuid.uuid4())'
}
Windows - PowerShell 7.4+
$ErrorActionPreference = 'Stop'
# Parse Portal's credentials file as data, not executable PowerShell.
function Read-Credentials([string] $Path) {
$values = @{}
foreach ($line in Get-Content -LiteralPath $Path) {
if ($line -match '^\s*(SERVICE_ID|SERVICE_TOKEN|SLICE_ID|SLICE_TOKEN)\s*=\s*(.*?)\s*$') {
$name = $Matches[1]
$value = $Matches[2]
if ($value -match '^(["''])(.*)\1$') { $value = $Matches[2] }
$values[$name] = $value
}
}
return $values
}
function Save-Json($Value, [string] $Path) {
$Value | ConvertTo-Json -Depth 30 | Set-Content -LiteralPath $Path -Encoding utf8NoBOM
}
function Read-Json([string] $Path) {
Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json -AsHashtable
}
function New-Key([string] $Path) {
# Keep an existing retry key. Use a new state directory for a new operation.
if (-not (Test-Path -LiteralPath $Path)) {
[Guid]::NewGuid().ToString() | Set-Content -LiteralPath $Path -Encoding utf8NoBOM
}
}
function New-RequestDirectory {
$parent = [Environment]::GetFolderPath('LocalApplicationData', 'DoNotVerify')
$path = Join-Path $parent "Budgethost/requests/$([Guid]::NewGuid())"
[void] [IO.Directory]::CreateDirectory($path)
if (-not $IsWindows) {
[IO.File]::SetUnixFileMode($path, [IO.UnixFileMode]::UserRead -bor [IO.UnixFileMode]::UserWrite -bor [IO.UnixFileMode]::UserExecute)
}
return $path
}
function Invoke-Api {
param([string] $Uri, [string] $Token, [string] $Method = 'Get',
[string] $BodyFile, [string] $UploadFile, [string] $KeyFile)
$headers = @{ Authorization = "Bearer $Token" }
if ($KeyFile) { $headers['X-Idempotency-Key'] = (Get-Content -LiteralPath $KeyFile -Raw).Trim() }
$request = @{ Uri = $Uri; Method = $Method; Headers = $headers; MaximumRedirection = 0 }
if ($BodyFile) {
$request.ContentType = 'application/json; charset=utf-8'
$request.InFile = $BodyFile
} elseif ($UploadFile) {
$request.ContentType = 'application/octet-stream'
$request.InFile = $UploadFile
}
Invoke-RestMethod @request
}
$credentials = Read-Credentials "$HOME/Downloads/my-service.env"
$ServiceId = $credentials.SERVICE_ID
$ServiceToken = $credentials.SERVICE_TOKEN
if (-not $ServiceId -or -not $ServiceToken) { throw 'Service credentials are missing.' }
$ApiUrl = 'https://api.budgethost.io'
$Base = "$ApiUrl/v1/deploy/services/$ServiceId"
$State = New-RequestDirectory
Write-Host "Keep this request directory: $State"
Node.js - all operating systems
import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
import { createReadStream } from 'node:fs';
import { createHash, randomUUID } from 'node:crypto';
import { homedir } from 'node:os';
import path from 'node:path';
import { spawnSync } from 'node:child_process';
// Parse Portal credentials as data; never execute a downloaded .env file.
async function readCredentials(file) {
const values = {};
for (const line of (await readFile(file, 'utf8')).split(/\r?\n/)) {
const match = line.match(/^\s*(SERVICE_ID|SERVICE_TOKEN|SLICE_ID|SLICE_TOKEN)\s*=\s*(.*?)\s*$/);
if (match) values[match[1]] = match[2].replace(/^(["'])(.*)\1$/, '$2');
}
return values;
}
const saveJson = (file, value) => writeFile(file, JSON.stringify(value, null, 2), { mode: 0o600 });
const readJson = async file => JSON.parse(await readFile(file, 'utf8'));
async function newKey(file) {
try { await writeFile(file, randomUUID(), { flag: 'wx', mode: 0o600 }); }
catch (error) { if (error.code !== 'EEXIST') throw error; }
}
async function newState() {
const directory = path.join(homedir(), '.budgethost', 'requests', randomUUID());
await mkdir(directory, { recursive: true, mode: 0o700 });
return directory;
}
async function api(url, { token = serviceToken, method = 'GET', bodyFile, uploadFile, keyFile } = {}) {
const headers = { Authorization: `Bearer ${token}` };
if (keyFile) headers['X-Idempotency-Key'] = (await readFile(keyFile, 'utf8')).trim();
let body;
if (bodyFile) {
headers['Content-Type'] = 'application/json';
body = await readFile(bodyFile);
} else if (uploadFile) {
headers['Content-Type'] = 'application/octet-stream';
headers['Content-Length'] = String((await stat(uploadFile)).size);
body = createReadStream(uploadFile);
}
try {
const response = await fetch(url, {
method, headers, body, redirect: 'error',
...(uploadFile ? { duplex: 'half' } : {}),
signal: AbortSignal.timeout(uploadFile ? 30 * 60_000 : 60_000),
});
const result = await response.json();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${result.error?.code ?? 'API_ERROR'}`);
return result;
} finally { if (uploadFile) body?.destroy(); }
}
function run(command, args, options = {}) {
const result = spawnSync(command, args, { stdio: 'inherit', ...options });
if (result.error) throw result.error;
if (result.status !== 0) throw new Error(`${command} failed`);
}
const apiUrl = 'https://api.budgethost.io';
let serviceId, serviceToken, base;
let state = await newState();
const deploy = {};
console.log(`Keep this request directory: ${state}`);
const credentials = await readCredentials(path.join(homedir(), 'Downloads', 'my-service.env'));
serviceId = credentials.SERVICE_ID;
serviceToken = credentials.SERVICE_TOKEN;
if (!serviceId || !serviceToken) throw new Error('Service credentials are missing');
base = `${apiUrl}/v1/deploy/services/${serviceId}`;
Never include tokens in source archives, images, tickets or build logs. Keep runtime secrets in the secret API or Portal's environment settings, rather than in images.
Requests, responses and retries#
Send the token as Authorization: Bearer <token>. JSON requests contain the fields
directly. Successful responses put the result inside data:
{
"data": {
"service_id": "your-service-id",
"saved": true,
"runtime_changed": false
}
}
Errors contain error.code and error.message, sometimes with error.details.
Keep request/correlation IDs when contacting support, but remove credentials.
Operations that require X-Idempotency-Key must use the same key and unchanged
request body on retry. Generate a new key only for a new operation. A changed body
with a reused key returns 409. Keep the state directory printed by the shell setup.
Only one deployment can be active for a service at a time.
202 Accepted means queued, not finished. Poll deployment status until it is
succeeded or failed. Provisioning-operation success may mean runtime work was
queued; see the relevant operation's guide.
What the API covers#
The public API uses /v1/deploy/services/ and /v1/deploy/slices/. Portal's
session-based settings endpoints are a separate interface; do not call them with
a service or slice token. The Portal guide explains features that do
not have a public deployment API equivalent.
Services share the slice's CPU, memory and storage allocation. Combined storage usage includes retained volumes and database storage.
A successful deployment confirms the configured readiness check and required platform work, not your application's business logic. Replacing a service may briefly interrupt traffic. Rollback is explicit and restores an image, not database contents, files or configuration.
For automation and AI assistants#
Read the OpenAPI reference and service capabilities before constructing requests. Use the supplied service rather than creating a duplicate. Inspect configuration and storage before modifying them. Save request bodies, IDs and retry keys; preview configuration before applying it. Never invent resource IDs, credentials, readiness paths or successful deployment results.