API reference

The operations your assistant uses. Connectors get them as tools at /mcp after signing in; the same list is in the OpenAPI schema. Scripts send Authorization: Bearer with the token from Settings → Advanced.

OpenAPI schema
https://liberture.com/api/v1/openapi.json
MCP endpoint
https://liberture.com/mcp

API reference

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 ![name](imageUrl)); 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 ![name](imageUrl)); 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)

Rate limit: 120 requests per minute per token. Over that, requests get 429 with Retry-After.

The full /api/v1 surface (by-id routes, ICS export, backups) is documented in API.md in the repository.

Liberture newsletter

Get articles and updates from Liberture by email.