Manual Water Intake Tracking

Plan & Token Requirements

Feature available in the following LogMeal Plans:

Accessible by the following User Types:

⚫ APICompany tokens cannot call the manual-water creation or deletion endpoints, but they can retrieve a user's water totals through the applicable history endpoints.

What It Does

Manual Water Intake Tracking provides a dedicated water-tracker workflow without requiring an image or a dish-selection step.

• POST /intake/manualWater/{userId} creates an image-less manual intake whose only dish is the configured water class.
• DELETE /intake/manualWater/{userId} removes a requested quantity from the user's newest water-only entries for a selected day and cutoff time.
• GET /history/getIntakesList returns each entry's is_water flag and a total_water summary that separates direct water entries from fluids found in other intakes.

A created water entry behaves like any other manual intake: it has an imageId, timestamp, occasion, recipe, nutritional information, and serving size, but it has no uploaded photo.

When to Use It / Outcomes

• Add quick water buttons such as one glass, one bottle, or a custom milliliter amount.
• Let an 🔴 APIUser record water for themselves without taking a photo.
• Let a 🔵 APIUserManager record or correct water for a managed user.
• Implement an undo or correction action that subtracts a quantity from the newest water entries.
• Display a hydration summary that distinguishes directly logged water from fluids contained in meals and drinks.
• Output on creation: a compact intake reference containing imageId, userId, and occasion.
• Output on deletion: the quantity actually removed, fully deactivated intake IDs, and the ID of any intake that was partially reduced.

Feature-Specific Details

Creating Water Entries

The POST request body is optional.

The water dish and its recipe are selected internally. Clients do not need to send a dish ID or ingredient list.

Example request body:

{
  "quantity": 500,
  "timestamp": "2026/07/22, 10:30:00",
  "intake_name": "Morning bottle"
}

Example response:

{
  "message": "Water intake created successfully.",
  "intake": {
    "imageId": 623657,
    "userId": 546,
    "occasion": "snack"
  }
}

The response does not contain the complete intake or refreshed hydration totals. Retrieve them through GET /intake/{imageId} or GET /history/getIntakesList.

Because the entry has no uploaded photo, image_url can be null. When an icon is configured for the water class or one of its ancestors, the history response can use that icon as a fallback.

Removing Water by Quantity

The DELETE request body is optional. quantity again defaults to 250 milliliters.

The optional timestamp has a different role than it does on POST: it selects the local day and acts as the inclusive cutoff time. The endpoint considers water entries from 00:00:00 on that day through the supplied time. Without a timestamp, it uses the current local day through the user's current localized time.

Deletion proceeds from the newest eligible entry backwards:

1. Entries fully covered by the requested quantity are deactivated and returned in deleted_intake_ids.
2. When the remaining quantity is smaller than the next entry, that entry's serving size is reduced and its ID is returned in edited_intake_id.
3. At most one entry is partially edited, but a response can contain both fully deleted IDs and one edited ID.
4. When less water is available than requested, all available water is removed and the endpoint still returns HTTP 200 with the actual deleted_quantity and a message describing the missing remainder.
5. When no eligible water is found, the endpoint returns HTTP 200 with removed: false and deleted_quantity: 0.

Example partial removal:

{
  "quantity": 250,
  "timestamp": "2026/07/22, 12:00:00"
}

{
  "removed": true,
  "deleted_quantity": 250.0,
  "unit": "ml",
  "message": "Water intake deleted successfully.",
  "deleted_intake_ids": null,
  "edited_intake_id": 623657
}

⚠️

DELETE /intake/manualWater/ is a quantity-removal operation, not a request to delete one fixed resource. Repeating the same request removes additional water from the then-current history. Do not retry it blindly. To remove one known entry, call DELETE /intake/{imageId}.

History and Hydration Totals

GET /history/getIntakesList returns the following fields for water-tracker integrations:

When food waste has been reported, fluid totals use the post-consumption recipe so the hydration total reflects the amount actually consumed.

A mixed intake containing water plus another dish is not a water-only entry. Its fluid ingredients contribute to from_intakes_water, and the manual-water DELETE endpoint does not target it. The same applies to drinks represented by a class other than the configured water class.

Related Endpoints

Use the following endpoints to create, correct, and retrieve water data:

• POST /intake/manualWater/{userId} → 🔴 🔵 Create a water-only manual intake.
• DELETE /intake/manualWater/{userId} → 🔴 🔵 Remove a quantity from the newest water-only entries.
• GET /history/getIntakesList → ⚫ 🔴 🔵 Retrieve intake entries, is_water, and total_water.
• GET /intake/{imageId} → ⚫ 🔴 🔵 Retrieve the complete details of one created water entry.
• DELETE /intake/{imageId} → ⚫ 🔴 🔵 Remove one specific intake by ID instead of subtracting a quantity.
• POST /intake/manualInput/{userId} → 🔴 🔵 Create a general manual intake, including an equivalent water-only entry when the configured water dish ID is used.

Typical Workflow

1. Choose the target user: an APIUser uses their own ID; an APIUserManager uses the ID of an accessible managed user.
2. Log water: call POST /intake/manualWater/\{userId\} with a quantity, or rely on the 250 ml default.
3. Refresh the tracker: call GET /history/getIntakesList for the relevant period and read total_water, is_water, and the created entry's image_id.
4. Correct by quantity: call DELETE /intake/manualWater/\{userId\} and use deleted_quantity, deleted_intake_ids, and edited_intake_id to reconcile the UI.
5. Correct one exact record when needed: use DELETE /intake/\{imageId\} instead of the quantity-removal endpoint.