Last updated on 2nd April 2026

Managing Scheduled Deployments via API

New deployments can also be scheduled through Create new deployment. Use these API endpoints for managing scheduled deployments directly.

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

List Scheduled Deployments

This endpoint displays all upcoming scheduled deployments on a project.

URL

/projects/<project>/scheduled_deployments

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

HTTP Method

GET

Example cURL request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
https://test.deployhq.com/projects/project/scheduled_deployments

Example Response

[  
   {  
      "identifier":"babc250c-5a89-473e-9bba-4d44b346f260",
      "server":{  
         "id":5,
         "identifier":"84a3e26f-b8fa-4d08-8ccd-801c946cc251",
         "name":"localhost",
         "protocol_type":"ssh",
         "server_path":"testing/",
         "last_revision":"0bb2e6bfb464c43a45495f74ae2de14defd1d861",
         "preferred_branch":"master",
         "branch":"",
         "notify_email":"",
         "server_group_identifier":null,
         "auto_deploy":true,
         "hostname":"localhost",
         "username":"dan",
         "port":"22",
         "use_ssh_keys":false,
         "unlink_before_upload":false
      },
      "start_revision":"___PREVIOUS___",
      "end_revision":"__CURRENT__",
      "frequency":"daily",
      "at":{  
         "hour":9,
         "minute":0
      },
      "next_deployment_at":"2019-01-05T09:00:00.000Z",
      "copy_config_files":true,
      "run_build_commands":false,
      "use_build_cache":false
   }
]

Create Scheduled Deployment

Create a new scheduled deployment for a project.

URL

/projects/<project>/scheduled_deployments

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

HTTP Method

POST

Parameters

Parameter Type Required Description
server_identifier String Yes The identifier of the server or server group to deploy to
frequency String Yes One of: future, daily, weekly, monthly, custom
at String or Object Yes Either HH:MM (e.g. 02:00) or an object containing schedule fields (hour, minute, plus weekday/day/month/year/schedule as required by frequency)
copy_config_files Boolean No Whether to copy config files
run_build_commands Boolean No Whether to run build commands
use_build_cache Boolean No Whether to use build cache
skip_if_not_changes Boolean No Skip deployment if no changes detected
start_revision String No Start revision (defaults to previous deployed commit)
end_revision String No End revision (defaults to latest repository commit)
weekday String No Day name for weekly frequency (e.g. Monday)
day Integer No Day of month for monthly/future frequency
month Integer No Month for future frequency
year Integer No Year for future frequency
schedule String No Cron expression for custom frequency

Example cURL request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
-X POST \
-d '{"scheduled_deployment":{"server_identifier":"84a3e26f-b8fa-4d08-8ccd-801c946cc251","frequency":"daily","at":"02:00","copy_config_files":false,"run_build_commands":false,"use_build_cache":false}}' \
https://test.deployhq.com/projects/project/scheduled_deployments

Example Response

HTTP Status will be 201 for Created and 422 if validation fails.

{
    "identifier": "babc250c-5a89-473e-9bba-4d44b346f260",
    "server": {
        "identifier": "84a3e26f-b8fa-4d08-8ccd-801c946cc251",
        "name": "localhost",
        "protocol_type": "ssh"
    },
    "start_revision": "___PREVIOUS___",
    "end_revision": "__CURRENT__",
    "frequency": "daily",
    "at": {
        "hour": 2,
        "minute": 0
    },
    "next_deployment_at": "2026-04-02T02:00:00.000Z",
    "copy_config_files": false,
    "run_build_commands": false,
    "use_build_cache": false
}

Update Scheduled Deployment

Update an existing scheduled deployment. All parameters are optional and only provided fields are updated.

URL

/projects/<project>/scheduled_deployments/<identifier>

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

HTTP Method

PUT

Parameters

Same parameters as Create (all optional for update).

Example cURL request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
-X PUT \
-d '{"scheduled_deployment":{"at":"04:30","copy_config_files":true}}' \
https://test.deployhq.com/projects/project/scheduled_deployments/babc250c-5a89-473e-9bba-4d44b346f260

Example Response

HTTP Status will be 200 for OK and 422 if validation fails. Returns the full updated scheduled deployment object.

View Scheduled Deployment

View a single scheduled deployment and its configuration.

URL

/projects/<project>/scheduled_deployments/<identifier>

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

HTTP Method

GET

Example cURL request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
https://test.deployhq.com/projects/project/scheduled_deployments/babc250c-5a89-473e-9bba-4d44b346f260

Example Response

{
    "identifier": "babc250c-5a89-473e-9bba-4d44b346f260",
    "server": {
        "id": 5,
        "identifier": "84a3e26f-b8fa-4d08-8ccd-801c946cc251",
        "name": "localhost",
        "protocol_type": "ssh",
        "server_path": "testing/",
        "last_revision": "0bb2e6bfb464c43a45495f74ae2de14defd1d861",
        "preferred_branch": "master",
        "branch": "",
        "notify_email": "",
        "server_group_identifier": null,
        "auto_deploy": true,
        "hostname": "localhost",
        "username": "dan",
        "port": "22",
        "use_ssh_keys": false,
        "unlink_before_upload": false
    },
    "start_revision": "___PREVIOUS___",
    "end_revision": "__CURRENT__",
    "frequency": "daily",
    "at": {
        "hour": 9,
        "minute": 0
    },
    "next_deployment_at": "2019-01-05T09:00:00.000Z",
    "copy_config_files": true,
    "run_build_commands": false,
    "use_build_cache": false
}

Delete Scheduled Deployment

Delete a scheduled deployment to stop it running in future.

URL

/projects/<project>/scheduled_deployments/<identifier>

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

HTTP Method

DELETE

Example cURL request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \ 
-X DELETE \
https://test.deployhq.com/projects/project/scheduled_deployments/babc250c-5a89-473e-9bba-4d44b346f260

Example Response

HTTP Status will be 200 for OK and 422 if the deletion fails.