Skip to content


Mangum provides support for both REST and the newer HTTP APIs in API Gateway. It also includes configurable binary response support.

from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from mangum import Mangum

app = FastAPI()
app.add_middleware(GZipMiddleware, minimum_size=1000)

async def main():
    return "somebigcontent"

handler = Mangum(app, TEXT_MIME_TYPES=["application/vnd.some.type"])

Configuring binary responses

Binary responses are determined using the Content-Type and Content-Encoding headers from the event request and a list of text MIME types.

Text MIME types

By default, all response data will be base64 encoded and include isBase64Encoded=True in the response except the default text MIME types and any MIME types included in the TEXT_MIME_TYPES list setting.

The following types are excluded from binary responses by default:

  • application/json
  • application/javascript
  • application/xml
  • application/vnd.api+json

Additionally, any Content-Type header prefixed with text/ is automatically excluded.


If the Content-Encoding header is set to gzip or br, then a binary response will be returned regardless of MIME type.

State machine

The HTTPCycle is used by the adapter to communicate message events between the application and AWS. It is a state machine that handles the entire ASGI request and response cycle.


class mangum.protocols.http.HTTPCycle(scope, text_mime_types, state=, response=)

Manages the application cycle for an ASGI http connection.

  • scope - A dictionary containing the connection scope used to run the ASGI application instance.
  • text_mime_types - A list of mime types of MIME types that should not return a binary response in API Gateway.
  • state - An enumerated HTTPCycleState type that indicates the state of the ASGI connection.
  • app_queue - An asyncio queue (FIFO) containing messages to be received by the application.
  • response - A dictionary containing the response data to return in AWS Lambda.
run(self, app)

Calls the application with the http connection scope.


Awaited by the application to receive ASGI http events.

send(self, message)

Awaited by the application to send ASGI http events.


class mangum.protocols.http.HTTPCycleState(value, names=None, *, module=None, qualname=None, type=None, start=1)

The state of the ASGI http connection.

  • REQUEST - Initial state. The ASGI application instance will be run with the connection scope containing the http type.
  • RESPONSE - The http.response.start event has been sent by the application. The next expected message is the http.response.body event, containing the body content. An application may pass the more_body argument to send content in chunks, however content will always be returned in a single response, never streamed.
  • COMPLETE - The body content from the ASGI application has been completely read. A disconnect event will be sent to the application, and the response will be returned.