> For the complete documentation index, see [llms.txt](https://docs.january.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.january.ai/rest-api/usage-guide.md).

# Usage Guide

The canonical flows, endpoint by endpoint. Every operation named here has a full request and response reference, with Try it out, in the reference pages below (Food Scans through Restaurants).

### Log a food, correctly sized

Find the food with [`GET /v1.2/foods?query=...`](https://docs.january.ai/rest-api/foods#get-v1.2-foods) or, while the user types, [`GET /v1.2/foods/autocomplete?query=...`](https://docs.january.ai/rest-api/foods#get-v1.2-foods-autocomplete) Then fetch [`GET /v1.2/foods/{food_id}`](https://docs.january.ai/rest-api/foods#get-v1.2-foods-food_id) for the complete serving list, let the user pick "1 cup" versus "100 g", and create the entry with [`POST /v1.2/food-logs`](https://docs.january.ai/rest-api/food-logs#post-v1.2-food-logs), sending the food `id`, the chosen serving `id`, and a `quantity`. Read the diary back with [`GET /v1.2/food-logs?start=...&end=...`](https://docs.january.ai/rest-api/food-logs#get-v1.2-food-logs) — both dates inclusive.

### Scan a meal photo

[`POST /v1.2/food-scans/photo`](https://docs.january.ai/rest-api/food-scans#post-v1.2-food-scans-photo) with an image URL or base64 data URI returns detections with nutrition and totals. Text works the same way through [`POST /v1.2/food-scans/text`](https://docs.january.ai/rest-api/food-scans#post-v1.2-food-scans-text). If something is wrong, send the detections back through [`POST /v1.2/food-scans/corrections`](https://docs.january.ai/rest-api/food-scans#post-v1.2-food-scans-corrections) with a plain-English `user_input` like "the portion was about half of that" — portions adjust through language, not by editing numbers.

### Look up a barcode

[`GET /v1.2/foods/barcode/{upc}`](https://docs.january.ai/rest-api/foods#get-v1.2-foods-barcode-upc) resolves a scanned barcode to a food. If it is not in the database yet, you get a clean `404` that says so.

### Predict glucose

[`POST /v1.2/glucose/predictions`](https://docs.january.ai/rest-api/glucose#post-v1.2-glucose-predictions) takes a user profile (`age`, `sex`, `height`, `weight` as `value`-and-`unit` pairs) plus the meal as food and serving selections, and returns a predicted curve, an impact score, and chart bounds. Partners with CGM history can include it, paired with the meals eaten during it, for personalization.

### Healthier alternatives

[`POST /v1.2/foods/{food_id}/alternatives`](https://docs.january.ai/rest-api/foods#post-v1.2-foods-food_id-alternatives) suggests better choices for a food, honoring lowercase diet vocabularies like `gluten`, `tree_nuts`, `vegan`, `low_carbohydrate`. Omit an array (or send it empty) when it does not apply.