MCP reference

Sereo for AI agents

Sereo has a Model Context Protocol server, sereo-mcp. An assistant that speaks MCP can read your days and goals and, if you let it, plan and tick things off.

It is a local stdio server launched by your MCP client. Each of its 49 tools wraps one or more calls to the Sereo API using your token; the reference below links each tool to the endpoints it calls. The server implements no business rules of its own: every rule is enforced by the API.

Tool descriptions are reproduced exactly as the server sends them to the model, which is why they are written as instructions to an agent.

Early access. The server ships with the Sereo Python package (Python 3.11+), which is not yet published to a public package index. To request access, write to [email protected]. The HTTP API does not require it.

Setup

1. Get a token

  1. Open the app and go to Settings › Data › Agent access.
  2. Name a token and choose Read only or Can change things.
  3. Copy it. It begins with sat_, authenticates as your account, and is shown once: only a digest is stored.

With a read-only token, tools marked as changing state fail with read_only_token. Put the token in the client configuration, not in the conversation.

2. Register the server

Add Sereo to your MCP client's configuration:

{
  "mcpServers": {
    "sereo": {
      "command": "/absolute/path/to/.venv/bin/sereo-mcp",
      "env": {
        "SEREO_API_URL": "https://app.usesereo.com",
        "SEREO_API_TOKEN": "sat_your_token"
      }
    }
  }
}

The server is a stdio process the client launches; python -m sereo.mcp is equivalent to the sereo-mcp entry point.

  • SEREO_API_URL: the API base URL. Set it explicitly: when it is unset the server falls back to the URL saved by sereo login, then to http://127.0.0.1:8080.
  • SEREO_API_TOKEN: the token. It is sent to whatever SEREO_API_URL names, so keep the two together. Without it the server falls back to a token saved by sereo login, and only uses that one for the URL it was issued for.

3. Call sereo_status first

It returns the user's current date and timezone, whether they have goals, whether today has a plan and whether it was accepted, and whether any items await reconciliation. The typical sequence for a day is: generate a plan, revise it from the user's feedback, accept it (which creates the to-do list), then set item statuses.

Rules for agents

  • Pass user text verbatim. Feedback on a plan (sereo_replan) and standing rules (sereo_state_rule) take the user's own words, not a summary; the planner uses the wording.
  • unreconciled is not skipped. An item still open after its day has passed has not been answered. Only the user can mark an item skipped.
  • Milestone tasks are not check-ins. Setting a milestone task's status does not record a work session.
  • Report changes from the response. After sereo_set_settings, read back its changed list; after a replan, report the changed object's moved, added and removed lists. Do not describe changes from your own reasoning.
  • isError results are business outcomes. For example: no plan for that date, or a read-only token. Read the message and act on it; retrying unchanged returns the same result.

Start here

sereo_status#

Where the user is today

Reads only · a read-only token is enough

Start here. date is the user's own today; onboarded, interests and goals say how much is set up (interests counts everything, goals only the projects, not the habits or leisure under them); plan_exists and plan_accepted say how far today has got; awaiting_checkin means a day is waiting to be answered; gap_days counts workdays since the user last showed up (null if <2); on_hold lists parked goals; needs_reconciling names earlier days with unanswered items; calendar_connected and todoist report the integrations, with a note when Todoist owns completion; architect means the conversational setup is served; email_verified is false until the address has answered its link, and until then model calls are refused; energy_default is the user's usual answer; unread_report is the latest unopened report, or null; report_written if any exists; report_running is true while a report is being written; timezone is the zone hours here are read in; walkthrough_owed/tutorial: the tour; checkout_first, access (full|checkout_first|lapsed, the last read-only): standing. Cheap, and it tells you which tool to reach for next.

Arguments

None.

result what comes back
  • datestring
  • onboardedboolean
  • plan_existsboolean
  • plan_acceptedboolean
  • awaiting_checkinboolean
  • gap_daysinteger or null
  • needs_reconcilingarray of any
  • architectboolean
  • todoistobject

Calls GET /v1/status

Days

sereo_get_day#

The whole of a day, as the user sees it

Reads only · a read-only token is enough

The richest read there is, and the one to prefer: every row of the day in order with what each is for, whether it is done, skipped or still open, the calendar around it, what Sereo thinks matters most, and the coach note. Works before the user has set anything up — it answers with an empty day rather than an error, so it is safe as a first call; reading today marks it seen. Use sereo_get_plan only when you specifically want the raw plan the engine wrote.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

result what comes back
  • datestring
  • onboardedboolean
  • plan_existsboolean
  • is_todayboolean
  • rowsarray of any
  • countsobject
  • bandsarray of any
  • coach_notestring

Calls GET /v1/day/{date}

sereo_get_plan#

Read a day's plan

Reads only · a read-only token is enough

The blocks scheduled for a day with the reasoning attached to each. issues lists anything Sereo's guards changed or removed — worth reading, since it is where the plan differs from what the model proposed. sereo_get_day is usually the better read: it carries this plus what the user has done with it.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

result what comes back
  • blocksarray of any
  • issuesarray of any
  • sourcestring
  • energyinteger
  • coach_notestring

Calls GET /v1/plans/{date}

sereo_get_reasoning#

Why the plan looks like that

Reads only · a read-only token is enough

The model's own reasoning for a day, the pressure state it was given, which of the user's standing rules applied, and what the guards did. Use when the user asks why something was or was not scheduled. include_prompt returns the literal prompt too — it is tens of kilobytes, so only ask when you need it.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

  • include_promptboolean

    include the full composed prompt

Calls GET /v1/plans/{date}/reasoning

sereo_generate_plan#

Make a plan for a day

Changes things · needs a token that can change things

Generates one day's plan; nothing beyond that day. You do not supply times — Sereo places blocks into the real gaps between the user's calendar events itself. Refuses if a plan already exists unless you pass replace; prefer sereo_replan, which rebuilds around the user's objection. Refuses week_not_planned.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

  • energyinteger

    1 running on empty, 3 ordinary, 5 strong. A budget, not a mood score: it caps how many blocks the day gets. Ask the user, and leave it out if they have not said — the profile default plans the day and the day records that nobody chose it, so a number you supply on their behalf is charted back to them as their own week.

    min 1 · max 5
  • moodstring

    optional free text

  • what_happenedstring

    if the user is returning after a gap, their own account of it

  • replaceboolean

    discard an existing plan instead of replanning

result what comes back
  • planobject
  • recovery_gapinteger or null
  • nextstring

Calls POST /v1/plans/{date}/generate

sereo_replan#

Push back on a plan

Changes things · needs a token that can change things

Rebuilds one day around the user's words, verbatim and whole, as note. Busy times (dinner, work until 5) are set aside, timed work held, lasting parts returned as proposals; a missing time gives question and no change. Read plan.pushback back. fresh starts over.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

  • notestringrequired

    what is wrong with the plan, in the user's words

  • freshboolean
  • energyinteger

    1 running on empty, 3 ordinary, 5 strong. A budget, not a mood score: it caps how many blocks the day gets. Ask the user, and leave it out if they have not said — the profile default plans the day and the day records that nobody chose it, so a number you supply on their behalf is charted back to them as their own week.

    min 1 · max 5
result what comes back
  • planobject
  • stabilitynumber
  • questionobject or null
  • proposalsarray of any
  • notestring

Calls POST /v1/plans/{date}/replan

sereo_talk#

Talk to Sereo

Changes things · needs a token that can change things

The one place to talk to Sereo, the scheduling assistant, about anything; scope says how far a turn reached. Pass the user's words verbatim and the turns so far as messages. It argues from their goals, says what a change gives up and offers fixes; reply, push back, or say yes. The user (and you for them) decides: "do it anyway" overrules it (override). did: answered (nothing written), changed (today), escalated (a week change proposed; a spoken yes applies it), week_changed, finished, held, ruled, unruled, hours_changed, adjusted/goal_added (a goal), job_removed, reranked. Report only what changed says.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

  • messagestringrequired

    the user's words, verbatim

  • messagesarray of object

    earlier turns

    2 fields
    • whostringrequired
      one of "user", "sereo"
    • textstringrequired
result what comes back
  • answerstring
  • didstring
  • escalatedboolean
  • changedobject
  • notestring

Calls POST /v1/conversation

sereo_set_plan#

Save a day the user laid out themselves

Removes or replaces something · needs a token that can change things

Replaces that day's whole block list: read sereo_get_plan and send every block to keep. A save that removes blocks is refused, naming them, unless replace: true (ask the user first). Blocks need task, start (HH:MM), end, and interest for a goal; no interest is a job unless chore: false. Read refused back; fixed times change with sereo_set_fixed_times. Blocks outside usual hours are kept and named in plan.outside_hours: say so.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

  • blocksarray of objectrequired
    5 fields
    • taskstringrequired
    • startstringrequired

      HH:MM

    • endstringrequired

      HH:MM

    • intereststring

      goal id, if any

    • choreboolean

      false for a break

  • replaceboolean

    true when the user agreed to remove the blocks this leaves out

result what comes back
  • planobject
  • refusedarray of any
  • issuesarray of any
  • notestring

Calls PUT /v1/plans/{date}

sereo_set_fixed_times#

Change a day's fixed times

Changes things · needs a token that can change things

Replaces that day's fixed times (dinner, work hours), which Sereo never moves but you may. [] clears.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

  • fixedarray of objectrequired
    3 fields
    • titlestringrequired
    • startstringrequired
    • endstringrequired

Calls PUT /v1/plans/{date}/fixed

sereo_accept_plan#

Accept the day

Changes things · needs a token that can change things

Turns one day's plan into that day's to-do list. Idempotent, and safe after a replan — anything already answered carries across and the response reports anything that could not. Accepting also counts as the user showing up, which prevents a false recovery plan later.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

result what comes back
  • todosobject
  • rebuildobject

Calls POST /v1/plans/{date}/accept

sereo_state_energy#

Say how the day feels

Changes things · needs a token that can change things

States the user's energy (1-5) on an existing day's plan. Only a stated number is charted; scheduler-built mornings carry an unstated default. No rebuild. Pass only a number the user actually gave.

Arguments

  • energyintegerrequired
    min 1 · max 5
  • datestring

    YYYY-MM-DD; defaults to today

result what comes back
  • datestring
  • energyinteger
  • energy_statedboolean

Calls POST /v1/plans/{date}/energy

sereo_check_in#

Record a day that was never accepted

Changes things · needs a token that can change things

Records what got done on one day, by 1-based block number ("1,3"). Only for days whose plan was never accepted — an accepted day is owned by its to-do list and this refuses, because it would overwrite every item already ticked.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

  • donestring

    block numbers, e.g. "1,3"

  • skippedstring
  • notestring

Calls POST /v1/plans/{date}/checkin

sereo_suggest_for_gap#

What would fit in this much time

Reads only · a read-only token is enough

Given a number of minutes, what is worth doing with them — chosen from the user's own goals and habits, with the reason for each. Deterministic: no model call, nothing written (gated like model calls), so this is the right tool when the user has a gap and does not want the day rebuilt. Returns nothing at all rather than truncating something to fit. The route behind it can also be asked to reason over this ranking with a model call; this tool cannot, deliberately, and has no field for it.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

  • minutesintegerrequired

    how long the gap is

    min 5 · max 480
result what comes back
  • picksarray of any

Calls POST /v1/plans/{date}/suggest

sereo_keep_lasting#

Keep a confirmed change

Changes things · needs a token that can change things

Saves one sereo_replan proposals entry for every future day, only AFTER the user said yes to its says.

Arguments

  • proposalobjectrequired

    one proposals entry, unchanged

    1 fields
    • kindstringrequired
      one of "weekly", "rule", "hours"

Calls POST /v1/lasting

To-dos

sereo_get_todos#

The accepted day's to-do list

Reads only · a read-only token is enough

What the user accepted for a day and how far through it they are. Statuses are open, done, skipped and unreconciled — the last meaning the day passed and they never answered either way. Unreconciled is NOT a miss; never report it as one.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

result what comes back
  • datestring
  • itemsarray of any
  • doneinteger
  • read_onlyboolean
  • todoist_connectedboolean

Calls GET /v1/todos

sereo_set_todo_status#

Tick an item off

Changes things · needs a token that can change things

Marks one item on a day's list done, skipped, or open. REFUSES when the user has connected Todoist — completion lives there, and the refusal will tell you so. Note that 'skipped' is the user actively saying it did not happen; leaving an item open is a different claim, so never skip something on their behalf.

Arguments

  • todo_idstringrequired

    id from sereo_get_todos

  • statusstringrequired
    one of "open", "done", "skipped"
  • datestring

    YYYY-MM-DD; defaults to today

result what comes back
  • idstring
  • statusstring

Calls POST /v1/todos/{todo}/status

sereo_comment_on_todo#

Note how something went

Changes things · needs a token that can change things

Appends a comment to one item on a day's list — append-only, a record rather than a draft. REFUSES when Todoist is connected; add the comment there instead and it syncs back.

Arguments

  • todo_idstringrequired
  • textstringrequired
  • datestring

    YYYY-MM-DD; defaults to today

Calls POST /v1/todos/{todo}/comments

Weeks and months

sereo_get_week#

The week the user is in

Reads only · a read-only token is enough

What a cadence week holds, what is due in it, and what the user said it is for. Omit week for the week containing today; cadence weeks run from the signup day, not from a Monday. Carries no figures about the week in progress — how a week went is sereo_get_report's answer, once it has ended. feedback is the last FINISHED week's edition; never present it as this week's.

Each day carries what the week decided it is FOR — its intent, the goals it serves, its untimed blocks and effort, and the reasoning for it. Quote that reasoning when the user asks why something is on a day; it is the answer, and re-deriving one would give them a second account of the same decision.

Arguments

  • weekstring

    a cadence week's ending, YYYY-MM-DD, or omitted for the current one

result what comes back
  • endingstring
  • daysarray of any
  • duearray of any
  • planobject

Calls GET /v1/weeks/{week}

sereo_plan_week#

Lay the week out by hand

Removes or replaces something · needs a token that can change things

Replaces this week's plan with what each day is for. This is the same artifact Sereo's own weekly planner writes, so what you set here is what the daily planner reads.

NOT THE SHAPE sereo_set_plan TAKES. A day carries blocks, each an untimed unit of work: text (required), goal (a goal id, if any), priority (high/normal/low). A block with no text, or any time field, is refused: the day sets the hours, and sereo_set_plan lays out a timed day. A day may also carry intent (a short name) and reasoning (why, in the user's own words — it is shown to them and quoted back when they ask why something is on today).

Send the whole week: omitted days become unplanned; empty days and unstarted weeks are refused. Ask before setting it — a week is the user's statement about their own week, and it shapes every day in it.

Arguments

  • weekstring

    ending date, or omitted for this week

  • daysobject

    date -> {blocks, intent, reasoning}

  • notestring
result what comes back
  • endingstring
  • daysarray of any

Calls PATCH /v1/weeks/{week}

sereo_discuss_week#

Push back on the week in conversation

Changes things · needs a token that can change things

Talks over this week and saves nothing: pass the user's words; get an answer, and with propose a revised draft plus changes, the server's own diff of it. Nothing is saved — if the user keeps it, write draft.days with sereo_plan_week and say so. day anchors on one day (edits it, reads the rest). Runs the model.

Arguments

  • weekstring

    ending date, or omitted for this week

  • daystring

    YYYY-MM-DD to anchor on one day

  • messagestringrequired

    the user's words, verbatim

  • proposeboolean

    ask for a revised draft rather than just an answer

result what comes back
  • replystring
  • changesarray of any
  • draftobject or null
  • notestring

Calls POST /v1/weeks/{week}/discuss

sereo_replan_week#

Have Sereo re-plan the week

Removes or replaces something · needs a token that can change things

Replans the rest of this week, replacing its plan: it decides what each remaining day is FOR, with reasoning the user reads. Pass their pushback as note verbatim — it becomes the brief the planner honours. Ask first: it replaces the remaining days, and runs the model. A week dropping owed work is refused (refused says why; the week is kept) — the guard working, not an error. working true means still going: poll sereo_get_week. Refuses a week that has not started.

Arguments

  • weekstring

    ending date, or omitted for this week

  • notestring

    the user's words about what the week should be, verbatim

result what comes back
  • plannedboolean
  • refusedarray of any
  • workingboolean
  • notestring

Calls POST /v1/weeks/{week}/replan

sereo_get_month#

A month, as four of the user's own weeks

Reads only · a read-only token is enough

The four cadence weeks a month holds, and the month's report if one is written. A month here is NOT a calendar month: it is four weeks running from the signup day, the same grid the monthly report is written over. Omit month for the block containing today. report.state is written, running or not_yet — a month still in progress carries no figures, and saying how it is going from the planned counts would be inventing a grade.

Arguments

  • monthstring

    a four-week block's ending, YYYY-MM-DD, or omitted for the current one

result what comes back
  • endingstring
  • weeksarray of any
  • reportobject

Calls GET /v1/months/{month}

sereo_get_year#

Every goal, and where its milestones fall

Reads only · a read-only token is enough

The year as a set of rails, one per goal, with every milestone placed on the date it is actually expected — plan_iso is the date the goal's own plan gives it, and drift, held and blocked marks are called out. This is the tool for 'how am I doing on X' and for anything about trajectory. Like the day, it answers for an account with nothing set up yet.

Arguments

None.

result what comes back
  • datestring
  • railsarray of any
  • countsobject
  • today_daysnumber

Calls GET /v1/year

Goals

sereo_list_goals#

Goals, milestones and tasks

Reads only · a read-only token is enough

Every live goal with its milestones, their concrete next tasks, and what Sereo derived — which milestone is current, blocks remaining, whether it is overdue. completed_goals carries the ones already finished, which are out of the scheduling path but still part of the user's record; a summary that leaves them out understates the year. Anything under derived is inference, not something the user said; keep that distinction when you report it.

Arguments

None.

result what comes back
  • datestring
  • goalsarray of any
  • completed_goalsarray of any

Calls GET /v1/library

sereo_list_habits#

Habits and leisure

Reads only · a read-only token is enough

Recurring things with a weekly cadence, and how many times each has been done this week. habits is what the user means to keep up; leisure is what they want to make room for — both arrive here, because a week read without the second one looks emptier than it is. Cadence weeks run from the user's start date, not from Monday.

Arguments

None.

result what comes back
  • datestring
  • habitsarray of any
  • leisurearray of any

Calls GET /v1/library

sereo_list_chores#

One-off things with a date

Reads only · a read-only token is enough

Chores and their due dates. A date already past stays past — Sereo never rounds an overdue chore up to 'due today'.

Arguments

None.

result what comes back
  • datestring
  • choresarray of any

Calls GET /v1/library

sereo_get_library#

Everything the user tracks

Reads only · a read-only token is enough

Goals, habits, leisure, chores and constraints in one call. Use the narrower tools when you only need one part.

Arguments

None.

result what comes back
  • datestring
  • onboardedboolean
  • goalsarray of any
  • completed_goalsarray of any
  • habitsarray of any
  • leisurearray of any
  • choresarray of any
  • constraintsarray of any

Calls GET /v1/library

sereo_edit_goal#

Change one goal

Removes or replaces something · needs a token that can change things

Changes one goal for every future day: its label, detail or milestones (a list replaces them; one left out is removed). To pause it use sereo_park_goal. It refuses milestones an integration owns. changed names what moved.

Arguments

  • interest_idstringrequired
  • labelstring
  • detailstring
  • milestonesarray of object

    the full replacement list; one left out is removed. The library's own shape is accepted back: ids, blocks and step ids are optional

    9 fields
    • idstring
    • namestringrequired
    • target_datestringrequired

      YYYY-MM-DD

    • estimate_blocksinteger
      min 1
    • blocksinteger
      min 1
    • statusstring
    • notestring
    • finishesboolean
    • tasksarray of object
      3 fields
      • idstring
      • titlestringrequired
      • statusstring
        one of "todo", "done"
  • blocked_untilstring

    YYYY-MM-DD

  • blocked_onstring

    who or what it is waiting on

result what comes back
  • intereststring
  • changedarray of any

Calls PATCH /v1/interests/{interest}

sereo_park_goal#

Put a goal on hold

Changes things · needs a token that can change things

Parks a goal until a date for every future day: nothing is planned for it until then, and nothing is deleted. The way to back-burner, pause or postpone something.

Arguments

  • interest_idstringrequired
  • untilstringrequired

    YYYY-MM-DD it comes back

  • onstring

    why, or who it waits on

Calls PATCH /v1/interests/{interest}

sereo_restore_goal#

Put back something deleted

Changes things · needs a token that can change things

Restores a goal, habit or job deleted in the last 30 days, whole, for every future day: milestones, tasks, history and its rules.

Arguments

  • interest_idstringrequired

Calls POST /v1/interests/{interest}/restore

sereo_delete_goal#

Take a goal off the plan

Removes or replaces something · needs a token that can change things

Removes a goal, habit or job from every future day; restorable for 30 days with sereo_restore_goal. To pause it use sereo_park_goal; to finish it, sereo_set_milestone_status. Refuses the last one.

Arguments

  • interest_idstringrequired
result what comes back
  • deletedstring

Calls DELETE /v1/interests/{interest}

sereo_set_task_status#

Tick a milestone task

Changes things · needs a token that can change things

Marks one of a goal's steps done or not-done, for every future day. This is the user's own checklist: it does NOT credit a work session and does not move any schedule. Only a check-in or a ticked to-do does that.

Arguments

  • interest_idstringrequired
  • task_idstringrequired
  • statusstringrequired
    one of "todo", "done"

Calls POST /v1/interests/{interest}/tasks/{task}

sereo_set_milestone_status#

Tick a milestone off

Changes things · needs a token that can change things

Marks a milestone reached, or takes it back, for every future day. Pass on when it was met on an earlier day than today; the default is the user's own today, not the server's. Reaching the last open milestone finishes the goal, which then moves out of the goal list and into completed_goals. This is a fact about the goal, not check-in credit — it moves no schedule. Refuses on a milestone an integration owns.

Arguments

  • interest_idstringrequired
  • milestonestringrequired

    milestone id

  • statusstringrequired
    one of "done", "todo"
  • onstring

    YYYY-MM-DD it was met

Calls POST /v1/interests/{interest}/milestones/status

sereo_drop_task#

Stop scheduling a task

Removes or replaces something · needs a token that can change things

Removes one of a goal's steps from every future day, so the planner stops offering it. Use this when the user says they are not going to do something at all — sereo_set_todo_status answers for one day and the task is open again tomorrow. A removal rather than a tick, because marking it done would be a lie about work nobody did.

Arguments

  • interest_idstringrequired
  • task_idstringrequired
result what comes back
  • droppedstring

Calls DELETE /v1/interests/{interest}/tasks/{task}

sereo_add_job#

Put a job and its date on the plan

Changes things · needs a token that can change things

Adds a job with a deadline to every future day until done — a delivery, a submission, an errand. Prefer this to a plan note: a date given as a field cannot be misread, and a note asking for one is parsed. for_whom is who is waiting, and it is what makes this a delivery rather than an errand — it changes what the day calls it and what a report leads with. Give minutes if the user has said how long a sitting takes; without it the planner guesses.

Arguments

  • labelstringrequired

    what the job is

  • duestringrequired

    YYYY-MM-DD

  • for_whomstring

    who is waiting for it, if anybody

  • minutesinteger
    min 5 · max 480
  • prioritystring
    one of "high", "normal", "low"
result what comes back
  • idstring

Calls POST /v1/jobs

sereo_finish_job#

Tick a job off the list, or untick it

Changes things · needs a token that can change things

Marks a job done for good, credited on a day's check-in (today unless date says). Only a chore: goals and habits answer not_a_job. done: false unticks. Call it only when the user has said the job is done.

Arguments

  • interest_idstringrequired

    the chore's id, as sereo_list_chores or the year's chores list it

  • doneboolean
    default true
  • datestring

    YYYY-MM-DD; defaults to today

result what comes back
  • idstring
  • doneboolean
  • daystring

Calls POST /v1/interests/{interest}/done

sereo_keep_this_job#

Say a suggested job is the user's

Changes things · needs a token that can change things

Keeps a job Sereo suggested on every future day until done; its own ideas otherwise last one day. A block the planner filed under chores with a date on it is a suggestion — the day carries keep on that row — and nothing about it is written down until this is called. Then it becomes a real chore, brought to the planner every day until it is done. Only call it when the user has actually said the job is theirs: the whole reason this gate exists is that a client one user never had took sixteen blocks of her month and a late badge that grew every morning.

Arguments

  • datestring

    YYYY-MM-DD; defaults to today

  • taskstringrequired

    the block's task text, exactly as the day carries it

result what comes back
  • keptstring
  • taskstring

Calls POST /v1/plans/{date}/keep

sereo_import#

Load or replace the user's whole setup

Removes or replaces something · needs a token that can change things

Replaces the user's whole setup from a sereo.import/1 bundle. DESTRUCTIVE, the blunt instrument: it rebuilds the profile wholesale, which races the background writers that update the same file, and unlike sereo_edit_goal it enforces no ownership — a bundle can overwrite milestones an integration owns, and the next sync will undo it or duplicate them. Use sereo_edit_goal to change something that already exists. This tool is for first setup and for restoring a backup. The report names every value Sereo had to default and everything it could not keep — read those back rather than assuming a clean import.

Arguments

  • bundleobjectrequired

    a sereo.import/1 bundle

  • replaceboolean

    required if the user already has goals

Calls POST /v1/import

sereo_export#

The user's whole configuration

Reads only · a read-only token is enough

The user's setup as a sereo.import/1 bundle (no plans, check-ins or reports), for backup or copying. To change one goal, use sereo_edit_goal — see the warning on sereo_import.

Arguments

None.

Calls GET /v1/export

Reports and briefs

sereo_get_report#

The week or month in counted sections

Reads only · a read-only token is enough

The review surface: what was planned against what was kept, how each goal is tracking, and proposals — concrete changes Sereo is offering, such as moving a date or planning fewer days. Nothing in proposals has happened; put each to the user and send the answer with sereo_answer_proposal. readiness says whether the period is finished enough to write up, and written whether it has been. Supersedes sereo_get_retro for a week.

Arguments

  • periodstringrequired
    one of "week", "month"
  • datestringrequired

    YYYY-MM-DD, the last day of the period

result what comes back
  • periodstring
  • endingstring
  • writtenboolean
  • readinessobject
  • tracksarray of any

Calls GET /v1/reports/{period}/{date}

sereo_make_report#

Write up the week or month

Changes things · needs a token that can change things

Writes the review for a finished period and plans nothing: counted sections, prose, and proposals the user can accept or argue with. Runs the model the first time; repeat calls return the stored report. A period that has not ended is never written up — the report is a weekly edition, and there is no force past that; check readiness from sereo_get_report to see when it arrives.

Arguments

  • periodstringrequired
    one of "week", "month"
  • datestringrequired

    YYYY-MM-DD, the last day of the period

result what comes back
  • periodstring
  • endingstring
  • writtenboolean
  • readinessobject
  • proposalsarray of any

Calls POST /v1/reports/{period}/{date}

sereo_answer_proposal#

Answer one of the review's proposals

Removes or replaces something · needs a token that can change things

Applies the user's decision on a report proposal to every future day, by its index in that list. 'yes' APPLIES IT: it really moves milestone dates, adds a standing rule, or parks a goal. 'no' declines it and 'argue' records that the user disagrees, with their reason in note — neither changes anything. Never answer 'yes' on the user's behalf: this changes their plan, not a document. The response reports what was applied.

Arguments

  • periodstringrequired
    one of "week", "month"
  • datestringrequired

    YYYY-MM-DD, the last day of the period

  • indexintegerrequired

    position in the report's proposals list

    min 0 · max 99
  • answerstringrequired
    one of "yes", "no", "argue"
  • notestring

    the user's reason, in their own words

result what comes back
  • proposalobject
  • appliedobject or null

Calls POST /v1/reports/{period}/{date}/proposals/{index}

sereo_get_retro#

A past week's short coaching brief

Reads only · a read-only token is enough

The older, smaller weekly write-up: what happened, what went well, what did not. Prefer sereo_get_report — for a week the two write the same record, and the report additionally carries counted sections and proposals, which are the part that can actually change the plan. Reach for this one only when the user asks for the brief specifically, or when a report has not been written.

Arguments

  • week_endingstringrequired

    YYYY-MM-DD, the last day of the week

Calls GET /v1/retro/{date}

sereo_make_retro#

Write the short weekly brief

Changes things · needs a token that can change things

Writes the older, smaller coaching brief for a week and plans nothing. Runs the model only if none exists; repeat calls return the stored brief, and an unfinished week is never written. Prefer sereo_make_report, which writes the same record for a week with counted sections and proposals.

Arguments

  • week_endingstringrequired

    YYYY-MM-DD

Calls POST /v1/retro/{date}

Settings and standing rules

sereo_get_settings#

The settings and standing rules

Reads only · a read-only token is enough

What the user has set: which days they never work, which hours of a weekday are never free, quiet hours, when the scheduler runs, their default energy, where they are. Plus rules — the standing rules handed to the planner for every future day. Read this before changing anything, and read ids from here to revoke a rule.

Arguments

None.

result what comes back
  • profileobject
  • rulesarray of any

Calls GET /v1/profile

sereo_set_settings#

Change a setting

Changes things · needs a token that can change things

Changes settings that shape EVERY FUTURE DAY, including days the user has not looked at. Only when they asked for the change; read changed back afterwards.

Send only the fields that change — the rest is left alone, null clears one, and anything not listed is refused by name.

MONDAY IS 0 everywhere below. - day_start, day_end: HH:MM, the hours the planner may use; an end before the start crosses midnight. - sleep: {start: bedtime, end: wake}; never planned into. Setting it or the hours may trim the other: read changed. - days_off: weekday NUMBERS never worked, e.g. [5, 6] for the weekend. Not names. Cannot be all seven. - hours_off: hours a weekday is never free, keyed by weekday number as a string: {"2": [{"start": "13:00", "end": "15:00", "title": "School run"}]}. Start must be before end — split an overnight window at midnight into two weekdays' halves. - quiet_hours: hours to leave alone. - auto_plan: true lets Sereo pre-build the morning plan and the re-entry day after an absence. Off by default; ask before turning it on. - evening_checkin: false stops it. - morning_plan_time, evening_checkin_time, miss_sweep_time, weekly_retro_time: HH:MM on the user's own clock; changing one re-queues that job today. - default_energy, place, latitude, longitude, buffer_after_shift_minutes, todoist_sync_minutes, timezone.

Arguments

  • settingsobjectrequired

    the fields to change, and only those

result what comes back
  • changedarray of any
  • profileobject

Calls PATCH /v1/profile

sereo_list_constraints#

The user's standing rules

Reads only · a read-only token is enough

Rules the user set about how their days work. gate is a precondition on acting at all, scheduling shapes when work goes, content shapes what the work should be. Read these before suggesting anything.

Arguments

None.

result what comes back
  • datestring
  • constraintsarray of any

Calls GET /v1/library

sereo_state_rule#

State a standing rule

Changes things · needs a token that can change things

Adds a standing rule every future day honours until revoked — "no meetings before 10", "never schedule the gym on a work night".

PASS THE USER'S OWN WORDS, VERBATIM. The text is stored as sent and handed to the planner unchanged, so your paraphrase would become the rule and they would never see that it had been reworded. If what they said is not quite a rule, ask them to say it as one rather than writing it for them.

kind is scheduling (when things happen, the default), gate (what must be true first) or content (what a day may hold).

Arguments

  • textstringrequired

    the user's own words, unedited

  • kindstring
    one of "scheduling", "gate", "content"
  • applies_tostring

    a goal id to narrow it to; omit for every day

result what comes back
  • idstring
  • textstring
  • kindstring

Calls POST /v1/constraints

sereo_revoke_rule#

Take a standing rule off

Removes or replaces something · needs a token that can change things

Stops a standing rule shaping any future day. Ids come from sereo_get_settings. Revoking one that is already gone reports so rather than pretending it did something.

This withdraws something the user put in place — only on their ask, and say which rule you are about to remove before you do.

Arguments

  • rule_idstringrequired

    from sereo_get_settings

result what comes back
  • removedstring

Calls DELETE /v1/constraints/{constraint}