_create.md.erb

### Create a deployment

```
Example Request with Droplet
```

```shell
curl "https://api.example.org/v3/deployments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
  "droplet": {
    "guid": "[droplet-guid]"
  },
  "strategy": "rolling",
  "relationships": {
    "app": {
      "data": {
        "guid": "[app-guid]"
      }
    }
  }
}'
```

```
Example Request with Revision
```

```shell
curl "https://api.example.org/v3/deployments" \
-X POST \
-H "Authorization: bearer [token]" \
-H "Content-type: application/json" \
-d '{
  "revision": {
    "guid": "[revision-guid]"
  },
  "strategy": "rolling",
  "relationships": {
    "app": {
      "data": {
        "guid": "[app-guid]"
      }
    }
  }
}'
```

```
Example Response
```

```http
HTTP/1.1 201 OK
Content-Type: application/json

<%= yield_content :single_deployment %>
```

When you create a new deployment you can either provide a specific droplet or revision to deploy. If no revision or droplet is provided, the droplet associated with the [app](#apps) is deployed.

#### Definition
`POST /v3/deployments`

#### Required parameters

Name | Type | Description
---- | ---- | -----------
**relationships.app** | [_to-one relationship_](#to-one-relationships) | The app to deploy a droplet for

#### Optional parameters

Name | Type | Description | Default
---- | ---- | ----------- | -------
**droplet**<sup>[1]</sup> | _object_ | The droplet to deploy for the app; this will update the app's [current droplet](#get-current-droplet-association-for-an-app) to this droplet | The app's [current droplet](#get-current-droplet-association-for-an-app)
**revision**<sup>[1]</sup> | _object_ | The [revision](#revisions) whose droplet to deploy for the app; this will update the app's [current droplet](#get-current-droplet-association-for-an-app) to this droplet |
**strategy** | _string_ | The strategy to use for the deployment | `rolling`
**options.max_in_flight** | _integer_ | The maximum number of new instances to deploy simultaneously | 1
**options.web_instances** | _integer_ | The number of web instances the deployment will scale to | The current web process's instance count
**options.memory_in_mb** |  _integer_ | The amount of memory in megabytes to allocate per web process instance.  If `null`, the amount allocated will be taken from the previous web process. | `null`
**options.disk_in_mb** | _integer_ | The amount of disk in megabytes to allocate per web process instance.  If `null`, the amount allocated will be taken from the previous web process. | `null`
**options.log_rate_limit_in_bytes_per_second** | _integer_ | Log rate limit in bytes per second to allocate per web process instance.  If `null`, the amount allocated will be taken from the previous web process. | `null`
**options.canary.steps** | _array of [canary step objects](#canary-steps-object)_ | An array of canary steps to use for the deployment
**metadata.labels** | [_label object_](#labels) | Labels applied to the deployment
**metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the deployment


<sup>1 Only a droplet _or_ a revision may be provided, not both.</sup>

#### Permitted roles
 |
--- |
Admin |
Space Developer |
Space Supporter |