Responses

Every handler that StarkForge provides answers in the same JSON shape. A client reads success to see the outcome, shows message to a person and takes the result from data, without learning a new format for each route. This page describes that shape, how lists are paginated, which fields never appear in a response and which headers come with it. Failures have a shape of their own, described in Errors.

The Response Envelope

A request for one product shows every part of the shape:

GET /api/v1/products/665f1c2e8b3a4d0012a10001

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message": "Product fetched successfully.",
  "data": {
    "name": "Mechanical keyboard",
    "price": 89.9,
    "sku": "KB-001",
    "_id": "665f1c2e8b3a4d0012a10001",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-15T10:30:00.000Z"
  }
}

A response has no data key when the handler has nothing to return. Signing out is the example, and it also clears both session cookies:

POST /api/v1/auth/logout

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message": "Logged out successfully."
}

Status and Message by Handler

A handler always answers with the same status and message pattern. Product in the messages is the model name of the collection, and the numbers are counts:

The account and sign-in handlers follow the same shape with messages of their own.

Lists and Pagination

readAll returns one page at a time. This request asks for the first page of two products, most expensive first:

GET /api/v1/products?page=1&limit=2&sort=-price

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message": "Product list fetched successfully.",
  "data": [
    {
      "name": "Mechanical keyboard",
      "price": 89.9,
      "sku": "KB-001",
      "_id": "665f1c2e8b3a4d0012a10001",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    },
    {
      "name": "Desk lamp",
      "price": 34,
      "sku": "LP-003",
      "_id": "665f1c2e8b3a4d0012a10003",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 2,
    "total": 3,
    "pages": 2
  }
}

Three query parameters control the page. All of them are optional:

The two limits are the options defaultPageSize and maxPageSize, described in Configuration. You can sort by _id, createdAt, updatedAt and every field of the schema, except fields that a client could not read: secret, hashed, encrypted and hidden fields. Read All covers sorting in full.

The meta object describes the whole list, not only the page:

A broken query answers 400 with the code INVALID_QUERY:

What a Response Never Contains

StarkForge cleans every document before it writes the response. These fields are removed, whatever the client asks for:

A route can hide more. Add config: { hiddenFields: ["internalNotes"] } to remove a field from the responses of that route only, and put "_id" in the list to drop the id too. A reference field normally holds an id. With config: { populate: "owner" } the response holds the referenced document instead, limited to the fields in populateSelect, which defaults to _id so that personal data does not leak by accident. Relations and Hidden and Encrypted Fields cover both in depth.

An after action can also replace data before the response is sent. Actions explains how.

Headers

Every response carries headers that help with debugging and with clients that retry. This is the start of the response to a list request under the default limits:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-Id: ad7a9c50-3964-49ef-a597-cda43ad4317f
RateLimit: limit=100, remaining=99, reset=900
RateLimit-Policy: 100;w=900

StarkForge also sets the standard secure headers of helmet, such as X-Content-Type-Options and Strict-Transport-Security.

Field Formats

An _id is a string of 24 hexadecimal characters. Dates such as createdAt and updatedAt are ISO 8601 text in UTC, like 2026-01-15T10:30:00.000Z. Numbers, booleans and arrays keep their JSON types.

Where to Go Next

:::