BudgethostAPI DOCUMENTATION
API v1OpenAPI
RUNTIME GUIDEREST / JSON

Operate your application

Private databases, health checks, maintenance jobs and resource measurements within your slice.

Use the service bearer token and base URL from Deploy a service. This contract is public-runtime-v1. Check GET $BASE/capabilities before use: each operation reports supported, permitted, and required_permission. TOKEN_PERMISSION_DENIED means the token lacks the grant; RUNTIME_CAPABILITY_UNAVAILABLE means the operation is not available for this service. Contact support if you need it.

For HTTP readiness, use {"path":"/health","expected_status":200} (type http is optional). The default is exactly 200; explicit expected statuses may be 200-399. A 403 or 404 is unhealthy. Results expose the observed HTTP status, expected status and probe timestamp. A successful prior deployment is historical readiness evidence, not a guarantee of current application health.

Private MariaDB and Redis#

For a platform-managed MariaDB service with a registered SQL database and managed credentials, use Managed services. The application workflow below is for self-managed images; it does not register a managed database resource.

Create an ordinary application with a slice token:

{"type":"application","display_name":"database","public_route":false}

Send it to POST /v1/deploy/slices/{sliceId}/services with an idempotency key. public_route:false creates no public HTTP route or published port. Services in the same slice use its shared network. Get the database's internal_hostname from the slice inventory and connect to the database container port (3306 for MariaDB, 6379 for Redis). Do not use a host port or public URL for these connections.

Deploy a source archive based on your chosen pinned image, or an image archive, using the ordinary deployment flow. Configure the image's native HEALTHCHECK with a bounded database/cache probe. If the base image lacks a health check, add one in your Dockerfile; no HTTP wrapper is required. For a Redis image containing redis-cli, an unauthenticated development example is:

HEALTHCHECK --interval=5s --timeout=3s --start-period=10s --retries=5 \
  CMD redis-cli ping | grep -qx PONG

For authenticated services, configure the health command to use an environment secret or an image-supported credential file. Do not bake credentials into the image or manifest. Use a real connection/initialization check appropriate to your MariaDB image. A healthy TCP listener alone does not prove database readiness.

Preview and apply a manifest such as:

{
  "version": 1,
  "port": 3306,
  "readiness": {"type": "docker"},
  "environment": {
    "MARIADB_DATABASE": {"required": true},
    "MARIADB_USER": {"required": true},
    "MARIADB_PASSWORD": {"required": true, "secret": true},
    "MARIADB_ROOT_PASSWORD": {"required": true, "secret": true}
  },
  "storage": [{"name": "database", "mount_path": "/var/lib/mysql"}]
}

Create storage within the slice, bind it to the declared mount, and bind secrets using the write-only service secret endpoint described in the deployment guide. Redis persistence, if enabled, uses its image's configured data directory. Docker readiness requires a running container and a successful HEALTHCHECK after the operation started. Deployment completion still requires the intended image digest. An image without a HEALTHCHECK fails this gate.

Start, stop and restart#

POST $BASE/start, $BASE/stop, or $BASE/restart accepts {} and requires an explicit lifecycle:manage grant plus X-Idempotency-Key. These operations reuse the deployed containers and preserve volumes. Results include container IDs before and after the operation. Start is not first deployment. Start and restart succeed only after fresh configured readiness. Stop does not remove containers, images or volumes.

Every accepted operation returns HTTP 202 with data.id. Poll GET $BASE/operations/{id} until succeeded, failed, or cancelled. The other states are queued, running, and cancel_requested. A failed operation can have changed runtime state; inspect it before submitting a new operation. Retrying the same request and key returns the same operation. A different payload with the same key returns IDEMPOTENCY_CONFLICT. Job, lifecycle and metrics receipts are retained while the issuing token remains valid, so retrying a completed request does not repeat the operation.

Bounded maintenance jobs#

Jobs require an explicit jobs:run grant. Existing tokens do not acquire it automatically. A slice token may delegate it only if the slice token itself has the grant. Keep read for status polling.

POST $BASE/jobs, with an idempotency key:

{
  "container": "app",
  "argv": ["wp", "cache", "flush", "--path=/var/www/html"],
  "timeout_seconds": 120,
  "memory_bytes": 268435456,
  "cpus": 1,
  "output_bytes": 32768
}

The selected Compose component must have exactly one running container. A job uses that container's immutable image, user, working directory, environment, mounted volumes and network namespace in a separate temporary container. Changes to mounted WordPress files or its database persist; changes to the job's writable image layer do not. Include WP-CLI and a timeout utility supporting -s TERM -k 5 in the application image. No shell is inserted around argv.

Secrets already bound to the service are inherited. Inline environment overrides, custom images and Docker options are not accepted. Keep credentials out of argv. Known secret values are redacted before applying the response output limit.

Limits are 1-600 seconds, 16 MiB-1 GiB memory, 0.1-2 CPUs, 128 processes, and 1-64 KiB output. Jobs remain within the service's shared resource slice. A timeout has code:JOB_TIMEOUT; a nonzero exit code is a failed job. The result includes the exit code, duration and bounded stdout/stderr. output_coverage:bounded_tail means log rotation may have omitted earlier output; output_truncated:true means the returned buffer was capped, and null means completeness is unknown. If job output cannot be safely returned, both output streams are suppressed: output_coverage:unavailable and output_truncated:true. Check this field before relying on output. The job's execution status and exit code remain independent of output availability.

Cancel using POST $BASE/operations/{id}/cancel with {}. Queued jobs cancel immediately. Running jobs remain cancel_requested until termination is confirmed. Cancellation may leave completed application changes in place. Lifecycle actions cannot be cancelled. A lost API connection does not remove the job time limit. Keep polling the operation; contact support if its status remains unsettled.

Resource measurements#

POST $BASE/metrics/samples with {}, a fresh idempotency key, and read queues a snapshot. Poll its operation ID. Repeat at the desired measurement interval and save the results with your benchmark. Collection is on demand, not an automatic time-series subscription. GET $BASE/operations?kind=metrics returns the latest 100 retained operations and reports has_more; it is not a permanent archive.

Each sample includes all service Compose containers, their IDs, start times, restart counts, sample timestamps, cumulative CPU nanoseconds, CPU throttling, current memory, memory limit and peak memory when the engine supplies it. Current memory includes the engine's accounted cache. Unsupported or unavailable counters are null, never an invented zero. Missing/stopped containers and containers changing during collection produce explicit incomplete coverage.

Calculate CPU time from counter differences only when container ID, start time, restart count and membership are unchanged and the counter did not decrease. Divide nanoseconds by 1e9 for CPU seconds. A replacement/restart or decreasing counter starts a new measurement segment. Sum per-container deltas for a service.

After sampling every service, a slice token with read can query GET /v1/deploy/slices/{sliceId}/metrics. This aggregates the latest samples from current members. Missing samples, changed configuration, samples older than 60 seconds, or timestamps more than 10 seconds apart produce incomplete coverage and null totals. The sum of independent container memory peaks is not a slice peak, so aggregate peak memory is always null. These are service-container totals; host overhead and temporary maintenance-job containers are excluded. Finish maintenance jobs before collecting benchmark samples.

Coordinated slice sampling#

Use a slice token with read:

POST /v1/deploy/slices/{sliceId}/metrics/samples
Authorization: Bearer <slice-token>
X-Idempotency-Key: <persisted-collection-key>
Content-Type: application/json

{}

HTTP 202 returns data.id and collection_id. Poll GET /v1/deploy/slices/{sliceId}/metrics/samples/{id}. A collection measures all current members of the slice. It requires 1-64 members; the request body is {}. Only one slice collection may be active at a time. Contact support if the API reports that collection is unavailable for your slice.

The receipt binds membership_revision and each member's configuration_revision. If membership or configuration changes, review the current slice before requesting a new collection with a new key. The sample includes collection start/end, actual per-container timestamps, IDs, start times, restart counts, skew_ms and alignment_window_ms:10000. Coverage is complete, incomplete, skewed or changed_during_sample. Only complete aligned collections have aggregate totals. These are aligned observations within a declared tolerance, not measurements taken at exactly the same instant.

parent_slice is separate from container-local limits. It reports the configured allocation, shared resource identity, effective CPU quota percentage, memory limit, current/peak memory, cumulative CPU usage/throttling nanoseconds and throttled periods. Use these effective limits when comparing usage with your slice allocation. A null applied limit with coverage:sampled means unlimited; with unavailable or membership_mismatch it means unverified. Missing counters stay null. A container-local memory limit alone does not describe your slice limit. A changed parent identity or decreasing cumulative counter starts a new segment.

Keep keys and receipts with the trial. Same-key retries return the original collection, including after a lost response. Metrics receipts are retained while the issuing token is valid. There is no automatic interval subscription.

Sampling retries#

HTTP 503 RUNTIME_ADMISSION_RETRY includes Retry-After: 2 and structured retryable, retry_after_seconds and reuse_idempotency_key details. Admission may already have succeeded: retry the same body and key, never a fresh key. HTTP 409 RUNTIME_OPERATION_ACTIVE means wait for the active collection. Do not interpret request failures or incomplete samples as zero resource usage.

Ingress policy and throttling#

GET /v1/deploy/services/{serviceId}/ingress requires the service token's read grant. It exposes desired automation and route rate policies, including user-agent matching, client-IP key, rate and burst. applied and applied_at come from a confirmed configuration update; coverage is not_observed, applied or configuration_changed. Desired configuration alone is not deployment proof. Automation patterns include curl; benchmark clients must record their user agent.

When a platform rate limit rejects a request, follow its Retry-After header before retrying. An HTTP 429 response can also come from your application; use the reported ingress counters to distinguish platform rate limiting.

counters contains observed rejected/delayed request counts and the source statistics window when measurements are available. Otherwise counts are null with coverage:unavailable; older logs yield incomplete coverage. This GET reads the last collected statistics, not a live counter or a collection trigger. Retained HTTP logs also expose limit_req_status and rate_limit_policy when HTTP logging is enabled. An application 429 is not counted as an edge rejection.