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.