Choose what your caller receives.

Send back a message and a status that describes the result.

Return a message

Return a string from your endpoint to send a text response with HTTP 200:

@app.get(path="/", methods=["GET"])
async def index():
    return "Hello from Karak"

The caller receives Hello from Karak. Text can include Unicode characters.

Choose a status code

Use Response when you want to specify the status yourself. This is a complete example you can save as main.py:

from karak import Karak
from karak import Response

app = Karak()


@app.get(path="/users/{user_id}", methods=["GET"])
async def user(user_id: int):
    if user_id != 42:
        return Response(status_code=404, content="User not found")
    return "User 42"

Start it with uv run uvicorn main:app --reload, then inspect the status and body together:

curl -i http://127.0.0.1:8000/users/7

The response has status 404 and the body User not found. Request /users/42 instead to receive HTTP 200 with User 42.

Return bytes or an empty body

You can return bytes directly. Return b"" when you want an empty response body, or use Response(status_code=204, content=b"") for a response with no content and an explicit 204 status.

Can I return JSON?

Automatic JSON responses, custom headers, and streaming are not available in the main framework yet. Use text or bytes for the current examples. JSON request and response support is part of the plan.

The free-threaded experiment already has its own JSON response support, but it uses a separate application API.

Understand error responses

For the routing-related cases, see current limitations.