Unbind
Services

Update Service

Update a service's config (source, build, runtime, networking). A running service rolls the change out right away, rebuilding when the source or a build setting changed. A service that was never deployed picks it up on its first deployment.

PUT
/services/update

Update a service's config (source, build, runtime, networking). A running service rolls the change out right away, rebuilding when the source or a build setting changed. A service that was never deployed picks it up on its first deployment.

Authorization

bearerAuth
AuthorizationBearer <token>

Access token or API key (unb_...) passed as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

add_ports?array<>|

Additional ports to add, will not remove existing ports

add_variable_mounts?array<>|

Additional variable mounts to add, will not remove existing mounts

add_volumes?array<>|

Volume to mount. A service holds one volume, so this only works on a service without one, or together with remove_volumes for the current one

auto_deploy?boolean

Deploy on every push to the branch. Only for a GitHub service

backup_retention_count?integer

Number of base backups to retain, e.g. 3

Formatint64
Range1 <= value
backup_schedule?string

Cron expression for the backup schedule, e.g. '0 0 * * *'

builder?ServiceBuilder

Value in

  • "railpack"
  • "docker"
  • "database"
client_ip_header?string

Header a proxy in front of the service, like Cloudflare, carries the visitor's IP address in, e.g. CF-Connecting-IP. An empty string goes back to automatic: CF-Connecting-IP while a domain is proxied through Cloudflare and nothing otherwise. Not for databases, only on installs that route through Envoy Gateway

cron_schedule?string

Cron expression (minute hour day month weekday). When set the service runs its command on this schedule and exits instead of running continuously, with no replicas, ports or domains. Set empty string to run continuously again. Not for databases

cron_timezone?string

IANA time zone for the cron schedule, e.g. 'Europe/Berlin'. Set empty string for UTC

database_config?
description?string|null
docker_builder_build_context?string

Optional path to Dockerfile context, if using docker builder - set empty string to reset to default

docker_builder_dockerfile_path?string

Optional path to Dockerfile, if using docker builder - set empty string to reset to default

environment_id*string
Formatuuid
git_branch?string

Branch to build from, must exist in the repository. Defaults to the default branch when the repository changes

git_tag?string

Tag to build from, supports glob patterns

github_installation_id?integer

Moves a git service to another repository, together with repository_owner and repository_name. The service is rebuilt from it

Formatint64
health_check?
image?string

Image to run, with an optional tag. Only for an image service

init_containers?array<>|

List of init containers

is_public?boolean

Whether the service is reachable from the internet. A database gets a public address when true and loses it when false. Any other service loses every domain when false

max_request_body_size_mb?integer

Largest request body the service's domains accept, in MB. 0 resets it to the default of 100. Not for databases, and has no effect on clusters that route through a gateway

Formatint32
Range0 <= value <= 10240
name?|

Has to be unique in the environment

Length1 <= length <= 32
overwrite_hosts?array<>|

Replaces every domain. An empty list removes them all

overwrite_ports?array<>|

Replaces every port. An empty list removes them all. Not for databases

overwrite_variable_mounts?array<>|

Mount variables as volumes

overwrite_volumes?array<>|

Volume to mount on the service, replacing the current one. One at most

project_id*string
Formatuuid
railpack_builder_build_command?string
railpack_builder_install_command?string
remove_hosts?array<>|

Hosts to remove

remove_ports?array<>|

Ports to remove

remove_variable_mounts?array<>|

Variable mounts to remove

remove_volumes?array<>|

Volumes to unmount from the service, matched by id. The data stays in the volume, which can be mounted on another service once this one's old replicas stop

replicas?integer

Must be 1 for a service with a volume

Formatint32
Range1 <= value <= 10
repository_name?string

Must be a repository the GitHub installation has access to

repository_owner?string

Must be the account the GitHub installation belongs to

resources?

Resource limits and requests for the service containers

rollout?Rollout

How a deployment replaces the running version. rolling starts the new version next to the old one, so there is no gap. stop-first stops the old version before the new one starts, so the two never run at once, for apps that must not overlap like bots or wallets, at the cost of a few seconds of downtime per deployment. A service with a volume always stops first. Not for databases

Value in

  • "rolling"
  • "stop-first"
run_command?string
s3_backup_bucket_id?string

S3 bucket to store database backups in. Only for database services

Formatuuid
service_id*string
Formatuuid
session_affinity?boolean

Pin each visitor to one replica with a cookie, for apps that keep sessions or websockets in memory. Caches like Cloudflare skip responses that set the cookie. Not for databases

stopped?boolean

Stop or start the service. A stopped service runs no replicas while its volumes, domains, variables and settings stay in place. Set false to start it again. Not for databases

team_id*string
Formatuuid
upsert_hosts?array<>|

Additional hosts to add, will not remove existing hosts

watch_paths?array<string>

Gitignore-style patterns, a push deploys only when a changed file matches. Empty deploys on every push

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/services/update" \  -H "Content-Type: application/json" \  -d '{    "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",    "service_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0",    "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba"  }'
{  "data": {    "config": {      "auto_deploy": true,      "backup_retention_count": 0,      "backup_schedule": "string",      "builder": "railpack",      "client_ip_header": "string",      "cron_schedule": "string",      "cron_timezone": "string",      "database_config": {        "append_only": true,        "default_database_name": "string",        "innodb_buffer_pool_size_mb": 0,        "max_replication_slots": 0,        "max_slot_wal_keep_size_mb": 0,        "max_wal_senders": 0,        "shared_buffers_mb": 0,        "storage": "string",        "version": "string",        "wal_level": "replica"      },      "docker_builder_build_context": "string",      "docker_builder_dockerfile_path": "string",      "git_branch": "string",      "git_tag": "string",      "health_check": {        "command": "string",        "health_failure_threshold": 0,        "health_period_seconds": 0,        "health_timeout_seconds": 0,        "path": "string",        "port": 0,        "startup_failure_threshold": 0,        "startup_period_seconds": 0,        "startup_timeout_seconds": 0,        "type": "http"      },      "hosts": [        {          "basic_auth": {            "password": "string",            "username": "string"          },          "description": "string",          "display_name": "string",          "host": "string",          "path": "string",          "prev_host": "string",          "prev_path": "string",          "protocol": "string",          "proxy": {            "to": "string"          },          "redirect": {            "status_code": 301,            "to": "string"          },          "response_headers": [            {              "name": "string",              "value": "string"            }          ],          "target_port": 0,          "template_input_id": "string"        }      ],      "icon": "string",      "image": "string",      "init_containers": [        {          "command": "string",          "image": "string"        }      ],      "is_public": true,      "max_request_body_size_mb": 0,      "ports": [        {          "is_nodeport": true,          "node_port": 0,          "port": 0,          "protocol": "TCP"        }      ],      "protected_variables": [        "string"      ],      "railpack_builder_build_command": "string",      "railpack_builder_install_command": "string",      "replicas": 0,      "resources": {        "cpu_limits_millicores": -1,        "cpu_requests_millicores": -1,        "memory_limits_megabytes": -1,        "memory_requests_megabytes": -1      },      "rollout": "rolling",      "run_command": "string",      "s3_backup_bucket_id": "7bf31046-51dc-4bdd-aac9-39810caac945",      "security_context": {        "capabilities": {          "add": [            "string"          ],          "drop": [            "string"          ]        },        "privileged": true      },      "session_affinity": true,      "stopped": true,      "variable_mounts": [        {          "name": "string",          "path": "string"        }      ],      "volumes": [        {          "can_delete": true,          "capacity_gb": 0.1,          "created_at": "2019-08-24T14:15:22Z",          "description": "string",          "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",          "id": "string",          "is_available": true,          "is_database": true,          "is_deleting": true,          "is_pending_resize": true,          "mount_path": "string",          "mount_status": "unattached",          "mounted_on_service_id": "6de1f4a4-7b8e-4432-bffa-782791ce061a",          "name": "string",          "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",          "requested_gb": 0.1,          "status": "Pending",          "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",          "type": "team",          "used_gb": 0.1        }      ],      "watch_paths": [        "string"      ]    },    "created_at": "2019-08-24T14:15:22Z",    "current_deployment": {      "attempts": 0,      "builder": "railpack",      "commit_author": {        "avatar_url": "string",        "name": "string"      },      "commit_message": "string",      "commit_sha": "string",      "completed_at": "2019-08-24T14:15:22Z",      "crashing_reasons": [        "string"      ],      "created_at": "2019-08-24T14:15:22Z",      "docker_builder_build_context": "string",      "docker_builder_dockerfile_path": "string",      "error": "string",      "git_branch": "string",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "image": "string",      "job_name": "string",      "queued_at": "2019-08-24T14:15:22Z",      "railpack_builder_build_command": "string",      "railpack_builder_install_command": "string",      "replica_events": [        {          "count": 0,          "first_seen": "string",          "last_seen": "string",          "message": "string",          "reason": "string",          "timestamp": "string",          "type": "oom_killed"        }      ],      "replica_restarts": 0,      "run_command": "string",      "service_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0",      "started_at": "2019-08-24T14:15:22Z",      "status": "build-pending",      "status_message": "string",      "updated_at": "2019-08-24T14:15:22Z"    },    "database_type": "string",    "database_version": "string",    "description": "string",    "detected_ports": [      {        "is_nodeport": true,        "node_port": 0,        "port": 0,        "protocol": "TCP"      }    ],    "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",    "git_repository": "string",    "git_repository_owner": "string",    "github_installation_id": 0,    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "kubernetes_name": "string",    "last_deployment": {      "attempts": 0,      "builder": "railpack",      "commit_author": {        "avatar_url": "string",        "name": "string"      },      "commit_message": "string",      "commit_sha": "string",      "completed_at": "2019-08-24T14:15:22Z",      "crashing_reasons": [        "string"      ],      "created_at": "2019-08-24T14:15:22Z",      "docker_builder_build_context": "string",      "docker_builder_dockerfile_path": "string",      "error": "string",      "git_branch": "string",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "image": "string",      "job_name": "string",      "queued_at": "2019-08-24T14:15:22Z",      "railpack_builder_build_command": "string",      "railpack_builder_install_command": "string",      "replica_events": [        {          "count": 0,          "first_seen": "string",          "last_seen": "string",          "message": "string",          "reason": "string",          "timestamp": "string",          "type": "oom_killed"        }      ],      "replica_restarts": 0,      "run_command": "string",      "service_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0",      "started_at": "2019-08-24T14:15:22Z",      "status": "build-pending",      "status_message": "string",      "updated_at": "2019-08-24T14:15:22Z"    },    "last_successful_deployment": {      "attempts": 0,      "builder": "railpack",      "commit_author": {        "avatar_url": "string",        "name": "string"      },      "commit_message": "string",      "commit_sha": "string",      "completed_at": "2019-08-24T14:15:22Z",      "crashing_reasons": [        "string"      ],      "created_at": "2019-08-24T14:15:22Z",      "docker_builder_build_context": "string",      "docker_builder_dockerfile_path": "string",      "error": "string",      "git_branch": "string",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "image": "string",      "job_name": "string",      "queued_at": "2019-08-24T14:15:22Z",      "railpack_builder_build_command": "string",      "railpack_builder_install_command": "string",      "replica_events": [        {          "count": 0,          "first_seen": "string",          "last_seen": "string",          "message": "string",          "reason": "string",          "timestamp": "string",          "type": "oom_killed"        }      ],      "replica_restarts": 0,      "run_command": "string",      "service_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0",      "started_at": "2019-08-24T14:15:22Z",      "status": "build-pending",      "status_message": "string",      "updated_at": "2019-08-24T14:15:22Z"    },    "name": "string",    "permissions": [      "admin"    ],    "service_group": {      "created_at": "2019-08-24T14:15:22Z",      "description": "string",      "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",      "icon": "string",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "template_id": "c6d67e98-83ea-49f0-8812-e4abae2b68bc"    },    "template": {      "created_at": "2019-08-24T14:15:22Z",      "description": "string",      "display_rank": 0,      "icon": "string",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "immutable": true,      "keywords": [        "string"      ],      "name": "string",      "resource_recommendations": {        "minimum_recommended_cpu": 0.1,        "minimum_recommended_ram_gb": 0.1      },      "version": 0    },    "template_instance_id": "b31637c1-1c84-4c03-af4e-c025a1593e8b",    "type": "github",    "updated_at": "2019-08-24T14:15:22Z"  }}