Sign in

v1

latestOpenAPI 3.0.0Apache 2.0 License2026-07-14120262383.5 KB

Creates a new Stage resource that references a pre-existing Deployment for the API.

post/restapis/{restapi_id}/stages

Path parameters

restapi_idstring required

The string identifier of the associated RestApi.

Request body

stageNamestring required

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

deploymentIdstring required

The identifier of the Deployment resource for the Stage resource.

descriptionstring

The description of the Stage resource.

cacheClusterEnabledboolean

Whether cache clustering is enabled for the stage.

cacheClusterSize'0.5' | '1.6' | '6.1' | '13.5' | '28.4' | '58.2' | '118' | '237'

Returns the size of the CacheCluster.

variablesobject

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 <code>[A-Za-z0-9-._~:/?#&=,]+</code>.

documentationVersionstring

The version of the associated API documentation.

tracingEnabledboolean

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

tagsobject

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 <code>aws:</code>. The tag value can be up to 256 characters.

Response

Success

deploymentIdstring

The identifier of the Deployment that the stage points to.

clientCertificateIdstring

The identifier of a client certificate for an API stage.

stageNamestring

The name of the stage is the first path segment in the Uniform Resource Identifier (URI) of a call to API Gateway. Stage names can only contain alphanumeric characters, hyphens, and underscores. Maximum length is 128 characters.

descriptionstring

The stage's description.

cacheClusterEnabledboolean

Specifies whether a cache cluster is enabled for the stage.

cacheClusterSize'0.5' | '1.6' | '6.1' | '13.5' | '28.4' | '58.2' | '118' | '237'

The stage's cache capacity in GB. For more information about choosing a cache size, see <a href="https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html">Enabling API caching to enhance responsiveness</a>.

cacheClusterStatus'CREATE_IN_PROGRESS' | 'AVAILABLE' | 'DELETE_IN_PROGRESS' | 'NOT_AVAILABLE' | 'FLUSH_IN_PROGRESS'

The status of the cache cluster for the stage, if enabled.

methodSettingsobject

A map that defines the method settings for a Stage resource. Keys (designated as <code>/{method_setting_key</code> below) are method paths defined as <code>{resource_path}/{http_method}</code> for an individual method override, or <code>/*/*</code> for overriding all methods in the stage.

variablesobject

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

documentationVersionstring

The version of the associated API documentation.

tracingEnabledboolean

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

webAclArnstring

The ARN of the WebAcl associated with the Stage.

tagsobject

The collection of tags. Each tag element is associated with a given resource.

createdDatestring date-time

The timestamp when the stage was created.

lastUpdatedDatestring date-time

The timestamp when the stage last updated.