---
title: "Create service preview (image-backed)"
method: POST
path: "/services/{serviceId}/preview"
tags: ["Services"]
---

# Create service preview (image-backed)

`POST /services/{serviceId}/preview`

Create a preview instance for an image-backed service. The preview uses the settings of the base service (referenced by `serviceId`), except settings overridden via provided parameters.

View all active previews from your service's Previews tab in the Render Dashboard.

Note that you can't create previews for Git-backed services using the Render API.

## Request body

- PreviewInput
  - `imagePath` string, required — Must be either a full URL or the relative path to an image. If a relative path, Render uses the base service's image URL as its root. For example, if the base service's image URL is `docker.io/library/nginx:latest`, then valid values are: `docker.io/library/nginx:<any tag or SHA>`, `library/nginx:<any tag or SHA>`, or `nginx:<any tag or SHA>`. Note that the path must match (only the tag or SHA can vary).
  - `name` string — A name for the service preview instance. If not specified, Render generates the name using the base service's name and the specified tag or SHA.
  - `plan` 'starter' | 'starter_plus' | 'standard' | 'standard_plus' | 'pro' | 'pro_plus' | 'pro_max' | 'pro_ultra' | 'free' | 'custom' | 'starter_legacy' | 'standard_legacy' | 'standard_plus_legacy' | 'pro_legacy' | 'pro_plus_legacy' — The instance type to use. Legacy variants (`*_legacy`) identify grandfathered plans no longer offered for new services. Note that base services on any paid instance type can't create preview instances with the `free` instance type.

## Response `200`

Created

- ServiceAndDeploy
  - `service` Service
    - `id` string, required
    - `autoDeploy` 'yes' | 'no', required
    - `branch` string
    - `buildFilter` BuildFilter
      - `paths` string[], required
      - `ignoredPaths` string[], required
    - `createdAt` string, date-time, required
    - `dashboardUrl` string, required — The URL to view the service in the Render Dashboard
    - `environmentId` string
    - `imagePath` string
    - `name` string, required
    - `notifyOnFail` 'default' | 'notify' | 'ignore', required
    - `ownerId` string, required
    - `registryCredential` RegistryCredentialSummary
      - `id` string, required
      - `name` string, required
    - `repo` string
    - `rootDir` string, required
    - `slug` string, required
    - `suspended` 'suspended' | 'not_suspended', required
    - `suspenders` SuspenderType[], required
    - `type` 'static_site' | 'web_service' | 'private_service' | 'background_worker' | 'cron_job', required
    - `updatedAt` string, date-time, required
    - `serviceDetails` union, required
      - StaticSiteDetails
        - `buildCommand` string, required
        - `ipAllowList` CidrBlockAndDescription[]
          - `cidrBlock` string, required
          - `description` string, required — User-provided description of the CIDR block
        - `parentServer` Resource
          - `id` string, required
          - `name` string, required
        - `publishPath` string, required
        - `pullRequestPreviewsEnabled` 'yes' | 'no' — This field has been deprecated. previews.generation should be used in its place.
        - `previews` Previews
          - `generation` 'off' | 'manual' | 'automatic' — Defaults to "off"
        - `url` string, required
        - `buildPlan` 'starter' | 'performance', required
        - `renderSubdomainPolicy` 'enabled' | 'disabled' — Controls whether render.com subdomains are available for the service
      - WebServiceDetails
        - `autoscaling` object
          - `enabled` boolean, required
          - `min` integer, required — The minimum number of instances for the service
          - `max` integer, required — The maximum number of instances for the service
          - `criteria` object, required
            - `cpu` object, required
              - …
            - `memory` Cpu, required — unresolved $ref
        - `cache` Cache
          - `profile` 'no-cache' | 'origin-controlled' | 'origin-controlled-all', required
        - `disk` object
          - `id` Schema, required — unresolved $ref
          - `name` string, required
          - `sizeGB` integer, required
          - `mountPath` string, required
        - `env` 'docker' | 'elixir' | 'go' | 'node' | 'python' | 'ruby' | 'rust' | 'image', required — This field has been deprecated, runtime should be used in its place.
        - `envSpecificDetails` union, required
          - DockerDetails
            - `dockerCommand` string, required
            - `dockerContext` string, required
            - `dockerfilePath` string, required
            - `preDeployCommand` string
            - `registryCredential` RegistryCredential
              - …
          - NativeEnvironmentDetails
            - `buildCommand` string, required
            - `startCommand` string, required
            - `preDeployCommand` string
        - `healthCheckPath` string, required
        - `ipAllowList` CidrBlockAndDescription[]
          - `cidrBlock` string, required
          - `description` string, required — User-provided description of the CIDR block
        - `maintenanceMode` MaintenanceMode
          - `enabled` boolean, required
          - `uri` string, required — The page to be served when [maintenance mode](https://render.com/docs/maintenance-mode) is enabled. When empty, the default maintenance mode page is served.
        - `numInstances` integer, required — For a *manually* scaled service, this is the number of instances the service is scaled to. DOES NOT indicate the number of running instances for an *autoscaled* service.
        - `openPorts` ServerPort[], required
          - `port` integer, required
          - `protocol` 'TCP' | 'UDP', required
        - `parentServer` Resource
          - `id` string, required
          - `name` string, required
        - `plan` 'starter' | 'starter_plus' | 'standard' | 'standard_plus' | 'pro' | 'pro_plus' | 'pro_max' | 'pro_ultra' | 'free' | 'custom' | 'starter_legacy' | 'standard_legacy' | 'standard_plus_legacy' | 'pro_legacy' | 'pro_plus_legacy', required — The instance type to use. Legacy variants (`*_legacy`) identify grandfathered plans no longer offered for new services. Note that base services on any paid instance type can't create preview instances with the `free` instance type.
        - `pullRequestPreviewsEnabled` 'yes' | 'no' — This field has been deprecated. previews.generation should be used in its place.
        - `previews` Previews
          - `generation` 'off' | 'manual' | 'automatic' — Defaults to "off"
        - `region` 'frankfurt' | 'oregon' | 'ohio' | 'singapore' | 'virginia', required — Defaults to "oregon"
        - `runtime` 'docker' | 'elixir' | 'go' | 'node' | 'python' | 'ruby' | 'rust' | 'image', required — Runtime
        - `sshAddress` string — The SSH address for the service. Only present for services that have SSH enabled.
        - `url` string, required
        - `buildPlan` 'starter' | 'performance', required
        - `maxShutdownDelaySeconds` integer — The maximum amount of time (in seconds) that Render waits for your application process to exit gracefully after sending it a SIGTERM signal.
        - `renderSubdomainPolicy` 'enabled' | 'disabled' — Controls whether render.com subdomains are available for the service
      - PrivateServiceDetails
        - `autoscaling` Autoscaling — unresolved $ref
        - `disk` Disk — unresolved $ref
        - `env` 'docker' | 'elixir' | 'go' | 'node' | 'python' | 'ruby' | 'rust' | 'image', required — This field has been deprecated, runtime should be used in its place.
        - `envSpecificDetails` union, required
          - DockerDetails
            - `dockerCommand` string, required
            - `dockerContext` string, required
            - `dockerfilePath` string, required
            - `preDeployCommand` string
            - `registryCredential` RegistryCredential
              - …
          - NativeEnvironmentDetails
            - `buildCommand` string, required
            - `startCommand` string, required
            - `preDeployCommand` string
        - `numInstances` integer, required — For a *manually* scaled service, this is the number of instances the service is scaled to. DOES NOT indicate the number of running instances for an *autoscaled* service.
        - `openPorts` ServerPort[], required
          - `port` integer, required
          - `protocol` 'TCP' | 'UDP', required
        - `parentServer` Resource
          - `id` string, required
          - `name` string, required
        - `plan` 'starter' | 'starter_plus' | 'standard' | 'standard_plus' | 'pro' | 'pro_plus' | 'pro_max' | 'pro_ultra' | 'free' | 'custom' | 'starter_legacy' | 'standard_legacy' | 'standard_plus_legacy' | 'pro_legacy' | 'pro_plus_legacy', required — The instance type to use. Legacy variants (`*_legacy`) identify grandfathered plans no longer offered for new services. Note that base services on any paid instance type can't create preview instances with the `free` instance type.
        - `pullRequestPreviewsEnabled` 'yes' | 'no' — This field has been deprecated. previews.generation should be used in its place.
        - `previews` Previews
          - `generation` 'off' | 'manual' | 'automatic' — Defaults to "off"
        - `region` 'frankfurt' | 'oregon' | 'ohio' | 'singapore' | 'virginia', required — Defaults to "oregon"
        - `runtime` 'docker' | 'elixir' | 'go' | 'node' | 'python' | 'ruby' | 'rust' | 'image', required — Runtime
        - `sshAddress` string — The SSH address for the service. Only present for services that have SSH enabled.
        - `url` string, required
        - `buildPlan` 'starter' | 'performance', required
        - `maxShutdownDelaySeconds` integer — The maximum amount of time (in seconds) that Render waits for your application process to exit gracefully after sending it a SIGTERM signal.
      - BackgroundWorkerDetails
        - `autoscaling` Autoscaling — unresolved $ref
        - `disk` Disk — unresolved $ref
        - `env` 'docker' | 'elixir' | 'go' | 'node' | 'python' | 'ruby' | 'rust' | 'image', required — This field has been deprecated, runtime should be used in its place.
        - `envSpecificDetails` union, required
          - DockerDetails
            - `dockerCommand` string, required
            - `dockerContext` string, required
            - `dockerfilePath` string, required
            - `preDeployCommand` string
            - `registryCredential` RegistryCredential
              - …
          - NativeEnvironmentDetails
            - `buildCommand` string, required
            - `startCommand` string, required
            - `preDeployCommand` string
        - `numInstances` integer, required — For a *manually* scaled service, this is the number of instances the service is scaled to. DOES NOT indicate the number of running instances for an *autoscaled* service.
        - `parentServer` Resource
          - `id` string, required
          - `name` string, required
        - `plan` 'starter' | 'starter_plus' | 'standard' | 'standard_plus' | 'pro' | 'pro_plus' | 'pro_max' | 'pro_ultra' | 'free' | 'custom' | 'starter_legacy' | 'standard_legacy' | 'standard_plus_legacy' | 'pro_legacy' | 'pro_plus_legacy', required — The instance type to use. Legacy variants (`*_legacy`) identify grandfathered plans no longer offered for new services. Note that base services on any paid instance type can't create preview instances with the `free` instance type.
        - `pullRequestPreviewsEnabled` 'yes' | 'no' — This field has been deprecated. previews.generation should be used in its place.
        - `previews` Previews
          - `generation` 'off' | 'manual' | 'automatic' — Defaults to "off"
        - `region` 'frankfurt' | 'oregon' | 'ohio' | 'singapore' | 'virginia', required — Defaults to "oregon"
        - `runtime` 'docker' | 'elixir' | 'go' | 'node' | 'python' | 'ruby' | 'rust' | 'image', required — Runtime
        - `sshAddress` string — The SSH address for the service. Only present for services that have SSH enabled.
        - `buildPlan` 'starter' | 'performance', required
        - `maxShutdownDelaySeconds` integer — The maximum amount of time (in seconds) that Render waits for your application process to exit gracefully after sending it a SIGTERM signal.
      - CronJobDetails
        - `env` 'docker' | 'elixir' | 'go' | 'node' | 'python' | 'ruby' | 'rust' | 'image', required — This field has been deprecated, runtime should be used in its place.
        - `envSpecificDetails` union, required
          - DockerDetails
            - `dockerCommand` string, required
            - `dockerContext` string, required
            - `dockerfilePath` string, required
            - `preDeployCommand` string
            - `registryCredential` RegistryCredential
              - …
          - NativeEnvironmentDetails
            - `buildCommand` string, required
            - `startCommand` string, required
            - `preDeployCommand` string
        - `lastSuccessfulRunAt` string, date-time
        - `plan` 'starter' | 'starter_plus' | 'standard' | 'standard_plus' | 'pro' | 'pro_plus' | 'pro_max' | 'pro_ultra' | 'free' | 'custom' | 'starter_legacy' | 'standard_legacy' | 'standard_plus_legacy' | 'pro_legacy' | 'pro_plus_legacy', required — The instance type to use. Legacy variants (`*_legacy`) identify grandfathered plans no longer offered for new services. Note that base services on any paid instance type can't create preview instances with the `free` instance type.
        - `region` 'frankfurt' | 'oregon' | 'ohio' | 'singapore' | 'virginia', required — Defaults to "oregon"
        - `runtime` 'docker' | 'elixir' | 'go' | 'node' | 'python' | 'ruby' | 'rust' | 'image', required — Runtime
        - `schedule` string, required
        - `buildPlan` 'starter' | 'performance', required
  - `deployId` string

## Other responses

- `400` — The request could not be understood by the server.
- `401` — Authorization information is missing or invalid.
- `403` — You do not have permissions for the requested resource.
- `404` — Unable to find the requested resource.
- `429` — Rate limit has been surpassed.
- `500` — An unexpected server error has occurred.
- `503` — Server currently unavailable.

---

[API](https://skmtc.dev/render/apis/render-public-api.md) · [All operations](https://skmtc.dev/render/apis/render-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/render/render-public-api/revisions/80e0ff74d033/schema)