--- title: "Create instance" method: POST path: "/environments/{environment}/instances" tags: ["Instances"] --- # Create instance `POST /environments/{environment}/instances` ## Request - Base URL: `https://cloud.laravel.com/api` - URL: `https://cloud.laravel.com/api/environments/{environment}/instances` - Auth: HTTP bearer Create a new instance for an environment. ## Path parameters - `environment` string, required ## Request body - CreateInstanceRequest - `name` string, required - `type` 'service' | 'managed_queue', required - `size` 'flex-512mb' | 'flex-1gb' | 'flex-2gb' | 'flex.c-1vcpu-256mb' | 'flex.g-1vcpu-512mb' | 'flex.m-1vcpu-1gb' | 'flex.c-2vcpu-512mb' | 'flex.g-2vcpu-1gb' | 'flex.m-2vcpu-2gb' | 'flex.c-4vcpu-1gb' | 'flex.g-4vcpu-2gb' | 'flex.m-4vcpu-4gb' | 'flex.c-8vcpu-2gb' | 'flex.g-8vcpu-4gb' | 'flex.m-8vcpu-8gb' | 'pro.c-1vcpu-1gb' | 'pro.g-1vcpu-2gb' | 'pro.m-1vcpu-4gb' | 'pro.c-2vcpu-2gb' | 'pro.g-2vcpu-4gb' | 'pro.m-2vcpu-8gb' | 'pro.c-4vcpu-4gb' | 'pro.g-4vcpu-8gb' | 'pro.m-4vcpu-16gb' | 'pro.c-8vcpu-8gb' | 'pro.g-8vcpu-16gb' | 'pro.m-8vcpu-32gb' | 'dedicated.c-0.25vcpu-512mb' | 'dedicated.c-0.5vcpu-1gb' | 'dedicated.c-1vcpu-2gb' | 'dedicated.g-1vcpu-4gb' | 'dedicated.m-1vcpu-8gb' | 'dedicated.c-2vcpu-4gb' | 'dedicated.g-2vcpu-8gb' | 'dedicated.m-2vcpu-16gb' | 'dedicated.c-4vcpu-8gb' | 'dedicated.g-4vcpu-16gb' | 'dedicated.m-4vcpu-32gb' | 'dedicated.c-8vcpu-16gb' | 'dedicated.g-8vcpu-32gb' | 'dedicated.m-8vcpu-64gb' | 'mq-pro-256mb' | 'mq-pro-512mb' | 'mq-pro-1gb' | 'mq-pro-2gb' | 'mq-pro-4gb' | 'mq-pro-8gb' | 'mq-dedicated-256mb' | 'mq-dedicated-512mb' | 'mq-dedicated-1gb' | 'mq-dedicated-2gb' | 'mq-dedicated-4gb' | 'mq-dedicated-8gb' | 'mq-dedicated-16gb' | 'mq.flex.256mb' | 'mq.flex.512mb' | 'mq.flex.1gb' | 'mq.flex.2gb' | 'mq.pro.256mb' | 'mq.pro.512mb' | 'mq.pro.1gb' | 'mq.pro.2gb' | 'mq.pro.4gb' | 'mq.pro.8gb' | 'mq.dedicated.flex.256mb' | 'mq.dedicated.flex.512mb' | 'mq.dedicated.flex.1gb' | 'mq.dedicated.flex.2gb' | 'mq.dedicated.pro.256mb' | 'mq.dedicated.pro.512mb' | 'mq.dedicated.pro.1gb' | 'mq.dedicated.pro.2gb' | 'mq.dedicated.pro.4gb' | 'mq.dedicated.pro.8gb' | 'mq.dedicated.pro.16gb', required - `scaling_type` 'none' | 'custom' | 'auto', required - `max_replicas` integer: The maximum number of replicas the instance can scale to. Only applicable to the `custom` scaling type, and rejected when used with `auto`. - `min_replicas` integer: The minimum number of replicas the instance runs. Only applicable to the `custom` scaling type, and rejected when used with `auto`. Not applicable to managed queues, which always scale to zero when idle. - `uses_scheduler` boolean - `sleep_with_app` boolean: Whether worker replicas scale to zero alongside the app cluster, waking when they receive traffic. Only applicable to worker (service) instances. - `scaling_cpu_threshold_percentage` integer, nullable - `scaling_memory_threshold_percentage` integer, nullable - `visibility_timeout` integer, nullable: How long a message stays hidden from other workers while one is processing it. Only available when the organization has the advanced managed queues entitlement; ignored otherwise, and the platform manages it. - `shutdown_timeout` integer, nullable: The time a worker has to finish its current job before being forcefully shut down. Only available when the organization has the advanced managed queues entitlement; ignored otherwise, and the platform manages it. - `background_processes` object[] - `type` 'worker' | 'custom', required - `processes` integer, required - `command` string: Custom command to run. Required when type is 'custom'. Not applicable for 'worker' type. - `config` object - `connection` string: The queue connection name. Only applicable for 'worker' type background processes. Managed queues must use 'cloud'. - `queue` string: The queue name(s) to process. Can be comma-separated for multiple queues. Only applicable for 'worker' type background processes. - `tries` integer: Number of times a job should be attempted. Only applicable for 'worker' type background processes. - `backoff` integer: Number of seconds to wait before retrying a failed job. Only applicable for 'worker' type background processes. - `sleep` integer: Number of seconds to sleep when no jobs are available. Only applicable for 'worker' type background processes. - `rest` integer: Number of seconds to rest between jobs. Only applicable for 'worker' type background processes. - `timeout` integer: Number of seconds a job can run before timing out. Only applicable for 'worker' type background processes. - `force` boolean: Force the worker to run even in maintenance mode. Only applicable for 'worker' type background processes. ## Response `201` `InstanceResource` - object - `data` InstanceResource, required - `id` string, required - `type` 'instances', required - `attributes` object - `name` string, required - `type` 'app' | 'service' | 'queue' | 'managed_queue', required - `size` 'flex-512mb' | 'flex-1gb' | 'flex-2gb' | 'flex.c-1vcpu-256mb' | 'flex.g-1vcpu-512mb' | 'flex.m-1vcpu-1gb' | 'flex.c-2vcpu-512mb' | 'flex.g-2vcpu-1gb' | 'flex.m-2vcpu-2gb' | 'flex.c-4vcpu-1gb' | 'flex.g-4vcpu-2gb' | 'flex.m-4vcpu-4gb' | 'flex.c-8vcpu-2gb' | 'flex.g-8vcpu-4gb' | 'flex.m-8vcpu-8gb' | 'pro.c-1vcpu-1gb' | 'pro.g-1vcpu-2gb' | 'pro.m-1vcpu-4gb' | 'pro.c-2vcpu-2gb' | 'pro.g-2vcpu-4gb' | 'pro.m-2vcpu-8gb' | 'pro.c-4vcpu-4gb' | 'pro.g-4vcpu-8gb' | 'pro.m-4vcpu-16gb' | 'pro.c-8vcpu-8gb' | 'pro.g-8vcpu-16gb' | 'pro.m-8vcpu-32gb' | 'dedicated.c-0.25vcpu-512mb' | 'dedicated.c-0.5vcpu-1gb' | 'dedicated.c-1vcpu-2gb' | 'dedicated.g-1vcpu-4gb' | 'dedicated.m-1vcpu-8gb' | 'dedicated.c-2vcpu-4gb' | 'dedicated.g-2vcpu-8gb' | 'dedicated.m-2vcpu-16gb' | 'dedicated.c-4vcpu-8gb' | 'dedicated.g-4vcpu-16gb' | 'dedicated.m-4vcpu-32gb' | 'dedicated.c-8vcpu-16gb' | 'dedicated.g-8vcpu-32gb' | 'dedicated.m-8vcpu-64gb' | 'mq-pro-256mb' | 'mq-pro-512mb' | 'mq-pro-1gb' | 'mq-pro-2gb' | 'mq-pro-4gb' | 'mq-pro-8gb' | 'mq-dedicated-256mb' | 'mq-dedicated-512mb' | 'mq-dedicated-1gb' | 'mq-dedicated-2gb' | 'mq-dedicated-4gb' | 'mq-dedicated-8gb' | 'mq-dedicated-16gb' | 'mq.flex.256mb' | 'mq.flex.512mb' | 'mq.flex.1gb' | 'mq.flex.2gb' | 'mq.pro.256mb' | 'mq.pro.512mb' | 'mq.pro.1gb' | 'mq.pro.2gb' | 'mq.pro.4gb' | 'mq.pro.8gb' | 'mq.dedicated.flex.256mb' | 'mq.dedicated.flex.512mb' | 'mq.dedicated.flex.1gb' | 'mq.dedicated.flex.2gb' | 'mq.dedicated.pro.256mb' | 'mq.dedicated.pro.512mb' | 'mq.dedicated.pro.1gb' | 'mq.dedicated.pro.2gb' | 'mq.dedicated.pro.4gb' | 'mq.dedicated.pro.8gb' | 'mq.dedicated.pro.16gb', required - `scaling_type` 'none' | 'custom' | 'auto', required - `min_replicas` integer, required - `max_replicas` integer, required - `queue_status` 'creating' | 'updating' | 'available' | 'deleting' | 'deleted' | 'unknown', required - `paused` boolean, nullable, required: Whether the managed queue is currently paused. Null for non-queue instances. - `retire_at` string, nullable, required: When the instance is scheduled to be retired because its size is being discontinued. - `retired_at` string, nullable, required: When the instance was retired because its size is no longer supported. Retired instances stop processing jobs until you upgrade. - `is_default` boolean, nullable, required: Whether this is the environment's default managed queue. Null for non-queue instances. - `visibility_timeout` integer, nullable, required: How long, in seconds (0–43200), a received job stays hidden from other workers before it becomes available again. Null for non-queue instances. - `polling_interval` integer, nullable, required: How often, in seconds (1–60), the queue is polled for new jobs. Null for non-queue instances. - `shutdown_timeout` integer, nullable, required - `uses_scheduler` boolean, required - `sleep_with_app` boolean, nullable, required - `hibernation_timeout` integer, nullable, required: Minutes of inactivity before the app hibernates. Null when hibernation is off, and for non-app instances. - `uses_octane` boolean, nullable, required: Whether the app is served by Laravel Octane. Null for non-app instances. - `uses_inertia_ssr` boolean, nullable, required: Whether the app runs an Inertia SSR server. Null for non-app instances. - `probes` object, nullable: Custom health checks for the app's web process, keyed by `startup`, `readiness`, and `liveness`. Unset checks and fields use the platform defaults. A path selects HTTP and a port alone selects TCP. Timing overrides without a path or port keep the default handler. Null when no custom checks are set, and for non-app instances. - `startup` object - `path` string - `port` integer - `delay` integer - `interval` integer - `timeout` integer - `tries` integer - `readiness` object - `path` string - `port` integer - `delay` integer - `interval` integer - `timeout` integer - `tries` integer - `liveness` object - `path` string - `port` integer - `delay` integer - `interval` integer - `timeout` integer - `tries` integer - `scaling_cpu_threshold_percentage` integer, nullable, required - `scaling_memory_threshold_percentage` integer, nullable, required - `created_at` string, date-time, nullable, required - `relationships` object - `environment` object - `data` EnvironmentResourceIdentifier, required - `type` 'environments', required - `id` string, required - `backgroundProcesses` object - `data` BackgroundProcessResourceIdentifier[], required - `type` 'background_processes', required - `id` string, required - `scheduledCommands` object - `data` ScheduledCommandResourceIdentifier[], required - `type` 'scheduled_commands', required - `id` string, required - `included` union[] - union - EnvironmentResource - `id` string, required - `type` 'environments', required - `attributes` object - `name` string, required - `slug` string, required - `status` 'deploying' | 'running' | 'hibernating' | 'stopped', required - `color` 'blue' | 'green' | 'orange' | 'purple' | 'red' | 'yellow' | 'cyan' | 'gray', required - `created_from_automation` boolean, required - `vanity_domain` string, required - `framework` 'laravel' | 'symfony' | 'jigsaw' | 'html' | 'php' | 'express' | 'hono' | 'nuxt' | 'next' | 'tanstack' | 'elysia' | 'nestjs' | 'astro' | 'javascript' | 'go' | 'hugo' | 'ruby' | 'rails' | 'jekyll' | 'django' | 'fastapi' | 'flask' | 'pelican' | 'python' | 'java' | 'spring' | 'rust' | 'zola' | 'axum' | 'rocket' | 'actix' | 'warp', required - `language` 'html' | 'php' | 'javascript' | 'python' | 'go' | 'ruby' | 'java' | 'rust', required - `php_major_version` string, required - `serving` string - `build_command` string, nullable, required - `node_version` '20' | '22' | '24' | '26', required - `deploy_command` string, nullable, required - `start_command` string, nullable, required - `uses_octane` boolean, required - `uses_hibernation` boolean, required - `hibernation_wake_up_interval` integer, nullable, required - `timeout` integer, required: The number of seconds the environment will wait for your application to respond before timing out. Changes take effect on the next deployment. - `shutdown_timeout` integer, required: The number of seconds to wait before stopping the previous deployment's compute instances, allowing it to finish processing requests and jobs after a new deployment becomes active. Changes take effect on the next deployment. - `uses_push_to_deploy` boolean, required - `uses_deploy_hook` boolean, required - `resend` object, nullable, required - `from_address` string, required - `from_name` string, required - `key_name` string, required - union - object - … - string[] - `network_settings` object, required - `cache` object, required - … - `response_headers` object, required - … - `firewall` object, required - … - `content_converter` boolean, required - `created_at` string, date-time, nullable, required - `relationships` object - `application` object - `data` ApplicationResourceIdentifier, required - … - `branch` object - `data` BranchResourceIdentifier, required - … - `deployments` object - `data` DeploymentResourceIdentifier[], required - … - `currentDeployment` object - `data` DeploymentResourceIdentifier, required - … - `domains` object - `data` DomainResourceIdentifier[], required - … - `primaryDomain` object - `data` DomainResourceIdentifier, required - … - `instances` object - `data` InstanceResourceIdentifier[], required - … - `database` object - `data` DatabaseSchemaResourceIdentifier, required - … - `cache` object - `data` CacheResourceIdentifier, required - … - `buckets` object - `data` FilesystemResourceIdentifier[], required - … - `websocketApplication` object - `data` WebsocketApplicationResourceIdentifier, required - … - `secrets` object - `data` SecretResourceIdentifier[], required - … - `links` object, required - `self` Link, required - `href` string, uri, required - `rel` string - `describedby` string - `title` string - `type` string - `hreflang` union - … - `meta` object - BackgroundProcessResource - `id` string, required - `type` 'background_processes', required - `attributes` object - `type` 'worker' | 'custom', required - `processes` integer, required - `command` string, required - `config` unknown[], required - unknown - `strategy_type` 'none' | 'growth_rate' | 'queue_size', required - `strategy_threshold` integer, nullable, required - `created_at` string, date-time, nullable, required - `relationships` object - `instance` object - `data` InstanceResourceIdentifier, required - … - ScheduledCommandResource - `id` string, required - `type` 'scheduled_commands', required - `attributes` object - `name` string, nullable, required - `command` string, required - `schedule` string, required: The cron expression the command runs on, evaluated in UTC. - `created_at` string, date-time, nullable, required - `relationships` object - `instance` object - `data` InstanceResourceIdentifier, required - … ## Other responses - `403`: Authorization error - `404`: Not found - `422`: Validation error --- [API](https://skmtc.dev/laravel/apis/laravel-cloud.md) - [All operations](https://skmtc.dev/laravel/apis/laravel-cloud/llms.txt) - [OpenAPI document](https://skmtc.dev/laravel/apis/laravel-cloud/revisions/af603f54ff33?raw)