Skip to the page

Preview a resource change with its price

POST/v1/organisations/{id}/environments/{envId}/changes/preview

Operation changes.preview · since 2026-11-05 · stable

Needs a session withwritescopeAnswers200 OK

The previewed change: its id, what it does, the price before and after, and until when it stands (an hour). Apply it with changes.apply.

spec for postgres: size (pg-...), storage_gb 1 to 4000, version 13 to 20, replicas 0 to 4, pooler { enabled, mode, max_client_conn }, backups { enabled, retention_days 1 to 35 }, protect, database; restore { to } (a time) with action restore; copy_of { resource, to, environment } with create.

spec for service: type "web", "worker" or "cron", image, size (svc-...), replicas 0 to 10, port, health { path, initial_delay_s, timeout_s }, command, args, schedule (cron), public, variables, secrets (group names), connections [{ resource, as }], registry { username }.

spec for valkey (Redis): size (vk-...), version, persistence, storage_gb 1 to 500, backups, eviction, maxmemory_percent 50 to 90, protect, restore { backup }.

spec for bucket: quota_gb 1 to 10000, public_read, versioning, lifecycle { expire_days, noncurrent_expire_days }, backups, protect, restore { backup }.

spec for secret: secrets (names), variables (NAME to value), from_project. spec for domain: hostname, service; add the domain with domains.add first.

Path parameters

idstring (uuid)required
The organisation id.
envIdstring (uuid)required
The environment id.

Body (JSON)

Fields not listed here are refused.

actionstringrequired
"create", "update", "delete", "restore" or "rotate".
kindstringrequired
"postgres", "service", "valkey" (Redis), "bucket", "secret" or "domain".
namestring, up to 24optional
The resource's name: lowercase letters, digits and dashes. Required except for a domain, named by spec.hostname.
specobjectoptional
The kind's settings (see below). Settings left out take the environment's defaults.
confirmstringoptional
For a delete: the resource's name, typed back.
sourceobjectoptional
A service: connectionId, repository (owner/name), branch, dockerfile, context, autoDeploy, or image (registry/name:tag or @digest).
secretsobjectoptional
A secret group: NAME to value (null removes it), at most 100.
generatearray of namesoptional
A secret group: names Rykloud makes a random value for.
buildstring (uuid)optional
A service: deploy this build.
registryPasswordstringoptional
A service from a private image: the registry's password.

Errors

Every error is { "error", "message", "detail"? } (Errors and references). Besides the codes any route can answer, this one refuses with:

  • name_taken
  • protected
  • in_use
  • no_change
  • change_open
  • wrong_state
  • not_ready
  • outside_window
  • not_allowed
POST/v1/organisations/{id}/environments/{envId}/changes/preview
curl -X POST "https://api.rykloud.com/v1/organisations/$ORG_ID/environments/$ENV_ID/changes/preview" \
  -H "Authorization: Bearer $RYKLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "create",
  "kind": "postgres",
  "name": "db",
  "spec": {
    "size": "pg-s",
    "storage_gb": 20
  }
}'
With the rykloud CLI
rykloud resources add KIND NAME [flags]
rykloud resources update RESOURCE [flags]
rykloud resources remove RESOURCE [flags]

Command reference: rykloud resources add, rykloud resources update, rykloud resources remove