API docs by Redocly

Intake API (2.0.0)

Download OpenAPI specification:

REST API for the Intake self-hosted nutrition and activity tracker.

Authentication: JWT stored in an HttpOnly session cookie (intake_session). All routes except /auth/register, /auth/login, and /auth/logout require a valid session. Set the AUTH_SECRET environment variable to a stable secret so sessions survive service restarts.

CORS: Credentials allowed from all origins.

Timeout: 10 seconds per request.

Base URL: http://localhost:8080 (direct) or via the web proxy at http://localhost:3001/api.

Auth

Register, login, logout, session info

Health check

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "time": "2019-08-24T14:15:22Z"
}

Register a new account

Request Body schema: application/json
required
email
required
string <email>
password
required
string non-empty
display_name
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "string",
  • "display_name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "display_name": "string",
  • "is_first_user": true
}

Log in

Request Body schema: application/json
required
email
required
string <email>
password
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "display_name": "string",
  • "is_first_user": true
}

Log out — clears session cookie

Responses

Response samples

Content type
application/json
{
  • "ok": true
}

Return the current authenticated user

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "display_name": "string",
  • "is_first_user": true
}

Migrate all data from the built-in local user to the current account

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
{
  • "migrated_rows": 0
}

Dashboard

Daily macro and activity summary

Macro and activity totals for a single day

Authorizations:
cookieAuth
query Parameters
date
string <date>

Day to summarise (default today)

Responses

Response samples

Content type
application/json
{
  • "date": "2019-08-24",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "calories_in": 0,
  • "protein_g": 0,
  • "carbs_g": 0,
  • "fat_g": 0,
  • "fiber_g": 0,
  • "steps": 0,
  • "active_calories_est": 0
}

Daily macro totals including entry count

Authorizations:
cookieAuth
query Parameters
date
string <date>

Responses

Response samples

Content type
application/json
{
  • "date": "2019-08-24",
  • "entry_count": 0,
  • "calories_in": 0,
  • "protein_g": 0,
  • "carbs_g": 0,
  • "fat_g": 0,
  • "fiber_g": 0
}

Food Items

Create and manage food items with macro profiles

List all food items (sorted by name)

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a food item (also creates a linked recipe record)

Authorizations:
cookieAuth
Request Body schema: application/json
required
name
required
string
brand
string
serving_label
string
Default: "1 serving"
calories_per_serving
number
protein_g_per_serving
number
carbs_g_per_serving
number
fat_g_per_serving
number
fiber_g_per_serving
number
recipe_instructions
string
recipe_yield_count
integer
Default: 1
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "brand": "string",
  • "serving_label": "1 serving",
  • "calories_per_serving": 0,
  • "protein_g_per_serving": 0,
  • "carbs_g_per_serving": 0,
  • "fat_g_per_serving": 0,
  • "fiber_g_per_serving": 0,
  • "recipe_instructions": "string",
  • "recipe_yield_count": 1,
  • "recipe_ingredients": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "recipe_id": "fa7d15d4-7670-4586-a94b-5079ed028135"
}

Get a single food item

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "Chicken Breast",
  • "brand": "Generic",
  • "serving_label": "100g",
  • "calories_per_serving": 165,
  • "protein_g_per_serving": 31,
  • "carbs_g_per_serving": 0,
  • "fat_g_per_serving": 3.6,
  • "fiber_g_per_serving": 0
}

Update a food item and its recipe

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
name
required
string
brand
string
serving_label
string
calories_per_serving
number
protein_g_per_serving
number
carbs_g_per_serving
number
fat_g_per_serving
number
fiber_g_per_serving
number
recipe_instructions
string
recipe_yield_count
integer

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "brand": "string",
  • "serving_label": "string",
  • "calories_per_serving": 0,
  • "protein_g_per_serving": 0,
  • "carbs_g_per_serving": 0,
  • "fat_g_per_serving": 0,
  • "fiber_g_per_serving": 0,
  • "recipe_instructions": "string",
  • "recipe_yield_count": 0
}

Delete a food item

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Log

Food log — record, query, and delete entries

All log entries for a day ordered by time

Authorizations:
cookieAuth
query Parameters
date
string <date>

Day to query (default today)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Per-day calorie totals for a date range (used by calendar)

Authorizations:
cookieAuth
query Parameters
from
required
string <date>
to
required
string <date>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Log a food item

Authorizations:
cookieAuth
Request Body schema: application/json
required
food_item_id
required
string <uuid>
servings
required
number >= 0.01
meal
string
Default: "breakfast"
Enum: "breakfast" "lunch" "dinner" "snack_1" "snack_2" "snack_3"
occurred_at
string <date-time>

Defaults to now

note
string

Responses

Request samples

Content type
application/json
{
  • "food_item_id": "2c3a1b3b-36cc-416d-bb39-8acf0e0f9d7a",
  • "servings": 0.01,
  • "meal": "breakfast",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "note": "string"
}

Delete a log entry

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Body Metrics

Body weight and daily activity (steps, calories, water)

Log a body weight measurement

Authorizations:
cookieAuth
Request Body schema: application/json
required
weight_kg
required
number
measured_at
string <date-time>
note
string

Responses

Request samples

Content type
application/json
{
  • "weight_kg": 0,
  • "measured_at": "2019-08-24T14:15:22Z",
  • "note": "string"
}

Log or update steps and active calories for a day

Authorizations:
cookieAuth
Request Body schema: application/json
required
date
string <date>
steps
integer
active_calories_est
number

Responses

Request samples

Content type
application/json
{
  • "date": "2019-08-24",
  • "steps": 0,
  • "active_calories_est": 0
}

Get water intake for a day

Authorizations:
cookieAuth
query Parameters
date
string <date>

Responses

Response samples

Content type
application/json
{
  • "glasses": 0
}

Set water intake for a day

Authorizations:
cookieAuth
Request Body schema: application/json
required
date
string <date>
glasses
integer >= 0

Responses

Request samples

Content type
application/json
{
  • "date": "2019-08-24",
  • "glasses": 0
}

Recipes

Recipes and their ingredients

List all recipes (sorted by name)

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a recipe and its linked food item

Authorizations:
cookieAuth
Request Body schema: application/json
required
name
required
string
brand
string
serving_label
string
calories_per_serving
number
protein_g_per_serving
number
carbs_g_per_serving
number
fat_g_per_serving
number
fiber_g_per_serving
number
instructions
string
yield_count
integer
Default: 1
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "brand": "string",
  • "serving_label": "string",
  • "calories_per_serving": 0,
  • "protein_g_per_serving": 0,
  • "carbs_g_per_serving": 0,
  • "fat_g_per_serving": 0,
  • "fiber_g_per_serving": 0,
  • "instructions": "string",
  • "yield_count": 1,
  • "shopping_items": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Merge and total ingredients across multiple recipes

Authorizations:
cookieAuth
Request Body schema: application/json
required
recipe_ids
required
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "recipe_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "ingredients": [
    ]
}

Get a recipe with full ingredient list

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "name": "string",
  • "instructions": "string",
  • "yield_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "ingredients": [
    ]
}

Update recipe name, instructions, or yield count

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
name
required
string
instructions
string
yield_count
integer

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "instructions": "string",
  • "yield_count": 0
}

Add an ingredient to a recipe

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
food_item_id
required
string <uuid>
amount_g
required
number

Responses

Request samples

Content type
application/json
{
  • "food_item_id": "2c3a1b3b-36cc-416d-bb39-8acf0e0f9d7a",
  • "amount_g": 0
}

Replace all ingredients for a recipe atomically

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "ingredients": [
    ]
}

Update a single ingredient's amount

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
ingredient_id
required
string <uuid>
Request Body schema: application/json
required
amount_g
required
number

Responses

Request samples

Content type
application/json
{
  • "amount_g": 0
}

Remove an ingredient from a recipe

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
ingredient_id
required
string <uuid>

Responses

List shopping items for a recipe

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Replace all shopping items for a recipe

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Recipe Photos

Upload and manage recipe photos

Download the recipe photo

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Upload a recipe photo

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
Request Body schema: multipart/form-data
required
photo
string <binary>

Responses

Delete the recipe photo

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Pantry

Track on-hand food quantities and expiration dates

List all pantry items

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set pantry quantity for a food item (upsert)

Authorizations:
cookieAuth
path Parameters
food_item_id
required
string <uuid>
Request Body schema: application/json
required
quantity
required
number
expires_at
string or null <date>

Responses

Request samples

Content type
application/json
{
  • "quantity": 0,
  • "expires_at": "2019-08-24"
}

Remove an item from the pantry

Authorizations:
cookieAuth
path Parameters
food_item_id
required
string <uuid>

Responses

Deduct servings from a pantry item (floors at 0)

Authorizations:
cookieAuth
Request Body schema: application/json
required
food_item_id
required
string <uuid>
servings
required
number

Responses

Request samples

Content type
application/json
{
  • "food_item_id": "2c3a1b3b-36cc-416d-bb39-8acf0e0f9d7a",
  • "servings": 0
}

Ingredient Categories

Map ingredient names to shopping list categories

List all ingredient-to-category mappings

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Replace all category mappings

Authorizations:
cookieAuth
Request Body schema: application/json
required
Array
ingredient_name
string
category_slug
string

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Batch set categories from a name→slug map

Authorizations:
cookieAuth
Request Body schema: application/json
required
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Set the category for a single ingredient name

Authorizations:
cookieAuth
path Parameters
name
required
string
Request Body schema: application/json
required
category_slug
string

Responses

Request samples

Content type
application/json
{
  • "category_slug": "string"
}

Remove a category mapping

Authorizations:
cookieAuth
path Parameters
name
required
string

Responses

Shopping

Merged ingredient shopping list

Full merged shopping list grouped by recipe

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Presets

Named groups of food items for quick logging

Create a meal preset

Authorizations:
cookieAuth
Request Body schema: application/json
required
name
required
string
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "items": [
    ]
}

Log all items in a preset

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
meal
string
date
string <date>

Responses

Request samples

Content type
application/json
{
  • "meal": "string",
  • "date": "2019-08-24"
}

Nudges

Discord webhook reminders for unlogged foods

List all nudges with today's log status

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a nudge (one per food item, upserts)

Authorizations:
cookieAuth
Request Body schema: application/json
required
food_item_id
required
string <uuid>
remind_at
required
string
webhook_url
required
string <uri>

Responses

Request samples

Content type
application/json
{
  • "food_item_id": "2c3a1b3b-36cc-416d-bb39-8acf0e0f9d7a",
  • "remind_at": "09:00",
  • "webhook_url": "http://example.com"
}

Update nudge time, webhook, or enabled state

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
remind_at
string
webhook_url
string <uri>
enabled
boolean

Responses

Request samples

Content type
application/json
{}

Delete a nudge

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Fire the nudge webhook immediately (for testing)

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Meal Plan

Planned meals with ICS calendar export

List all meal plan entries

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a meal plan entry

Authorizations:
cookieAuth
Request Body schema: application/json
required
date
required
string <date>
meal
required
string
food_item_id
required
string <uuid>
servings
required
number

Responses

Request samples

Content type
application/json
{
  • "date": "2019-08-24",
  • "meal": "string",
  • "food_item_id": "2c3a1b3b-36cc-416d-bb39-8acf0e0f9d7a",
  • "servings": 0
}

Remove a meal plan entry

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Export the meal plan as an iCalendar file

Authorizations:
cookieAuth
query Parameters
weeks
integer
Default: 2

Responses

Workouts

Workout programs, exercises, sessions, and set logging

List all workout programs with exercises

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a workout program

Authorizations:
cookieAuth
Request Body schema: application/json
required
name
required
string
days
Array of integers

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "days": [
    ]
}

Update program name and/or scheduled days

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
name
string
days
Array of integers

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "days": [
    ]
}

Delete a program and all its data

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>

Responses

Add an exercise to a program

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
name
required
string
sets
integer
Default: 3
reps_min
integer
reps_max
integer
sort_order
integer

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "sets": 3,
  • "reps_min": 0,
  • "reps_max": 0,
  • "sort_order": 0
}

Remove an exercise

Authorizations:
cookieAuth
path Parameters
id
required
string <uuid>
exercise_id
required
string <uuid>

Responses

Get scheduled workouts and logged sets for a day

Authorizations:
cookieAuth
query Parameters
date
string <date>

Defaults to today

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Start a workout session (upserts on program + date)

Authorizations:
cookieAuth
Request Body schema: application/json
required
program_id
required
string <uuid>
date
required
string <date>

Responses

Request samples

Content type
application/json
{
  • "program_id": "70c1146b-e933-4cb2-a789-bbca5312b517",
  • "date": "2019-08-24"
}

Log or update a single workout set (upserts)

Authorizations:
cookieAuth
Request Body schema: application/json
required
session_id
required
string <uuid>
exercise_id
required
string <uuid>
set_number
required
integer >= 1
weight_kg
number or null
reps_actual
integer or null
completed
boolean

Responses

Request samples

Content type
application/json
{
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  • "exercise_id": "506f9fcd-d1ac-40ff-8eae-940f7fd80178",
  • "set_number": 1,
  • "weight_kg": 0,
  • "reps_actual": 0,
  • "completed": true
}

Settings

Per-user key/value configuration

Return all settings for the current user

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
{
  • "ai_provider": "claude",
  • "ai_review_time": "20:00",
  • "meal_plan_weeks": "2"
}

Set a single key/value pair (upserts)

Authorizations:
cookieAuth
Request Body schema: application/json
required
key
required
string
value
required
string

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "value": "string"
}

AI Review

Automated food log review via Claude or OpenAI

Trigger an AI review immediately

Authorizations:
cookieAuth
Request Body schema: application/json
custom_prompt
string

Replaces the default macro-summary task

date
string <date>

Responses

Request samples

Content type
application/json
{
  • "custom_prompt": "string",
  • "date": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "text": "string",
  • "provider": "string",
  • "date": "2019-08-24",
  • "run_at": "2019-08-24T14:15:22Z"
}

Return the most recent AI review

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
{
  • "text": "string",
  • "provider": "string",
  • "date": "2019-08-24",
  • "run_at": "2019-08-24T14:15:22Z"
}

Data

Full data export and import

Export all user data as JSON

Authorizations:
cookieAuth

Responses

Response samples

Content type
application/json
{ }

Export food log as Markdown

Authorizations:
cookieAuth

Responses

Import a previously exported JSON blob

Authorizations:
cookieAuth
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "imported_rows": 0
}