Amazon API Gateway REST API Reference


Creates a new Deployment for the API, which will be referenced by the provided Stage. If the specified stage already exists, it will be updated to point to the new deployment. If the stage does not exist, a new one will be created and point to this deployment.

HTTP Request

POST /restapis/<restapi_id>/deployments

Request Body

  "stageName" : "String",
  "stageDescription" : "String",
  "description" : "String",
  "cacheClusterEnabled" : "Boolean",
  "cacheClusterSize" : "String",
  "variables" : {
    "String" : "String"
  "canarySettings" : {
    "percentTraffic" : "Double",
    "stageVariableOverrides" : {
      "String" : "String"
    "useStageCache" : "Boolean"
  "tracingEnabled" : "Boolean"

Request Body Fields

The request accepts the following fields in JSON format.

  • stageName
  • The name of the Stage resource for the Deployment resource to create.

  • stageDescription
  • The description of the Stage resource for the Deployment resource to create.

  • description
  • The description for the Deployment resource to create.

  • cacheClusterEnabled
  • Enables a cache cluster for the Stage resource specified in the input.

  • cacheClusterSize
  • Specifies the cache cluster size for the Stage resource specified in the input, if a cache cluster is enabled.

  • variables
  • A map that defines the stage variables for the Stage resource that is associated with the new deployment. Variable names can have alphanumeric and underscore characters, and the values must match [A-Za-z0-9-._~:/?#&=,]+.

  • canarySettings
  • The input configuration for the canary deployment when the deployment is a canary release deployment.

    • percentTraffic
    • The percentage (0.0-100.0) of traffic routed to the canary deployment.

    • stageVariableOverrides
    • A stage variable overrides used for the canary release deployment. They can override existing stage variables or add new stage variables for the canary release deployment. These stage variables are represented as a string-to-string map between stage variable names and their values.

    • useStageCache
    • A Boolean flag to indicate whether the canary release deployment uses the stage cache or not.

  • tracingEnabled
  • Specifies whether active tracing with X-ray is enabled for the Stage.




You must create a deployment to make your API publicly accessible.

Example: Create a new deployment of an API


The following example request creates a deployment for a specified API (fugvjdxtri) along with a given stage (stage1) and a stage variable (sv1).

POST /restapis/fugvjdxtri/deployments HTTP/1.1
Content-Type: application/json
X-Amz-Date: 20160603T175605Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash}

  "stageName" : "stage1",
  "stageDescription" : "First stage",
  "description" : "First deployment",
  "cacheClusterEnabled" : "false",
  "variables" : {
    "sv1" : "opVar"

The successful response returns the 201 Created status and a payload similar to the following:

  "_links": {
    "curies": {
      "href": "{rel}.html&quot;,
      "name": "deployment",
      "templated": true
    "self": {
      "href": "/restapis/fugvjdxtri/deployments/dzacq7"
    "deployment:delete": {
      "href": "/restapis/fugvjdxtri/deployments/dzacq7"
    "deployment:stages": {
      "href": "/restapis/fugvjdxtri/stages?deployment_id=dzacq7"
    "deployment:update": {
      "href": "/restapis/fugvjdxtri/deployments/dzacq7"
  "createdDate": "2016-06-03T17:56:06Z",
  "description": "First deployment",
  "id": "dzacq7"

When an API is deployed successfully as above, the API becomes accessible with the https://{restapi_id}.execute-api.{region}}{stage_name} URL. In this example, it becomes

See Also

Deploying an API, AWS CLI