Response Data

Minimal API handlers can use mach::Context& to inspect and modify the outgoing response.

The context exposes the response through context.response.

Response Metadata

The response exposes its current HTTP version, status code, and body:

const auto version = context.response.version();
const auto status = context.response.status();
const auto& body = context.response.body();

These accessors let a handler inspect the response state that will be sent to the client.

Set the Status Code

Use status() to set the response status:

app.mapGet("/example", [](mach::Context& context) {
    context.response.status(mach::http::StatusCode::Ok);
    return mach::ok();
});

In most endpoints, returning an appropriate result such as mach::ok() or mach::notFound() is clearer than setting the status manually.

Direct status manipulation is useful when the handler needs finer control over the response.

Set the Response Body

The response body can be set directly:

app.mapGet("/raw", [](mach::Context& context) {
    context.response.body("Hello, World!");
    return mach::ok();
});

For normal endpoint results, returning a typed reply is usually preferable because it keeps the response body and result type together.

Headers

Use setHeader() to add or replace a response header:

app.mapGet("/example", [](mach::Context& context) {
    context.response.setHeader("X-Example", "Mach");
    return mach::ok();
});

Headers can also be inspected:

const auto value = context.response.header("X-Example");

if (value) {
    // Use *value
}

header() returns std::optional<std::string_view> because the requested header may not be present.

To check for a header directly:

if (context.response.containsHeader("X-Example")) {
    // ...
}

Cookies

Cookies can be added to the response using addCookie():

app.mapGet("/login", [](mach::Context& context) {
    context.response.addCookie("session", "abc123");
    return mach::ok();
});

You can also add a configured mach::http::Cookie:

mach::http::Cookie cookie{"session", "abc123"};

context.response.addCookie(cookie);

Existing response cookies can be inspected:

const auto session = context.response.cookie("session");

if (session) {
    // Use *session
}

cookie() returns std::optional<mach::http::Cookie>.

To check for a cookie without retrieving it:

if (context.response.containsCookie("session")) {
    // ...
}

Direct Response Manipulation vs Results

Minimal API handlers can modify context.response directly, but most endpoints should still return a result that represents the outcome of the request.

For example:

app.mapGet("/users/{id:int}", [](mach::Context& context) {
    context.response.setHeader("X-Source", "users");
    return mach::ok(42);
});

Here, the response API is used for additional response metadata, while the returned result defines the main status and body.

Tip

Use returned results for the primary outcome of an endpoint, and use context.response for additional response details such as headers and cookies.

The Response API

context.response provides access to:

• HTTP version
• status code
• response body
• headers
• cookies

For the complete interface, see the Response API reference.

---

Next, you’ll learn how minimal API handlers return results.