Amazon API Gateway REST API Reference


Creates a new stage, as represented by a Stage instance, in a pre-existing Deployment of an API.

HTTP Request

POST /restapis/<restapi_id>/stages

Request Body

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

Request Body Fields

The request accepts the following fields in JSON format.

  • stageName
  • [Required] The name for the Stage resource. Stage names can only contain alphanumeric characters, hyphens, and underscores. Maximum length is 128 characters.

  • deploymentId
  • [Required] The identifier of the Deployment resource for the Stage resource.

  • description
  • The description of the Stage resource.

  • cacheClusterEnabled
  • Whether cache clustering is enabled for the stage.

  • cacheClusterSize
  • The stage's cache cluster size.

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

  • documentationVersion
  • The version of the associated API documentation.

  • canarySettings
  • The canary deployment settings of this stage.

    • percentTraffic
    • The percent (0-100) of traffic diverted to a canary deployment.

    • stageVariableOverrides
    • Stage variables overridden for a canary release deployment, including new stage variables introduced in the canary. 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 deployment uses the stage cache or not.

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

  • tags
  • The key-value map of strings. The valid character set is [a-zA-Z+-=._:/]. The tag key can be up to 128 characters and must not start with aws:. The tag value can be up to 256 characters.




Example: Create a new stage for a deployed API


The following request creates a new stage named alpha, enabling the stage-level API caching with the cache cluster size of 0.5 GB and adding two stage variables, sv_1 and sv_2.

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

  "stageName" : "alpha",
  "deploymentId" : "vakw79",
  "description" : "alpha stage",
  "cacheClusterEnabled" : "true",
  "cacheClusterSize" : "0.5",
  "variables" : {
    "sv_1" : "value_1",
    "sv_2" : "value_2"

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

  "_links": {
    "curies": {
      "href": "{rel}.html&quot;,
      "name": "stage",
      "templated": true
    "self": {
      "href": "/restapis/uycll6xg9a/stages/alpha"
    "stage:delete": {
      "href": "/restapis/uycll6xg9a/stages/alpha"
    "stage:flush-authorizer-cache": {
      "href": "/restapis/uycll6xg9a/stages/alpha/cache/authorizers"
    "stage:flush-cache": {
      "href": "/restapis/uycll6xg9a/stages/alpha/cache/data"
    "stage:update": {
      "href": "/restapis/uycll6xg9a/stages/alpha"
  "cacheClusterEnabled": true,
  "cacheClusterSize": "0.5",
  "cacheClusterStatus": "CREATE_IN_PROGRESS",
  "createdDate": "2016-06-08T20:02:50Z",
  "deploymentId": "vakw79",
  "description": "alpha stage",
  "lastUpdatedDate": "2016-06-08T20:02:50Z",
  "methodSettings": {},
  "stageName": "alpha",
  "variables": {
    "sv_2": "value_2",
    "sv_1": "value_1"

See Also