BudgethostAPI DOCUMENTATION
API v1OpenAPI
YOUR SERVICE SLICEREST / JSON

Room for your applications

Create applications and persistent storage within your allocation. One place to see what belongs together.

A slice is the allocation shared by your services. You can create services and storage within it. Deploying one service does not deploy its neighbours.

Already have a service? Skip creation and go to Deploy a service. You can also manage services and tokens through Portal.

See Runtime operations and private database services for Docker HEALTHCHECK readiness, private MariaDB/Redis provisioning, maintenance jobs, start/stop/restart, resource samples and capability discovery.

1. Connect to your slice#

Download a slice token from Slice settings → API tokens. Store .slice.env outside your project directory. The file contains SLICE_ID and SLICE_TOKEN.

Choose Bash, PowerShell or Node.js and use the same language throughout this guide. See shell and runtime prerequisites. This setup includes the helpers needed by the later examples. Use a new state directory for a new operation; reuse the saved directory and keys for recovery.

Linux / macOS - Bash
set -euo pipefail
set +x
umask 077

chmod 600 ~/.slice.env
source ~/.slice.env

API_URL=https://api.budgethost.io
SLICE_BASE="$API_URL/v1/deploy/slices/$SLICE_ID"
STATE=$(mktemp -d)
printf 'Save this request directory: %s\n' "$STATE"

slice_api() {
  curl --fail-with-body --silent --show-error \
    --header "Authorization: Bearer $SLICE_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-slice.env"
$SliceId = $credentials.SLICE_ID
$SliceToken = $credentials.SLICE_TOKEN
if (-not $SliceId -or -not $SliceToken) { throw 'Slice credentials are missing.' }
$ApiUrl = 'https://api.budgethost.io'
$SliceBase = "$ApiUrl/v1/deploy/slices/$SliceId"
$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-slice.env'));
const sliceId = credentials.SLICE_ID;
const sliceToken = credentials.SLICE_TOKEN;
if (!sliceId || !sliceToken) throw new Error('Slice credentials are missing');
const sliceBase = `${apiUrl}/v1/deploy/slices/${sliceId}`;

Check what already exists:

Linux / macOS - Bash
slice_api "$SLICE_BASE" | jq .data
Windows - PowerShell 7.4+
(Invoke-Api -Uri $SliceBase -Token $SliceToken).data | ConvertTo-Json -Depth 30
Node.js - all operating systems
console.log((await api(sliceBase, { token: sliceToken })).data);

2. Create a service#

Write the request to a file so you can reuse it if the connection drops:

Linux / macOS - Bash
cat > "$STATE/service-request.json" <<'JSON'
{
  "type": "application",
  "display_name": "My website"
}
JSON

uuid > "$STATE/service.key"
Windows - PowerShell 7.4+
Save-Json @{
    type = 'application'
    display_name = 'My website'
} "$State/service-request.json"
New-Key "$State/service.key"
Node.js - all operating systems
await saveJson(`${state}/service-request.json`, {
  type: 'application', display_name: 'My website',
});
await newKey(`${state}/service.key`);

Send it:

Linux / macOS - Bash
slice_api \
  --header 'Content-Type: application/json' \
  --header "X-Idempotency-Key: $(cat "$STATE/service.key")" \
  --data-binary @"$STATE/service-request.json" \
  "$SLICE_BASE/services" > "$STATE/service.json"

jq .data "$STATE/service.json"
SERVICE_ID=$(jq -er '.data.service_id' "$STATE/service.json")
Windows - PowerShell 7.4+
$service = Invoke-Api -Uri "$SliceBase/services" -Token $SliceToken -Method Post `
    -KeyFile "$State/service.key" -BodyFile "$State/service-request.json"
Save-Json $service "$State/service.json"
$service.data | ConvertTo-Json -Depth 30
$ServiceId = $service.data.service_id
Node.js - all operating systems
{
  const service = await api(`${sliceBase}/services`, {
    token: sliceToken, method: 'POST', keyFile: `${state}/service.key`,
    bodyFile: `${state}/service-request.json`,
  });
  await saveJson(`${state}/service.json`, service);
  console.log(service.data);
  serviceId = service.data.service_id;
}

This creates the service configuration. It does not upload or start your application. If you retry, reuse the saved request and key; do not generate another key.

3. Create a service token#

Use a separate service token for deployment automation. This example grants configuration, deployment and storage access to this service only:

Linux / macOS - Bash
# Generate once and save privately; reuse this value after a lost response.
[ -f "$STATE/service-token-key.txt" ] || uuid > "$STATE/service-token-key.txt"
SERVICE_TOKEN_KEY=$(cat "$STATE/service-token-key.txt")
cat > "$STATE/token-request.json" <<'JSON'
{
  "name": "Website deployments",
  "expires_in_days": 90,
  "permissions": [
    "read",
    "applications:manage",
    "deploy",
    "storage:manage"
  ]
}
JSON

slice_api \
  --header "X-Idempotency-Key: $SERVICE_TOKEN_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @"$STATE/token-request.json" \
  "$SLICE_BASE/services/$SERVICE_ID/deployment-tokens" \
  > "$STATE/service-token.json"

# Display metadata without printing the secret.
jq '.data | del(.token)' "$STATE/service-token.json"
SERVICE_TOKEN=$(jq -er '.data.token' "$STATE/service-token.json")
Windows - PowerShell 7.4+
Save-Json @{
    name = 'Website deployments'
    expires_in_days = 90
    permissions = @('read', 'applications:manage', 'deploy', 'storage:manage')
} "$State/token-request.json"
New-Key "$State/service-token-key.txt"
$issued = Invoke-Api -Uri "$SliceBase/services/$ServiceId/deployment-tokens" `
    -Token $SliceToken -Method Post -BodyFile "$State/token-request.json" `
    -KeyFile "$State/service-token-key.txt"
Save-Json $issued "$State/service-token.json"
# Display metadata without printing the secret.
$issued.data | Select-Object * -ExcludeProperty token
$ServiceToken = $issued.data.token
# Continue with the deployment guide using the same helper functions.
$Base = "$ApiUrl/v1/deploy/services/$ServiceId"
Node.js - all operating systems
{
  await saveJson(`${state}/token-request.json`, {
    name: 'Website deployments', expires_in_days: 90,
    permissions: ['read', 'applications:manage', 'deploy', 'storage:manage'],
  });
  await newKey(`${state}/service-token.key`);
  const issued = await api(`${sliceBase}/services/${serviceId}/deployment-tokens`, {
    token: sliceToken, method: 'POST', bodyFile: `${state}/token-request.json`, keyFile: `${state}/service-token.key`,
  });
  await saveJson(`${state}/service-token.json`, issued);
  const { token, ...metadata } = issued.data;
  console.log(metadata);
  serviceToken = token;
  base = `${apiUrl}/v1/deploy/services/${serviceId}`;
  // Continue with deployment examples using these helpers and this service token.
}

Token names are optional in the API and limited to 120 characters. Portal requires a name when creating a token. Keep the returned token and expiry in your private credentials file, then follow Deploy a service.

Service-token issuance is replay-safe with X-Idempotency-Key (required). Persist a unique key before issuing. The first response is HTTP 201 with the one-time token, replayed:false and secret_available:true. A retry returns HTTP 200 with the original ID, replayed:true, secret_available:false and no secret. A changed payload with the same key returns IDEMPOTENCY_CONFLICT. Never overwrite a saved secret with a replay response.

With tokens:manage, use GET /v1/deploy/slices/{sliceId}/services/{serviceId}/deployment-tokens to list non-secret metadata, including name, service/slice IDs, creation/expiry, grants and revocation. Only tokens issued for this slice are included. Revoke exactly the inaccessible token with DELETE on that path followed by /{tokenId}, then issue a replacement with a new key. Revoking a service token does not revoke the working slice token or another service's token. Portal shows token names and scope in the slice API tokens list. Secrets are never returned by list or replay.

Add storage#

Choose a name such as app-data: 1-63 characters, starting with a lowercase letter. Use only lowercase letters, numbers, hyphens or underscores. API requests must already use lowercase; Portal converts the name to lowercase as you type.

A volume can be created and attached in one request. The mount path is inside the container and must begin with /.

Linux / macOS - Bash
cat > "$STATE/storage-request.json" <<JSON
{
  "name": "data",
  "service_id": "$SERVICE_ID",
  "mount_path": "/data",
  "compose_service_name": "app"
}
JSON

uuid > "$STATE/storage.key"

slice_api \
  --header 'Content-Type: application/json' \
  --header "X-Idempotency-Key: $(cat "$STATE/storage.key")" \
  --data-binary @"$STATE/storage-request.json" \
  "$SLICE_BASE/storage" > "$STATE/storage.json"

jq .data "$STATE/storage.json"
Windows - PowerShell 7.4+
Save-Json @{
    name = 'data'
    service_id = $ServiceId
    mount_path = '/data'
    compose_service_name = 'app'
} "$State/storage-request.json"
New-Key "$State/storage.key"
$storage = Invoke-Api -Uri "$SliceBase/storage" -Token $SliceToken -Method Post `
    -KeyFile "$State/storage.key" -BodyFile "$State/storage-request.json"
Save-Json $storage "$State/storage.json"
$storage.data | ConvertTo-Json -Depth 30
Node.js - all operating systems
{
  await saveJson(`${state}/storage-request.json`, {
    name: 'data', service_id: serviceId, mount_path: '/data', compose_service_name: 'app',
  });
  await newKey(`${state}/storage.key`);
  const storage = await api(`${sliceBase}/storage`, {
    token: sliceToken, method: 'POST', keyFile: `${state}/storage.key`,
    bodyFile: `${state}/storage-request.json`,
  });
  await saveJson(`${state}/storage.json`, storage);
  console.log(storage.data);
}

Use the actual container name; app is the standard application container. Deploy the service to activate the mount. Container-local files do not survive replacement unless they are stored in a persistent volume.

Other storage operations:

What you want to do Request
Create an unattached volume POST /storage with {"name": "archive"}
Attach an existing volume POST /storage/attach with storage_id, service_id, mount_path and optionally compose_service_name
Delete an unattached volume permanently DELETE /storage/{storageId}

Regular file storage created through the public API is snapshot-enabled and eligible for file backup groups. Storage created for a managed database service defaults to snapshots disabled; use database backups for its data. This does not create a backup schedule; configure and activate a backup group separately.

These paths are relative to SLICE_BASE. Each mutation requires an idempotency key. Inspect inventory before retrying. Deleting storage requires storage:delete; attached volumes and volumes with snapshots cannot be deleted through this flow. Use Portal to edit or remove individual mounts.

Connect services internally#

The service configuration response includes internal_hostname. The slice inventory also includes it on each item in data.services, so a slice token can discover another service without needing that service's deployment token.

For example, find a PostgreSQL service by its saved ID:

Linux / macOS - Bash
slice_api "$SLICE_BASE" | jq --arg id "$POSTGRES_SERVICE_ID" \
  '.data.services[] | select(.id == $id) | {id, internal_hostname}'
Windows - PowerShell 7.4+
$slice = Invoke-Api -Uri $SliceBase -Token $SliceToken
$slice.data.services | Where-Object id -EQ $PostgresServiceId | Select-Object id, internal_hostname
Node.js - all operating systems
{
  // Set postgresServiceId to the saved service ID.
  const slice = await api(sliceBase, { token: sliceToken });
  const service = slice.data.services.find(item => item.id === postgresServiceId);
  if (!service) throw new Error('PostgreSQL service is not in this slice');
  console.log({ id: service.id, internal_hostname: service.internal_hostname });
}

Use the returned hostname as the application's database host and PostgreSQL's container port (normally 5432). Both services must share the same Docker virtual network. Deploy PostgreSQL first and configure it to listen on that port. No public database endpoint is needed.

The hostname stays the same across redeployments of the same service. It is not the display name, a public domain, or a readiness check. The field is null for other service templates; do not construct a hostname from their display names.

Tokens#

The permissions on your token determine which operations are available:

Operation Required permission
Inspect the slice read
Create/configure services applications:manage
Deploy deploy
Create/attach storage storage:manage
Delete services applications:delete
Permanently delete storage storage:delete
List/revoke slice tokens or issue service tokens tokens:manage
Renew the current slice token tokens:renew

A delegated service token cannot receive permissions or a lifetime beyond those allowed by the slice token issuing it.

List slice tokens:

Linux / macOS - Bash
slice_api "$SLICE_BASE/tokens" | jq .data
Windows - PowerShell 7.4+
(Invoke-Api -Uri "$SliceBase/tokens" -Token $SliceToken).data | ConvertTo-Json -Depth 30
Node.js - all operating systems
console.log((await api(`${sliceBase}/tokens`, { token: sliceToken })).data);

Renew the slice token making the request:

Linux / macOS - Bash
slice_api \
  --header 'Content-Type: application/json' \
  --data '{}' \
  "$SLICE_BASE/tokens/renew" > "$STATE/replacement-token.json"

jq '.data | del(.token)' "$STATE/replacement-token.json"
Windows - PowerShell 7.4+
Save-Json @{} "$State/renew-request.json"
$replacement = Invoke-Api -Uri "$SliceBase/tokens/renew" -Token $SliceToken `
    -Method Post -BodyFile "$State/renew-request.json"
Save-Json $replacement "$State/replacement-token.json"
$replacement.data | Select-Object * -ExcludeProperty token
Node.js - all operating systems
{
  await saveJson(`${state}/renew-request.json`, {});
  const replacement = await api(`${sliceBase}/tokens/renew`, {
    token: sliceToken, method: 'POST', bodyFile: `${state}/renew-request.json`,
  });
  await saveJson(`${state}/replacement-token.json`, replacement);
  const { token, ...metadata } = replacement.data;
  console.log(metadata);
}

The replacement retains the name, permissions and lifetime policy unless you request a permitted reduction. Its secret is returned once. A second renewal of the same token is rejected. Store the new token, update your clients, and verify it before revoking the old one.

Revoke a slice token by its ID, using a token authorized to manage it:

Linux / macOS - Bash
# Copy the ID from the token list. This is not the token secret.
TOKEN_ID=replace-with-token-id
slice_api --request DELETE "$SLICE_BASE/tokens/$TOKEN_ID" | jq .data
Windows - PowerShell 7.4+
# Copy the ID from the token list. This is not the token secret.
$TokenId = 'replace-with-token-id'
$revoked = Invoke-Api -Uri "$SliceBase/tokens/$TokenId" -Token $SliceToken -Method Delete
$revoked.data | ConvertTo-Json -Depth 30
Node.js - all operating systems
{
  // Copy the ID from the token list. This is not the token secret.
  const tokenId = 'replace-with-token-id';
  console.log((await api(`${sliceBase}/tokens/${tokenId}`, {
    token: sliceToken, method: 'DELETE',
  })).data);
}

This revokes access; it does not delete the list entry. Adding ?cascade=true explicitly revokes descendant slice tokens in the renewal chain. Normal revocation does not revoke previously issued service tokens. Use Portal to rename tokens or remove revoked entries from the list.

Delete a service#

Deletion retains its storage and backups. It requires applications:delete and an idempotency key:

Linux / macOS - Bash
uuid > "$STATE/delete-service.key"
slice_api \
  --request DELETE \
  --header "X-Idempotency-Key: $(cat "$STATE/delete-service.key")" \
  "$SLICE_BASE/services/$SERVICE_ID" | jq .data
Windows - PowerShell 7.4+
New-Key "$State/delete-service.key"
$deleted = Invoke-Api -Uri "$SliceBase/services/$ServiceId" -Token $SliceToken `
    -Method Delete -KeyFile "$State/delete-service.key"
$deleted.data | ConvertTo-Json -Depth 30
Node.js - all operating systems
{
  await newKey(`${state}/delete-service.key`);
  console.log((await api(`${sliceBase}/services/${serviceId}`, {
    token: sliceToken, method: 'DELETE', keyFile: `${state}/delete-service.key`,
  })).data);
}

A 202 response means deletion was accepted. Refresh slice inventory or watch Portal until the service disappears. Do not treat acceptance as completed deletion.

Check provisioning progress#

When a request returns operation_id, save it and inspect the operation:

Linux / macOS - Bash
OPERATION_ID=$(jq -er '.data.operation_id' "$STATE/service.json")
slice_api "$SLICE_BASE/operations/$OPERATION_ID" | jq .data
Windows - PowerShell 7.4+
$OperationId = (Read-Json "$State/service.json").data.operation_id
(Invoke-Api -Uri "$SliceBase/operations/$OperationId" -Token $SliceToken).data | ConvertTo-Json -Depth 30
Node.js - all operating systems
{
  const operationId = (await readJson(`${state}/service.json`)).data.operation_id;
  console.log((await api(`${sliceBase}/operations/${operationId}`, { token: sliceToken })).data);
}

SLICE_OPERATION_INCOMPLETE means provisioning was interrupted. Inspect inventory and contact support with the operation ID. Do not bypass it with a new retry key.

Manage backup groups and sets#

Use a Bearer slice token. GET /v1/deploy/slices/{sliceId}/backups requires read and returns data.revision, eligible resources, groups, captured sets, legacy holdings, budget and restore operations. It is also the polling endpoint for backup capture, cleanup and restore progress. Without a backup plan, the view reports state:legacy and revision 0. Contact support to enable backup groups before using group scheduling or restore operations.

The following POST paths are relative to /v1/deploy/slices/{sliceId}/backups. Each requires X-Idempotency-Key (1-128 letters, digits, underscores, dots, colons or hyphens) and a body with the current revision and action data:

Path Permission Action data
/groups/preview backups:manage group, optional existing id and retention confirmations
/groups backups:manage Same reviewed group input; pruning also requires backups:delete
/groups/delete backups:delete group_id; retained backups are preserved
/groups/run backups:manage group_id; queues a set on an active plan
/sets/protect backups:manage set_id, boolean protected
/sets/retry backups:manage set_id of the failed capture
/sets/delete backups:delete set_id; protected sets are rejected
/legacy/delete backups:delete kind (storage or database), artifact_id
/cleanup/retry backups:delete set_id and member_key (kind:resourceId), or legacy kind and artifact_id

For example, preview a nightly group using resource IDs from data.eligible:

{
  "revision": 3,
  "data": {
    "group": {
      "name": "Application backups",
      "members": [{"kind": "storage", "id": "STORAGE_ID"}],
      "schedule": {"mode": "nightly", "timezone": "Europe/Stockholm"},
      "retention_sets": 7
    }
  }
}

Preview validates the key but saves neither a receipt nor a new revision. Review its budget and deletion IDs before saving. Retention supports a count of 1-10000 sets or retention:{"mode":"tiered","days":7,"weeks":4,"months":3}; tiered retention takes precedence and must reserve at most 10000 sets. Interval schedules use mode:interval, interval_hours of 3, 6, 12 or 24, and local start_time in HH:mm format. Omitted timezone uses the tenant timezone.

When editing, include the existing group id. Use the preview's delete_set_ids as confirm_delete_set_ids and, when opting into legacy pruning with prune_legacy:true, its delete_legacy_ids as confirm_delete_legacy_ids. Saving with legacy pruning or nonempty set deletion confirmation requires backups:delete as well as backups:manage. If the save returns cleanup_required:true and schedule_saved:false, it has queued cleanup; poll the view until cleanup finishes, preview again and save with the new revision and a new key. Accepted deletion does not prove that the backup has physically been removed. Cleanup retries require failed cleanup and the previous attempt to have finished processing.

Mutation results include revision and budget, plus action-specific fields. Retry an uncertain accepted request with the same body and key. On BACKUP_PLAN_CHANGED, reload the view and review the change again. A new intent uses a new key. IDEMPOTENCY_CONFLICT means a key was reused with different action data. Tokens do not acquire these backup permissions automatically.

Restore a backup set and recover a failed restore#

Restores require backups:restore and an active backup plan. First POST {"set_id":"SET_ID"} to /backups/sets/restore-preview. Inspect the returned review, affected services, conflicts and warning. Then POST {"set_id":"SET_ID","review_id":"REVIEW_ID","confirm_overwrite":true} to /backups/sets/restore with a new X-Idempotency-Key. These paths use the same /v1/deploy/slices/{sliceId} prefix. Restore bodies do not use the revision/data wrapper from group mutations.

Start returns HTTP 202 with a restore resource in data. Poll the backups view and locate its ID in data.restores. Services are stopped and resumed around the restore; pause external writers separately. Changed runtime state requires a new preview. Retry an uncertain start with the same body and key.

For a failed operation, read current_state.step_index and obtain that step's dispatch_id from desired_state.steps. POST {"restore_id":"RESTORE_ID", "dispatch_id":"FAILED_STEP_DISPATCH_ID"} to /backups/restores/retry. Alternatively, POST those fields plus "confirm_partial_data":true to /backups/restores/resume-services to accept partial data and resume services without completing the remaining restore steps. Both recovery endpoints require backups:restore, return the operation with HTTP 200 and use dispatch_id to identify the specific failed step and reject stale recovery attempts; no idempotency header is required. Refresh the operation after an uncertain response before trying recovery again.

See the OpenAPI reference for request and response schemas.

Restore files or a database separately#

Individual restores use an active slice backup plan and a Bearer slice token with backups:restore. They restore one artifact, including retained legacy backups. They do not restore the other components of a backup set.

Use GET /v1/deploy/slices/{sliceId}/backups to find artifact IDs in sets[].members[].artifact_id or legacy_holdings[].artifact_id. Use storage for file backups and database for database backups.

First, POST /v1/deploy/slices/{sliceId}/backups/artifacts/restore-preview:

{"artifact":{"kind":"storage","id":"STORAGE_SNAPSHOT_ID"}}

Inspect data.warning, data.affected_service_ids, data.steps, data.work_order_ids (conflicting operations) and data.active_restore_ids. Preview does not change data or stop services. Starting the reviewed restore stops all running services in the slice, overwrites only the selected resource, and resumes services after success. Pause external writers separately.

Then POST /v1/deploy/slices/{sliceId}/backups/artifacts/restore with X-Idempotency-Key: YOUR_UNIQUE_REQUEST_KEY and:

{
  "artifact":{"kind":"storage","id":"STORAGE_SNAPSHOT_ID"},
  "review_id":"REVIEW_ID_FROM_PREVIEW",
  "confirm_overwrite":true
}

For a database restore, use {"kind":"database","id":"DATABASE_BACKUP_ID"} in both requests. A review is bound to the artifact and current runtime state; changed state requires a new review. Retry an uncertain request with the same body and idempotency key.

A successful start returns HTTP 202 with the restore operation in data. Poll GET /v1/deploy/slices/{sliceId}/backups and find its ID in data.restores. Existing /backups/restores/retry and /backups/restores/resume-services recovery endpoints also apply. Backups from another slice, unusable archives, and backups pending deletion are rejected. Whole-set restore remains available under /backups/sets/restore-preview and /backups/sets/restore.

Data imports#

Import a local .sql.gz database dump or .zip file archive from a backup or another hosting provider into an isolated destination. The default requires an empty destination. Explicit replacement mode clears its contents first, after a separate review and approval. Imports never merge data, change retention or start the application. The destination must support data imports; admission checks this when creating the upload. Service tokens cannot use these slice endpoints. No separate feature-enablement request is needed.

Choose the workflow by where the data is stored:

Workflow Destination Permission Approval
Retained individual backup restore (/backups/artifacts/restore) Original resource in the slice; existing data is overwritten backups:restore review_id and confirm_overwrite:true
Local file upload/import (/data-imports) Selected isolated database or storage resource; empty by default backups:upload and backups:import for the full workflow review_id and mode-specific confirmation

Uploaded files are private import artifacts. They are not inserted into the retained backup catalog and cannot be passed to /backups/artifacts/restore.

Grant backups:upload explicitly for upload/status/cancellation and backups:import explicitly for validation/approval. Neither is granted to existing or default tokens; upload does not imply import. Use both for the full workflow. Permissions and current workspace ownership are checked on every request. Token renewal cannot widen grants.

The preferred base path is /v1/deploy/slices/{sliceId}/data-imports. The former /v1/deploy/slices/{sliceId}/backup-imports routes remain compatibility aliases for every operation. Both names access the same uploads, reviews and idempotency records. Existing permission names (backups:upload, backups:import) are unchanged; clients do not need new grants. No backup schedule is required.

All paths below use the preferred base:

Method and suffix Success Permission Purpose
GET /capabilities 200 backups:upload Supported formats, limits and isolation requirements
POST (no suffix) 201 backups:upload Create upload with kind, target_id, original file bytes and sha256; supply X-Idempotency-Key
GET /{importId} 200 backups:upload Read durable state and uploaded_bytes, including validation/import progress
PUT /{importId}/chunks 200 backups:upload Stream next chunk as application/octet-stream with Upload-Offset, Content-Length, X-Content-SHA256
POST /{importId}/finalize 200 backups:upload Verify full size and checksum
POST /{importId}/validate 202 backups:import Send {"confirm_stop_services":true} for restore preparation, empty mode and root detection; add mode:"replace" for replacement and optional content_root for a ZIP folder
POST /{importId}/start 202 backups:import Send the preview's review_id and mode-specific confirmation, with X-Idempotency-Key
POST /{importId}/cancel 200 backups:upload Cancel an inactive upload or preview

All JSON requests use Content-Type: application/json and an unwrapped body, not a data request wrapper. All responses use the normal envelope: read the operation from data, and request failures from error. A successful status poll can still describe a failed operation in data.status and data.error.

Use the original file unchanged. Chunks are sequential, 8 MiB except the final remainder. After an interrupted request, GET the operation and resume from uploaded_bytes. Retrying an acknowledged chunk with its original offset, length and checksum is safe. A changed checksum/body requires a new key/upload. Uploads are private, limited to 8 GiB each, and expire after 24 hours. Expanded archives are limited to 32 GiB and 100,000 entries. Reservations include space for both uploaded chunks and final assembly.

Poll through preparing and validating until ready, needs_root_selection, invalid or recovery_required. Preparation uses the same service stop/start commands as backup restore. It stops slice services and starts only the selected, already-deployed database. Unknown or never-deployed placeholders require an authoritative container check; unknown state is not assumed stopped. Preview names the exact destination and maps representative archive paths to output paths. A validated UUID snapshot folder with its explicit data/ folder is recognized automatically; arbitrary application data/ folders are preserved. Ambiguous layouts require selecting a listed folder, or "" for archive root, and validating again. Excluded sibling files are disclosed. Hidden files and relative directories are preserved; links, special files, duplicate paths, traversal and corrupt ZIP entries are rejected.

Review approval expires after 10 minutes and is bound to the artifact checksum, root, import mode, destination revision and destination fingerprint. Validation never starts an import or clears data. Import rechecks the destination and isolation immediately before writing. The first version supports local legacy-layout storage and table-only MariaDB exports. Views, triggers/routines, unsafe SQL and dumps needing data omissions are rejected. The database must be an existing application schema (empty unless replacement is explicitly approved) in a normal TCP runtime with no other client sessions. No socket-only configuration is required. The agent must advertise data_import_restore_lifecycle_v1. Controlled startup uses the normal stop intent rather than disabling host startup protection. Only that database service may run; application writers remain stopped. Pause external database writers separately, just as for backup restore. External storage access must be disabled, and running writable container mounts are rejected. Unsupported service-family path adoption is rejected rather than guessed.

The preview lists resume_service_ids: only application services running before preparation. The optional approval field resume_services:true resumes those services after verified import; default false leaves them stopped. Previously stopped or never-deployed services are never started. A resume failure retains protection and requires recovery. Poll through resuming until complete.

complete means storage bytes/directories match the inspected manifest, or SQL execution completed and the expected table names were read back. This is not an application functional test or a guarantee that separately exported database and storage snapshots represent the same instant. Keep the clone isolated until its own acceptance checks pass.

An interrupted or failed apply becomes recovery_required: the destination stays protected and the application stays stopped. Do not resubmit as a new import or delete its operation record to bypass protection. Contact support to inspect partial destination data and resolve the failed operation. Automatic rollback and self-service recovery are not provided in this version. Active preparation/validation/import/resume and recovery artifacts are excluded from TTL cleanup; abandoned inactive uploads and previews are removed after expiry.

Clear existing data before import#

Empty mode remains the default. To replace data, validate with:

{"mode":"replace","confirm_stop_services":true}

For a selected ZIP folder, send {"mode":"replace","content_root":"site"}. Poll until ready. Review preview.mode, preview.destination, existing_entries (tables or files and folders), and existing_bytes (storage). Then approve with a new X-Idempotency-Key:

{
  "review_id": "REVIEW_ID_FROM_REPLACEMENT_PREVIEW",
  "confirm_clear_destination": true,
  "confirm_target_id": "EXACT_UPLOAD_TARGET_ID"
}

Do not send confirm_empty_destination for replacement. A review from empty mode cannot authorize clearing. Changing modes requires validation again. The target agent must advertise private_data_import_replace_v1; older agents are rejected.

This deletes all contents of the selected storage mount or all tables in the selected database before importing. Other storage paths and database schemas are not cleared. Database replacement currently rejects views, sequences, routines, events and foreign keys referencing this schema from another database. Storage replacement rejects symbolic/hard links, special files and nested mounts. Its existing inventory must fit the advertised entry and expanded-byte limits. Storage must have enough free capacity for the import before clearing begins.

Keep a separate backup. Clearing and import are not atomic: failure may leave an empty or partially imported destination. The application stays stopped and recovery is manual. Once replacement begins, a durable agent marker prevents any retry of that operation from clearing again, including after restart. Reuse the same approval idempotency key to check a previously submitted request; never create a new import to bypass recovery_required.

Resumable upload example#

Use a slice token with both grants. First GET /data-imports/capabilities and read data.limits; the response describes supported formats and limits, but does not validate a particular destination. Find the destination resource ID in the slice inventory: target_id is a database or storage ID, not a service ID, backup ID or filesystem path.

For a 10 MiB ZIP, POST /data-imports with a persisted X-Idempotency-Key and the following body. Replace the illustrative digest with the lowercase SHA-256 of the complete original file:

{
  "kind": "storage",
  "target_id": "DESTINATION_STORAGE_ID",
  "bytes": 10485760,
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Use kind:"database" and the destination database ID for a .sql.gz file. Keep the original file unchanged throughout the upload. Persist data.id as importId. To recover a lost creation response, send the same key and body using the same token; a different token is a different issuance identity.

Read data.chunk_bytes (currently 8388608) and send the first chunk:

PUT /v1/deploy/slices/SLICE_ID/data-imports/IMPORT_ID/chunks
Authorization: Bearer SLICE_TOKEN
Content-Type: application/octet-stream
Upload-Offset: 0
Content-Length: 8388608
X-Content-SHA256: SHA256_OF_THIS_CHUNK

[original file bytes 0 through 8388607]

After acknowledgment, data.uploaded_bytes is 8388608. The second request uses Upload-Offset: 8388608, Content-Length: 2097152, and the checksum of that final chunk. This is a raw byte body, not JSON, Base64 or multipart. Never expose the bearer value in logs or shared request examples.

If a request is interrupted, GET /data-imports/{importId} before retrying. Resume at the server's uploaded_bytes, not the number of bytes your client attempted to send. Replaying an acknowledged offset with identical length and checksum is accepted; changing that metadata returns CHUNK_CONFLICT. POST /{importId}/finalize after all bytes are acknowledged. Only an uploaded operation is ready for its first validation.

Automatic root detection and folder selection#

Root selection is optional. POST /{importId}/validate with:

{}

HTTP 202 means validation was accepted. Poll GET /{importId} until its data.status is ready, needs_root_selection or invalid. When ready, inspect data.preview.destination, content_root, examples, excluded_files and warning. Database previews have table counts instead of ZIP directory/path examples; they do not require a root selection.

If the status is needs_root_selection, read data.preview.directories and ask the user to choose a folder. For example, if site is listed, POST /{importId}/validate again with:

{"content_root":"site"}

This maps site/assets/logo.png to assets/logo.png below the reviewed destination mount. Use {"content_root":""} to select the archive root explicitly; omitting the field asks for automatic detection again. The value is an archive-relative directory, never an absolute destination path. Choosing a folder does not bypass archive safety or destination checks. Poll again and review the new preview, including any excluded sibling files.

Approve, poll and handle failures#

Once data.status is ready, POST /{importId}/start with a new persisted X-Idempotency-Key and the exact data.preview.review_id:

{
  "review_id": "REVIEW_ID_FROM_LATEST_PREVIEW",
  "confirm_empty_destination": true
}

Approval is a separate explicit step; do not automatically approve a preview merely because validation finished. HTTP 202 is acceptance, not completion. Poll GET /{importId} until complete or recovery_required. Retry a lost start response with the same key and body; creating a new import is not a recovery mechanism. The application remains stopped on both outcomes.

Response or operation state Client action
CHUNK_OFFSET_MISMATCH (409) GET status and resume at uploaded_bytes with the advertised chunk size
CHUNK_CONFLICT or IDEMPOTENCY_CONFLICT (409) Check saved file, checksum, key and body; do not substitute different data under the same request
INVALID_ARTIFACT (400) Check the original bytes and checksum; inspect status before retrying a failed transfer
IMPORT_REVIEW_REQUIRED or IMPORT_TARGET_CHANGED (409) Validate again, review the fresh destination/root and explicitly approve the new review
IMPORT_AGENT_UPDATE_REQUIRED, IMPORT_WRITERS_NOT_STOPPED, IMPORT_EXTERNAL_WRITERS or DESTINATION_BUSY (409) Resolve destination readiness/isolation with the hosting support team, then retry the appropriate step
BACKUP_UPLOAD_CAPACITY (409) Wait for capacity or cancel abandoned inactive uploads; cleanup is asynchronous
invalid Inspect data.error; correct the archive/destination problem before validation again
recovery_required Stop automatic retries and request support recovery; preserve the operation and upload
expired or cancelled Create a fresh upload if still needed; keep the original data file

POST /{importId}/cancel can abandon an inactive upload or preview. It does not undo destination changes. Cancellation is rejected during validation, import, recovery, or after successful completion.

Managed services#

See database and access management for CRUD, credentials and password rotation.

Use managed services when you need a platform-managed runtime, rather than an application container using your own image. The first supported type is mariadb. WordPress bundles are not yet exposed through this catalogue. Imports are a separate workflow and are not part of provisioning.

  1. Discover types with GET /v1/deploy/slices/{sliceId}/managed-service-types using a slice token with read.
  2. Configure with POST /v1/deploy/slices/{sliceId}/managed-services, a saved X-Idempotency-Key, and applications:manage plus storage:manage grants:
{
  "type": "mariadb",
  "display_name": "Sorento database",
  "configuration": { "database_name": "sorento_test" }
}

The 201 response envelope contains operation_id, service_id, service_ids, database_id, storage_ids, status:"configured" and runtime_changed:false. The service inherits the slice tenant, node, network and allowance. Root credentials are managed internally; no public SQL port, phpMyAdmin, domain or TLS route is created. This does not issue an application database user/password; use the database access controls to create the access your application needs. Image selection follows the platform's managed MariaDB template, not a customer-supplied image or tag.

  1. Save the returned identifiers. Deploy with POST /v1/deploy/slices/{sliceId}/services/{serviceId}/apply, an empty body, a separate saved X-Idempotency-Key, and the deploy grant. This queues preflight, service deployment and database initialization. It affects this service, not its neighbours. 202 is acceptance, not readiness.
  2. Use GET /v1/deploy/slices/{sliceId}/managed-services for observed service and database state, including queued preflight and its failures. The response includes the latest deployment operation and work-order IDs for support. running requires a running service and successful application of this logical database. Check observed_at and database_observed_at; historical success is not a new health check.

Repeated creation with the same key and body returns the same identifiers. Changed input under that key returns IDEMPOTENCY_CONFLICT. If creation fails, inspect GET /v1/deploy/slices/{sliceId}/operations/{operationId}. A partial failure retains the intended service/database identifiers for support-assisted recovery; do not change the key to bypass it. Incomplete managed configurations cannot be deployed. Existing placeholder applications are not converted or removed.

In Portal: Services → your slice → Add managed service. Choose MariaDB, enter the service and database names, then Create managed service. Review before Deploy service, or choose Deploy later. Reopen Add managed service to continue a configured service. Deployment progress remains on the Services page.