Amazon API Gateway

openapi: 3.0.0
info:
  version: 2015-07-09
  x-release: v4
  title: Amazon API Gateway
  description: <fullname>Amazon API Gateway</fullname> <p>Amazon API Gateway helps developers deliver robust, secure, and scalable mobile and web application back ends. API Gateway allows developers to securely connect mobile and web applications to APIs that run on AWS Lambda, Amazon EC2, or other publicly addressable web services that are hosted outside of AWS.</p>
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_twitter.com_awscloud_profile_image.png
    backgroundColor: "#FFFFFF"
  termsOfService: https://aws.amazon.com/service-terms/
  contact:
    name: Mike Ralphson
    email: mike.ralphson@gmail.com
    url: https://github.com/mermade/aws2openapi
    x-twitter: PermittedSoc
  license:
    name: Apache 2.0 License
    url: http://www.apache.org/licenses/
  x-providerName: amazonaws.com
  x-serviceName: apigateway
  x-origin:
    - contentType: application/json
      url: https://raw.githubusercontent.com/aws/aws-sdk-js/master/apis/apigateway-2015-07-09.normal.json
      converter:
        url: https://github.com/mermade/aws2openapi
        version: 1.0.0
      x-apisguru-driver: external
  x-apiClientRegistration:
    url: https://portal.aws.amazon.com/gp/aws/developer/registration/index.html?nc2=h_ct
  x-apisguru-categories:
    - cloud
  x-preferred: true
externalDocs:
  description: Amazon Web Services documentation
  url: https://docs.aws.amazon.com/apigateway/
servers:
  - url: http://apigateway.{region}.amazonaws.com
    variables:
      region:
        description: The AWS region
        enum:
          - us-east-1
          - us-east-2
          - us-west-1
          - us-west-2
          - us-gov-west-1
          - us-gov-east-1
          - ca-central-1
          - eu-north-1
          - eu-west-1
          - eu-west-2
          - eu-west-3
          - eu-central-1
          - eu-south-1
          - af-south-1
          - ap-northeast-1
          - ap-northeast-2
          - ap-northeast-3
          - ap-southeast-1
          - ap-southeast-2
          - ap-east-1
          - ap-south-1
          - sa-east-1
          - me-south-1
        default: us-east-1
    description: The Amazon API Gateway multi-region endpoint
  - url: https://apigateway.{region}.amazonaws.com
    variables:
      region:
        description: The AWS region
        enum:
          - us-east-1
          - us-east-2
          - us-west-1
          - us-west-2
          - us-gov-west-1
          - us-gov-east-1
          - ca-central-1
          - eu-north-1
          - eu-west-1
          - eu-west-2
          - eu-west-3
          - eu-central-1
          - eu-south-1
          - af-south-1
          - ap-northeast-1
          - ap-northeast-2
          - ap-northeast-3
          - ap-southeast-1
          - ap-southeast-2
          - ap-east-1
          - ap-south-1
          - sa-east-1
          - me-south-1
        default: us-east-1
    description: The Amazon API Gateway multi-region endpoint
  - url: http://apigateway.{region}.amazonaws.com.cn
    variables:
      region:
        description: The AWS region
        enum:
          - cn-north-1
          - cn-northwest-1
        default: cn-north-1
    description: The Amazon API Gateway endpoint for China (Beijing) and China (Ningxia)
  - url: https://apigateway.{region}.amazonaws.com.cn
    variables:
      region:
        description: The AWS region
        enum:
          - cn-north-1
          - cn-northwest-1
        default: cn-north-1
    description: The Amazon API Gateway endpoint for China (Beijing) and China (Ningxia)
x-hasEquivalentPaths: true
paths:
  /apikeys:
    post:
      operationId: CreateApiKey
      description: "Create an ApiKey resource. "
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKey"
        "480":
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestException"
        "481":
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictException"
        "482":
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededException"
        "483":
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundException"
        "484":
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedException"
        "485":
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsException"
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: The name of the ApiKey.
                  type: string
                description:
                  description: The description of the ApiKey.
                  type: string
                enabled:
                  description: Specifies whether the ApiKey can be used by callers.
                  type: boolean
                generateDistinctId:
                  description: Specifies whether (<code>true</code>) or not (<code>false</code>) the key identifier is distinct from the created API key value. This parameter is deprecated and should not be used.
                  type: boolean
                value:
                  description: Specifies a value of the API key.
                  type: string
                stageKeys:
                  description: DEPRECATED FOR USAGE PLANS - Specifies stages associated with the API key.
                  type: array
                  items:
                    $ref: "#/components/schemas/StageKey"
                customerId:
                  description: An AWS Marketplace customer identifier , when integrating with the AWS SaaS Marketplace.
                  type: string
                tags:
                  description: 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.
                  type: object
                  additionalProperties:
                    $ref: "#/components/schemas/String"
      tags:
        - Apikeys
    parameters:
      - $ref: "#/components/parameters/X-Amz-Content-Sha256"
      - $ref: "#/components/parameters/X-Amz-Date"
      - $ref: "#/components/parameters/X-Amz-Algorithm"
      - $ref: "#/components/parameters/X-Amz-Credential"
      - $ref: "#/components/parameters/X-Amz-Security-Token"
      - $ref: "#/components/parameters/X-Amz-Signature"
      - $ref: "#/components/parameters/X-Amz-SignedHeaders"
    get:
      operationId: GetApiKeys
      description: Gets information about the current ApiKeys resource.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeys"
        "480":
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestException"
        "481":
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundException"
        "482":
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedException"
        "483":
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsException"
      parameters:
        - name: position
          in: query
          required: false
          description: The current pagination position in the paged result set.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: The maximum number of returned results per page. The default value is 25 and the maximum value is 500.
          schema:
            type: integer
        - name: name
          in: query
          required: false
          description: The name of queried API keys.
          schema:
            type: string
        - name: customerId
          in: query
          required: false
          description: The identifier of a customer in AWS Marketplace or an external system, such as a developer portal.
          schema:
            type: string
        - name: includeValues
          in: query
          required: false
          description: A boolean flag to specify whether (<code>true</code>) or not (<code>false</code>) the result contains key values.
          schema:
            type: boolean
      tags:
        - Apikeys
  "/restapis/{restapi_id}/authorizers":
    post:
      operationId: CreateAuthorizer
      description: Adds a new Authorizer resource to an existing RestApi resource.
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Authorizer"
        "480":
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestException"
        "481":
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictException"
        "482":
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededException"
        "483":
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundException"
        "484":
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedException"
        "485":
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsException"
      parameters:
        - name: restapi_id
          in: path
          required: true
          description: The string identifier of the associated RestApi.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - type
              properties:
                name:
                  description: The name of the authorizer.
                  type: string
                type:
                  description: The authorizer type. Valid values are <code>TOKEN</code> for a Lambda function using a single authorization token submitted in a custom header, <code>REQUEST</code> for a Lambda function using incoming request parameters, and <code>COGNITO_USER_POOLS</code> for using an Amazon Cognito user pool.
                  type: string
                  enum:
                    - TOKEN
                    - REQUEST
                    - COGNITO_USER_POOLS
                providerARNs:
                  description: "A list of the Amazon Cognito user pool ARNs for the <code>COGNITO_USER_POOLS</code> authorizer. Each element is of this format: <code>arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}</code>. For a <code>TOKEN</code> or <code>REQUEST</code> authorizer, this is not defined. "
                  type: array
                  items:
                    $ref: "#/components/schemas/ProviderARN"
                authType:
                  description: Optional customer-defined field, used in OpenAPI imports and exports without functional impact.
                  type: string
                authorizerUri:
                  description: Specifies the authorizer's Uniform Resource Identifier (URI). For <code>TOKEN</code> or <code>REQUEST</code> authorizers, this must be a well-formed Lambda function URI, for example, <code>arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:{account_id}:function:{lambda_function_name}/invocations</code>. In general, the URI has this form <code>arn:aws:apigateway:{region}:lambda:path/{service_api}</code>, where <code>{region}</code> is the same as the region hosting the Lambda function, <code>path</code> indicates that the remaining substring in the URI should be treated as the path to the resource, including the initial <code>/</code>. For Lambda functions, this is usually of the form <code>/2015-03-31/functions/[FunctionARN]/invocations</code>.
                  type: string
                authorizerCredentials:
                  description: Specifies the required credentials as an IAM role for API Gateway to invoke the authorizer. To specify an IAM role for API Gateway to assume, use the role's Amazon Resource Name (ARN). To use resource-based permissions on the Lambda function, specify null.
                  type: string
                identitySource:
                  description: The identity source for which authorization is requested. For a <code>TOKEN</code> or <code>COGNITO_USER_POOLS</code> authorizer, this is required and specifies the request header mapping expression for the custom header holding the authorization token submitted by the client. For example, if the token header name is <code>Auth</code>, the header mapping expression is <code>method.request.header.Auth</code>. For the <code>REQUEST</code> authorizer, this is required when authorization caching is enabled. The value is a comma-separated string of one or more mapping expressions of the specified request parameters. For example, if an <code>Auth</code> header, a <code>Name</code> query string parameter are defined as identity sources, this value is <code>method.request.header.Auth, method.request.querystring.Name</code>. These parameters will be used to derive the authorization caching key and to perform runtime validation of the <code>REQUEST</code> authorizer by verifying all of the identity-related request parameters are present, not null and non-empty. Only when this is true does the authorizer invoke the authorizer Lambda function, otherwise, it returns a 401 Unauthorized response without calling the Lambda function. The valid value is a string of comma-separated mapping expressions of the specified request parameters. When the authorization caching is not enabled, this property is optional.
                  type: string
                identityValidationExpression:
                  description: A validation expression for the incoming identity token. For <code>TOKEN</code> authorizers, this value is a regular expression. For <code>COGNITO_USER_POOLS</code> authorizers, API Gateway will match the <code>aud</code> field of the incoming token from the client against the specified regular expression. It will invoke the authorizer's Lambda function when there is a match. Otherwise, it will return a 401 Unauthorized response without calling the Lambda function. The validation expression does not apply to the <code>REQUEST</code> authorizer.
                  type: string
                authorizerResultTtlInSeconds:
                  description: The TTL in seconds of cached authorizer results. If it equals 0, authorization caching is disabled. If it is greater than 0, API Gateway will cache authorizer responses. If this field is not set, the default value is 300. The maximum value is 3600, or 1 hour.
                  type: integer
      tags:
        - Restapis
    parameters:
      - $ref: "#/components/parameters/X-Amz-Content-Sha256"
      - $ref: "#/components/parameters/X-Amz-Date"
      - $ref: "#/components/parameters/X-Amz-Algorithm"
      - $ref: "#/components/parameters/X-Amz-Credential"
      - $ref: "#/components/parameters/X-Amz-Security-Token"
      - $ref: "#/components/parameters/X-Amz-Signature"
      - $ref: "#/components/parameters/X-Amz-SignedHeaders"
    get:
      operationId: GetAuthorizers
      description: Describe an existing Authorizers resource.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Authorizers"
        "480":
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestException"
        "481":
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundException"
        "482":
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedException"
        "483":
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsException"
      parameters:
        - name: restapi_id
          in: path
          required: true
          description: The string identifier of the associated RestApi.
          schema:
            type: string
        - name: position
          in: query
          required: false
          description: The current pagination position in the paged result set.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: The maximum number of returned results per page. The default value is 25 and the maximum value is 500.
          schema:
            type: integer
      tags:
        - Restapis
  "/domainnames/{domain_name}/basepathmappings":
    post:
      operationId: CreateBasePathMapping
      description: Creates a new BasePathMapping resource.
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasePathMapping"
        "480":
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestException"
        "481":
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictException"
        "482":
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededException"
        "483":
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundException"
        "484":
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedException"
        "485":
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsException"
      parameters:
        - name: domain_name
          in: path
          required: true
          description: The domain name of the BasePathMapping resource to create.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - restApiId
              properties:
                basePath:
                  description: The base path name that callers of the API must provide as part of the URL after the domain name. This value must be unique for all of the mappings across a single API. Specify '(none)' if you do not want callers to specify a base path name after the domain name.
                  type: string
                restApiId:
                  description: The string identifier of the associated RestApi.
                  type: string
                stage:
                  description: The name of the API's stage that you want to use for this mapping. Specify '(none)' if you want callers to explicitly specify the stage name after any base path name.
                  type: string
      tags:
        - Domainnames
    parameters:
      - $ref: "#/components/parameters/X-Amz-Content-Sha256"
      - $ref: "#/components/parameters/X-Amz-Date"
      - $ref: "#/components/parameters/X-Amz-Algorithm"
      - $ref: "#/components/parameters/X-Amz-Credential"
      - $ref: "#/components/parameters/X-Amz-Security-Token"
      - $ref: "#/components/parameters/X-Amz-Signature"
      - $ref: "#/components/parameters/X-Amz-SignedHeaders"
    get:
      operationId: GetBasePathMappings
      description: Represents a collection of BasePathMapping resources.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasePathMappings"
        "480":
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestException"
        "481":
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundException"
        "482":
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedException"
        "483":
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsException"
      parameters:
        - name: domain_name
          in: path
          required: true
          description: The domain name of a BasePathMapping resource.
          schema:
            type: string
        - name: position
          in: query
          required: false
          description: The current pagination position in the paged result set.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: The maximum number of returned results per page. The default value is 25 and the maximum value is 500.
          schema:
            type: integer
      tags:
        - Domainnames
  "/restapis/{restapi_id}/deployments":
    post:
      operationId: CreateDeployment
      description: Creates a Deployment resource, which makes a specified RestApi callable over the internet.
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deployment"
        "480":
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestException"
        "481":
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictException"
        "482":
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededException"
        "483":
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundException"
        "484":
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedException"
        "485":
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsException"
        "486":
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceUnavailableException"
      parameters:
        - name: restapi_id
          in: path
          required: true
          description: The string identifier of the associated RestApi.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                stageName:
                  description: The name of the Stage resource for the Deployment resource to create.
                  type: string
                stageDescription:
                  description: The description of the Stage resource for the Deployment resource to create.
                  type: string
                description:
                  description: The description for the Deployment resource to create.
                  type: string
                cacheClusterEnabled:
                  description: Enables a cache cluster for the Stage resource specified in the input.
                  type: boolean
                cacheClusterSize:
                  description: Returns the size of the CacheCluster.
                  type: string
                  enum:
                    - "0.5"
                    - "1.6"
                    - "6.1"
                    - "13.5"
                    - "28.4"
                    - "58.2"
                    - "118"
                    - "237"
                variables:
                  description: 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 <code>[A-Za-z0-9-._~:/?#&amp;=,]+</code>.
                  type: object
                  additionalProperties:
                    $ref: "#/components/schemas/String"
                canarySettings:
                  description: The input configuration for a canary deployment.
                  type: object
                  properties:
                    percentTraffic:
                      allOf:
                        - $ref: "#/components/schemas/Double"
                        - description: The percentage (0.0-100.0) of traffic routed to the canary deployment.
                    stageVariableOverrides:
                      allOf:
                        - $ref: "#/components/schemas/MapOfStringToString"
                        - description: 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:
                      allOf:
                        - $ref: "#/components/schemas/Boolean"
                        - description: A Boolean flag to indicate whether the canary release deployment uses the stage cache or not.
                tracingEnabled:
                  description: Specifies whether active tracing with X-ray is enabled for the Stage.
                  type: boolean
      tags:
        - Restapis
    parameters:
      - $ref: "#/components/parameters/X-Amz-Content-Sha256"
      - $ref: "#/components/parameters/X-Amz-Date"
      - $ref: "#/components/parameters/X-Amz-Algorithm"
      - $ref: "#/components/parameters/X-Amz-Credential"
      - $ref: "#/components/parameters/X-Amz-Security-Token"
      - $ref: "#/components/parameters/X-Amz-Signature"
      - $ref: "#/components/parameters/X-Amz-SignedHeaders"
    get:
      operationId: GetDeployments
      description: Gets information about a Deployments collection.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deployments"
        "480":
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestException"
        "481":
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundException"
        "482":
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedException"
        "483":
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsException"
        "484":
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceUnavailableException"
      parameters:
        - name: restapi_id
          in: path
          required: true
          description: The string identifier of the associated RestApi.
          schema:
            type: string
        - name: position
          in: query
          required: false
          description: The current pagination position in the paged result set.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: The maximum number of returned results per page. The default value is 25 and the maximum value is 500.
          schema:
            type: integer
      tags:
        - Restapis
  "/restapis/{restapi_id}/documentation/parts":
    post:
      operationId: CreateDocumentationPart
      description: Creates a documentation part.
      responses:
        "201":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentationPart"
        "480":
          description: BadRequestException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestException"
        "481":
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictException"
        "482":
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LimitExceededException"
        "483":
          description: NotFoundException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundException"
        "484":
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedException"
        "485":
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TooManyRequestsException"
      parameters:
        - name: restapi_id
          in: path
          required: true
          description: The string identifier of the associated RestApi.
          schema:
            type: string
      requestBody:
      

# --- truncated at 32 KB (475 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/engineering-platform/refs/heads/main/openapi/_original/aws-api-gateway-openapi-original.yml