Unbind
Services

Create Service

Create a service from a git repo, container image, or database. Does not deploy it; trigger a deployment separately.

POST
/services/create

Create a service from a git repo, container image, or database. Does not deploy it; trigger a deployment separately.

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.

auto_deploy?boolean

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

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

Builder of the service - docker, nixpacks, railpack

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. Unset picks 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. Not for databases

cron_timezone?string

IANA time zone for the cron schedule, e.g. 'Europe/Berlin'. UTC when unset

database_config?
database_type?string
description?string
docker_builder_build_context?string

Optional path to Dockerfile context, if using docker builder

docker_builder_dockerfile_path?string

Optional path to Dockerfile, if using docker builder

environment_id*string
Formatuuid
github_installation_id?integer

An installation usable in the team, from list-github-installations. list-github-repositories shows which repositories each one reaches

Formatint64
health_check?

Health check configuration for the service

hosts?array<>|null
image?string
init_containers?array<>|

Init containers to run before the main container

is_public?boolean

Whether the service is reachable from the internet. Defaults to true for a service with a port and to false for a database

max_request_body_size_mb?integer

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

Formatint32
Range1 <= value <= 10240
name*string

Has to be unique in the environment. A taken name gets a short suffix, so read the name from the response

Length1 <= length <= 32
ports?array<>|null
project_id*string
Formatuuid
railpack_builder_build_command?string
railpack_builder_install_command?string
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 (default) 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
session_affinity?boolean

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

team_id*string
Formatuuid
type*ServiceType

Type of service, e.g. 'github', 'docker-image'

Value in

  • "github"
  • "docker-image"
  • "database"
variable_mounts?array<>|

Mount variables as volumes

volumes?array<>|

Volume to mount in the service, one at most

watch_paths?array<string>|

Gitignore-style patterns, a push deploys only when a changed file matches. Unset deploys on every push. Only for a GitHub service

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 POST "https://example.com/services/create" \  -H "Content-Type: application/json" \  -d '{    "builder": "railpack",    "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",    "name": "string",    "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",    "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba",    "type": "github"  }'
{  "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"  }}