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.
Setup
1. Get a token
- Open the app and go to Settings › Data › Agent access.
- Name a token and choose Read only or Can change things.
- 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 bysereo login, then tohttp://127.0.0.1:8080.SEREO_API_TOKEN: the token. It is sent to whateverSEREO_API_URLnames, so keep the two together. Without it the server falls back to a token saved bysereo 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. unreconciledis notskipped. 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 itschangedlist; after a replan, report thechangedobject'smoved,addedandremovedlists. Do not describe changes from your own reasoning. isErrorresults 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 enoughStart 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
datestringonboardedbooleanplan_existsbooleanplan_acceptedbooleanawaiting_checkinbooleangap_daysinteger or nullneeds_reconcilingarray of anyarchitectbooleantodoistobject
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 enoughThe 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
datestringYYYY-MM-DD; defaults to today
result what comes back
datestringonboardedbooleanplan_existsbooleanis_todaybooleanrowsarray of anycountsobjectbandsarray of anycoach_notestring
Calls GET /v1/day/{date}
sereo_get_plan#Read a day's plan
Reads only · a read-only token is enoughThe 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
datestringYYYY-MM-DD; defaults to today
result what comes back
blocksarray of anyissuesarray of anysourcestringenergyintegercoach_notestring
Calls GET /v1/plans/{date}
sereo_get_reasoning#Why the plan looks like that
Reads only · a read-only token is enoughThe 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
datestringYYYY-MM-DD; defaults to today
include_promptbooleaninclude the full composed prompt
sereo_generate_plan#Make a plan for a day
Changes things · needs a token that can change thingsGenerates 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
datestringYYYY-MM-DD; defaults to today
energyinteger1 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 5moodstringoptional free text
what_happenedstringif the user is returning after a gap, their own account of it
replacebooleandiscard an existing plan instead of replanning
result what comes back
planobjectrecovery_gapinteger or nullnextstring
sereo_replan#Push back on a plan
Changes things · needs a token that can change thingsRebuilds 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
datestringYYYY-MM-DD; defaults to today
notestringrequiredwhat is wrong with the plan, in the user's words
freshbooleanenergyinteger1 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
planobjectstabilitynumberquestionobject or nullproposalsarray of anynotestring
sereo_talk#Talk to Sereo
Changes things · needs a token that can change thingsThe 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
datestringYYYY-MM-DD; defaults to today
messagestringrequiredthe user's words, verbatim
messagesarray of objectearlier turns
2 fields
whostringrequiredone of"user","sereo"textstringrequired
result what comes back
answerstringdidstringescalatedbooleanchangedobjectnotestring
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 thingsReplaces 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
datestringYYYY-MM-DD; defaults to today
blocksarray of objectrequired5 fields
taskstringrequiredstartstringrequiredHH:MM
endstringrequiredHH:MM
intereststringgoal id, if any
chorebooleanfalse for a break
replacebooleantrue when the user agreed to remove the blocks this leaves out
result what comes back
planobjectrefusedarray of anyissuesarray of anynotestring
Calls PUT /v1/plans/{date}
sereo_set_fixed_times#Change a day's fixed times
Changes things · needs a token that can change thingsReplaces that day's fixed times (dinner, work hours), which Sereo never moves but you may. [] clears.
Arguments
datestringYYYY-MM-DD; defaults to today
fixedarray of objectrequired3 fields
titlestringrequiredstartstringrequiredendstringrequired
sereo_accept_plan#Accept the day
Changes things · needs a token that can change thingsTurns 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
datestringYYYY-MM-DD; defaults to today
result what comes back
todosobjectrebuildobject
sereo_state_energy#Say how the day feels
Changes things · needs a token that can change thingsStates 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
energyintegerrequiredmin 1 · max 5datestringYYYY-MM-DD; defaults to today
result what comes back
datestringenergyintegerenergy_statedboolean
sereo_check_in#Record a day that was never accepted
Changes things · needs a token that can change thingsRecords 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
datestringYYYY-MM-DD; defaults to today
donestringblock numbers, e.g. "1,3"
skippedstringnotestring
sereo_suggest_for_gap#What would fit in this much time
Reads only · a read-only token is enoughGiven 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
datestringYYYY-MM-DD; defaults to today
minutesintegerrequiredhow long the gap is
min 5 · max 480
result what comes back
picksarray of any
sereo_keep_lasting#Keep a confirmed change
Changes things · needs a token that can change thingsSaves one sereo_replan proposals entry for every future day, only AFTER the user said yes to its says.
Arguments
proposalobjectrequiredone
proposalsentry, unchanged1 fields
kindstringrequiredone 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 enoughWhat 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
datestringYYYY-MM-DD; defaults to today
result what comes back
datestringitemsarray of anydoneintegerread_onlybooleantodoist_connectedboolean
Calls GET /v1/todos
sereo_set_todo_status#Tick an item off
Changes things · needs a token that can change thingsMarks 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_idstringrequiredid from sereo_get_todos
statusstringrequiredone of"open","done","skipped"datestringYYYY-MM-DD; defaults to today
result what comes back
idstringstatusstring
sereo_comment_on_todo#Note how something went
Changes things · needs a token that can change thingsAppends 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_idstringrequiredtextstringrequireddatestringYYYY-MM-DD; defaults to today
Weeks and months
sereo_get_week#The week the user is in
Reads only · a read-only token is enoughWhat 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
weekstringa cadence week's ending, YYYY-MM-DD, or omitted for the current one
result what comes back
endingstringdaysarray of anyduearray of anyplanobject
Calls GET /v1/weeks/{week}
sereo_plan_week#Lay the week out by hand
Removes or replaces something · needs a token that can change thingsReplaces 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
weekstringending date, or omitted for this week
daysobjectdate -> {blocks, intent, reasoning}
notestring
result what comes back
endingstringdaysarray 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 thingsTalks 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
weekstringending date, or omitted for this week
daystringYYYY-MM-DD to anchor on one day
messagestringrequiredthe user's words, verbatim
proposebooleanask for a revised draft rather than just an answer
result what comes back
replystringchangesarray of anydraftobject or nullnotestring
sereo_replan_week#Have Sereo re-plan the week
Removes or replaces something · needs a token that can change thingsReplans 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
weekstringending date, or omitted for this week
notestringthe user's words about what the week should be, verbatim
result what comes back
plannedbooleanrefusedarray of anyworkingbooleannotestring
sereo_get_month#A month, as four of the user's own weeks
Reads only · a read-only token is enoughThe 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
monthstringa four-week block's ending, YYYY-MM-DD, or omitted for the current one
result what comes back
endingstringweeksarray of anyreportobject
Calls GET /v1/months/{month}
sereo_get_year#Every goal, and where its milestones fall
Reads only · a read-only token is enoughThe 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
datestringrailsarray of anycountsobjecttoday_daysnumber
Calls GET /v1/year
Goals
sereo_list_goals#Goals, milestones and tasks
Reads only · a read-only token is enoughEvery 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
datestringgoalsarray of anycompleted_goalsarray of any
Calls GET /v1/library
sereo_list_habits#Habits and leisure
Reads only · a read-only token is enoughRecurring 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
datestringhabitsarray of anyleisurearray of any
Calls GET /v1/library
sereo_list_chores#One-off things with a date
Reads only · a read-only token is enoughChores 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
datestringchoresarray of any
Calls GET /v1/library
sereo_get_library#Everything the user tracks
Reads only · a read-only token is enoughGoals, habits, leisure, chores and constraints in one call. Use the narrower tools when you only need one part.
Arguments
None.
result what comes back
datestringonboardedbooleangoalsarray of anycompleted_goalsarray of anyhabitsarray of anyleisurearray of anychoresarray of anyconstraintsarray of any
Calls GET /v1/library
sereo_edit_goal#Change one goal
Removes or replaces something · needs a token that can change thingsChanges 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_idstringrequiredlabelstringdetailstringmilestonesarray of objectthe 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
idstringnamestringrequiredtarget_datestringrequiredYYYY-MM-DD
estimate_blocksintegermin 1blocksintegermin 1statusstringnotestringfinishesbooleantasksarray of object3 fields
idstringtitlestringrequiredstatusstringone of"todo","done"
blocked_untilstringYYYY-MM-DD
blocked_onstringwho or what it is waiting on
result what comes back
intereststringchangedarray of any
sereo_park_goal#Put a goal on hold
Changes things · needs a token that can change thingsParks 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_idstringrequireduntilstringrequiredYYYY-MM-DD it comes back
onstringwhy, or who it waits on
sereo_restore_goal#Put back something deleted
Changes things · needs a token that can change thingsRestores 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
sereo_delete_goal#Take a goal off the plan
Removes or replaces something · needs a token that can change thingsRemoves 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
sereo_set_task_status#Tick a milestone task
Changes things · needs a token that can change thingsMarks 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_idstringrequiredtask_idstringrequiredstatusstringrequiredone of"todo","done"
sereo_set_milestone_status#Tick a milestone off
Changes things · needs a token that can change thingsMarks 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_idstringrequiredmilestonestringrequiredmilestone id
statusstringrequiredone of"done","todo"onstringYYYY-MM-DD it was met
sereo_drop_task#Stop scheduling a task
Removes or replaces something · needs a token that can change thingsRemoves 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_idstringrequiredtask_idstringrequired
result what comes back
droppedstring
sereo_add_job#Put a job and its date on the plan
Changes things · needs a token that can change thingsAdds 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
labelstringrequiredwhat the job is
duestringrequiredYYYY-MM-DD
for_whomstringwho is waiting for it, if anybody
minutesintegermin 5 · max 480prioritystringone 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 thingsMarks 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_idstringrequiredthe chore's id, as sereo_list_chores or the year's chores list it
donebooleandefaulttruedatestringYYYY-MM-DD; defaults to today
result what comes back
idstringdonebooleandaystring
sereo_keep_this_job#Say a suggested job is the user's
Changes things · needs a token that can change thingsKeeps 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
datestringYYYY-MM-DD; defaults to today
taskstringrequiredthe block's task text, exactly as the day carries it
result what comes back
keptstringtaskstring
sereo_import#Load or replace the user's whole setup
Removes or replaces something · needs a token that can change thingsReplaces 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
bundleobjectrequireda sereo.import/1 bundle
replacebooleanrequired if the user already has goals
Calls POST /v1/import
sereo_export#The user's whole configuration
Reads only · a read-only token is enoughThe 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 enoughThe 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
periodstringrequiredone of"week","month"datestringrequiredYYYY-MM-DD, the last day of the period
result what comes back
periodstringendingstringwrittenbooleanreadinessobjecttracksarray of any
sereo_make_report#Write up the week or month
Changes things · needs a token that can change thingsWrites 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
periodstringrequiredone of"week","month"datestringrequiredYYYY-MM-DD, the last day of the period
result what comes back
periodstringendingstringwrittenbooleanreadinessobjectproposalsarray of any
sereo_answer_proposal#Answer one of the review's proposals
Removes or replaces something · needs a token that can change thingsApplies 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
periodstringrequiredone of"week","month"datestringrequiredYYYY-MM-DD, the last day of the period
indexintegerrequiredposition in the report's proposals list
min 0 · max 99answerstringrequiredone of"yes","no","argue"notestringthe user's reason, in their own words
result what comes back
proposalobjectappliedobject or null
sereo_get_retro#A past week's short coaching brief
Reads only · a read-only token is enoughThe 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_endingstringrequiredYYYY-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 thingsWrites 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_endingstringrequiredYYYY-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 enoughWhat 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
profileobjectrulesarray of any
Calls GET /v1/profile
sereo_set_settings#Change a setting
Changes things · needs a token that can change thingsChanges 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
settingsobjectrequiredthe fields to change, and only those
result what comes back
changedarray of anyprofileobject
Calls PATCH /v1/profile
sereo_list_constraints#The user's standing rules
Reads only · a read-only token is enoughRules 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
datestringconstraintsarray of any
Calls GET /v1/library
sereo_state_rule#State a standing rule
Changes things · needs a token that can change thingsAdds 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
textstringrequiredthe user's own words, unedited
kindstringone of"scheduling","gate","content"applies_tostringa goal id to narrow it to; omit for every day
result what comes back
idstringtextstringkindstring
Calls POST /v1/constraints
sereo_revoke_rule#Take a standing rule off
Removes or replaces something · needs a token that can change thingsStops 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_idstringrequiredfrom sereo_get_settings
result what comes back
removedstring