API reference

Start here: the date, the user, today's habits and urgent todos

The only call needed to start a conversation. Short markdown: today's date and weekday, the user's name, any actions they switched off, habits still to do and done (with streaks), notable streaks, overdue and due-today todos. Call it once, then act directly — the write tools take names, so don't list habits or todos first.

Tool:

get_today

Permission:

read

Mark a habit done (or undo it), by name

Marks a habit done for today, or for `date`. Pass the habit as the user said it ("walk", "meditación"); it's matched for you, no lookup needed. completed: false undoes. Read back the `say` field. On 409 ask which of `options`; on 404 offer create_habit.

Tool:

log_habit

Permission:

log_completions

Create any habit, e.g. running

Creates a habit that isn't in the catalog. Only name is required: it defaults to every day with no reminder, so don't ask follow-up questions — create it, read back `say`, and let the user change it. days takes names (["mon","thu"], "weekdays", "weekends"); time HH:MM sets a reminder.

Tool:

create_habit

Permission:

add_habits

Rename or change a habit, by name

Renames a habit or changes its description, days or time. Pass the habit as the user said it plus only the fields to change: name for a rename, days (["mon","thu"], "weekdays", "every day"), timesPerWeek, time (HH:MM, or "" for no reminder), description. Read back `say`.

Tool:

update_habit

Permission:

edit_habits

Delete a habit and its history (off unless enabled)

Permanently deletes a habit and all its completions. Only when the user explicitly asks to delete it, and confirm the name with them first. Off by default: if it returns scope_disabled, relay the message (suggest archiving in the app). Read back `say`.

Tool:

delete_habit

Permission:

delete_habits

Create a todo

Adds a todo. Only title is required; dueDate for 'by Friday'. Read back `say`.

Tool:

add_todo

Permission:

todos

Finish, start or reopen a todo, by name

Pass the todo as the user said it ("the bank call"); it's matched for you. status defaults to completed. Read back `say`; on 409 ask which of `options`.

Tool:

set_todo_status

Permission:

todos

All open todos

Only when the user asks for their todo list beyond what get_today shows.

Tool:

list_todos

Permission:

read

Week and month numbers

Completion rate today and over 7 days, best current streak, 30-day series. For 'how was my week'.

Tool:

get_stats

Permission:

read

Every habit with streaks and 7/30-day rates

Only for questions about specific habits' history or rates. Not needed before log_habit.

Tool:

list_habits

Permission:

read

Find protocols and habits to recommend

Searches the Liberture catalog. Give the user `infoUrl` (its page on this site) for anything you suggest. `adopted` = they already track it. For something the user simply wants to track, use create_habit instead.

Tool:

search_catalog

Permission:

read

Add a catalog protocol or habit

Adds a protocol's habits (protocolSlug) or one catalog habit (habitSlug) from search_catalog, when the user asks. Read back `say`. If refused with scope_disabled, give them the infoUrl instead.

Tool:

adopt_habit

Permission:

add_habits

The in-app coach's latest suggestions

What the in-app coach last suggested, with reasons and infoUrl links. Empty if it hasn't run.

Tool:

get_recommendations

Permission:

read