New deployments can also be scheduled through [Create new deployment](/support/api/deployments/create-a-new-deployment#scheduling-a-deployment). Use these API endpoints for managing scheduled deployments directly.

**Tip**: You can explore and test this endpoint interactively using our [OpenAPI documentation](https://api.deployhq.com/docs).

# 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

```bash
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

```json
[  
   {  
      "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

```text
/projects/<project>/scheduled_deployments
```

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

## HTTP Method

```http
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

```bash
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.

```json
{
    "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

```text
/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

```http
PUT
```

## Parameters

Same parameters as Create (all optional for update).

## Example cURL request

```bash
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

```text
/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

```text
GET
```

## Example cURL request

```shell
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

```json
{
    "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

```bash
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.