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 SpecView on GitHubAPI 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: 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"
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.