Cookie

API reference for the FastAPI Cookie parameter function

Cookie

Declare a cookie parameter for a path operation. Cookie parameters are extracted from HTTP request cookies.

from typing import Annotated
from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/items/")
async def read_items(
    session_id: Annotated[str | None, Cookie()] = None
):
    return {"session_id": session_id}

Signature

def Cookie(
    default: Any = Undefined,
    *,
    alias: str | None = None,
    title: str | None = None,
    description: str | None = None,
    gt: float | None = None,
    ge: float | None = None,
    lt: float | None = None,
    le: float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    pattern: str | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | str | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
) -> Any

Parameters

default · Any · default: "Undefined"

Default value if the parameter field is not set.

alias · str | None · default: "None"

An alternative name for the parameter field. This will be used to extract the data and for the generated OpenAPI.

title · str | None · default: "None"

Human-readable title for the parameter.

description · str | None · default: "None"

Human-readable description for the parameter.

gt · float | None · default: "None"

Greater than validation. If set, the value must be greater than this. Only applicable to numbers.

ge · float | None · default: "None"

Greater than or equal validation. If set, the value must be greater than or equal to this. Only applicable to numbers.

lt · float | None · default: "None"

Less than validation. If set, the value must be less than this. Only applicable to numbers.

le · float | None · default: "None"

Less than or equal validation. If set, the value must be less than or equal to this. Only applicable to numbers.

min_length · int | None · default: "None"

Minimum length for strings.

max_length · int | None · default: "None"

Maximum length for strings.

pattern · str | None · default: "None"

RegEx pattern for strings.

discriminator · str | None · default: "None"

Parameter field name for discriminating the type in a tagged union.

strict · bool | None · default: "None"

If True, strict validation is applied to the field.

multiple_of · float | None · default: "None"

Value must be a multiple of this. Only applicable to numbers.

allow_inf_nan · bool | None · default: "None"

Allow inf, -inf, nan. Only applicable to numbers.

max_digits · int | None · default: "None"

Maximum number of allowed digits for numbers.

decimal_places · int | None · default: "None"

Maximum number of decimal places allowed for numbers.

examples · list[Any] | None · default: "None"

Example values for this field.

deprecated · bool | str | None · default: "None"

Mark this parameter field as deprecated. It will affect the generated OpenAPI (visible at /docs).

include_in_schema · bool · default: "True"

Whether to include this parameter field in the generated OpenAPI.

json_schema_extra · dict[str, Any] | None · default: "None"

Any additional JSON schema data.

Examples

Basic Cookie Parameter

from typing import Annotated
from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/items/")
async def read_items(
    session_id: Annotated[str | None, Cookie()] = None
):
    return {"session_id": session_id}

Required Cookie

@app.get("/items/")
async def read_items(
    session_id: Annotated[str, Cookie()]
):
    return {"session_id": session_id}

A cookie parameter is required when there is no default value.

Cookie with Validation

@app.get("/items/")
async def read_items(
    session_id: Annotated[str, Cookie(min_length=32, max_length=64)]
):
    return {"session_id": session_id}

Multiple Cookies

@app.get("/items/")
async def read_items(
    session_id: Annotated[str | None, Cookie()] = None,
    tracking_id: Annotated[str | None, Cookie()] = None
):
    return {
        "session_id": session_id,
        "tracking_id": tracking_id
    }

Cookie with Metadata

@app.get("/items/")
async def read_items(
    session_id: Annotated[
        str | None,
        Cookie(
            title="Session ID",
            description="The session identifier cookie"
        )
    ] = None
):
    return {"session_id": session_id}

Common Use Cases

Session Management

@app.get("/user/profile")
async def get_profile(
    session_token: Annotated[str, Cookie()]
):
    # Validate session and return user profile
    return {"session": session_token}

Authentication Cookies

@app.get("/dashboard")
async def dashboard(
    access_token: Annotated[str | None, Cookie()] = None,
    refresh_token: Annotated[str | None, Cookie()] = None
):
    return {
        "access_token": access_token,
        "refresh_token": refresh_token
    }

Tracking and Analytics

@app.get("/")
async def root(
    analytics_id: Annotated[str | None, Cookie()] = None,
    user_preferences: Annotated[str | None, Cookie()] = None
):
    return {
        "analytics_id": analytics_id,
        "preferences": user_preferences
    }

CSRF Token

@app.post("/submit")
async def submit_form(
    csrf_token: Annotated[str, Cookie()]
):
    # Validate CSRF token
    return {"csrf_token": csrf_token}

Cookie parameters are read-only. To set cookies in the response, use the Response object or return a custom Response.

Setting Cookies in Response

from fastapi import Response

@app.post("/login")
async def login(response: Response):
    response.set_cookie(key="session_id", value="abc123")
    return {"message": "Logged in"}

The Cookie() parameter function is only for reading cookies from requests. Use response.set_cookie() to set cookies in responses.