GET/api/v1/summary
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. format=json returns the same as data.
- Tool:
get_today- Permission:
read
POST/api/v1/completions/toggle
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 it, which removes that day's record including any note or values logged with it. Optional note ("felt great") and value (a number for habits that track one). Read back the `say` field. On 409 ask which of `options`; on 404 offer create_habit.
- Tool:
log_habit- Permission:
log_completions
POST/api/v1/completions/log
Log an amount or a note for a habit ("20 pushups")
For amounts and notes: "log 20 pushups", "slept 7 hours, woke up rested". Amounts add up over the day and the habit counts as done once its goal is reached. value goes to the habit's tracked number (unit picks which one when it tracks several); values sets several by name. For a plain "I did it" use log_habit. Read back `say`.
- Tool:
log_habit_value- Permission:
log_completions
GET/api/v1/habits/detail
Everything about one habit, by name
One habit in detail: schedule, time, plan (intention), what number it tracks, streaks, the last two weeks with notes, and its catalog page (infoUrl) and official image (imageUrl) if it came from one. For "how is my running going".
- Tool:
get_habit- Permission:
read
GET/api/v1/habits/history
One habit's logged days, values and notes
The days a habit was logged, newest first, with amounts and notes. Paged: pass nextCursor back as cursor for older days. For "how many pushups did I do this month".
- Tool:
get_habit_history- Permission:
read
POST/api/v1/habits
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. For "100 pushups a day" set dataEntry { unit: "pushups", goalValue: 100 }.
- Tool:
create_habit- Permission:
add_habits
POST/api/v1/habits/update
Rename or change a habit, by name
Changes a habit. 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, pillar, priority, tags, dataEntry (a number to track and its goal), intention, identity, randomReminders. Read back `say`.
- Tool:
update_habit- Permission:
edit_habits
POST/api/v1/habits/archive
Archive a habit (keeps its history), by name
Hides a habit and pauses it without losing its history. What to do when the user wants to stop or drop a habit; prefer it to delete_habit. Read back `say`.
- Tool:
archive_habit- Permission:
edit_habits
POST/api/v1/habits/unarchive
Bring an archived habit back, by name
Restores an archived habit to the user's list. Read back `say`.
- Tool:
unarchive_habit- Permission:
edit_habits
POST/api/v1/habits/delete
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; to stop a habit, archive_habit is usually what they want. Off by default: if it returns scope_disabled, offer archive_habit. Read back `say`.
- Tool:
delete_habit- Permission:
delete_habits
GET/api/v1/habits
Every habit with streaks and 7/30-day rates
Only for questions about all habits' rates or streaks. Not needed before log_habit; for one habit use get_habit.
- Tool:
list_habits- Permission:
read
POST/api/v1/todos
Create a todo
Adds a todo. Only title is required; dueDate for 'by Friday'. project is a name; a new name creates the project. subtasks can be plain strings. Read back `say`.
- Tool:
add_todo- Permission:
todos
POST/api/v1/todos/update
Change a todo, by name
Changes a todo: new title, due date or time ("move it to Friday"), priority, project (a name; "" removes it), tags, subtasks, notes, description, estimatedMinutes, energyLevel. Send only what changes. To finish it use set_todo_status. Read back `say`; on 409 ask which of `options`.
- Tool:
update_todo- Permission:
todos
POST/api/v1/todos/status
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
POST/api/v1/todos/delete
Delete a todo (off unless enabled)
Deletes a todo for good. Only when the user asks to delete or remove it; if it's done, use set_todo_status instead. Off by default: on scope_disabled, relay the message. Read back `say`.
- Tool:
delete_todo- Permission:
delete_items
GET/api/v1/todos
The todo list, filtered and paged
Only when the user asks for their todo list beyond what get_today shows. Filter by status, overdue or project; paged (pass nextCursor back as cursor).
- Tool:
list_todos- Permission:
read
GET/api/v1/projects
The user's todo projects
Project names and ids. Rarely needed: add_todo, update_todo and list_todos take project names.
- Tool:
list_projects- Permission:
read
POST/api/v1/projects
Create a todo project
Creates a project, or returns the existing one with that name. add_todo also creates one when given a new project name.
- Tool:
create_project- Permission:
todos
POST/api/v1/projects/update
Rename or recolor a project, by name
Renames or recolors a project. Read back `say`.
- Tool:
update_project- Permission:
todos
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)
POST/api/v1/projects/delete
Delete a project; its todos stay (off unless enabled)
Deletes a project; its todos are kept without a project. Only when the user asks. Off by default. Read back `say`.
- Tool:
delete_project- Permission:
delete_items
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)
GET/api/v1/calendar/agenda
Upcoming events plus the todos to focus on
Calendar events for the next days (default 7) with the in-progress and next todos. For "what's my week look like".
- Tool:
get_agenda- Permission:
read
GET/api/v1/calendar
Calendar events in a date range, paged
Events between start and end (default the next 30 days), optionally by tag. Paged: pass nextCursor back as cursor. get_agenda is usually enough.
- Tool:
list_events- Permission:
read
POST/api/v1/calendar
Add a calendar event
Adds an event: title and startsAt (local time is fine, e.g. 2026-10-09T15:00); default one hour. To block time for an existing todo use schedule_todo. Read back `say`.
- Tool:
create_event- Permission:
calendar
POST/api/v1/calendar/update
Move or change an event, by name
Moves or edits an event by its title ("move the dentist to Friday at 10"). A new startsAt keeps the length unless endsAt or durationMinutes is given. Read back `say`; on 409 ask which of `options`.
- Tool:
update_event- Permission:
calendar
POST/api/v1/calendar/delete
Delete a calendar event (off unless enabled)
Deletes an event, by title. Only when the user asks to cancel or delete it. Off by default: on scope_disabled, offer update_event to move it. Read back `say`.
- Tool:
delete_event- Permission:
delete_items
POST/api/v1/todos/schedule
Block calendar time for a todo, by name
Puts a todo on the calendar ("do the taxes Saturday at 10"). Length defaults to the todo's estimate, else an hour. Read back `say`.
- Tool:
schedule_todo- Permission:
calendar
GET/api/v1/stats
Week and month numbers
Completion rate today and over 7 days, best current streak, 30-day series. For 'how was my week'. `definitions` explains each number (activeHabits = logged in the last 30 days, not 'not archived'); archived habits are excluded, so archive_habit removes test habits from stats.
- Tool:
get_stats- Permission:
read
GET/api/v1/catalog
Find protocols and habits to recommend
Searches the Liberture catalog. Give the user `infoUrl` (its page on this site) for anything you suggest. `imageUrl` is Liberture's official image for it (absolute HTTPS PNG, 1200×630, public), or null when there is none; a catalog habit uses its protocol's image. When presenting a recommendation, show that image if your interface can display images (e.g. markdown ); never substitute an image from elsewhere. `adopted` = they already track it. For something the user simply wants to track, use create_habit instead.
- Tool:
search_catalog- Permission:
read
POST/api/v1/habits/adopt
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
GET/api/v1/coach/recommendations
The in-app coach's latest suggestions
What the in-app coach last suggested, with reasons, infoUrl links and imageUrl. `imageUrl` is Liberture's official image for it (absolute HTTPS PNG, 1200×630, public), or null when there is none; a catalog habit uses its protocol's image. When presenting a recommendation, show that image if your interface can display images (e.g. markdown ); never substitute an image from elsewhere. Empty if it hasn't run.
- Tool:
get_recommendations- Permission:
read
GET/api/v1/coach/state
Coach settings, nudges left today and habits needing a word
Call before any proactive message (a scheduled check-in or automation). Returns the check-in settings, quiet hours, the daily limit with nudges sent and remaining today, the last nudge per kind, pending and snoozed suggestions (each with infoUrl and imageUrl), and per habit lastLoggedOn, unloggedDueDays and weeklyProgress. Then call record_coach_nudge and message the user only if it says allowed.
- Tool:
get_coach_state- Permission:
read
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)
POST/api/v1/assistant/welcome
Mark the first-conversation welcome as done
Call once after running the welcome that get_today asks for on a new connection (outcome done), or if the user would rather skip it (outcome skipped). get_today then stops asking for it.
- Tool:
complete_welcome- Permission:
read
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)
POST/api/v1/coach/nudge
Ask to send one coach message; records it if allowed
Call right before you message the user unprompted. Applies quiet hours, the daily limit and duplicate checks, shared with Liberture's own push check-ins, and records the nudge when allowed. Duplicates: one morning, afternoon, evening and missed_logging nudge per day, one weekly per ISO week; `other` is checked per message, so different `other` messages are each allowed until the daily limit. Only message the user if `allowed` is true; otherwise stay silent (reason: quiet_hours, daily_limit or duplicate). Not needed when the user started the conversation.
- Tool:
record_coach_nudge- Permission:
settings
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)
POST/api/v1/coach/respond
Accept, dismiss or snooze a coach suggestion, by name
Records what the user said about one of the coach's suggestions (get_recommendations or get_coach_state): accept, dismiss, or snooze for `days` (default 7). Pass the suggestion's name or slug. Accepting doesn't add the habit; use adopt_habit for that. Read back `say`.
- Tool:
respond_to_suggestion- Permission:
settings
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)
GET/api/v1/reminders/status
Whether reminders and check-ins can reach the user
Whether push reminders are set up (devices subscribed, server push on) and what was sent today. For "why didn't I get a reminder". sentToday counts claims, not confirmed deliveries: see sentTodayByChannel (assistant = nudges recorded by an assistant, which Liberture didn't deliver) and lastDeliveredAt. When you log a habit or finish a todo, the user's devices get a receipt with Undo (sentTodayByKind.log; assistantReceipts says whether that's on).
- Tool:
get_reminder_status- Permission:
read
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)
GET/api/v1/profile
The user's profile and app preferences
Name, mission statement, focus habits, check-in times, and preferences: theme, week start, 12/24h clock, time zone, habits layout, morning dashboard, default reminder time, reminders on/off.
- Tool:
get_profile- Permission:
read
POST/api/v1/profile
Change the user's profile or preferences
Sets any of: name, missionStatement, focusHabits (up to 3 habit names), checkInTimes, theme, weekStartsOn (monday/sunday), timeFormat, timeZone (IANA), morningDashboard, habitsLayout, defaultReminderTime, notifications (reminders on/off), language, coach (check-in times, quiet hours, daily nudge limit). Send only what changes. Read back `say`.
- Tool:
update_profile- Permission:
settings
GET/api/v1/assistant
What the user allows assistants to do
The permission switches (on/off per action), today's date and the saved time zone. get_today already lists what's off; call this only when asked about permissions.
- Tool:
get_permissions- Permission:
read
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)
GET/api/v1/audit
Drift check: missed critical habits and what to do
Whether the user is drifting today: critical habits (their focus habits and priority 4-5) not yet done, current streaks, and short recommendations. For an evening check or "am I on track".
- Tool:
get_audit- Permission:
read
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)
GET/api/v1/export
Full JSON backup of the user's data
Everything: habits, completions, todos, projects, events, profile and preferences. Large; only when the user asks for a backup or export.
- Tool:
export_data- Permission:
export
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)
POST/api/v1/import/habit-history
Merge completion history from another tracker's backup
Imports past check-ins (habit, day, done, time logged, values) from a habit-tracker backup JSON into this account, without replacing or removing anything. Always call with dryRun: true first and tell the user the result: how many would be imported, already there, conflicts, and which old habits are ambiguous or unmatched (habitMapping, with candidates). Then call without dryRun, passing habitMapping only for matches the user confirmed — never pick between candidates yourself. Days that already have a record are kept as they are (conflicts are reported); `completed: false` in the backup never un-marks a day. Records whose habit isn't matched stay pending: the response's importId lets you import them later with a habitMapping, without sending the file again. Safe to repeat: the same backup twice imports nothing new. Streaks and stats are rebuilt from the history. Read back `say`.
- Tool:
import_habit_history- Permission:
log_completions
MCP only (not in the OpenAPI schema, which a Custom GPT caps at 30 operations)