Create new deployment via API

Last updated on 12th November 2025

This method will create a deployment.

Tip: You can explore and test this endpoint interactively using our OpenAPI documentation.

URL

/projects/<project>/deployments

Replace <project> with either the permalink or identifier of the project.

HTTP Method

POST

Supported Parameters

parent_identifier - The UUID of the server or server group to deploy to (required)
start_revision - The start revision of the deployment (required, a blank value can be sent if you wish to deploy the entire branch)
end_revision - The end revision of the deployment (required)
branch - The branch you wish to deploy from
mode - The deployment mode, can be queue or preview
copy_config_files - If config files should be copied during the deployment, either true or false
run_build_commands - If you want to run build commands during the deployment, either true or false
use_build_cache - If you want to use the project's build cache (if configured), either true or false
use_latest - Set the deployment to use the last commit deployed and the latest in the repository (used only for scheduling deployments). Send a string of "1" to enable the option.
deploy_entire_repository - Deploy the entire repository on each scheduled deployment run (used only for scheduling deployments). When enabled, deploys all files from the very first commit to the latest commit, overriding any commit selection. Send true or false.

Example cURL request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
-d '{"deployment":{ "parent_identifier":"7563d091-ca73-588e-cfe2-e4936f190145", \
      "start_revision" : "e8f6302c76baae1cef0ea4960f770087bfe3a129", \
      "end_revision" : "e84b5937f1132932dd56026db26a76f406555c19", \
      "mode" : "queue", \
      "copy_config_files" : 1, \
      "email_notify" : 1 \
    }}' http://test.deployhq.com/projects/project/deployments/

Example Response (Completed)

{
  "files": {
    "7563d091-ca73-588e-cfe2-e4936f190145" : {
      "removed": [
        "removed_file_1.txt",
        "removed_file_2.txt"
      ],
      "changed": [
        "added_file_1.txt",
        "modified_file_1.txt"
      ]
    }
  },
  "log": [
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "info",
      "message": "Disconnected from SFTP/SSH server"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "success",
      "message": "Deployment complete"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "info",
      "message": "0 config file(s) need to be uploaded"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "info",
      "message": "0 file(s) have been changed and will be uploaded"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "info",
      "message": "0 file(s) are no longer required and will be removed"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "info",
      "message": "Connected to SFTP/SSH server at host.example.com:22"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "note",
      "message": "Connecting to server at host.example.com:22"
    },
    {
      "timestamp": "2011-11-28T12:36:13Z",
      "type": "note",
      "message": "Calculating changes required for deployment"
    },
    {
      "timestamp": "2011-11-28T12:35:55Z",
      "type": "note",
      "message": "Beginning deployment from e84b5937f1132932dd56026db26a76f406555c19 to e84b5937f1132932dd56026db26a76f406555c19 (master)"
    }
  ],
  "project": {
    "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAsj+rjTUvuaXXAsI4WapI8WXH...= DeployHQ.com Key for example-project",
    "permalink": "example-project",
    "name": "Example Project",
    "repository": {
      "port": null,
      "username": "",
      "url": "git@codebasehq.account/example-project/app.git",
      "branch": "master",
      "scm_type": "git",
      "cached": true,
      "hosting_service": {
        "name": "Codebase",
        "url": "http://www.codebasehq.com",
        "commits_url": "http://account.codebasehq.com/projects/example-project/repositories/app/commits/master",
        "tree_url": "http://phoenixdev5.codebasehq.com/projects/example-project/repositories/app/tree/master"
      }
    }
  },
  "servers": [
    {
      "name": "Server",
      "port": 22,
      "server_path": "/var/www/app",
      "username": "dan",
      "use_ssh_keys": false,
      "last_revision": "e84b5937f1132932dd56026db26a76f406555c19",
      "hostname": "host.example.com",
      "identifier": "7563d091-ca73-588e-cfe2-e4936f190145",
      "protocol_type": "ssh"
    }
  ],
  "start_revision": {
    "author": "Dan Wentworth",
    "timestamp": "2011-01-30T00:12:58+00:00",
    "ref": "e84b5937f1132932dd56026db26a76f406555c19",
    "message": "updated configs",
    "email": "dan@atechmedia.com"
  },
  "configuration": {
    "email_notify": false,
    "notification_addresses": "dan@atechmedia.com",
    "copy_config_files": true
  },
  "timestamps": {
    "duration": null,
    "completed_at": "2011-11-28T12:36:13Z",
    "queued_at": "2011-11-28T12:35:52Z",
    "started_at": "2011-11-28T12:35:55Z"
  },
  "identifier": "22585edc-e0c6-24d7-372e-c13755d1c2da",
  "end_revision": {
    "author": "Dan Wentworth",
    "timestamp": "2011-01-30T00:12:58+00:00",
    "ref": "e84b5937f1132932dd56026db26a76f406555c19",
    "message": "updated database configs",
    "email": "dan@atechmedia.com"
  },
  "status": "completed"
}

Example Response (Preview)

{
  "status":"preview_pending",
  "identifier":"6bd5cdc4-d652-92e8-322f-287929091f03"
}

When creating a preview deployment, you can poll the /projects/<project>/deployments/<uuid>/preview endpoint to see its progress and a list of potential file changes once the preview has been fully generated.

Scheduling a deployment

When scheduling a deployment using the API, the following data must be sent in addition to the normal parameters for a deployment:

at - Use future, daily, weekly or monthly to schedule a new deployment.

Depending on the type of at schedule used, the following parameters will be required (all values are numeric unless otherwise stated):

`future`

day - The starting day of the month
month - The starting month of the year
year - The starting year
hour - The starting hour
minute - The starting minute

`daily`

hour - The starting hour
minute - The starting minute

`weekly`

weekday - The start day of the week (send as literal string representing the day of the week, i.e. "Monday")
hour - The starting hour
minute - The starting minute

`monthly`

day - The starting day of the month
hour - The starting hour
minute - The starting minute

Example cURL request (for a weekly schedule set for 9am every Monday)

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
-d '{ \
      "deployment":{ \
        "parent_identifier":"7563d091-ca73-588e-cfe2-e4936f190145", \
        "start_revision" : "e84b5937f1132932dd56026db26a76f406555c19", \
        "end_revision" : "e84b5937f1132932dd56026db26a76f406555c19", \
        "mode" : "queue", \
        "copy_config_files" : 1, \
        "email_notify" : 1 \
      }, \
      "schedule":{ \
        "frequency": "weekly", \
        "weekly":{ \
          "weekday" : "Monday", \
          "hour": "9", \
          "minute": "0" \
        } \
      } \
    }' http://test.deployhq.com/projects/project/deployments/

Example Response

This additional data is returned if a deployment has been scheduled, along with the normal payload for a deployment:

  "frequency":"weekly",
  "at":{
    "weekday":"Monday",
    "hour":9,
    "minute":0
  },
  "next_deployment_at":"2018-07-30T09:00:00.000+01:00"

Free account deployments

For free DeployHQ accounts, there are some details to note in the response body. These are the following:

The deferred variable, which is set to true during the deployment execution, and set to false once the deployment is completed.
While the deferred variable is set to true, the deployment will be queued for 90 seconds before it starts running. This is reflected in the difference between the queued_at and runs_at timestamps found in the response body.