/v2/apis/{apiId}/stages

POST

Creates a Stage for an API.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/v2/apis//stages' \
--header 'Content-Type: application/json' \
--data-raw ''

Response Example

201 - Example 1

{
  "AccessLogSettings": {
    "DestinationArn": "string",
    "Format": "string"
  },
  "ApiGatewayManaged": true,
  "AutoDeploy": true,
  "ClientCertificateId": "string",
  "CreatedDate": "string",
  "DefaultRouteSettings": {
    "DataTraceEnabled": true,
    "DetailedMetricsEnabled": true,
    "LoggingLevel": "ERROR",
    "ThrottlingBurstLimit": 0,
    "ThrottlingRateLimit": 0
  },
  "DeploymentId": "string",
  "Description": "string",
  "LastDeploymentStatusMessage": "string",
  "LastUpdatedDate": "string",
  "RouteSettings": {
    "property1": {},
    "property2": {}
  },
  "StageName": "string",
  "StageVariables": {
    "property1": "string",
    "property2": "string"
  },
  "Tags": {
    "property1": "string",
    "property2": "string"
  }
}

Request

Path Params

apiId

string

required

The API identifier.

Body Params application/json

accessLogSettings

object

optional

Settings for logging access in a stage.

DestinationArn

string

optional

The ARN of the CloudWatch Logs log group to receive access logs.

Format

string

optional

A single line format of the access logs of data, as specified by selected

co n t e x t v a r iab l es . T h e f or ma t m u s t in c l u d e a tl e a s t

context.requestId.

autoDeploy

boolean

optional

Specifies whether updates to an API automatically trigger a new deployment. The default value is false.

clientCertificateId

string

optional

The identifier.

defaultRouteSettings

object

optional

Represents a collection of route settings.

DataTraceEnabled

boolean

optional

Specifies whether (true) or not (false) data trace logging is enabled for this route. This property affects the log entries pushed to Amazon CloudWatch Logs. Supported only for WebSocket APIs.

DetailedMetricsEnabled

boolean

optional

Specifies whether detailed metrics are enabled.

LoggingLevel

enum<string>

optional

Specifies the logging level for this route: INFO, ERROR, or OFF. This property affects the log entries pushed to Amazon CloudWatch Logs. Supported only for WebSocket APIs.

Allowed values:

ERRORINFOOFF

ThrottlingBurstLimit

integer

optional

Specifies the throttling burst limit.

ThrottlingRateLimit

number <double>

optional

Specifies the throttling rate limit.

deploymentId

string

optional

The identifier.

description

string

optional

A string with a length between [0-1024].

routeSettings

object

optional

The route settings map.

Additional properties

object (RouteSettings)

optional

Represents a collection of route settings.

stageName

string

required

A string with a length between [1-128].

stageVariables

object

optional

The stage variable map.

Additional properties

string

optional

A string with a length between [0-2048].

Responses

🟢201Success

application/json

Body

AccessLogSettings

object

optional

Settings for logging access in this stage.

DestinationArn

string

optional

The ARN of the CloudWatch Logs log group to receive access logs.

Format

string

optional

A single line format of the access logs of data, as specified by selected

co n t e x t v a r iab l es . T h e f or ma t m u s t in c l u d e a tl e a s t

context.requestId.

ApiGatewayManaged

boolean

optional

Specifies whether a stage is managed by API Gateway. If you created an API using quick create, the

d e f a u lt s t a g e i s mana g e d b y A P I G a t e w a y . Y o u c a n^{'} t m o d i f y t h e

default stage.

AutoDeploy

boolean

optional

Specifies whether updates to an API automatically trigger a new deployment. The default value is false.

ClientCertificateId

string

optional

The identifier of a client certificate for a Stage. Supported only for WebSocket APIs.

CreatedDate

string <date-time>

optional

The timestamp when the stage was created.

DefaultRouteSettings

object

optional

Default route settings for the stage.

DataTraceEnabled

boolean

optional

Specifies whether (true) or not (false) data trace logging is enabled for this route. This property affects the log entries pushed to Amazon CloudWatch Logs. Supported only for WebSocket APIs.

DetailedMetricsEnabled

boolean

optional

Specifies whether detailed metrics are enabled.

LoggingLevel

enum<string>

optional

Specifies the logging level for this route: INFO, ERROR, or OFF. This property affects the log entries pushed to Amazon CloudWatch Logs. Supported only for WebSocket APIs.

Allowed values:

ERRORINFOOFF

ThrottlingBurstLimit

integer

optional

Specifies the throttling burst limit.

ThrottlingRateLimit

number <double>

optional

Specifies the throttling rate limit.

DeploymentId

string

optional

The identifier of the Deployment that the Stage is associated with. Can't be updated if autoDeploy is enabled.

Description

string

optional

The description of the stage.

LastDeploymentStatusMessage

string

optional

Describes the status of the last deployment of a stage. Supported only for stages with autoDeploy enabled.

LastUpdatedDate

string <date-time>

optional

The timestamp when the stage was last updated.

RouteSettings

object

optional

Route settings for the stage, by routeKey.

StageName

string

optional

The name of the stage.

StageVariables

object

optional

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