jsonify

The jsonify helper in Esmerald makes it simple to return JSON responses from your endpoints, similar to Flask’s jsonify.

It automatically encodes Python objects into JSON, sets the correct Content-Type, and allows you to customize status codes, headers, and cookies.

---

When to Use jsonify

Use jsonify when you want to:

• Return JSON from your endpoints without manually creating a Response.
• Pass dicts, lists, or keyword arguments directly.
• Control status codes, headers, or cookies in a JSON response.
• Make migration from Flask smoother.

---

Basic Example

from esmerald import Esmerald, Gateway, get
from esmerald.contrib.responses.json import jsonify

@get()
async def hello():
    return jsonify(message="Hello, World!", status="ok")

app = Esmerald(routes=[
    Gateway("/hello", hello)
])

Request:

curl http://localhost:8000/hello

Response:

{"message": "Hello, World!", "status": "ok"}

---

Returning Lists

If you pass a list or multiple arguments, they will be returned as JSON arrays:

@get()
async def numbers():
    return jsonify([1, 2, 3])

@get()
async def multi():
    return jsonify(1, 2, 3)

• /numbers → [1, 2, 3]
• /multi → [1, 2, 3]

---

Custom Status Codes

You can return custom HTTP status codes:

@get()
async def created_user():
    return jsonify(id=1, name="Alice", status="created", status_code=200)

Response:

• Status → 200 Success
• Body → {"id": 1, "name": "Alice", "status": "created"}

---

Adding Headers

Custom headers can be added easily:

@get()
async def with_headers():
    return jsonify(
        message="Hello",
        headers={"X-App-Version": "1.0"}
    )

Response will include:

X-App-Version: 1.0

---

Adding Cookies

You can also set cookies directly:

@get()
async def with_cookie():
    return jsonify(
        message="Hello",
        cookies={"session": "abc123"}
    )

Response will include:

Set-Cookie: session=abc123; Path=/

---

Error Handling

It’s not allowed to mix both positional arguments and keyword arguments:

# ❌ This raises TypeError
return jsonify({"a": 1}, b=2)

---

API Reference

jsonify(
    *args: Any,
    status_code: int = 200,
    headers: Optional[Dict[str, str]] = None,
    cookies: Optional[Dict[str, str]] = None,
    **kwargs: Any,
) -> Response

Parameters

• *args – A single dict, list, or multiple values (converted to a list).
• status_code – Custom HTTP status code (default: 200).
• headers – Optional dictionary of response headers.
• cookies – Optional dictionary of cookies to set.
• **kwargs – Treated as a dict payload if no *args provided.

with jsonify, Esmerald makes returning JSON fast, safe, and friendly, while adding async-native power.