Amazon API Gateway · AsyncAPI Specification

Amazon API Gateway WebSocket API Protocol

Version 1.0.0

AsyncAPI description of the *platform protocol* exposed by Amazon API Gateway WebSocket APIs. Customer-deployed WebSocket APIs are message-routed based on a route selection expression evaluated against each incoming JSON message; this document specifies only the platform-defined surface (the WebSocket connection lifecycle and the route extraction model) plus the IAM-signed back-channel used by backend services to push messages to connected clients. Customer-specific application routes (the values matched by `routeSelectionExpression`) are intentionally NOT enumerated here, because they are defined per deployed API by the customer. Only the platform-reserved routes `$connect`, `$disconnect`, and `$default` are first-class.

View Spec View on GitHub API GatewayAmazon Web ServicesCloudRESTHTTPWebSocketServerlessMCPAgent CoreDeveloper PortalDeveloper ToolsReal-TimeAsyncAPIEventsWebSockets

Channels

connection
The WebSocket connection itself. A client opens a single bidirectional WebSocket against this path; API Gateway then routes the lifecycle and each inbound JSON message through the routing model described below. Route selection is configured at the API level by `routeSelectionExpression` (e.g. `${request.body.action}`). API Gateway evaluates the expression against each inbound message and dispatches to the matching route key. Three route keys are reserved by the platform: - `$connect` - invoked once when the WebSocket connection is established. - `$disconnect` - invoked once when either side closes the connection. - `$default` - invoked for non-JSON messages or when no custom route key matches. Customer-defined route keys (matched against the value extracted by `routeSelectionExpression`) sit alongside these three platform routes and are not enumerated here.
lifecycle-connect
Platform-reserved route invoked exactly once when API Gateway accepts a new WebSocket connection. The integration receives no message body; instead it receives the connection's `requestContext`, query string, headers, and any identity claims. A non-2xx response from this route's integration causes API Gateway to reject the connection (used for AuthN/Z gating).
lifecycle-disconnect
Platform-reserved route invoked on connection teardown (client close, server-side `DELETE @connections/{id}`, idle timeout at 10 minutes, or the 2-hour max connection lifetime). Best-effort delivery - integrations MUST treat it as an at-most-once notification.
lifecycle-default
Platform-reserved fallback route. Invoked when the inbound payload is not valid JSON, when `routeSelectionExpression` cannot be evaluated against the payload, or when no customer-defined route key matches the extracted value.

Messages

✉
RouteSelectedMessage
Client message matching a customer-defined route key
Inbound JSON message where the value extracted by `routeSelectionExpression` matches a customer-configured route key.
✉
DefaultMessage
Client message routed to $default
Inbound message that did not match any custom route key, or that could not be parsed as JSON for route selection.
✉
ServerMessage
Server-originated frame pushed to client
Outbound frame produced either by an integration response on the matched route or by a backend `PostToConnection` call against the ApiGatewayManagementApi.
✉
ConnectEvent
$connect lifecycle event
✉
DisconnectEvent
$disconnect lifecycle event

Servers

wss
production
Default WebSocket connection endpoint for a deployed API Gateway WebSocket API. Clients connect to `wss://{api-id}.execute-api.{region}.amazonaws.com/{stage}`. The `stage` segment is included in the connection path (see channel address).
wss
custom-domain
Optional custom domain name mapped to a WebSocket API stage via API Gateway custom domain names + ACM certificates. When a custom domain is in use the `stage` path segment is omitted from the connection URL.

AsyncAPI Specification

Raw ↑
asyncapi: 3.0.0
info:
  title: Amazon API Gateway WebSocket API Protocol
  version: 1.0.0
  description: 'AsyncAPI description of the *platform protocol* exposed by Amazon API Gateway

    WebSocket APIs. Customer-deployed WebSocket APIs are message-routed based on a

    route selection expression evaluated against each incoming JSON message; this

    document specifies only the platform-defined surface (the WebSocket connection

    lifecycle and the route extraction model) plus the IAM-signed back-channel

    used by backend services to push messages to connected clients.


    Customer-specific application routes (the values matched by

    `routeSelectionExpression`) are intentionally NOT enumerated here, because

    they are defined per deployed API by the customer. Only the platform-reserved

    routes `$connect`, `$disconnect`, and `$default` are first-class.

    '
  contact:
    name: AWS API Gateway
    url: https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html
  license:
    name: AWS Service Terms
    url: https://aws.amazon.com/service-terms/
  tags:
  - name: AWS
  - name: API Gateway
  - name: WebSocket
  - name: Real-Time
  externalDocs:
    description: AWS - API Gateway WebSocket APIs developer guide
    url: https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html
defaultContentType: application/json
servers:
  production:
    protocol: wss
    description: 'Default WebSocket connection endpoint for a deployed API Gateway WebSocket

      API. Clients connect to `wss://{api-id}.execute-api.{region}.amazonaws.com/{stage}`.

      The `stage` segment is included in the connection path (see channel address).

      '
    variables:
      api-id:
        description: The 10-character API identifier returned when the WebSocket API is created.
        default: aabbccddee
      region:
        description: AWS Region in which the API is deployed.
        default: us-east-1
        enum:
        - us-east-1
        - us-east-2
        - us-west-1
        - us-west-2
        - eu-west-1
        - eu-central-1
        - ap-northeast-1
        - ap-southeast-1
        - ap-southeast-2
    host: '{api-id}.execute-api.{region}.amazonaws.com'
  custom-domain:
    protocol: wss
    description: 'Optional custom domain name mapped to a WebSocket API stage via API Gateway

      custom domain names + ACM certificates. When a custom domain is in use the

      `stage` path segment is omitted from the connection URL.

      '
    variables:
      domain-name:
        description: Customer-mapped custom domain (e.g. ws.example.com).
        default: ws.example.com
    host: '{domain-name}'
channels:
  connection:
    address: /{stage}
    description: "The WebSocket connection itself. A client opens a single bidirectional\nWebSocket against this\
      \ path; API Gateway then routes the lifecycle and each\ninbound JSON message through the routing model described\
      \ below.\n\nRoute selection is configured at the API level by `routeSelectionExpression`\n(e.g. `${request.body.action}`).\
      \ API Gateway evaluates the expression\nagainst each inbound message and dispatches to the matching route\
      \ key.\nThree route keys are reserved by the platform:\n\n  - `$connect`  - invoked once when the WebSocket\
      \ connection is established.\n  - `$disconnect` - invoked once when either side closes the connection.\n \
      \ - `$default`  - invoked for non-JSON messages or when no custom route key matches.\n\nCustomer-defined route\
      \ keys (matched against the value extracted by\n`routeSelectionExpression`) sit alongside these three platform\
      \ routes and\nare not enumerated here.\n"
    parameters:
      stage:
        description: 'Deployment stage name (e.g. `prod`, `dev`). Omit when connecting via a

          custom domain name mapping.

          '
        default: prod
    bindings:
      ws:
        bindingVersion: 0.1.0
        method: GET
    messages:
      RouteSelectedMessage:
        $ref: '#/components/messages/RouteSelectedMessage'
      DefaultMessage:
        $ref: '#/components/messages/DefaultMessage'
      ServerMessage:
        $ref: '#/components/messages/ServerMessage'
  lifecycle-connect:
    address: $connect
    description: 'Platform-reserved route invoked exactly once when API Gateway accepts a new

      WebSocket connection. The integration receives no message body; instead it

      receives the connection''s `requestContext`, query string, headers, and any

      identity claims. A non-2xx response from this route''s integration causes

      API Gateway to reject the connection (used for AuthN/Z gating).

      '
    messages:
      ConnectEvent:
        $ref: '#/components/messages/ConnectEvent'
  lifecycle-disconnect:
    address: $disconnect
    description: 'Platform-reserved route invoked on connection teardown (client close,

      server-side `DELETE @connections/{id}`, idle timeout at 10 minutes, or

      the 2-hour max connection lifetime). Best-effort delivery - integrations

      MUST treat it as an at-most-once notification.

      '
    messages:
      DisconnectEvent:
        $ref: '#/components/messages/DisconnectEvent'
  lifecycle-default:
    address: $default
    description: 'Platform-reserved fallback route. Invoked when the inbound payload is not

      valid JSON, when `routeSelectionExpression` cannot be evaluated against the

      payload, or when no customer-defined route key matches the extracted value.

      '
    messages:
      DefaultMessage:
        $ref: '#/components/messages/DefaultMessage'
components:
  messages:
    RouteSelectedMessage:
      name: RouteSelectedMessage
      title: Client message matching a customer-defined route key
      summary: 'Inbound JSON message where the value extracted by `routeSelectionExpression`

        matches a customer-configured route key.

        '
      contentType: application/json
      payload:
        $ref: '#/components/schemas/JsonObject'
    DefaultMessage:
      name: DefaultMessage
      title: Client message routed to $default
      summary: 'Inbound message that did not match any custom route key, or that could

        not be parsed as JSON for route selection.

        '
      payload:
        type: string
        description: Raw frame payload as received from the client.
    ServerMessage:
      name: ServerMessage
      title: Server-originated frame pushed to client
      summary: 'Outbound frame produced either by an integration response on the

        matched route or by a backend `PostToConnection` call against the

        ApiGatewayManagementApi.

        '
      payload:
        oneOf:
        - type: string
        - $ref: '#/components/schemas/JsonObject'
    ConnectEvent:
      name: ConnectEvent
      title: $connect lifecycle event
      contentType: application/json
      payload:
        type: object
        properties:
          requestContext:
            $ref: '#/components/schemas/RequestContext'
          headers:
            type: object
            additionalProperties:
              type: string
          queryStringParameters:
            type: object
            additionalProperties:
              type: string
    DisconnectEvent:
      name: DisconnectEvent
      title: $disconnect lifecycle event
      contentType: application/json
      payload:
        type: object
        properties:
          requestContext:
            $ref: '#/components/schemas/RequestContext'
  schemas:
    JsonObject:
      type: object
      description: 'Arbitrary JSON object. API Gateway evaluates the API-level

        `routeSelectionExpression` (e.g. `${request.body.action}`) against this

        payload to extract a route key.

        '
      additionalProperties: true
    RequestContext:
      type: object
      description: 'Platform-injected event context delivered to every WebSocket route

        integration. Contains the `connectionId` required for back-channel

        pushes via the ApiGatewayManagementApi.

        '
      properties:
        connectionId:
          type: string
          description: Unique identifier for the open WebSocket connection.
        domainName:
          type: string
          description: 'Fully-qualified domain name of the deployed API. Combined with

            `stage`, forms the `@connections` callback URL base.

            '
        stage:
          type: string
          description: Deployment stage name. Omitted when invoked via a custom domain mapping.
        routeKey:
          type: string
          description: 'The route key invoked - one of `$connect`, `$disconnect`,

            `$default`, or a customer-defined value extracted from the message

            by `routeSelectionExpression`.

            '
        eventType:
          type: string
          enum:
          - CONNECT
          - MESSAGE
          - DISCONNECT
        messageId:
          type: string
        requestTime:
          type: string
        identity:
          type: object
          additionalProperties: true
operations:
  clientSendMessage:
    summary: Client sends a message frame to the WebSocket API.
    description: 'Inbound frame from the client. API Gateway parses the payload as JSON,

      evaluates `routeSelectionExpression` against it to extract a route key,

      and routes the message to either a customer-defined route, the

      `$default` route (no match / non-JSON), or back to `$disconnect` on

      close. The full event delivered to the integration includes a

      `requestContext` containing `connectionId`, `domainName`, `stage`,

      `routeKey`, `eventType`, `messageId`, and `requestTime`.

      '
    action: receive
    channel:
      $ref: '#/channels/connection'
    messages:
    - $ref: '#/channels/connection/messages/RouteSelectedMessage'
    - $ref: '#/channels/connection/messages/DefaultMessage'
  serverPushMessage:
    summary: Server pushes a message frame to the connected client.
    description: 'Outbound frame delivered to the client. Two platform mechanisms produce

      these frames: (1) an integration response returned from the route''s

      backend (e.g. Lambda) via a configured route response, and (2) an

      out-of-band push from a backend service that calls

      `@connections/{connectionId}` on the ApiGatewayManagementApi (see

      `components.operations` below).

      '
    action: send
    channel:
      $ref: '#/channels/connection'
    messages:
    - $ref: '#/channels/connection/messages/ServerMessage'
  onConnect:
    summary: API Gateway delivers a `$connect` lifecycle event to the integration.
    action: send
    channel:
      $ref: '#/channels/lifecycle-connect'
    messages:
    - $ref: '#/channels/lifecycle-connect/messages/ConnectEvent'
  onDisconnect:
    summary: API Gateway delivers a `$disconnect` lifecycle event to the integration.
    action: send
    channel:
      $ref: '#/channels/lifecycle-disconnect'
    messages:
    - $ref: '#/channels/lifecycle-disconnect/messages/DisconnectEvent'
  onDefault:
    summary: API Gateway delivers an unrouted inbound message to the `$default` integration.
    action: send
    channel:
      $ref: '#/channels/lifecycle-default'
    messages:
    - $ref: '#/channels/lifecycle-default/messages/DefaultMessage'
x-management-api-operations:
  PostToConnection:
    description: "IAM-signed (SigV4) HTTPS back-channel used by a backend service to push\na message frame to a\
      \ connected WebSocket client.\n\n    POST https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/@connections/{connectionId}\n\
      \nReturns `410 GoneException` if the connection no longer exists.\n"
  GetConnection:
    description: "IAM-signed HTTPS request returning the latest status of a WebSocket\nconnection (connectedAt,\
      \ identity, lastActiveAt, source IP).\n\n    GET https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/@connections/{connectionId}\n"
  DeleteConnection:
    description: "IAM-signed HTTPS request that forcibly closes a WebSocket connection\nfrom the server side.\n\n\
      \    DELETE https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/@connections/{connectionId}\n"

Work with this as data

Every AsyncAPI spec here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for asyncapi

4 MCP tools reach this
  • find_asyncapisBrowse and filter every AsyncAPI spec in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This AsyncAPI spec
curl "https://apis.io/api/v1/asyncapis/aws-api-gateway-asyncapi"
All asyncapi
curl "https://apis.io/api/v1/asyncapis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.