Services
Update a service
Change a service's environment, size, replicas, port, health check, build settings or source.
Updated
https://cloud.cahaves.com/api/services/{id}
Authorization
cahaves.cloud.sessionstringcookierequired
The session cookie Cloud sets when a customer signs in to the console with GitHub or Google. It is HttpOnly, so scripts cannot read it, and there are no API keys or tokens yet.
Path parameters
idstring<uuid>required
The service's id.
Example: "0b9e4d2a-7c13-4f6e-a8d5-3e1c9b7f2a40"
Headers
X-Cloud-Organizationstring<uuid>
The id of the organization the request works in, one the signed-in customer owns. Left out or empty, the request works in their oldest organization. Any other value answers 404 with `reason: "organization"`. A customer with no organization yet gets 409 "Create an organization first." from every route that works in one.
Example: "2f6c8e0a-4b1d-4e7f-9a3c-5d7e9f1b3a5c"
Body
application/jsonrequired
envstring | null
The whole environment, one NAME=value per line, at most 64 KB. Null or empty clears it. Ignored for a database.
portinteger
Applications only. Null answers 422.
sourceobject
For a GitHub service. What a service is built from cannot change type.
replicasinteger
Applications only. Null answers 422.
build_typestring | null
GitHub services only. Null returns to nixpacks.
Allowed values: "nixpacks""dockerfile""railpack""static"null
build_commandstring | null
GitHub services only. Null clears it.
instance_sizestring
Null answers 422, and so does `nano` on a service charged at the dedicated rate.
Allowed values: "nano""small""medium""large""xlarge"
start_commandstring | null
Applications only. Null clears it, and the image's or the build's own command runs.
install_commandstring | null
GitHub services only. Null clears it.
health_check_pathstring | null
Applications only. Null or empty turns the check off.
publish_directorystring | null
GitHub services only. Null clears it.
Responses
application/json
The updated service.
serviceobjectrequired
Send only what changes: a key left out is unchanged. null clears a value that can be empty, such as env, health_check_path or start_command; null for replicas, port or instance_size answers 422.
| Change | Reaches a running application |
|---|---|
env, replicas, instance_size, port, health_check_path, start_command | At once: the application is reloaded |
build_type, the build commands, publish_directory, source | At the next deploy |
A stopped or idle application takes every change at its next start or deploy.
A compose stack takes env, applied at its next deploy, and instance_size. A database takes only instance_size. For both, the size sets the rate charged and is not applied as a limit. nano on a service charged at the dedicated rate answers 422. What a service is built from cannot change type.
A suspended account, a service with unfinished backup work and one with an unconfirmed volume attachment all answer 409. Enlarging a paid service, a larger size or more replicas, is paid work, and answers 409 with a reason while the organization is not in good standing or is stopped for billing; a smaller size or fewer replicas never does. A 502 can leave part of a change applied on the engine; Errors says how to recover.