Agentic Ollama chat endpoint for cooking guidance, meal plan updates, and pantry-aware assistance

AI Chat

POST /api/chat

Send a message to the AI cooking assistant.

Method	Path	Auth	Tier
POST	`/api/chat`	JWT Bearer	Free (10/day) / Pro (unlimited)

Free tier users are limited to 10 messages per day. Pro and Family tier users have unlimited access.

Request body

{
  "message": "What can I make with chicken breast and pasta?",
  "session_id": 42,
  "recipe_id": 128
}

message: Required natural-language prompt.
session_id: Optional. Omit it to create a new chat session.
recipe_id: Optional. Pins a recipe so the assistant can switch into step-by-step cooking guidance for that recipe.

The request body does not include a context object. The system prompt automatically includes the user's dietary restrictions, allergies, household size, and current pantry inventory.

Response `200 OK`

{
  "session_id": 42,
  "message_id": 314,
  "reply": "You could make a quick chicken pasta with garlic, spinach, and olive oil...",
  "tokens_used": 893,
  "actions_taken": ["search_recipes"]
}

reply: Assistant text returned to the client.
tokens_used: Token count when provided by the underlying model.
actions_taken: Tool names the assistant actually called while producing the reply.

Agentic Capabilities

Cookest AI uses Ollama's native tools API and can call tools over multiple rounds in a single response cycle (up to the configured max tool rounds).

Tool	Description
`search_recipes(query?, cuisine?, meal_type?, max_time_min?, limit?)`	Search the recipe catalog by keywords and structured filters.
`get_meal_plan()`	Fetch the current weekly meal plan before suggesting changes.
`update_meal_plan_slot(day_of_week, meal_type, recipe_id)`	Replace one meal-plan slot with a specific recipe.
`mark_meal_completed(day_of_week, meal_type)`	Mark a meal as cooked or completed.
`get_pantry()`	Read the current pantry and inventory state.
`add_to_pantry(name, quantity, unit, storage_location?, expiry_date?)`	Add a pantry item on the user's behalf.
`remove_from_pantry(item_id)`	Remove an inventory item by ID.
`clear_meal_plan()`	Wipe the full weekly meal plan when the user explicitly asks for a reset.
`get_recipe_details(recipe_id)`	Load full recipe details, including ingredients and steps.

GET /api/chat/sessions

List the user's chat sessions.

Method	Path	Auth	Tier
GET	`/api/chat/sessions`	JWT Bearer	Free

Response `200 OK`

[
  {
    "id": 42,
    "title": "Chicken pasta ideas",
    "created_at": "2024-01-20T15:28:00Z",
    "updated_at": "2024-01-20T15:30:00Z"
  }
]

Each item is a SessionListItem:

Field	Type	Notes
`id`	integer	Session ID
`title`	string \| null	Optional auto-generated title
`created_at`	string	ISO-8601 timestamp
`updated_at`	string	ISO-8601 timestamp

GET /api/chat/sessions/:id/messages

Get all non-system messages in a chat session.

Method	Path	Auth	Tier
GET	`/api/chat/sessions/:id/messages`	JWT Bearer	Free

Response `200 OK`

[
  {
    "id": 313,
    "role": "user",
    "content": "What can I make with chicken breast and pasta?",
    "created_at": "2024-01-20T15:28:00Z"
  },
  {
    "id": 314,
    "role": "assistant",
    "content": "You could make a quick chicken pasta with garlic, spinach, and olive oil...",
    "created_at": "2024-01-20T15:28:05Z"
  }
]

Each item is a MessageItem:

Field	Type	Notes
`id`	integer	Message ID
`role`	string	Usually `user` or `assistant`
`content`	string	Message body
`created_at`	string	ISO-8601 timestamp

DELETE /api/chat/sessions/:id

Delete a chat session and all of its messages.

Method	Path	Auth	Tier
DELETE	`/api/chat/sessions/:id`	JWT Bearer	Free

Response `204 No Content`

Model configuration

The chat model is configured via the OLLAMA_MODEL environment variable. Cookest typically uses llama3.1:8b for chat, but any Ollama-compatible text model can be substituted.

When recipe_id is set, the same /api/chat endpoint can move from general assistant chat into recipe-specific cooking help without changing routes.

AI Chat

On this page