Build something. Ship it.

Deploy an application from a Dockerfile or a prebuilt Linux container image. No GitHub integration or container registry account is required.

• API base URL: https://api.budgethost.io
• OpenAPI reference for API clients and AI assistants.
• Deploy an existing application
• Create applications and storage in a service slice

Start with your slice#

The API address is always https://api.budgethost.io. You only need two values from my.budgethost: your SLICE_ID and SLICE_TOKEN.

Open your slice to find its SLICE_ID. Under API tokens, create a slice token and copy its value into your private credentials file as SLICE_TOKEN. my.budgethost shows the token's scope and expiry date.

Your slice is the CPU, memory and storage allocation you ordered. It can start empty; you do not need a service ID to begin.

1. Inspect your slice and its existing applications and storage.
2. Create an application, or select an existing one from the slice inventory.
3. Use the slice token to issue a deployment token for that application.
4. Configure, upload and deploy using the returned service ID and service token.

A slice token manages applications and storage within your allocation. A service token is the narrower credential used to configure and deploy one application. You obtain it through the slice API; it is not an additional credential you need from BudgetHost before getting started. The two token scopes are not interchangeable.

Follow applications and storage after checking your slice below. If your application already exists, reuse it and its storage instead of provisioning a duplicate. For routine releases with an existing service token, go directly to the deployment guide.

Credentials and expiration#

Manage your tokens in my.budgethost. Open a slice or application and select API tokens to create a token, view its scope and expiry date, renew it, or revoke access. Use a separate token for each person or automation so access can be managed individually. Token values are shown once; existing values cannot be retrieved.

Tokens expire after 90 days by default. my.budgethost shows approaching expirations so you can renew credentials before deployments are interrupted. Renewal issues a replacement token with a new expiry date; it does not silently update credentials stored on your computer or in an automation.

To renew a slice or service token:

1. Open the token in my.budgethost and choose Renew.
2. Copy the replacement value into your private credentials file or automation's secret store. Record its expiry date.
3. Verify the replacement with a read request to its slice or service endpoint.
4. Once all consumers use the replacement, revoke the old token in my.budgethost.

The old token remains valid until it expires or you revoke it, allowing a controlled switch. Finish active deployments before switching credentials: retry keys are token-scoped and revocation can block further deployment stages. An expired or revoked token cannot make API requests, but it does not shut down an application that is already running. If a token is exposed, revoke it immediately and issue a replacement.

Slice and service tokens have separate lifecycles. Revoking a slice token does not revoke service tokens it previously issued; manage those on their applications in my.budgethost. For automated provisioning, an active slice token can also issue a service token through the API as shown in the slice guide.

Store your initial slice credentials in a trusted, local .slice.env file, excluded from Git and source archives:

SLICE_ID=REPLACE_WITH_YOUR_SLICE_ID
SLICE_TOKEN=REPLACE_WITH_YOUR_SLICE_TOKEN

The examples require Bash, curl with --fail-with-body, jq, GNU tar, sha256sum, and Python 3. Load only your own trusted credentials file:

chmod 600 .slice.env
set -euo pipefail
set +x
source .slice.env
SLICE_BASE="https://api.budgethost.io/v1/deploy/slices/$SLICE_ID"
umask 077
# Keep response files outside the application source directory.
STATE=$(mktemp -d)
printf 'Save this deployment state directory: %s\n' "$STATE"
slice_api() { curl --fail-with-body -sS -H "Authorization: Bearer $SLICE_TOKEN" "$@"; }
uuid() { python3 -c 'import uuid; print(uuid.uuid4())'; }
slice_api "$SLICE_BASE" > "$STATE/slice.json"
jq .data "$STATE/slice.json"

Do not paste tokens into chat, tickets, repositories, screenshots, or build logs. Do not disable TLS verification. Runtime secrets belong in the secret API; never bake them into an image or source archive.

API conventions#

Send Authorization: Bearer <token>. JSON request bodies use the documented fields directly, without a data wrapper. Responses wrap results in data; errors include error.code, error.message, and sometimes error.details. Preserve the response request/correlation IDs when contacting support, but redact credentials and secrets.

Creation and deployment start require X-Idempotency-Key. Keep the key and exact request body for retries with the same token. Use a new key for each new operation. A changed body with a reused key returns 409. Retrying with a new token/key can create a separate operation. Only one deployment may be active per service.

Boundaries#

The slice shares its CPU, memory and storage allowance across its applications. Storage accounting includes all slice volumes, including database and file volumes; view combined usage and your plan limits in my.budgethost. BudgetHost manages the infrastructure behind your allocation. The customer API manages application settings, secrets, persistent mounts and deployment. Manage your plan and public domains in my.budgethost.

Deployment success confirms the configured HTTP readiness check and required platform work completed for the deployed image. It does not validate the customer's business logic. Replacing an application can briefly interrupt traffic. Rollback is explicit and restores an image only, not database contents, files or configuration.

Instructions for AI assistants#

Start with the supplied SLICE_ID and SLICE_TOKEN. Read openapi.json and inspect the slice before creating an application. Obtain a service token through the slice API, then read that service's capabilities before deploying. Use only resources inside the supplied slice. Inspect existing configuration and storage before creating resources. Preview and review configuration before applying it. Persist IDs, request bodies and retry keys. Poll until succeeded or failed; a 202 response is acceptance, not completion. Do not invent secrets, domain names, resource IDs, readiness paths or successful test results. Never include local credentials or production data in an uploaded archive.