---
title: "Queue, preview or schedule a deployment"
method: POST
path: "/projects/{project_id}/deployments"
tags: ["Deployments"]
---

# Queue, preview or schedule a deployment

`POST /projects/{project_id}/deployments`

## Request

- Base URL: `https://sg.deployhq.com`
- URL: `https://sg.deployhq.com/projects/{project_id}/deployments`
- Auth: HTTP basic

Creates a new deployment for the project. Set mode to 'queue' to execute immediately or 'preview' to generate a preview of changes without deploying. If a schedule block is provided, the deployment is scheduled for future or recurring execution. Use parent_identifier to target a specific server or server group. The deployment status field can be: pending, running, completed, failed, preview_pending, preview_ready, or preview_failed.

## Path parameters

- `project_id` string, required

## Request body

- DeploymentScheduleSaveServerBranchObject
  - `deployment` object, required
    - `start_revision` string
    - `end_revision` string
    - `copy_config_files` boolean
    - `notification_addresses` string
    - `branch` string
    - `parent_identifier` string
    - `server_identifier` string
    - `run_build_commands` boolean
    - `use_build_cache` boolean
    - `config_files_deployment` boolean
    - `mode` string
    - `use_latest` boolean
    - `skip_if_not_changes` boolean
  - `schedule` object
    - `frequency` string
    - `future` object
      - `day` integer
      - `month` integer
      - `year` integer
      - `hour` integer
      - `minute` integer
    - `daily` object
      - `hour` integer
      - `minute` integer
    - `weekly` object
      - `weekday` integer
      - `hour` integer
      - `minute` integer
    - `monthly` object
      - `day` integer
      - `hour` integer
      - `minute` integer
    - `custom` object
      - `schedule` string
      - `hour` integer
      - `minute` integer
  - `save_server_branch` string
  - `deployment_overview` string

## Response `201`

Queued Deployment

- Deployment
  - `identifier` string
  - `servers` object[]
    - `id` integer
    - `identifier` string
    - `name` string
    - `protocol_type` string
    - `server_path` string
    - `last_revision` string
    - `preferred_branch` string
    - `branch` string
    - `notify_email` string
    - `server_group_identifier` string, nullable
    - `auto_deploy` boolean
    - `environment` string
    - `enabled` boolean
    - `agent` string, nullable
    - `atomic` boolean
    - `atomic_strategy` string
    - `atomic_retention` integer
    - `use_compression` boolean
    - `use_accelerated_transfer` boolean
    - `use_parallel_upload` boolean
    - `root_path` string
    - `position` integer
    - `created_at` string
    - `updated_at` string
    - `connection_checked_at` string, nullable
    - `connection_error_message` string, nullable
    - `hostname` string
    - `username` string
    - `port` string
    - `use_ssh_keys` boolean
    - `host_key` string
    - `unlink_before_upload` boolean
  - `project` object
    - `name` string
    - `permalink` string
    - `identifier` string
    - `public_key` string
    - `repository` object
      - `scm_type` string
      - `url` string
      - `port` integer, nullable
      - `username` string, nullable
      - `branch` string
      - `cached` boolean
      - `hosting_service` object
        - `name` string
        - `url` string
        - `tree_url` string
        - `commits_url` string
    - `repository_url` string
    - `zone` string
    - `last_deployed_at` string
    - `folder` string, nullable
    - `auto_deploy_url` string
  - `deployer` string, nullable
  - `deployer_avatar` string, nullable
  - `branch` string
  - `start_revision` object
    - `ref` string
  - `end_revision` object
    - `ref` string
  - `status` string
  - `timestamps` object
    - `queued_at` string
    - `started_at` string, nullable
    - `completed_at` string, nullable
    - `duration` string, nullable
    - `runs_at` string
  - `files` object
    - `0eac5db5-1bfa-46fd-a296-c617622de301` object
      - `changed` unknown[]
        - unknown
      - `removed` unknown[]
        - unknown
  - `configuration` object
    - `copy_config_files` boolean
    - `notification_addresses` string
    - `skip_project_files` boolean
  - `legacy` boolean
  - `deferred` boolean
  - `config_files_deployment` boolean
  - `overview` string, nullable
  - `metadata` object
  - `archived` boolean
  - `archived_at` string, nullable
  - `log_summary` string, nullable
  - `steps` object[]
    - `step` string
    - `stage` string
    - `identifier` string
    - `server` string, nullable
    - `total_items` string, nullable
    - `completed_items` string, nullable
    - `description` string
    - `status` string
    - `logs` boolean
    - `explainable` boolean
    - `deployment_started_at` string, nullable
    - `updated_at` string

## Other responses

- `401`: You are not authorized to access this resource. You need to authenticate yourself first.
- `403`: You are not allowed to access this resource. You do not have the necessary permissions.
- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: An unexpected error occurred on the server. The server was unable to process the request.

---

[API](https://skmtc.dev/deployhq/apis/deployhq-api-interactive-documentation.md) · [All operations](https://skmtc.dev/deployhq/apis/deployhq-api-interactive-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/deployhq/apis/deployhq-api-interactive-documentation/revisions/830264ae58be?raw)