API reference · v1.0.0
The Sereo API
The HTTP API behind Sereo's web app, iOS app, CLI and MCP server. Base URL https://app.usesereo.com. Request and response bodies are JSON, except the two …/stream routes, which respond with Server-Sent Events (text/event-stream).
This reference documents 65 endpoints for integrations. Routes used only by Sereo's own clients (sign-in, token management, billing, onboarding state) are omitted. The machine-readable OpenAPI 3.1 description is served at app.usesereo.com/openapi.json; it is generated from the server's route table, and this page is generated from it.
GET /v1/day/{date} rather than recomputing them in a client.Authentication
Every endpoint below requires a personal API token, sent as a bearer token in the Authorization header.
- 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.
curl https://app.usesereo.com/v1/whoami \ -H "Authorization: Bearer $SEREO_API_TOKEN"
A read-only token may call GET routes only; any other method returns 403 with code read_only_token. Each endpoint below states which kind of token it needs.
Errors
Errors return a non-2xx status and a JSON envelope. Branch on error.code, which is stable; message is human-readable and may change; include request_id when contacting support.
{ "error": { "code": "read_only_token",
"message": "this token is read-only; it cannot change anything",
"request_id": "…" } }
400invalid_request: malformed body or parameter, or a value out of range.401unauthorized: missing, unknown or revoked token.402: no active subscription (checkout_required,subscription_lapsed), or the account's monthly usage limit was reached (spend_cap_reached). With a lapsed subscription,GETroutes keep working.403:read_only_token(a read-only token called a non-GETroute), oremail_unverified(a route that runs the model, before the account's email address is confirmed).404not_found: the day, goal, item or route does not exist for this account.409conflict: the request conflicts with the account's current state, e.g. no goals yet, a week that has not started, or a run already in progress.429rate_limited: too many requests. Wait for the number of seconds inRetry-Afterwhen present.503busy: the model provider is temporarily rate-limiting. Retry afterRetry-Afterseconds.
400, 401, 403 and 404 are deterministic: retrying the same request unchanged returns the same error.
Days and weeks
Day and week plans: generating, editing, replanning and discussing them, standing constraints, and periodic reports.
Get the account's current status
Any token · read only is enoughReturns the account's state for a date (default: today in the account's timezone): whether goals are imported (onboarded), whether the day has a plan and whether it is accepted, whether a check-in is outstanding, the recovery gap, items awaiting reconciliation, goals on hold, report state, email verification, subscription standing (access) and first-run tutorial progress. Read-only; invokes no model.
date (YYYY-MM-DD) evaluates the same fields for another day; a malformed date is 400 invalid_request. awaiting_checkin is true when the date has a plan but no check-in record. gap_days counts workable days since the user's last activity and is null when fewer than two.
Answers for an account in any standing, including checkout_first, so a client can use it to decide what to offer next.
Query parameters
datestringOverride today, YYYY-MM-DD.
Responses
200 OK
datestringrequiredonboardedbooleanrequiredinterestsintegergoalsintegergoals only (the projects), not the habits, leisure or chores under them — what the band counts so it agrees with the year wheel
plan_existsbooleanrequiredplan_acceptedbooleanawaiting_checkinbooleangap_daysinteger or nullworkable days (days off excluded) since the user's last activity: a user-built or accepted plan, a check-in, or opening today's day view. Null when fewer than 2; a value means the next generated plan is a recovery plan
needs_reconcilingarray of objecton_holdarray of objectcalendar_connectedbooleantimezonestringthe zone every hour in this API is read in. A client that finds "UTC" here and a real zone in the browser is looking at the default nobody chose
navigation_tracedbooleanthis account's navigation is being recorded for the beta, and the screen says so
architectbooleanwhether the goal-elicitation conversation is served by this deployment at all. Read it here rather than probing for a 404 on /v1/architect/start.
report_runningbooleana report for this account is being generated right now
report_writtenbooleanwhether any report has been written for this account, read or not — the tour's Reports page has steps about one only when it does
unread_reportobject or nullthe latest written report not yet marked read; cleared by
POST /v1/reports/{period}/{date}/seen2 fields
periodstringendingstring
email_verifiedbooleanwhether the address has answered. False means the account works, but routes that invoke the model answer 403
email_unverified.energy_defaultintegerwhere the energy control starts
min 1 · max 5accessanythe account's standing:
full;checkout_first, which may only start a subscription, sign out or delete itself (everything else answers 402checkout_required); orlapsed, which reads everything and changes nothing until it renews. Alwaysfullwith billing off.one of"full","checkout_first","lapsed"checkout_firstbooleana new account that has not been through checkout yet. Every route outside a small allowlist answers 402
checkout_requireduntil it has. Always false with billing off.walkthrough_owedbooleanwhether the first-run tutorial is still owed: true once a profile exists, while the account's standing is
full, until POST /v1/walkthrough/seentutorialobject or nullthe tutorial's progress while it is owed, else null: each section
todo,done(from product state: the week accepted by the person, today's plan taken; Goals, Calendar, Reports and Settings reported seen) orskipped;currentis the first step still to do, null once every step is done or skipped2 fields
stepsarray of object2 fields
keyanyrequiredone of"goals","calendar","week","today","reports","settings"stateanyrequiredone of"todo","done","skipped"
currentanyone of"goals","calendar","week","today","reports","settings",null
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/status \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Mark a chore done or not done
Needs a token that can change thingsRecords that the user finished a chore (an interest of type chore), or reverses that with done: false, and returns {id, done, day}.
The statement is stored per day, and that day's check-in record is rebuilt from it: from the to-do list if the day's plan was accepted, from the statement alone if not. Once credited, the planner stops scheduling the chore and reports count it as done. Unticking the only item a day held removes that day's check-in record. date is the day it was done (YYYY-MM-DD, default today). Repeating a call has no further effect.
Errors: 404 not_found for an unknown interest id; 409 not_a_job when the interest is not a chore (goals complete through their milestones, habits through the days they are worked); 400 invalid_request for a non-boolean done or a malformed date; 409 not_onboarded before any goals exist. Invokes no model.
Path parameters
intereststringrequiredA goal, habit or chore id.
pattern^[a-z0-9][a-z0-9_]{0,63}$
Request body optional
donebooleandefaulttruedatestringYYYY-MM-DD; today by default
Responses
200 OK
idstringrequireddonebooleanrequireddaystringrequired
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/interests/$INTEREST/done \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Get the day view
Any token · read only is enoughReturns the derived view of one day: the plan's blocks and the calendar's events as rows (events have kind: "busy"), each row resolved to its goal, milestone, guard adjustment (adapt), deadline risk and to-do status; plus counts, the day window, solar bands, blocks that did not fit (unfit, each with server-computed offers), the week plan's intent for the day, standing rules, and flags such as accepted, settled, week_planned and read_only. Status, ordering and the current time (now_minutes, today only) are decided server-side; render these fields rather than recomputing them. An item still open after its day is unreconciled, which is not a miss.
Use this for display. GET /v1/plans/{date} returns the raw stored plan in the engine's fixed shape.
Answers 200 for any valid date: before onboarding with no rows and onboarded: false, and for dates before the account's anchor date with read_only: true. 400 invalid_request for a malformed date.
Side effect: reading today records the user as present, which counts as activity for gap detection. Reading any other date writes nothing. Invokes no model.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
200 OK
datestringrequiredweekdaystringonboardedbooleanrequiredis_todaybooleannow_minutesintegermin 0 · max 2879energyinteger or nullmin 1 · max 5week_changed_since_planbooleanthe week's decision for this day moved after the day was planned — a replan of the week or an amendment naming the day. Not premise drift, which is
week_plan_stale.askobject or nullthe week's re-read behind the last ask on this day, while it runs and once done; null when there is none or the process has forgotten it
5 fields
workingbooleanstepsarray of stringweekobject or nullendingstringerrorstring or null
energy_statedbooleanwhether that number is the user's own or the default the planner had to pick. The client must not infer this from
energybeing present — a planned day always has oneplan_existsbooleanrequiredweek_plannedboolean or nullwhether this day's cadence week has been planned. While false, generate answers 409
week_not_planned. Null when it does not apply (no account set up yet, or a day before the account began). The client reads it, never derives itacceptedbooleanread_onlybooleaninfluencesarray of objectstanding rules agreed in a report review that apply to planning (W19); revoke one with
DELETE /v1/constraints/{id}3 fields
idstringtextstringfromstring
milestone_reviewsarray of objectmilestones whose date has passed but which nobody has ticked reached: the day asks rather than guess, and answering feeds the review route.
stateis 'asked' for a fresh nudge, 'not_yet' once the user deferred and owes an adjustment7 fields
intereststringinterest_labelstringmilestonestringmilestone_namestringwas_duestringwhystring or nullstatestringone of"asked","not_yet"
settledbooleanthe date is before today in the account's timezone. Use this rather than the client's clock; confirm with the user before rewriting a settled day
sourcestring or nullone of"user","scheduler",nullday_offbooleana weekday the user said they never work; generating it produces a day-off placeholder plan
reshapingbooleanthe day is being edited; server-held, so the state survives reloads and other clients
day_startstringday_endstringplans_betweenstringa server-written sentence describing when this day is planned: the day window and the unavailable hours inside it
day_wrapsbooleanwhether this day crosses midnight: day_end is then a next-morning hour
day_end_extendedintegerday_end in minutes since midnight on the extended axis (above 1439 when the day wraps)
min 0 · max 2879outside_hoursarray of objectblocks the user placed outside their day window; they are kept, not refused
4 fields
taskstringrequiredstartstringrequiredendstringrequiredsidestringrequiredone of"before","after"
pushbackarray of objectwhere Sereo would change one of the person's own blocks, and why; the block stays
2 fields
taskstringrequiredreasonstringrequired
most_importantstringcoach_notestringrecoverybooleanissuesarray of stringon_holdarray of objectwork deliberately not in the day, named here as {interest, label} — the plan file keeps bare ids
unfitarray of objectblocks placement could not fit today (no_room), each with the two ways out — move to a day with room, or drop the habit in the way
6 fields
taskstringrequiredgoalstring or nullminutesinteger or nullaskedbooleanwhystringrequiredoffersarray of object8 fields
kindstringrequiredone of"move","drop_habit"textstringrequiredtostringday_labelstringeffortstringfree_minutesintegertaskstringintereststring or null
committed_actionsarray of stringa Day-0 plan whose calendar input was too thin to earn time blocks carries these instead (P13)
backupstringpinsarray of objectsolarobject or nulllocal clock minutes for the day's solar events, or null when the profile has no location
8 fields
placestringlatitudenumberlongitudenumberdawninteger or nullriseinteger or nullnooninteger or nullsetinteger or nullduskinteger or null
bandsarray of objectthe stretches of the day the ledger is drawn in, in order and covering every minute of it. Bounded by solar events where there is a location and split evenly around the user's own hours where there is not
7 fields
namestringrequiredneverbooleanrequireda stretch wholly outside the hours Sereo plans: one of the hours it never touches
fromintegerrequiredmin 0 · max 2879tointegerrequiredinclusive: the last minute this stretch owns. Past 1439 = a wrapped day's small hours
min 0 · max 2879emptystringrequiredwhat to say when nothing was placed here
coveredbooleanrequiredwhether any block reaches into this stretch, wherever it began. A block is drawn where it starts and occupies everything it spans, so this is what says an hour is spoken for — never the drawing
titlestringrequiredwhere the sun stands over this stretch — empty when there is no location to say it from
rowsarray of objectrequired20 fields
idstringrequiredstartstringrequiredpattern^[0-9]{2}:[0-9]{2}$endstringrequiredpattern^[0-9]{2}:[0-9]{2}$start_minutesintegerend_minutesintegerminutesintegertaskstringrequiredkindstringrequiredbusyis a calendar event, not a plan block;breakis a plan block with no interest behind it, so it is not work and never a to-doone of"goal","rhythm","leisure","chore","break","busy"iconstringtagstringthe goal or rhythm this hour serves
nodestring or nullthe milestone it serves, when there is one
intereststring or nullwhystringwhy this hour is here — the model's own sentence for a plan block, and for a
busyrow the server's attribution, since nothing is ever asked about an event the user did not schedule here. Never empty for a row a client can openadaptbooleanthe day changed under the user here: a guard cut its length, or a replan moved its hour
extbooleanowned by the calendar, not movable
riskobject or null2 fields
labelstringlevelstringone of"late","soon"
keepobject or null2 fields
duestringformatdateprioritystringone of"high","normal","low"
todo_idstring or nulltask_idstring or nullstatusstring or nullthe derived status —
unreconciledis silence, never a missone of"open","done","skipped","unreconciled",null
goalsarray of objectwhat a block the user writes in the day editor can be put in service of. Anything waiting on a third party today is left out, because the engine is not scheduling it today either
6 fields
idstringrequiredtagstringrequiredwhat the goal is called out loud — the one or two words a control can print
labelstringrequiredkindstringrequiredone of"goal","rhythm","leisure","chore"nodestring or nullrequiredthe milestone a block put in service of this goal would land under. The server decides it: a plan block carries no milestone of its own
inkinteger or nullthe ink this goal wears everywhere; a habit wears its goal's
countsobjectrequired5 fields
workintegerdoneintegeropenintegerskippedintegerunreconciledinteger
knowsarray of objectserver-written statements about the day (e.g. calendar and goal facts) for display when it has no plan
2 fields
textstringweightstring
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/day/2026-11-12 \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Get a cadence week
Any token · read only is enoughReturns one cadence week: a row per day with the week plan's abstract blocks, intent, reasoning and effort, the realized day plan (items), the checkpoints due (due), the week plan's note, summary and amendments (plan), the last finished week's report (feedback), working (a POST /v1/weeks/{week}/replan pass is in flight) and last_error (why the last background pass failed, if it did).
{week} is latest (the week containing today) or any date, which is resolved to the cadence week containing it. Cadence weeks start on the account's signup weekday, not on Monday.
No performance figures for the week are returned (no completion share, pace, or done/skipped counts); those appear only in the weekly report once the week has ended. A day with stale: true has reasoning that rests on facts that have since changed; present it as the original intent, not as current fact.
Answers before onboarding with empty days. 409 not_onboarded for latest when the account has no anchor date; 400 invalid_request for a malformed date. Invokes no model.
Path parameters
weekstringrequiredA cadence week's ending date, or
latestfor the week you are in. Cadence weeks run from the account's signup day, not from a Monday, solatestsaves a caller doing that arithmetic.pattern^latest|\d{4}-\d{2}-\d{2}$
Responses
200 OK
endingstringrequiredfromstringrequiredtostringrequiredtodaystringcurrentbooleanoverbooleanits last day has gone by: replan and discuss answer 409 week_over
daysarray of objectrequired19 fields
datestringrequiredweekdaystringrequiredday_offbooleanpastbooleanis_todaybooleanplannedbooleanrequireda plan exists for this day
scheduledintegerrealized work blocks on the day's plan
minutesintegeracceptedbooleanrecoverybooleaneffortstringrequiredhow heavy the day is, a readout of its abstract blocks — never a set cap
one of"clear","light","normal","heavy"blocksarray of objectrequiredthe week's ABSTRACT, untimed blocks for this day; the day elaborates each into timed work. Distinct from
items7 fields
idstringrequiredtextstringrequiredgoalstring or nullprioritystringrequiredone of"high","normal","low"sourcestringone of"agent","user"inkinteger or nulllabelstring
intentstringwhat the week decided this day is for
goalsarray of stringids of the goals its blocks serve
itemsarray of objectwhat is on the day, in order, each block naming and inking the goal it serves
8 fields
startstringrequiredendstringminutesintegertaskstringrequiredgoalstringlabelstringinkintegerrequiredchoreboolean
prioritystringone of"high","normal","low"reasoningstringwhy the week put this here, in the words the user reads
releasedarray of stringtext of the week blocks for this day that the day plan left off at the user's request
tasksarray of string
duearray of objectcheckpoints landing in the week, and recent ones still owed
planobjectrequirednote: the user's note, set by PATCH;summary: the weekly planner's closing text;written_at,by(agentoruser),amendmentsfeedbackobject or nullthe last finished week's edition
countsobject
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/weeks/2026-11-12 \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Replace the week plan
Needs a token that can change thingsWrites a user-authored week plan for a cadence week and returns the week view (the GET /v1/weeks/{week} shape). This is how a client saves or accepts a week draft, including one revised by POST /v1/weeks/{week}/discuss. It is the same stored plan the weekly planner writes, and it is what day generation reads.
days maps each date to {intent, blocks, reasoning}. Blocks are untimed: {id, text, goal, priority, source}, where goal is an existing interest id and priority is high, normal or low. The plan is replaced whole: a date omitted from days is left unplanned. If days is omitted entirely, the current days are kept and only note (truncated to 400 characters) is updated. The plan is recorded as written by the user (by: "user").
Validation fails with 400 bad_week_plan and nothing is written for: a date outside the week; a day with no blocks (omit the day to clear it); a block without text; a block carrying start, end, minutes or duration; a block naming its goal as interest; an unknown goal id or an invalid priority; blocks on a day the user does not work. Unlike an agent-written plan, a user plan may leave out due or overdue work and need not include reasoning.
409 week_not_started if the week's first day is in the future; 409 not_onboarded before any goals exist. Invokes no model.
Path parameters
weekstringrequiredA cadence week's ending date, or
latestfor the week you are in. Cadence weeks run from the account's signup day, not from a Monday, solatestsaves a caller doing that arithmetic.pattern^latest|\d{4}-\d{2}-\d{2}$
Request body optional
daysobjectdate -> {intent, blocks:[{id, text, goal, priority, source}], reasoning}. Sent whole; this is how the weekly editor saves an accepted draft
notestringmax length 400
Responses
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X PATCH https://app.usesereo.com/v1/weeks/2026-11-12 \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
Discuss and revise a week draft
Needs a token that can change thingsSends one conversational turn about a week draft to the model and returns {reply, changes, draft}. Stateless: the client sends the transcript (messages; the last entry must be the user's; only the last 12 are used, each clipped to 1000 characters), the draft it holds (draft, {days: {date: {intent, blocks, reasoning}}}; the stored week plan is used if omitted), an anchor and propose.
anchor is a date in the week to scope edits to that day, with the rest of the week as read-only context, or null for the whole week; a date outside the week is treated as null. propose: true asks the model for a revision this turn.
When the model revises, draft is the full revised draft and changes is the server's diff of it against the input (move_block, add_block, remove_block, reword, reprioritise, reword_day). Each revised day is validated before it is returned (well-formed untimed blocks, nothing on days off, non-empty reasoning); an invalid revision is retried once and otherwise discarded. When the model only answers, changes is empty and draft is null. Blocks with source: "user" keep their original text.
Nothing is persisted except a diagnostic trace. To keep a revision, send it with PATCH /v1/weeks/{week}.
Invokes the planner model (fast tier); typically under 30 s. Errors: 400 invalid_request (for example, last message not from the user); 409 not_onboarded; 403 email_unverified; 402 (checkout_required, subscription_lapsed, or spend_cap_reached when the monthly usage limit is reached); 429 rate_limited; 503 busy when the model provider is rate-limiting.
Path parameters
weekstringrequiredA cadence week's ending date, or
latestfor the week you are in. Cadence weeks run from the account's signup day, not from a Monday, solatestsaves a caller doing that arithmetic.pattern^latest|\d{4}-\d{2}-\d{2}$
Request body required
messagesarray of objectrequired2 fields
whostringtextstring
draftobject or nullthe client's working week draft: {days: {date -> {intent, blocks, reasoning}}}
anchorstring or nullthe day being edited, or null for the whole week
proposebooleanask the model for a revision this turn; it may still answer without one
Responses
200 OK
replystringrequiredchangesarray of objectrequired5 fields
callstringrequiredmove_block | add_block | remove_block | reword | reprioritise | reword_day
taskstringrequiredwasstringnowstringnotestring
draftobject or nullthe revised draft, or null when answering
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
503 That integration is not configured on this deployment
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/weeks/2026-11-12/discuss \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
Run the weekly planner
Needs a token that can change thingsRuns the weekly planning agent for a cadence week and stores the plan it writes: for each day from today onward, a few abstract, untimed blocks and the reasoning for them. It never sets times or durations. Days already lived keep their existing plan. Returns the week view (the GET /v1/weeks/{week} shape) with planned and, when refused, refused.
An agent plan must place every due and overdue goal on some day and give each day a reasoning. If it cannot, nothing is stored and the response is 200 with planned: false and refused listing the reasons; the week is left as it was. planned: true with no days is a valid empty week.
brief (optional) carries a conversation the user had about the week: {messages: [...], proposal: {days: {...}}}. The proposal is given to the agent as a suggestion to weigh, not applied directly.
Long-running. A pass typically takes around 160 s. The request waits up to 25 s; if the pass has not finished it returns 202 with the current week view and working: true and the pass continues in the background. Poll GET /v1/weeks/{week} until working is false; a failure after the 202 is reported there as last_error.
Invokes the planner model. Errors: 409 plan_in_progress if a pass is already running for the week; 409 week_not_started if the week's first day is in the future; 409 not_onboarded; 403 email_unverified; 402 (checkout_required, subscription_lapsed, or spend_cap_reached when the monthly usage limit is reached); 429 rate_limited; 503 busy.
Path parameters
weekstringrequiredA cadence week's ending date, or
latestfor the week you are in. Cadence weeks run from the account's signup day, not from a Monday, solatestsaves a caller doing that arithmetic.pattern^latest|\d{4}-\d{2}-\d{2}$
Request body optional
briefobject{messages: [...], proposal: {days: {...}}}
Responses
200 OK
endingstringworkingbooleanplannedbooleanwhether a plan was written; false with
refusedwhen the guard would not sign offrefusedarray of stringdaysarray of object
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
403 The account's email address is not confirmed (email_unverified), or a read-only token called a non-GET route (read_only_token)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
429 Too many attempts; wait and retry — retry-after says how long
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/weeks/2026-11-12/replan \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Apply an amendment to the week plan
Needs a token that can change thingsMerges an amendment into the stored week plan and returns the week view (the GET /v1/weeks/{week} shape) plus days_affected and today_affected. Use it to apply a proposal returned as week.amendment by POST /v1/plans/{date}/escalate, or carried on the day as ask.week, once the user has accepted it. Proposals are never applied by the server on its own; this call is the write. Invokes no model.
amendment is {days: {date: entry}}. Each entry is a day in the week plan's shape ({intent, blocks, reasoning}) and replaces that day whole; null clears the day. Dates before today are ignored. why (truncated to 400 characters) and from (default "day") are recorded with the amendment in the plan's amendments list.
The merged week is validated as an agent plan: each amended day needs blocks with text and a non-empty reasoning, no blocks may fall on a day off, and due or overdue work must still appear somewhere in the week. Only problems the amendment introduces cause a refusal. A refusal, an amendment naming no days, or one naming only past days is 400 bad_amendment, and nothing is written.
days_affected lists the amended dates whose day plan was generated before this change; today_affected is true when today is one of them, in which case the client can offer POST /v1/plans/{date}/replan. Applying an amendment also withdraws any pending week proposal for that week. 409 not_onboarded before any goals exist.
Path parameters
weekstringrequiredA cadence week's ending date, or
latestfor the week you are in. Cadence weeks run from the account's signup day, not from a Monday, solatestsaves a caller doing that arithmetic.pattern^latest|\d{4}-\d{2}-\d{2}$
Request body required
amendmentobjectrequired{days: {date: {intent, blocks, reasoning}}}; each entry replaces the day whole and needs a non-empty reasoning; null clears the day; past dates are ignored
whystringmax length 400fromstring
Responses
200 OK
today_affectedbooleanrequiredtoday is among
days_affected, so today's plan predates the change; consider offering POST /v1/plans/{date}/replandays_affectedarray of stringrequired
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/weeks/2026-11-12/amend \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
Get a four-week month block
Any token · read only is enoughReturns one month block: its four cadence weeks (weeks, each with planned-day counts and planned minutes), the goal colour legend (goals), and the monthly report's state (report.state: written with a headline, running while it is being generated, or not_yet).
A month here is not a calendar month. Blocks are four cadence weeks counted from the account's anchor date, the same periods monthly reports cover. {month} is latest (the block containing today) or a block's ending date as listed by GET /v1/home; an explicit date is used as the ending exactly as given and is not aligned to the grid.
No performance figures are returned for a block still in progress. Answers before onboarding. 409 not_onboarded for latest when the account has no anchor date; 400 invalid_request for a malformed date. Invokes no model.
Path parameters
monthstringrequiredA four-week block's ending date, or
latestfor the block today falls in. A month here is four of the account's own cadence weeks — the grid a monthly report is written over — never a calendar month.pattern^latest|\d{4}-\d{2}-\d{2}$
Responses
200 OK
endingstringrequiredfromstring or nulltostring or nulltodaystringcurrentbooleanweeksarray of objectrequired10 fields
endingstringrequiredfromstringtostringplannedintegerrequireddays of this week that have a plan. A structural count, never a grade
ofintegerrequiredpastbooleancurrentbooleanshapedbooleansomebody has said what this week is for
minutesintegerwork laid out across the week, in minutes — planned, never kept
daysarray of object7 fields
datestringrequiredweekdaystringrequiredis_todaybooleanpastbooleanplannedbooleanminutesintegerrequiredgoalsarray of objectrequired3 fields
idstringrequiredinkinteger or nullrequiredwhich of the client's goal inks this goal wears; decided here so every screen agrees. Null for a job, which wears no goal's colour
minutesintegerrequired
reportobjectrequired3 fields
statestringrequiredone of"written","running","not_yet"endingstringrequiredheadlinestring
countsobjectweekdaysarray of stringgoalsarray of object3 fields
idstringrequiredlabelstringrequiredinkintegerrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/months/2026-11-12 \
-H "Authorization: Bearer $SEREO_API_TOKEN"
List the openable days, weeks and months
Any token · read only is enoughReturns the navigation index: days.first and days.last (the openable date range, from the account's anchor date to today), up to six most recent cadence weeks (weeks, newest first, each with its report state), and twelve month slots (months, newest first). Month slots before the account existed are placeholders with available: false and no ending. Before the account has an anchor date, days.first is null and months is empty.
Nothing in the future is offered: days.last is always today. Week and month boundaries are computed on the account's own cadence grid, so use these values rather than calculating them. For the state of today, use GET /v1/status. Invokes no model.
Responses
200 OK
todaystringrequireddaysobjectrequired2 fields
firststring or nullrequiredlaststring or nullrequired
weeksarray of objectrequired10 fields
endingstringrequiredfromstringtostringplannedintegerrequireddays of this week that have a plan. A structural count, never a grade
ofintegerrequiredpastbooleancurrentbooleanshapedbooleansomebody has said what this week is for
minutesintegerwork laid out across the week, in minutes — planned, never kept
daysarray of object7 fields
datestringrequiredweekdaystringrequiredis_todaybooleanpastbooleanplannedbooleanminutesintegerrequiredgoalsarray of objectrequired3 fields
idstringrequiredinkinteger or nullrequiredwhich of the client's goal inks this goal wears; decided here so every screen agrees. Null for a job, which wears no goal's colour
minutesintegerrequired
monthsarray of objectrequiredtwelve slots, newest first, once the account has an anchor date (empty before); slots before the anchor are
available: falsewith noending8 fields
availablebooleanrequiredtrue for a block within the account's lifetime; false for a placeholder before the anchor date
endingstringabsent on an unavailable slot
fromstringrequiredtostringrequiredcurrentbooleanpastbooleanminutesintegerreportobject
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/home \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Get a day's stored plan
Any token · read only is enoughPath parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
200 OK
blocksarray of objectrequired6 fields
startstringrequiredpattern^[0-9]{2}:[0-9]{2}$endstringrequiredpattern^[0-9]{2}:[0-9]{2}$taskstringrequiredmax length 120intereststring or nullrequirednull for a chore or a break — see
chore, which tells the two apartwhystringrequiredmax length 200chorebooleanwork that serves no tracked goal. A block with no
interestand nochoreis a break: not work, and never a to-do item. Send it onPUT /v1/plans/{date}for work with no goal, or the block is stored as a break
laidarray of objectthe blocks the user laid out themselves, held at their hours through a rebuild
pushbackarray of objectwhere Sereo would change one of the user's own blocks, and why. Advice only: the block stays
2 fields
taskstringrequiredreasonstringrequired
outside_hoursarray of objecton a day the user laid out: the work blocks running outside the hours they keep, kept and named
4 fields
taskstringrequiredstartstringrequiredendstringrequiredsidestringrequiredone of"before","after"
most_importantstringrequiredcoach_notestringrequiredgenerated_atstringenergyinteger or nullmin 1 · max 5energy_statedbooleantrue when the user chose
energy; false when the profile default was used. Only treat a stated energy as the user's report, e.g. in chartsrecoverybooleanrecovery_gapinteger or nulldays away the day was planned to recover from; a replan of the day keeps it, so a rebuilt recovery day is still one
issuesarray of stringwhat the guards changed, as
kind:subject— e.g. energy_clamped, duration_trimmed, no_room, orphaned_break; week_placed names a session the week asked for that code put on the day, week_held one it did not put on because the goal is on hold or refused today, held_block a stored block removed on a rebuild for the same reasonreleasedarray of objectweek-plan blocks for this day that the planner left off at the user's request:
blockis the week block id,textits text. Only written when the user's own words asked for it4 fields
blockstringrequiredtextstringwhystringrequiredatstring
sourcestringone of"user","scheduler"accepted_atstringpresent once accepted; also counts as the user showing up for gap detection
on_holdarray of string
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/plans/2026-11-12 \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Save a user-laid-out day plan
Needs a token that can change thingsReplaces a day's blocks with the timed blocks sent and returns the stored plan with changed, refused, issues, accepted, fixed, rebuild and week_check. Times are stored as sent; the save itself invokes no model.
Guards. Only the calendar-overlap guard runs. A block on an hour owned by a calendar event or a fixed time is not stored and is listed in refused with a reason; the rest of the day is saved. Blocks outside the user's day window are kept and listed in the plan's outside_hours. The energy cap, block-duration check and orphaned-break sweep do not run. A block whose interest matches no goal is stored with interest: null; send chore: true for work that serves no goal, or the block is stored as a break.
Whole-day replace. A block not sent is removed, and removed work blocks are named in changed.removed. With if_removes: "refuse", a save that would remove any block fails with 409 would_remove naming them. With strict: true, a block whose times cannot be read (not HH:MM, or end not after start) fails the save with 400 unreadable_blocks; without it, such blocks are dropped and listed in refused. Either failure writes nothing. The day's previous blocks are kept on the plan as prior.
Fixed times. fixed replaces the day's fixed (busy) times before the save; [] clears them and omitting the field leaves them unchanged.
Acceptance. If the day was already accepted, its to-do list is rebuilt: answered items are carried across, and an answered item whose block was removed stays on the to-do list; rebuild reports both. accept: true accepts the day in the same request unless a block was refused. Otherwise an unaccepted day remains a proposal.
Week follow-up. If the saved day no longer contains week-plan work assigned to it, the server may start a background re-read of the rest of the week, which invokes the planner model and is limited per day. week_check reports started, the displaced work, or the reason it did not start. The resulting proposal appears on GET /v1/day/{date} as ask.week and is applied only through POST /v1/weeks/{week}/amend.
Errors: 400 invalid_request (blocks not a list, or invalid fixed); 409 not_onboarded.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body required
blocksarray of objectrequired6 fields
startstringrequiredpattern^[0-9]{2}:[0-9]{2}$endstringrequiredpattern^[0-9]{2}:[0-9]{2}$taskstringrequiredmax length 120intereststring or nullrequirednull for a chore or a break — see
chore, which tells the two apartwhystringrequiredmax length 200chorebooleanwork that serves no tracked goal. A block with no
interestand nochoreis a break: not work, and never a to-do item. Send it onPUT /v1/plans/{date}for work with no goal, or the block is stored as a break
pinsarray of objectblocks the user has pinned to their time, matched by
startandtask; pins that match no saved block are dropped3 fields
startstringendstringtaskstring
most_importantstringcoach_notestringfixedarray of objectthe day's fixed times, replacing the existing list; [] clears it, absent leaves it unchanged. Treated as busy time like a calendar event; not tracked as work
3 fields
startstringrequiredendstringrequiredtitlestringrequired
acceptbooleanalso accept the day in this request; ignored if any block is refused (W8)
if_removesstringrefuse, writing nothing, a save that would remove a block
one of"refuse"strictbooleana block whose times cannot be read fails the save (400 unreadable_blocks) instead of being left out
Responses
200 OK
scopestringhow far this write reaches: today's plan only, this week, every future day, or nothing at all
one of"today","this week","every future day","nothing"persistedobjectwhat lasts beyond today, by kind; empty lists when nothing lasting changed
5 fields
goalsarray of stringrulesarray of stringsettingsarray of stringjobsarray of stringweekarray of string
changedobjectrequiredwhat the day gained, lost, moved and kept, from the state before and after — the server's account, not the editor's prediction
4 fields
movedarray of stringaddedarray of stringremovedarray of stringkeptarray of string
week_checkobject or nullwhether the rest of the week is being re-read against the day as it now stands:
started, thedisplacedweek work, or areasonit was not. The proposal lands on the day asask.weekplanobjectrequired16 fields
blocksarray of objectrequired6 fields
startstringrequiredpattern^[0-9]{2}:[0-9]{2}$endstringrequiredpattern^[0-9]{2}:[0-9]{2}$taskstringrequiredmax length 120intereststring or nullrequirednull for a chore or a break — see
chore, which tells the two apartwhystringrequiredmax length 200chorebooleanwork that serves no tracked goal. A block with no
interestand nochoreis a break: not work, and never a to-do item. Send it onPUT /v1/plans/{date}for work with no goal, or the block is stored as a break
laidarray of objectthe blocks the user laid out themselves, held at their hours through a rebuild
pushbackarray of objectwhere Sereo would change one of the user's own blocks, and why. Advice only: the block stays
2 fields
taskstringrequiredreasonstringrequired
outside_hoursarray of objecton a day the user laid out: the work blocks running outside the hours they keep, kept and named
4 fields
taskstringrequiredstartstringrequiredendstringrequiredsidestringrequiredone of"before","after"
most_importantstringrequiredcoach_notestringrequiredgenerated_atstringenergyinteger or nullmin 1 · max 5energy_statedbooleantrue when the user chose
energy; false when the profile default was used. Only treat a stated energy as the user's report, e.g. in chartsrecoverybooleanrecovery_gapinteger or nulldays away the day was planned to recover from; a replan of the day keeps it, so a rebuilt recovery day is still one
issuesarray of stringwhat the guards changed, as
kind:subject— e.g. energy_clamped, duration_trimmed, no_room, orphaned_break; week_placed names a session the week asked for that code put on the day, week_held one it did not put on because the goal is on hold or refused today, held_block a stored block removed on a rebuild for the same reasonreleasedarray of objectweek-plan blocks for this day that the planner left off at the user's request:
blockis the week block id,textits text. Only written when the user's own words asked for it4 fields
blockstringrequiredtextstringwhystringrequiredatstring
sourcestringone of"user","scheduler"accepted_atstringpresent once accepted; also counts as the user showing up for gap detection
on_holdarray of string
fixedarray of objectthe day's fixed times as they now stand
3 fields
startstringrequiredendstringrequiredtitlestringrequired
acceptedbooleanwhether the day is taken after this save
issuesarray of stringrefusedarray of objectrequired4 fields
taskstringrequiredstartstring or nullendstring or nullreasonstringrequired
rebuildobject or null
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X PUT https://app.usesereo.com/v1/plans/2026-11-12 \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
Get the generation trace for a day's plan
Any token · read only is enoughReturns the diagnostic trace recorded when the day's plan was last generated or rebuilt: the prompt sent to the model (prompt, system), the model's reasoning text when the model returned one (reasoning), the pressure state it was given (pressure), the ids of standing rules applied (constraints_applied), the guard issues (guard_issues), and call metadata (model, provider, token counts, latency_s). Conversations about the day through the discuss endpoints are appended under discussions. The trace can be tens of kilobytes, which is why it is not part of GET /v1/plans/{date}.
A hand-laid save (PUT /v1/plans/{date}) writes no trace, so the trace may describe an earlier generated version of the day. Traces are deleted after 30 days by default. 404 not_found when no trace exists for the date; 400 invalid_request for a malformed date.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
200 OK
daystringenergyintegerguard_issuesarray of anypressureobjectconstraints_appliedarray of anyreasoningstring or nullpromptstringmodelstringlatency_snumber
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/plans/2026-11-12/reasoning \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Generate a day's plan
Needs a token that can change thingsRuns the planner model for a date and stores the result as a proposal, returning {plan, recovery_gap, accepted: false, rebuild: null, scope, persisted}. The model chooses tasks, durations and order; the server places the blocks into the gaps between calendar events and then runs the plan guards. Nothing is accepted: the user accepts with POST /v1/plans/{date}/accept (or PUT /v1/plans/{date} with accept: true), and only then do the blocks become to-do items.
Body: send energy (1-5) only if the user chose it; otherwise the profile default is used and the plan records energy_stated: false. note is the user's own words about the day (clipped to 500 characters); what_happened is the user's account of an absence; mood is a short text description; force: true overwrites an existing plan. If the user has been away for two or more workable days, the day is built as a recovery plan and recovery_gap gives the gap. A generated plan counts as user activity for gap detection.
Invokes the planner model; a request typically takes tens of seconds and can take up to two minutes on a large profile. Progress can be followed on GET /v1/plans/{date}/stream. On a day the user does not work, or when every goal is on hold, a placeholder plan is stored without invoking the model.
Errors: 409 plan_exists when the day already has a plan and force is not set (use POST /v1/plans/{date}/replan to revise it); 409 week_not_planned when the day's cadence week has no plan yet (plan it with POST /v1/weeks/{week}/replan or PATCH /v1/weeks/{week} first); 409 not_onboarded; 400 invalid_request for invalid energy or date; 403 email_unverified; 402 (checkout_required, subscription_lapsed, or spend_cap_reached when the monthly usage limit is reached); 429 rate_limited; 503 busy.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body optional
energyintegera budget, not a mood: 1-2 caps the day at three work blocks, 3 allows five, 4-5 allow six. Optional, and send it only when the user has actually chosen it — omitted, the profile default plans the day and the day records that nobody said it
min 1 · max 5moodstringwhat_happenedstringthe user's account of a gap, if they are returning
notestringwhat the user said about today when they asked for the plan — their own words, honoured over any general pattern, spent with this one day (W1). Clipped to 500 characters
forcebooleandiscard an existing plan
Responses
200 OK
scopestringhow far this write reaches: today's plan only, this week, every future day, or nothing at all
one of"today","this week","every future day","nothing"persistedobjectwhat lasts beyond today, by kind; empty lists when nothing lasting changed
5 fields
goalsarray of stringrulesarray of stringsettingsarray of stringjobsarray of stringweekarray of string
planobjectrequired16 fields
blocksarray of objectrequired6 fields
startstringrequiredpattern^[0-9]{2}:[0-9]{2}$endstringrequiredpattern^[0-9]{2}:[0-9]{2}$taskstringrequiredmax length 120intereststring or nullrequirednull for a chore or a break — see
chore, which tells the two apartwhystringrequiredmax length 200chorebooleanwork that serves no tracked goal. A block with no
interestand nochoreis a break: not work, and never a to-do item. Send it onPUT /v1/plans/{date}for work with no goal, or the block is stored as a break
laidarray of objectthe blocks the user laid out themselves, held at their hours through a rebuild
pushbackarray of objectwhere Sereo would change one of the user's own blocks, and why. Advice only: the block stays
2 fields
taskstringrequiredreasonstringrequired
outside_hoursarray of objecton a day the user laid out: the work blocks running outside the hours they keep, kept and named
4 fields
taskstringrequiredstartstringrequiredendstringrequiredsidestringrequiredone of"before","after"
most_importantstringrequiredcoach_notestringrequiredgenerated_atstringenergyinteger or nullmin 1 · max 5energy_statedbooleantrue when the user chose
energy; false when the profile default was used. Only treat a stated energy as the user's report, e.g. in chartsrecoverybooleanrecovery_gapinteger or nulldays away the day was planned to recover from; a replan of the day keeps it, so a rebuilt recovery day is still one
issuesarray of stringwhat the guards changed, as
kind:subject— e.g. energy_clamped, duration_trimmed, no_room, orphaned_break; week_placed names a session the week asked for that code put on the day, week_held one it did not put on because the goal is on hold or refused today, held_block a stored block removed on a rebuild for the same reasonreleasedarray of objectweek-plan blocks for this day that the planner left off at the user's request:
blockis the week block id,textits text. Only written when the user's own words asked for it4 fields
blockstringrequiredtextstringwhystringrequiredatstring
sourcestringone of"user","scheduler"accepted_atstringpresent once accepted; also counts as the user showing up for gap detection
on_holdarray of string
recovery_gapinteger or nullacceptedbooleanalways false: a generated plan is a proposal until accepted
rebuildobject or null
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/generate \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Stream plan-build progress events
Any token · read only is enoughOpens a text/event-stream of progress events for plan builds on one date, for the authenticated account only. Each event is a data: line holding JSON {type: "plan_stage", day, stage, ...}, where stage is one of thinking, asking, drafted, placing, placed, checking or stored, with stage-specific counts. Events come from POST /v1/plans/{date}/generate, POST /v1/plans/{date}/replan and other server-side rebuilds of that day. An idle stream sends a : keepalive comment every 20 s.
Events are advisory and describe pipeline stages in the server's words. They are not replayed, so open the stream before starting the build, and they may be dropped if the client reads slowly. The finished plan is always available from the building request or GET /v1/plans/{date}.
The stream does not end when a build finishes; the server closes it after 15 minutes. At most four streams per account stay open; opening a fifth closes the oldest. 400 invalid_request for a malformed date.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/plans/2026-11-12/stream \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Regenerate a day's plan from user feedback
Needs a token that can change thingsRebuilds an existing day plan from the user's note and returns the new plan with changed, stability, moved, previous, accepted, rebuild, understood, proposals, question and week_check.
Pass the user's words verbatim in note; the planner uses the wording. The previous plan is the basis for the rebuild. Blocks the user laid out themselves are held at their times unless fresh: true; other blocks may be changed by the model. Energy carries over from the existing plan unless energy is sent.
The note is parsed before planning. A one-off busy time today (for example, dinner) is added to the day's fixed times, and work at a stated time is held at that time. Lasting changes (a weekly time, a standing rule, the day's hours) are not written: each is returned in proposals and is applied only through POST /v1/lasting when the user agrees. understood reports what was done with each part of the note. If a part needs clarification and the request set ask: true, the response carries question ({text, options}) and scope: "nothing", and nothing is written or rebuilt. Without ask, an unclear part is passed to the planner as part of the note.
Show changed. It is the server's diff of the day before and after: moved, added, removed and kept, each a list of task names. Always show removed by name; stability and moved cannot represent a block that left the day. A block dropped because it did not fit is not in removed; it appears in the plan's issues as no_room: and in unfit.
An accepted day stays accepted and its to-do list is rebuilt (rebuild); an unaccepted day stays a proposal. Only today's plan changes (scope: "today"). When a note was sent and the day no longer holds week-plan work assigned to it, a background re-read of the week may start (week_check).
Invokes the planner model: once to parse a non-empty note and once to rebuild, so expect tens of seconds. Errors: 404 not_found when the date has no plan; 400 invalid_request for invalid energy or date; 409 not_onboarded; 403 email_unverified; 402 (checkout_required, subscription_lapsed, or spend_cap_reached when the monthly usage limit is reached); 429 rate_limited; 503 busy.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body optional
notestringthe user's feedback, verbatim
askbooleanthe caller can relay a clarifying
questionto the user. Without it an unclear part is passed to the planner in the noteenergyintegermin 1 · max 5moodstringfreshbooleanstart the day over. Without it, the blocks the user laid out stay at their hours and the day is planned around them; one is changed only when the note names it
Responses
200 OK
scopestringhow far this write reaches: today's plan only, this week, every future day, or nothing at all
one of"today","this week","every future day","nothing"persistedobjectwhat lasts beyond today, by kind; empty lists when nothing lasting changed
5 fields
goalsarray of stringrulesarray of stringsettingsarray of stringjobsarray of stringweekarray of string
week_checkobject or nullwhether the rest of the week is being re-read against the day as it now stands:
started, thedisplacedweek work, or areasonit was not. The proposal lands on the day asask.weekplanobjectrequired16 fields
blocksarray of objectrequired6 fields
startstringrequiredpattern^[0-9]{2}:[0-9]{2}$endstringrequiredpattern^[0-9]{2}:[0-9]{2}$taskstringrequiredmax length 120intereststring or nullrequirednull for a chore or a break — see
chore, which tells the two apartwhystringrequiredmax length 200chorebooleanwork that serves no tracked goal. A block with no
interestand nochoreis a break: not work, and never a to-do item. Send it onPUT /v1/plans/{date}for work with no goal, or the block is stored as a break
laidarray of objectthe blocks the user laid out themselves, held at their hours through a rebuild
pushbackarray of objectwhere Sereo would change one of the user's own blocks, and why. Advice only: the block stays
2 fields
taskstringrequiredreasonstringrequired
outside_hoursarray of objecton a day the user laid out: the work blocks running outside the hours they keep, kept and named
4 fields
taskstringrequiredstartstringrequiredendstringrequiredsidestringrequiredone of"before","after"
most_importantstringrequiredcoach_notestringrequiredgenerated_atstringenergyinteger or nullmin 1 · max 5energy_statedbooleantrue when the user chose
energy; false when the profile default was used. Only treat a stated energy as the user's report, e.g. in chartsrecoverybooleanrecovery_gapinteger or nulldays away the day was planned to recover from; a replan of the day keeps it, so a rebuilt recovery day is still one
issuesarray of stringwhat the guards changed, as
kind:subject— e.g. energy_clamped, duration_trimmed, no_room, orphaned_break; week_placed names a session the week asked for that code put on the day, week_held one it did not put on because the goal is on hold or refused today, held_block a stored block removed on a rebuild for the same reasonreleasedarray of objectweek-plan blocks for this day that the planner left off at the user's request:
blockis the week block id,textits text. Only written when the user's own words asked for it4 fields
blockstringrequiredtextstringwhystringrequiredatstring
sourcestringone of"user","scheduler"accepted_atstringpresent once accepted; also counts as the user showing up for gap detection
on_holdarray of string
stabilitynumberrequiredshare of the previous plan unchanged; cannot show removals, use
changedmin 0 · max 1movedintegerrequiredlength of
changed.movedmin 0changedobjectrequiredthe server's diff of the day before and after, by task name, over work blocks only (breaks are ignored). A reworded task reads as removed plus added. A block dropped because it did not fit is not in
removed; read it from the plan'sno_room:issues andunfit. Display this rather than any model-written summary.4 fields
movedarray of stringrequiredon the day before and after, at a different hour
addedarray of stringrequiredremovedarray of stringrequiredwas on the day and is not. Never fold this into a count — name them
keptarray of stringrequiredsame task, same hour
previousobject or nullacceptedbooleanrebuildobject or nullquestionobject or nullset when the note needs an answer first; nothing was written or rebuilt
2 fields
textstringoptionsarray of string
understoodarray of objectwhat became of each part of the note
3 fields
kindstringrequiredsaysstringrequiredappliedstringrequired
proposalsarray of objectlasting changes found in the note; not written. Apply one with POST /v1/lasting when the user agrees
10 fields
kindstringrequiredone of"weekly","rule","hours"titlestringdaysarray of integerstartstringendstringtextstringday_startstringday_endstringforstringa habit or goal id: the weekly time is reserved for it, not busy
saysstring
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/replan \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Suggest tasks for an open time slot
Needs a token that can change thingsReturns up to three suggestions for an empty stretch of a day as {picks, mode, note}. Nothing is written.
By default (ask absent or false) no model is invoked and mode is ranked: tracked goals, habits, leisure and chores that are not satisfied, on hold or refused, and whose usual length fits within minutes, ranked by words matching note, then by pressure status (overdue, due, starving, on track), then by days since last scheduled.
With ask: true the model is given the top eight candidates and the stretch's context (neighbouring blocks from day if sent, otherwise the stored plan) and picks those that suit it; mode is reasoned. It may add at most one pick that is not a tracked item, marked registered: false with interest: null. If the model is unavailable or its answer is unusable, the ranked list is returned with mode: "ranked" and note saying why; the call still answers 200. The model call times out after 20 s.
at is the stretch's start (HH:MM) and minutes its length (0 or absent for no limit). Every call, including a ranked one, passes the same access checks as model-invoking routes: 403 email_unverified; 402 (checkout_required, subscription_lapsed, or spend_cap_reached when the monthly usage limit is reached); 429 rate_limited. Also 400 invalid_request for a negative minutes or a non-list day, and 409 not_onboarded.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body optional
atstringHH:MM the stretch begins
minutesintegerhow long it is; 0 for no limit
notestringanything the user said they want there
askbooleanhave the model choose from the ranking; invokes the model once. Absent or false: deterministic ranking, no model call
dayarray of objectthe client's unsaved draft of the day, used only with
askto describe the neighbouring blocks to the model. Never stored6 fields
startstringrequiredpattern^[0-9]{2}:[0-9]{2}$endstringrequiredpattern^[0-9]{2}:[0-9]{2}$taskstringrequiredmax length 120intereststring or nullrequirednull for a chore or a break — see
chore, which tells the two apartwhystringrequiredmax length 200chorebooleanwork that serves no tracked goal. A block with no
interestand nochoreis a break: not work, and never a to-do item. Send it onPUT /v1/plans/{date}for work with no goal, or the block is stored as a break
Responses
200 OK
modestringrequiredhow this answer was arrived at
one of"ranked","reasoned"notestring or nullwhy it is ranked rather than reasoned, when it is
picksarray of objectrequired8 fields
taskstringrequiredintereststring or nullrequirednull when it serves no goal, which only an off-list pick does
registeredbooleanrequiredtrue for a tracked interest; false for the single off-list pick a reasoned answer may add
kindstringtagstringnodestring or nullminutesintegerrequiredwhystringrequired
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/suggest \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Discuss a draft day with the planner
Needs a token that can change thingsSends a conversation about a draft day to the planner model and returns its reply, plus a revised block list when the model proposes a change. Stateless: the client sends the transcript (messages) and the editor's working copy (blocks) on every turn, and the stored plan is not modified. To keep a revision, save it with PUT /v1/plans/{date}.
The model returns only tasks, durations and order; the server times the revision against the day's free time and runs the same guards as plan generation. A block the model omits is kept unchanged; removal must be explicit. anchor limits the revision to one block and pins holds blocks at their times; edits refused by these guards are reported in issues. blocks is null when the day stands. changes is computed by the server by diffing the submitted and returned blocks, and reply is filtered so it cannot claim a change that changes does not show.
Invokes the planner model (fast tier) synchronously, with at most one corrective retry; timeout 60 s per call. A diagnostic trace of the exchange is kept server-side for 30 days; no plan data is written.
Errors: 400 when blocks is not a list or the last message is not the user's; 409 not_onboarded; 403 email_unverified; 402 subscription_lapsed or spend_cap_reached (monthly usage limit reached); 429 rate_limited.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body required
messagesarray of objectrequiredThe client-held transcript, oldest first; the last entry must have
who: "user". Only the last 12 entries are used, each truncated to 1000 characters; anywhoother thanuseris treated as the planner.2 fields
whostringone of"user","planner"textstring
blocksarray of objectrequiredthe editor's working copy
6 fields
startstringrequiredpattern^[0-9]{2}:[0-9]{2}$endstringrequiredpattern^[0-9]{2}:[0-9]{2}$taskstringrequiredmax length 120intereststring or nullrequirednull for a chore or a break — see
chore, which tells the two apartwhystringrequiredmax length 200chorebooleanwork that serves no tracked goal. A block with no
interestand nochoreis a break: not work, and never a to-do item. Send it onPUT /v1/plans/{date}for work with no goal, or the block is stored as a break
anchorobject or nullRestricts the revision to one block, matched on
taskandstart. Changes the model makes to any other block are discarded and reported inissuesasoutside_anchor:<task>.2 fields
startstringtaskstring
pinsarray of stringTask names whose start and end are held. The model cannot move, resize or remove a pinned block; a requested removal is refused and reported in
issuesaspinned_block_kept:<task>.proposebooleanWhen true, the model is instructed to return a revised block list this turn.
Responses
200 OK
replystringrequiredblocksarray or nullthe working copy's replacement, or null when the day stands
6 fields
startstringrequiredpattern^[0-9]{2}:[0-9]{2}$endstringrequiredpattern^[0-9]{2}:[0-9]{2}$taskstringrequiredmax length 120intereststring or nullrequirednull for a chore or a break — see
chore, which tells the two apartwhystringrequiredmax length 200chorebooleanwork that serves no tracked goal. A block with no
interestand nochoreis a break: not work, and never a to-do item. Send it onPUT /v1/plans/{date}for work with no goal, or the block is stored as a break
changesarray of objectPer-block differences between the submitted
blocksand the returned ones, computed by the server (never the model's own account).callisadded,removed,moved(start changed, possibly also length) orresized(same start, different length);was/nowcarry{start, end}.5 fields
callstringone of"added","removed","moved","resized"taskstringwasobject or nullnowobject or nullnotestring
issuesarray of string
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
403 The account's email address is not confirmed (email_unverified), or a read-only token called a non-GET route (read_only_token)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/discuss \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
Send a message about a day
Needs a token that can change thingsInterprets a free-text message about a day, acts on it, and returns the server's account of what happened: did, the answer to display, and changed. The model classifies the message; any resulting write goes through the same code paths as the dedicated endpoints, and did, changed, scope and persisted describe what was actually written, never the model's account of it.
did values:
answered— explained only; nothing written. Also returned when the words did not name a valid target for the act the model chose. -changed— the day's stored plan was edited (or rebuilt when a targeted edit made no change) and saved.changedholdsmoved/added/removed/kept,planthe new plan,accepted/rebuildthe re-acceptance of an already accepted day's to-do list,unfitblocks that no longer fit, andpushbackobjections to the user's own blocks. Other days are not touched. -escalated— the message concerns other days. A background re-read of the week starts and the response returns at once withworking: true; the resulting proposal appears onGET /v1/day/{date}underaskand is applied only byPOST /v1/weeks/{week}/amendor by a later message accepting it. On a day with no stored plan, a change request is escalated. -week_changed— the message accepted a week proposal pending from an earlier escalation on this day, and it was applied.changed.weeknames the weekdays;today_affectedis true when today's plan predates the change. -finished— a job was marked done, or a milestone step named in the words. Goals and habits are never marked finished this way; the answer says how they finish. -held— a goal, job or habit was paused (until a date or indefinitely) or resumed. If the week plan still relies on it, a week re-read starts andworkingis true. -adjusted— goal fields were changed. -ruled/unruled— a standing rule was added in the user's words, or removed. -hours_changed— the day window or the recurring unavailable hours changed (changed.hours). -goal_added— a goal was created with checkpoints and steps. -job_removed— a job was removed, restorable for at least 30 days (changed.removed). -reranked— goal priority or areas were reordered.
When a message also asks for today to be rearranged, the day edit runs in the same request and its result is merged into changed; did keeps the primary act.
Send earlier turns in messages ({who: "user"|"planner", text}; the last 12 are used, each truncated to 1000 characters) so a confirmation reaches the offer it answers. question is truncated to 1000 characters.
drift lists premises of the week's stored reasoning that have changed since it was written, and stale the days that rely on them; that reasoning is not presented as current.
Week re-reads are limited to 6 per account per day. Past the limit, ceiling_reached is true and the answer says the week could not be re-checked. If a re-read for the day is already running, no second one starts and working is true.
Invokes the planner model (fast tier, 60 s timeout per call); a changed result adds a day-edit call, and an escalation a background call on the week model. The answer text is filtered server-side to remove claims of changes the server did not make and specific clock times.
Errors: 400 for an empty question or invalid date; 409 not_onboarded (no profile or no anchor date); 409 ask_in_progress when a hold needs a week re-read while one is already running; 403 email_unverified; 402 subscription_lapsed or spend_cap_reached (monthly usage limit reached); 429 rate_limited.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body required
questionstringrequiredmessagesarray of object
Responses
200 OK
scopestringhow far this write reaches: today's plan only, this week, every future day, or nothing at all
one of"today","this week","every future day","nothing"persistedobjectwhat lasts beyond today, by kind; empty lists when nothing lasting changed
5 fields
goalsarray of stringrulesarray of stringsettingsarray of stringjobsarray of stringweekarray of string
answerstringrequiredpushbackarray of objectThe user's own blocks the planner would have changed, each with its reason. These blocks are left as they are.
2 fields
taskstringrequiredreasonstringrequired
didstringrequiredone of"answered","changed","escalated","finished","held","ruled","adjusted","week_changed","unruled","hours_changed","reranked","goal_added","job_removed"overridebooleanTrue when the user's words were read as an explicit override of the planner's objection: the request was carried out and no
pushbackis returned.today_affectedbooleanescalatedbooleanrequiredworkingbooleanA background week re-read is running for this day. Poll
GET /v1/day/{date}: itsaskfield carries the steps and, when finished, the proposed week change.ceiling_reachedbooleanchangedobjectplanobjectacceptedbooleanrebuildobject or nulldriftarray of objectstalearray of stringendingstringunfitarray of object6 fields
taskstringrequiredgoalstring or nullminutesinteger or nullaskedbooleanwhystringrequiredoffersarray of object8 fields
kindstringrequiredone of"move","drop_habit"textstringrequiredtostringday_labelstringeffortstringfree_minutesintegertaskstringintereststring or null
weekobject4 fields
answerstringrequiredreasoningstringamendmentobject or nullrequiredthe proposed days,
{days: {date: entry}}, in the week plan's own shape; null when the week would standrefusedarray of object
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
403 The account's email address is not confirmed (email_unverified), or a read-only token called a non-GET route (read_only_token)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
429 Too many attempts; wait and retry — retry-after says how long
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/escalate \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"question": "…"}'
Send a message to the account conversation
Needs a token that can change thingsSame as POST /v1/plans/{date}/escalate, anchored on date (default: the account's current day), with the text in message. Covers today, the week, goals, standing rules and hours: the server interprets the message, performs any resulting write, and reports it in did, changed, scope and persisted. Response shape, side effects, limits and errors are those of the escalate endpoint.
The planner may object to a request; a message that explicitly overrides the objection is carried out and the response sets override: true. Pass earlier turns in messages so a confirmation reaches the offer it answers. question is accepted as an alias for message.
Invokes the planner model.
Request body required
messagestringrequireddatestringmessagesarray of object
Responses
200 OK
scopestringhow far this write reaches: today's plan only, this week, every future day, or nothing at all
one of"today","this week","every future day","nothing"persistedobjectwhat lasts beyond today, by kind; empty lists when nothing lasting changed
5 fields
goalsarray of stringrulesarray of stringsettingsarray of stringjobsarray of stringweekarray of string
answerstringrequiredpushbackarray of objectThe user's own blocks the planner would have changed, each with its reason. These blocks are left as they are.
2 fields
taskstringrequiredreasonstringrequired
didstringrequiredone of"answered","changed","escalated","finished","held","ruled","adjusted","week_changed","unruled","hours_changed","reranked","goal_added","job_removed"overridebooleanTrue when the user's words were read as an explicit override of the planner's objection: the request was carried out and no
pushbackis returned.today_affectedbooleanescalatedbooleanrequiredworkingbooleanA background week re-read is running for this day. Poll
GET /v1/day/{date}: itsaskfield carries the steps and, when finished, the proposed week change.ceiling_reachedbooleanchangedobjectplanobjectacceptedbooleanrebuildobject or nulldriftarray of objectstalearray of stringendingstringunfitarray of object6 fields
taskstringrequiredgoalstring or nullminutesinteger or nullaskedbooleanwhystringrequiredoffersarray of object8 fields
kindstringrequiredone of"move","drop_habit"textstringrequiredtostringday_labelstringeffortstringfree_minutesintegertaskstringintereststring or null
weekobject4 fields
answerstringrequiredreasoningstringamendmentobject or nullrequiredthe proposed days,
{days: {date: entry}}, in the week plan's own shape; null when the week would standrefusedarray of object
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
403 The account's email address is not confirmed (email_unverified), or a read-only token called a non-GET route (read_only_token)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
429 Too many attempts; wait and retry — retry-after says how long
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/conversation \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": "…"}'
Resolve a block that did not fit the day
Needs a token that can change thingsApplies one of the server-computed remedies for a block in the day's unfit list and returns the updated day view (the same body as GET /v1/day/{date}). task must equal an unfit entry's task; choice selects one of that entry's offers by kind. The client does not choose the target day or habit.
move— adds the block to the later day of the current cadence week given in the offer'sto, through the week-amendment writer, and removes the entry from today'sunfit. No model call. -drop_habit— rebuilds today without the habit named in the offer (task/interest) so the block can be placed. Invokes the planner model.
Errors: 400 for an invalid choice; 400 bad_amendment when the week plan rejects the move; 409 nothing_unfit when the block is not, or no longer, unfit on that day; 409 offer_unavailable when that remedy is not offered for the block; 409 not_onboarded; 403 email_unverified; 402 subscription_lapsed or spend_cap_reached (monthly usage limit reached); 429 rate_limited (checked for both choices).
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body required
taskstringrequiredchoicestringrequiredone of"move","drop_habit"
Responses
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
403 The account's email address is not confirmed (email_unverified), or a read-only token called a non-GET route (read_only_token)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/unfit \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"task": "…", "choice": "move"}'
Dismiss a pending week proposal for a day
Needs a token that can change thingsDismisses the week change proposed by the latest week re-read for this day, so GET /v1/day/{date} no longer returns it in ask.week. The week plan is not changed. Returns {left: true, scope: "nothing", persisted: {}}.
Idempotent: succeeds when there is no proposal. The dismissal is held in server memory with the re-read itself, not in the user's stored data. No model call.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
200 OK
leftbooleanrequiredscopestringpersistedobject
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/week-proposal/leave \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Replace a day's fixed busy times
Needs a token that can change thingsReplaces the fixed busy times for one date (for example dinner, working hours, a pickup) and returns the list as stored. Each entry needs start and end as HH:MM with start before end, and a non-empty title (truncated to 80 characters; task is accepted as an alias). Entries are sorted by start. [] clears the date.
Fixed times are stored on the profile and treated as busy time: placement plans around them and never moves them. Blocks already on the day's plan are not re-placed; replan the day to apply them. Entries for dates more than 31 days before date are pruned on write. No model call. The response also carries scope (today) and persisted.
Errors: 400 when fixed is not a list or an entry is invalid; 409 not_onboarded.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body required
fixedarray of objectrequired3 fields
startstringrequiredendstringrequiredtitlestringrequired
Responses
200 OK
fixedarray of objectrequired3 fields
startstringrequiredendstringrequiredtitlestringrequired
scopestringhow far this write reaches: today's plan only, this week, every future day, or nothing at all
one of"today","this week","every future day","nothing"persistedobjectwhat lasts beyond today, by kind; empty lists when nothing lasting changed
5 fields
goalsarray of stringrulesarray of stringsettingsarray of stringjobsarray of stringweekarray of string
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X PUT https://app.usesereo.com/v1/plans/2026-11-12/fixed \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
Create a standing rule
Needs a token that can change thingsAdds a standing rule in the user's own words (for example "nothing too late in the evening") to the profile and returns it with 200. The rule is included in the planner prompt for later plan generation, replans, gap suggestions and day discussions; the planner is asked to honour it and to cite it in a block's why when it shaped the choice. A rule is prompt text, not a guaranteed constraint. No model call.
text is stored verbatim, truncated to 300 characters. kind is gate, scheduling (default) or content; applies_to is a list of interest ids or ["all"] (default). The id is user_ followed by 8 hex characters and priority is 2. Remove a rule with DELETE /v1/constraints/{id}.
Errors: 400 for empty text, an unknown kind or an unknown interest id in applies_to; 409 not_onboarded.
Request body required
textstringrequiredmax length 300kindstringdefaults to scheduling
one of"gate","scheduling","content"applies_toarray of stringinterest ids, or ["all"] (the default)
Responses
200 OK
idstringrequiredtextstringrequiredkindstringrequiredpriorityintegerrequiredapplies_toarray of stringrequired
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/constraints \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"text": "…"}'
Save a lasting change proposed by a replan
Needs a token that can change thingsWrites one entry from a replan's proposals (POST /v1/plans/{date}/replan) to the profile; send it unchanged, after the user has confirmed it. By kind:
weekly— a recurring busy window on weekdaysdays(0 = Monday) fromstarttoend(HH:MM, start before end), titledtitle(default "Not available"). Added tohours_off, replacing any window it overlaps on those weekdays. Withfor(a goal or habit id) it is added tofree_by_weekdayinstead, as time reserved for that interest. The response returns the updated map. -rule—textbecomes a standing rule, as withPOST /v1/constraintsandkind: "scheduling"; returned asrule. -hours— setsday_startand/orday_end(HH:MM).
Applies to later plans; existing plans are not rebuilt. kept names the kind written and scope is every future day. No model call.
Errors: 400 for an unknown kind, missing or malformed fields, or an unknown for id; 409 not_onboarded.
Request body required
proposalobjectrequired10 fields
kindstringrequiredone of"weekly","rule","hours"titlestringdaysarray of integerstartstringendstringtextstringday_startstringday_endstringforstringa habit or goal id: the weekly time is reserved for it, not busy
saysstring
Responses
200 OK
keptstringrequiredone of"weekly","rule","hours"hours_offobjectfree_by_weekdayobjectruleobjectday_startstringday_endstringscopestringhow far this write reaches: today's plan only, this week, every future day, or nothing at all
one of"today","this week","every future day","nothing"persistedobjectwhat lasts beyond today, by kind; empty lists when nothing lasting changed
5 fields
goalsarray of stringrulesarray of stringsettingsarray of stringjobsarray of stringweekarray of string
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/lasting \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
Delete a standing rule
Needs a token that can change thingsRemoves the standing rule with id {constraint} from the profile and returns {removed: <id>}. Any rule can be removed, whether the user created it (user_…) or it came from an agreed report proposal (report_…). Later plans no longer include it; existing plans are unchanged. No model call.
Errors: 404 when no rule has that id (including a repeated delete); 409 not_onboarded.
Path parameters
constraintstringrequiredA standing rule's id, from the day's own influences list.
pattern^[a-z0-9_]+$
Responses
200 OK
removedstring
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X DELETE https://app.usesereo.com/v1/constraints/$CONSTRAINT \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Keep a chore the planner suggested
Needs a token that can change thingsTurns a dated chore the planner suggested on a day into a chore on the user's profile. Such blocks appear on GET /v1/day/{date} with a non-null keep ({due, priority}); until this call they exist only on that day. task must equal the block's task text.
The chore is written with origin: "user" and the block's due date, priority and minutes, and is then planned on later days until done like any other chore. If a chore with the same label (case-insensitive) already exists it is left unchanged and kept is null. Either way the offer is cleared from the block, so its keep becomes null and a repeat call returns 404. No model call.
Errors: 400 when task is missing or empty; 404 when the day has no dated chore block with that task; 409 not_onboarded.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body required
taskstringrequiredthe block's task text, exactly as the day carries it
Responses
200 OK
keptstring or nullrequiredThe new chore's interest id; null when a chore with the same label (case-insensitive) already exists or its due date could not be recorded.
taskstringrequired
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/keep \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"task": "…"}'
Set the energy level for a planned day
Needs a token that can change thingsRecords the user's stated energy (integer 1–5) on a day that already has a plan, sets energy_stated: true, and returns {date, energy, energy_stated}. The plan is not rebuilt, nothing else on it changes, and no model call is made. Only days with energy_stated: true are charted as stated energy. Intended for plans the scheduler generated; POST /v1/plans/{date}/generate takes energy directly.
Errors: 400 when energy is not an integer from 1 to 5; 404 when the date has no plan; 409 not_onboarded.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body required
energyintegerrequiredmin 1 · max 5
Responses
200 OK
datestringrequiredenergyintegerrequiredenergy_statedbooleanrequired
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/energy \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"energy": 3}'
Set a day's editing state
Needs a token that can change thingsSets or clears the reshaping flag on a day's stored plan and returns {date, reshaping}. The flag records that the user is editing the day, so any client opening it can resume in the editor; GET /v1/day/{date} returns it as reshaping. Only the flag is stored, not the client's draft. A missing on is treated as false.
The flag is cleared by on: false, by accepting the plan (POST /v1/plans/{date}/accept) and by saving a hand-edited plan (PUT /v1/plans/{date}). No model call.
Errors: 404 when the date has no plan; 409 not_onboarded.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body required
onbooleanrequired
Responses
200 OK
datestringrequiredreshapingbooleanrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/reshape \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"on": true}'
Get a weekly or monthly report
Any token · read only is enoughReturns the report for a period: sections computed from the user's plans, check-ins and to-do lists, plus the prose and proposals if POST /v1/reports/{period}/{date} has written them (written). No model call.
{period} is week or month. For week, {date} is the last day of a cadence week; cadence weeks start on the weekday of the user's signup, not on Monday. A week date that is not a cadence-week ending resolves to the most recent finished cadence week. For month, {date} is the last day of a four-cadence-week block and is used as given.
An unfinished period returns readiness.ready: false with the count it is waiting for (on_record of of) and arrives. To-do items nobody answered count as unanswered, never as skipped, and are excluded from kept_share.
Errors: 400 for an invalid period or date; 409 not_onboarded.
Path parameters
periodstringrequiredweek or month.
pattern^week|month$datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
200 OK
periodstringrequiredone of"week","month"endingstringrequiredfromstringtostringweekintegerISO week number of
endinglabelstringwhat to call this period on a page — named here so a client never has to do ISO week arithmetic and disagree about January. A month is named for the calendar month most of its days fall in, because four cadence weeks from a signup day are not one
spanstring or nullthe weeks a monthly period actually covers, to run under its name; null for a week
issueobjectthe number on the masthead: a week's is its ISO week, a month's is its position among the four-week blocks ending that year
2 fields
nointegeryearinteger
writtenbooleanwhether the prose has been generated yet
readinessobjectrequired5 fields
readybooleanrequiredon_recordintegerrequiredofintegerrequiredunitstringready_onstring or nullthe date this issue can first be written, if the user keeps planning. A horizon, not a promise — but "a pattern needs four weeks" with no date on it reads as never
kept_sharenumber or nullof what was ANSWERED, not of what was planned — null when nothing was answered, because silence is not nought per cent
plannedintegerkeptintegertracksarray of objectrequired23 fields
idstringrequiredlabelstringrequiredinkinteger or nullthe ink this goal wears everywhere
unitstringtotalintegerrequireddoneintegerrequiredeverything behind them
addedintegerwhat this period added
shouldintegerrequiredthe mark this goal's own dates set for now: the bar position where the current milestone begins plus its linear share of its own window, floor-rounded
floorintegerwhat stands whatever the current milestone's date does — the bar position where its window begins
current_blocksintegerthe current milestone's own size; with window_days, what a preview needs to re-run the pacing exactly
window_daysintegerhow long the current milestone's own stretch of the goal runs
statestringthe grade, decided here — the plan first, the date second.
behind_plan: short of what the period's plans prescribed;behind_date: the plan kept but the milestone's own date missed;not_due_yet: nothing asked by either;kept: neither shortfallone of"behind_plan","behind_date","not_due_yet","kept"plan_shortintegerblocks short of the period's plan (prescribed - done), never negative
min 0date_shortintegerblocks short of the date mark, whole-block floored, never negative
min 0date_fixedbooleanthe current milestone's date is not the plan's to move — fixed_reason, an integration's, or adjudicated by somebody else
behindintegerblocks short of the date mark — the bar's gap piece; same number as
date_shortmin 0daysinteger or nullstatusstring or nullmilestonestring or nullmilestone_duestring or nullthe date the pace line answers to
askedintegerblocks this period's plans prescribed for the goal
prescribedintegerthe PLAN line: where the bar would sit had every block the period's plans prescribed landed
pacenumberthe DATE line: the mark's exact position before the grade's whole-block floor — where you must be to make the current milestone on time
energyarray of objectper day of the period: the energy reported and the blocks the day asked for beside what came back, so the two can be read against each other
6 fields
daystringdatestringvalueinteger or nullnull when nobody said
min 1 · max 5hardbooleanthe plan was rebuilt after a gap
plannedintegerkeptinteger
blockedobject3 fields
plannedintegersplitarray of objectcausesarray of objectdays that lost blocks, with what the user wrote on that day's check-in. Refusals only, and nobody's words but theirs
daysarray of objectparkedarray of objectwhat the user put down, with the date it comes back. Named rather than left out: a goal that vanishes from a report reads as forgotten. Nothing here is in
tracks, in any count above, or in front of the model that writes the prose4 fields
idstringlabelstringuntilstring or nullwhystring or null
weekday_profilearray of objectone entry per weekday: blocks on an average Monday, an average Tuesday, across the period
6 fields
daystringplannednumberblocks planned into an average one of these
keptnumberand blocks kept — the page used to derive this from the share
kept_sharenumber or nulllow_daysintegerdaysinteger
goal_hoursarray of objectstreaksarray of objectenergy_outarray of objectarchivearray of objectrequiredThe account's last 32 cadence weeks, ending at the newest finished week (or at the requested
endingif later), each withending, ISOweek,keptshare,had_daysandwritten. Independent of which issue is requested.archive_monthsarray of objectThe same weeks grouped into the four-week blocks monthly reports are written over, aligned to the account's own month grid and ending at the newest finished block; each carries
written.next_issueobject or nullThe next weekly report: its period
endingand thedateandtimeit is due to be written, computed from the account's cadence and the current date, independent of the requestedending. Null when it cannot be computed.3 fields
endingstringdatestringtimestring
latestobjectPer period, the newest
endingthat has a written report, or null. Use it to open the latest issue instead of computing a cadence-week ending.2 fields
weekstring or nullmonthstring or null
arrivesobjectpresent only while a period is unfinished: when it will be written
2 fields
datestringtimestring
headlinestringfindingsarray of objectproposal_introstringproposalsarray of object13 fields
kindstringrequiredone of"Move a date","Protect hours","Do it now","Drop a goal","Schedule less"goalstringgoal_idstring or nulltitlestringrequiredwhystringeffectstringshift_daysintegerpark_daysinteger"Drop a goal" only: how long the goal is parked if agreed, in days, clamped to 14–56.
gain_blocksintegeranswerstring or nullone of"yes","argue","no",nullnotestringappliedobjectpreviewobject or nullWhat agreeing would do, per kind, computed from the same
tracksthe report returns. Only a "Move a date" preview carries mark positions (should,done,total, ...); for other kindslinedescribes the effect.14 fields
goal_idstring or nulllabelstring or nulleffect_kindstring or nullone of"move","park","free","protect","now",nulllinestring or nullThe preview sentence, written server-side.
shouldnumberMove only: the expected-by-now mark if agreed, unrounded.every realistic shift)
should_nownumbermove only: the mark as it stands, exact
donenumberdone_nownumbertotalnumbernew_duestring or nullmove only: where the current milestone's date would land
still_latebooleanmove only: the shifted date is still behind you
park_untilstringpark only
park_weeksintegerpark only
freedintegerfree only: blocks a week bought back
generated_atstring
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/reports/week/2026-11-12 \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Generate a report's prose and proposals
Needs a token that can change thingsGenerates the prose (headline, findings) and proposals for a finished period, stores them, and returns the full report in the same shape as GET /v1/reports/{period}/{date}. Path parameters resolve as in that endpoint.
Invokes the report model once, synchronously. If the period is not finished (readiness.ready: false), nothing is generated and the unwritten report is returned; there is no override. If a report already exists, it is returned unchanged, so repeat calls are idempotent. Before storing, proposals the system cannot apply or that the user refused for good are dropped, and prose contradicted by the period's data is removed. Answers already given to proposals with the same title are carried over.
Errors: 400 for an invalid period or date; 409 not_onboarded; 403 email_unverified; 402 subscription_lapsed or spend_cap_reached (monthly usage limit reached); 429 rate_limited. The usage checks run before the readiness and existing-report checks, so they can fail even when no model call would be made.
Path parameters
periodstringrequiredweek or month.
pattern^week|month$datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
200 OK
periodstringrequiredone of"week","month"endingstringrequiredfromstringtostringweekintegerISO week number of
endinglabelstringwhat to call this period on a page — named here so a client never has to do ISO week arithmetic and disagree about January. A month is named for the calendar month most of its days fall in, because four cadence weeks from a signup day are not one
spanstring or nullthe weeks a monthly period actually covers, to run under its name; null for a week
issueobjectthe number on the masthead: a week's is its ISO week, a month's is its position among the four-week blocks ending that year
2 fields
nointegeryearinteger
writtenbooleanwhether the prose has been generated yet
readinessobjectrequired5 fields
readybooleanrequiredon_recordintegerrequiredofintegerrequiredunitstringready_onstring or nullthe date this issue can first be written, if the user keeps planning. A horizon, not a promise — but "a pattern needs four weeks" with no date on it reads as never
kept_sharenumber or nullof what was ANSWERED, not of what was planned — null when nothing was answered, because silence is not nought per cent
plannedintegerkeptintegertracksarray of objectrequired23 fields
idstringrequiredlabelstringrequiredinkinteger or nullthe ink this goal wears everywhere
unitstringtotalintegerrequireddoneintegerrequiredeverything behind them
addedintegerwhat this period added
shouldintegerrequiredthe mark this goal's own dates set for now: the bar position where the current milestone begins plus its linear share of its own window, floor-rounded
floorintegerwhat stands whatever the current milestone's date does — the bar position where its window begins
current_blocksintegerthe current milestone's own size; with window_days, what a preview needs to re-run the pacing exactly
window_daysintegerhow long the current milestone's own stretch of the goal runs
statestringthe grade, decided here — the plan first, the date second.
behind_plan: short of what the period's plans prescribed;behind_date: the plan kept but the milestone's own date missed;not_due_yet: nothing asked by either;kept: neither shortfallone of"behind_plan","behind_date","not_due_yet","kept"plan_shortintegerblocks short of the period's plan (prescribed - done), never negative
min 0date_shortintegerblocks short of the date mark, whole-block floored, never negative
min 0date_fixedbooleanthe current milestone's date is not the plan's to move — fixed_reason, an integration's, or adjudicated by somebody else
behindintegerblocks short of the date mark — the bar's gap piece; same number as
date_shortmin 0daysinteger or nullstatusstring or nullmilestonestring or nullmilestone_duestring or nullthe date the pace line answers to
askedintegerblocks this period's plans prescribed for the goal
prescribedintegerthe PLAN line: where the bar would sit had every block the period's plans prescribed landed
pacenumberthe DATE line: the mark's exact position before the grade's whole-block floor — where you must be to make the current milestone on time
energyarray of objectper day of the period: the energy reported and the blocks the day asked for beside what came back, so the two can be read against each other
6 fields
daystringdatestringvalueinteger or nullnull when nobody said
min 1 · max 5hardbooleanthe plan was rebuilt after a gap
plannedintegerkeptinteger
blockedobject3 fields
plannedintegersplitarray of objectcausesarray of objectdays that lost blocks, with what the user wrote on that day's check-in. Refusals only, and nobody's words but theirs
daysarray of objectparkedarray of objectwhat the user put down, with the date it comes back. Named rather than left out: a goal that vanishes from a report reads as forgotten. Nothing here is in
tracks, in any count above, or in front of the model that writes the prose4 fields
idstringlabelstringuntilstring or nullwhystring or null
weekday_profilearray of objectone entry per weekday: blocks on an average Monday, an average Tuesday, across the period
6 fields
daystringplannednumberblocks planned into an average one of these
keptnumberand blocks kept — the page used to derive this from the share
kept_sharenumber or nulllow_daysintegerdaysinteger
goal_hoursarray of objectstreaksarray of objectenergy_outarray of objectarchivearray of objectrequiredThe account's last 32 cadence weeks, ending at the newest finished week (or at the requested
endingif later), each withending, ISOweek,keptshare,had_daysandwritten. Independent of which issue is requested.archive_monthsarray of objectThe same weeks grouped into the four-week blocks monthly reports are written over, aligned to the account's own month grid and ending at the newest finished block; each carries
written.next_issueobject or nullThe next weekly report: its period
endingand thedateandtimeit is due to be written, computed from the account's cadence and the current date, independent of the requestedending. Null when it cannot be computed.3 fields
endingstringdatestringtimestring
latestobjectPer period, the newest
endingthat has a written report, or null. Use it to open the latest issue instead of computing a cadence-week ending.2 fields
weekstring or nullmonthstring or null
arrivesobjectpresent only while a period is unfinished: when it will be written
2 fields
datestringtimestring
headlinestringfindingsarray of objectproposal_introstringproposalsarray of object13 fields
kindstringrequiredone of"Move a date","Protect hours","Do it now","Drop a goal","Schedule less"goalstringgoal_idstring or nulltitlestringrequiredwhystringeffectstringshift_daysintegerpark_daysinteger"Drop a goal" only: how long the goal is parked if agreed, in days, clamped to 14–56.
gain_blocksintegeranswerstring or nullone of"yes","argue","no",nullnotestringappliedobjectpreviewobject or nullWhat agreeing would do, per kind, computed from the same
tracksthe report returns. Only a "Move a date" preview carries mark positions (should,done,total, ...); for other kindslinedescribes the effect.14 fields
goal_idstring or nulllabelstring or nulleffect_kindstring or nullone of"move","park","free","protect","now",nulllinestring or nullThe preview sentence, written server-side.
shouldnumberMove only: the expected-by-now mark if agreed, unrounded.every realistic shift)
should_nownumbermove only: the mark as it stands, exact
donenumberdone_nownumbertotalnumbernew_duestring or nullmove only: where the current milestone's date would land
still_latebooleanmove only: the shifted date is still behind you
park_untilstringpark only
park_weeksintegerpark only
freedintegerfree only: blocks a week bought back
generated_atstring
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/reports/week/2026-11-12 \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Mark a report as read
Needs a token that can change thingsSets read_at on the period's written report, which clears it from unread_report in GET /v1/status, and returns {seen: true}. Path parameters resolve as in GET /v1/reports/{period}/{date}.
Idempotent: an already-read report keeps its first read_at, and a period with no written report is a no-op that still returns 200. Allowed while a subscription has lapsed. No model call.
Errors: 400 for an invalid period or date; 409 not_onboarded.
Path parameters
periodstringrequiredweek or month.
pattern^week|month$datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
200 OK
seenboolean
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/reports/week/2026-11-12/seen \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Discuss a report proposal with the model
Needs a token that can change thingsSends a conversation about one proposal in a written report to the model and returns its reply. {index} is the proposal's zero-based position in the report's proposals. Stateless: send the full transcript in messages ({who, text}; the last 12 are used, each truncated to 1000 characters; the last must be the user's).
Nothing is stored and the proposal's state does not change; answer it with POST /v1/reports/{period}/{date}/proposals/{index}, where an argue answer's note is the durable record of an objection.
Invokes the planner model (fast tier) synchronously; timeout 60 s. Unlike the other report routes, a week {date} is not resolved to a cadence-week ending, so pass the report's exact ending.
Errors: 400 for an invalid period or date, or when the last message is not the user's; 404 when the report has no proposal at that index; 409 not_onboarded; 403 email_unverified; 402 subscription_lapsed or spend_cap_reached (monthly usage limit reached); 429 rate_limited.
Path parameters
periodstringrequiredweek or month.
pattern^week|month$datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$indexstringrequiredWhich proposal, counting from zero.
pattern^[0-9]{1,2}$
Request body required
messagesarray of objectrequired2 fields
whostringtextstring
Responses
200 OK
replystringrequired
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
403 The account's email address is not confirmed (email_unverified), or a read-only token called a non-GET route (read_only_token)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/reports/week/2026-11-12/proposals/0/discuss \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
Answer a report proposal
Needs a token that can change thingsRecords the user's answer to the proposal at zero-based {index} in the report's proposals and, for yes, applies it. Returns the updated proposal, applied (what changed, or null) and refused. Path parameters resolve as in GET /v1/reports/{period}/{date}. No model call.
answer: "yes" applies the proposal by kind:
Move a date— shifts the goal's milestone dates byshift_days. Milestones with a fixed date or owned by an integration are not moved and are named inapplied.held_names. -Protect hours— adds a standing rule (kind: "scheduling") from the proposal's title, with clock times clamped to the user's day window. -Schedule less— adds a standing rule withkind: "gate". -Drop a goal— parks the goal untilpark_daysafter the period's end. -Do it now— changes nothing.
argue records the answer and optional note and leaves the proposal open. no records the answer; with for_good: true it also records a permanent refusal that later reports, the planner and the goal architect honour. Titles of proposals answered no or argue are given to the next report's prompt as not to be proposed again.
yes and no are final: answering again returns 409 already_answered, except that a no may be repeated once with for_good: true. After argue, any answer is accepted.
Errors: 400 for an invalid answer or for_good without no; 404 when there is no proposal at that index; 409 already_answered; 409 github_owned when a date move conflicts with an integration-owned milestone; 409 not_onboarded.
Path parameters
periodstringrequiredweek or month.
pattern^week|month$datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$indexstringrequiredWhich proposal, counting from zero.
pattern^[0-9]{1,2}$
Request body required
answerstringrequiredone of"yes","argue","no"for_goodbooleanOnly valid with
answer: "no"(400 otherwise). Records a permanent refusal in the user's refusal record, keyed on the proposal's title and on its kind and goal; later reports drop a matching proposal in code, and the planner and goal architect honour the refusal too.notestring
Responses
200 OK
proposalobjectrequired13 fields
kindstringrequiredone of"Move a date","Protect hours","Do it now","Drop a goal","Schedule less"goalstringgoal_idstring or nulltitlestringrequiredwhystringeffectstringshift_daysintegerpark_daysinteger"Drop a goal" only: how long the goal is parked if agreed, in days, clamped to 14–56.
gain_blocksintegeranswerstring or nullone of"yes","argue","no",nullnotestringappliedobjectpreviewobject or nullWhat agreeing would do, per kind, computed from the same
tracksthe report returns. Only a "Move a date" preview carries mark positions (should,done,total, ...); for other kindslinedescribes the effect.14 fields
goal_idstring or nulllabelstring or nulleffect_kindstring or nullone of"move","park","free","protect","now",nulllinestring or nullThe preview sentence, written server-side.
shouldnumberMove only: the expected-by-now mark if agreed, unrounded.every realistic shift)
should_nownumbermove only: the mark as it stands, exact
donenumberdone_nownumbertotalnumbernew_duestring or nullmove only: where the current milestone's date would land
still_latebooleanmove only: the shifted date is still behind you
park_untilstringpark only
park_weeksintegerpark only
freedintegerfree only: blocks a week bought back
appliedobject or nullrefusedbooleanwhether this answer was recorded as a refusal for good
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/reports/week/2026-11-12/proposals/0 \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"answer": "yes"}'
To-dos
Accepting a day's plan as a to-do list, and recording completion against it.
Accept a day's plan
Needs a token that can change thingsAccepts the plan for date and builds its to-do list. Returns the list as todos (the same shape as GET /v1/todos), a rebuild report and a todoist push result.
One item is created per work block: a block with an interest or a chore flag. Breaks and meals are not items. Blocks with the same interest and title collapse into one item.
Accepting sets the plan's accepted_at (on first acceptance only) and ends any in-progress edit of the day (reshaping). accepted_at counts as user activity for gap detection, so an accepted day never triggers a recovery plan. Once a day is accepted its to-do list is the only writer of its check-in record, and POST /v1/plans/{date}/checkin refuses it with 409 accepted_use_todos.
Idempotent, and safe to repeat after the plan changes. The list is rebuilt from the current plan; items already answered (done or skipped) keep their id, status and comments, matched by interest and title, or by interest alone when a block was only renamed. An answered item whose block has left the plan is kept at the end of the list with off_plan: true and named in rebuild.kept_off_plan; answers are never discarded, and rebuild.dropped is always empty. rebuild.carried_over names the items whose answers were carried.
When Todoist is enabled on the deployment and connected, the items are pushed to it; an unreachable Todoist queues the write and never fails the request. todoist.source reports the outcome (not-connected otherwise).
Errors: 404 when there is no plan for date; 400 for a malformed date. No model call.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
200 OK
todosobjectrequired10 fields
datestringrequiredaccepted_atstring or nullacceptedbooleanread_onlybooleanrequiredtrue when Todoist owns completion for this account. The status and comment routes then refuse with
todoist_owns_status, so a client must not offer those controls. Read it here rather than inferring it from /v1/todoist/status — this is the same condition the write routes enforce.itemsarray of objectrequired12 fields
idstringrequiredpattern^t_[a-f0-9]+$startstring or nullendstring or nulltitlestringrequiredwhystringintereststringrequiredstatusstringrequiredthe stored status. Display
derived_statusinsteadone of"open","done","skipped"derived_statusstringwhat to display.
unreconciledmeans still open and the day has passed — the user never answered. It is NOT a miss and must not be shown as one.one of"open","done","skipped","unreconciled"done_atstring or nulloff_planbooleantrue for an answered item whose block is no longer in the plan; kept so the answer is not lost
commentsarray of object3 fields
tsstringtextstringexternal_idstring
todoistobject
openintegerrequireddoneintegerrequiredskippedintegerrequiredunreconciledintegerrequiredpending_reconciliationarray of objectpast days within the last two days that still have stored-
openitems2 fields
datestringcountinteger
rebuildobjectrequired4 fields
carried_overarray of anykept_off_planarray of anytitles of answered items no longer in the plan, kept with
off_plan: truedroppedarray of anyalways empty; answered items are never dropped
rebuilt_atstring
todoistobject
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/accept \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Record a check-in by block number
Needs a token that can change thingsWrites the day's check-in record from 1-based block numbers in the plan, and returns the record.
done and skipped are strings of comma-separated block numbers (e.g. "1,3"), not arrays. The record is replaced wholesale: done_tasks and skipped_tasks take the blocks' task titles, and done_interests the interest of each done block. Jobs ticked off the jobs list for that day are folded into the record. This record is what pressure, milestone progress and gap detection read.
Applies only to a plan that has not been accepted. An accepted day's record is owned by its to-do list (POST /v1/todos/{todo}/status), and this route answers 409 accepted_use_todos rather than overwrite it.
Errors: 400 for a block number that is not an integer or is out of range, or a malformed date; 404 when there is no plan for date; 409 accepted_use_todos. No model call.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Request body optional
donestringcomma-separated 1-based block numbers as a string, e.g. "1,3"
skippedstringcomma-separated 1-based block numbers, as for
donenotestring
Responses
200 OK
done_tasksarray of stringskipped_tasksarray of stringunreconciled_tasksarray of stringtitles of items still
openmore than two days after their day. Never included inskipped_tasks: an unanswered item is not a missdone_interestsarray of stringduplicates are meaningful: membership credits a habit's weekly cadence once, while each occurrence credits one block of a project's milestone
notestring or nulltsstringsourcestringtodoswhen rebuilt from an accepted to-do list; absent on a block-number check-in
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/checkin \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Get a day's to-do list
Any token · read only is enoughReturns the to-do list for date (default: today in the user's timezone), with counts by status and the recent days still awaiting reconciliation.
A day that was never accepted returns an empty items list with accepted: false, not 404.
Each item has a stored status (open, done, skipped) and a derived_status for display. derived_status is unreconciled when the item is still open and its day is more than two days before today. unreconciled means the user never answered; it is not a miss and must not be shown as one. The open/done/skipped/unreconciled counts are computed from derived_status.
pending_reconciliation lists past days within the last two days that still have stored-open items, as {date, count}. read_only is true when Todoist owns completion for the account; the status and comment routes then refuse writes.
Errors: 400 for a malformed date.
Query parameters
datestringThe day, YYYY-MM-DD. Defaults to today.
Responses
200 OK
datestringrequiredaccepted_atstring or nullacceptedbooleanread_onlybooleanrequiredtrue when Todoist owns completion for this account. The status and comment routes then refuse with
todoist_owns_status, so a client must not offer those controls. Read it here rather than inferring it from /v1/todoist/status — this is the same condition the write routes enforce.itemsarray of objectrequired12 fields
idstringrequiredpattern^t_[a-f0-9]+$startstring or nullendstring or nulltitlestringrequiredwhystringintereststringrequiredstatusstringrequiredthe stored status. Display
derived_statusinsteadone of"open","done","skipped"derived_statusstringwhat to display.
unreconciledmeans still open and the day has passed — the user never answered. It is NOT a miss and must not be shown as one.one of"open","done","skipped","unreconciled"done_atstring or nulloff_planbooleantrue for an answered item whose block is no longer in the plan; kept so the answer is not lost
commentsarray of object3 fields
tsstringtextstringexternal_idstring
todoistobject
openintegerrequireddoneintegerrequiredskippedintegerrequiredunreconciledintegerrequiredpending_reconciliationarray of objectpast days within the last two days that still have stored-
openitems2 fields
datestringcountinteger
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/todos \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Set a to-do's status
Needs a token that can change thingsSets one item's status to open, done or skipped and returns the updated item as stored (without derived_status).
The day is taken from date in the body or query string, default today. Any accepted day can be edited, including past days.
skipped records that the user said the work did not happen; an item left open makes no such claim. done sets done_at to the current time (repeating it refreshes the timestamp); any other status clears it.
Side effects: the day's check-in record is rebuilt wholesale from the list, so this is how completion is recorded for an accepted day; it is what pressure, milestone progress and gap detection read. The status is also mirrored to the matching task on the goal (matched by interest and title): done marks it done, open or skipped marks it to-do. The mirror is best-effort and never completes a milestone.
Errors: 400 for a missing or invalid status or malformed date; 404 when the day has no accepted plan or the item id is not on it; 409 todoist_owns_status when Todoist is connected and owns completion (change the status in Todoist; it syncs back). No model call.
Path parameters
todostringrequiredA to-do id from GET /v1/todos.
pattern^t_[a-f0-9]{6,32}$
Request body required
statusstringrequiredone of"open","done","skipped"datestring
Responses
200 OK
idstringrequiredpattern^t_[a-f0-9]+$startstring or nullendstring or nulltitlestringrequiredwhystringintereststringrequiredstatusstringrequiredthe stored status. Display
derived_statusinsteadone of"open","done","skipped"derived_statusstringwhat to display.
unreconciledmeans still open and the day has passed — the user never answered. It is NOT a miss and must not be shown as one.one of"open","done","skipped","unreconciled"done_atstring or nulloff_planbooleantrue for an answered item whose block is no longer in the plan; kept so the answer is not lost
commentsarray of object3 fields
tsstringtextstringexternal_idstring
todoistobject
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/todos/$TODO/status \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status": "done"}'
Add a comment to a to-do
Needs a token that can change thingsAppends a comment to one item and returns the comment (ts, text) with status 201.
The day is taken from date in the body or query string, default today. text is trimmed and truncated to 2,000 characters. Comments are append-only: there is no edit or delete. A comment does not change the item's status or the check-in record.
Errors: 400 when text is missing or blank; 404 when the day has no accepted plan or the item id is not on it; 409 todoist_owns_status when Todoist is connected. No model call.
Path parameters
todostringrequiredA to-do id from GET /v1/todos.
pattern^t_[a-f0-9]{6,32}$
Request body required
textstringrequireddatestring
Responses
201 Created
tsstringrequiredtextstringrequiredexternal_idstring
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/todos/$TODO/comments \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"text": "…"}'
Goals
The profile and goals: interests, milestones and tasks, the year view, and import/export.
Get the profile
Any token · read only is enoughReturns the stored profile: interests, constraints, the weekly busy pattern (calendar_by_weekday), availability settings, scheduled-job times and anchor_date. Answers for an account with no goals yet; interests is then an empty array.
Four fields are computed on read and are never written back:
day_window— the hours in force,{start, end, start_from, end_from, wraps}; each*_fromisstated,sleepordefault. Read this rather thanday_start/day_end, which are absent when the window followssleep. -never— the unavailable hours as[{label, start, end, days}]rows, the shapePATCH /v1/profileaccepts. With nosleepstated, the edges of the day window in force (defaults included) appear as rows. -never_stated— whether any ofsleep,day_start,day_endorhours_offis set. -never_suggested— a default sleep row for a first-run form.
For interests with derived state, use GET /v1/library.
Responses
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/profile \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Update profile settings
Needs a token that can change thingsUpdates user-owned settings on the profile and returns {changed, profile}: the names of the fields written, and the profile in the GET /v1/profile shape.
Send only the fields to change; null removes a field. Accepted fields are those in the request schema plus never; any other key, or an empty body, is 400. Interests cannot be changed here — use POST /v1/import, POST /v1/jobs and the /v1/interests routes. timezone is also written to the account; timezone: null is ignored.
never replaces all unavailable hours in one statement, as rows [{label, start, end, days}] (HH:MM 24-hour; days null for every day, or weekday numbers with Monday 0). The row labelled as sleep (e.g. asleep, night), or else the first every-day row crossing midnight, is stored as sleep; all other rows become hours_off, split at midnight. day_start and day_end are removed. 400 with code never_hours when a row is malformed or a working weekday (one not in days_off) would keep under four open hours.
sleep and the day window may not overlap. When only one of them is sent, the other is trimmed to fit and the trimmed fields are listed in changed.
place, latitude and longitude are optional; without them daylight times are not shown.
Changing any *_time or *_minutes field re-queues the user's scheduled jobs so the new time applies the same day.
Errors: 400 invalid_request for unknown fields or values that fail validation; 400 never_hours as above.
Request body optional
timezonestringIANA name
neverarray or nullThe complete set of unavailable hours, as rows; replaces
sleep,hours_off,day_startandday_end. null or [] clears them all4 fields
labelstringstartstringrequiredpattern^[0-9]{2}:[0-9]{2}$endstringrequiredpattern^[0-9]{2}:[0-9]{2}$daysarray or null
day_startstring or nullpattern^[0-9]{2}:[0-9]{2}$day_endstring or nullpattern^[0-9]{2}:[0-9]{2}$days_offarray or nullWeekdays the user never works, 0 (Monday) to 6 (Sunday). Each is treated as a whole-day busy block, so nothing is scheduled on it. Cannot list all seven days.
hours_offobject or nullRecurring unavailable windows per weekday, keyed "0"–"6" (Monday 0); each value is a list of
{start, end, title?}in HH:MM. Merged into the calendar as busy time, so nothing is placed inside them.days_offcovers whole days; this field covers hours within a day. Replaced wholesale whenneveris sent.placestring or nulllatitudenumber or nullmin -90 · max 90longitudenumber or nullmin -180 · max 180default_energyinteger or nullmin 1 · max 5buffer_after_shift_minutesinteger or nullsleepobject or null{start: bedtime, end: wake}, HH:MM; usually crosses midnight. Never planned into, and a day_start/day_end left unset follows it. It and the day's hours never overlap: setting one trims the other, named in
changed2 fields
startstringendstring
quiet_hoursobject or null2 fields
startstringendstring
morning_plan_timestring or nullevening_checkin_timestring or nullmiss_sweep_timestring or nullweekly_retro_timestring or nulltodoist_sync_minutesinteger or nullauto_planboolean or nullwhether Sereo may pre-build days — the morning plan and the post-absence re-entry day. Off by default
evening_checkinboolean or nullwhether the evening check-in is asked for. Absent or true: on; false: no check-in and no nudge
Responses
200 OK
changedarray of stringrequiredprofileobjectrequired
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X PATCH https://app.usesereo.com/v1/profile \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
List interests with derived state
Any token · read only is enoughReturns every interest on the profile grouped by type — goals, habits, leisure, chores — plus constraints, areas, completed_goals and deleted (interests restorable with POST /v1/interests/{interest}/restore).
Each interest carries a derived object: values Sereo computes (status, days since last scheduled or completed, momentum) rather than values the user stated. Keep the two distinct when displaying them.
date (YYYY-MM-DD) computes derived state as of that day instead of the user's current date; a date before the account's anchor_date is treated as anchor_date. 400 if date is not a valid date.
Before onboarding the response is onboarded: false with empty lists.
Query parameters
datestringCompute derived state for this day instead of today.
Responses
200 OK
onboardedbooleanrequireddatestringcompleted_goalsarray of objectGoals with every milestone complete. A goal moves here from
goalswhen its last open milestone is marked done (POST /v1/interests/{interest}/milestones/status) and back if one is reopened.16 fields
idstringrequiredlabelstringrequireddetailstringdone_whenarray of stringAcceptance criteria: conditions the user can check to confirm the goal is complete. Absent on goals created before the field existed and on habits and leisure, which have no end.
minutesinteger or nullcadence_per_weekintegermin 1 · max 7due_datestringblocked_untilstring or nullblocked_onstring or nulloriginstringone of"user","confirmed","integration","model"refusedbooleanareastring or nullarea_rankinteger or nullmin 1milestonesarray of objectcompleted_milestonesarray of objectderivedobjectrequiredSereo's inference, not anything the user said
3 fields
statusstring or nullone of"on_track","due","overdue","satisfied","starving",nulldays_since_scheduledinteger or nulldays_since_completedinteger or null
deletedarray of objectInterests removed with
DELETE /v1/interests/{interest}and restorable withPOST /v1/interests/{interest}/restore. Records older than 30 days are pruned when another interest is deleted, so an entry pastrestorable_untilcan still be listed.5 fields
idstringrequiredlabelstring or nulltypestring or nulldeleted_atstringrequiredrestorable_untilstringrequired
areasarray of objectThe user's grouping of goals into ranked areas, most important first. Each goal references its area with
areaand its position within it witharea_rank. Used as planning emphasis, not as a hard constraint.4 fields
idstringrequirednamestringrequiredwhystringrankintegerrequiredmin 1
goalsarray of object16 fields
idstringrequiredlabelstringrequireddetailstringdone_whenarray of stringAcceptance criteria: conditions the user can check to confirm the goal is complete. Absent on goals created before the field existed and on habits and leisure, which have no end.
minutesinteger or nullcadence_per_weekintegermin 1 · max 7due_datestringblocked_untilstring or nullblocked_onstring or nulloriginstringone of"user","confirmed","integration","model"refusedbooleanareastring or nullarea_rankinteger or nullmin 1milestonesarray of objectcompleted_milestonesarray of objectderivedobjectrequiredSereo's inference, not anything the user said
3 fields
statusstring or nullone of"on_track","due","overdue","satisfied","starving",nulldays_since_scheduledinteger or nulldays_since_completedinteger or null
habitsarray of object16 fields
idstringrequiredlabelstringrequireddetailstringdone_whenarray of stringAcceptance criteria: conditions the user can check to confirm the goal is complete. Absent on goals created before the field existed and on habits and leisure, which have no end.
minutesinteger or nullcadence_per_weekintegermin 1 · max 7due_datestringblocked_untilstring or nullblocked_onstring or nulloriginstringone of"user","confirmed","integration","model"refusedbooleanareastring or nullarea_rankinteger or nullmin 1milestonesarray of objectcompleted_milestonesarray of objectderivedobjectrequiredSereo's inference, not anything the user said
3 fields
statusstring or nullone of"on_track","due","overdue","satisfied","starving",nulldays_since_scheduledinteger or nulldays_since_completedinteger or null
leisurearray of object16 fields
idstringrequiredlabelstringrequireddetailstringdone_whenarray of stringAcceptance criteria: conditions the user can check to confirm the goal is complete. Absent on goals created before the field existed and on habits and leisure, which have no end.
minutesinteger or nullcadence_per_weekintegermin 1 · max 7due_datestringblocked_untilstring or nullblocked_onstring or nulloriginstringone of"user","confirmed","integration","model"refusedbooleanareastring or nullarea_rankinteger or nullmin 1milestonesarray of objectcompleted_milestonesarray of objectderivedobjectrequiredSereo's inference, not anything the user said
3 fields
statusstring or nullone of"on_track","due","overdue","satisfied","starving",nulldays_since_scheduledinteger or nulldays_since_completedinteger or null
choresarray of object16 fields
idstringrequiredlabelstringrequireddetailstringdone_whenarray of stringAcceptance criteria: conditions the user can check to confirm the goal is complete. Absent on goals created before the field existed and on habits and leisure, which have no end.
minutesinteger or nullcadence_per_weekintegermin 1 · max 7due_datestringblocked_untilstring or nullblocked_onstring or nulloriginstringone of"user","confirmed","integration","model"refusedbooleanareastring or nullarea_rankinteger or nullmin 1milestonesarray of objectcompleted_milestonesarray of objectderivedobjectrequiredSereo's inference, not anything the user said
3 fields
statusstring or nullone of"on_track","due","overdue","satisfied","starving",nulldays_since_scheduledinteger or nulldays_since_completedinteger or null
constraintsarray of object5 fields
idstringrequiredtextstringrequiredkindstringrequiredone of"gate","scheduling","content"priorityintegermin 1 · max 3applies_toarray of string
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/library \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Get goals as year-view rails
Any token · read only is enoughReturns every goal as a rail with its milestones positioned in time, plus the year's chores and summary counts. GET /v1/library returns the same goals unpositioned; this endpoint adds the computed placement.
For each goal, the server decides: where each milestone actually falls versus its stored date (at_days, plan_days, drift_days); which dates are fixed (fixed); which milestones are held because an earlier one is (block_derived); how unordered milestone groups fill their slots (free, item_slot); whether a fixed date passed unmet (failed_index); and which milestones are past due (held, stuck). Clients should render these rather than recompute them.
Positions are at_days: float days since 1970-01-01, fractional where two marks would otherwise coincide. The adjacent *_iso field is the same position as a date.
Each rail also carries history (the 84 days ending on date) and weeks (one entry per cadence week since adoption, up to 52).
date (YYYY-MM-DD) computes the view as of that day; 400 if it is not a valid date. Before onboarding the response has an empty rails list.
Query parameters
datestringDraw the year as of this day instead of today.
Responses
200 OK
datestringrequiredyearintegertoday_daysnumberrailsarray of objectrequired36 fields
idstringrequiredlabelstringrequiredtagstringrequiredShort display name for the goal, a word or two.
detailstringdone_whenarray of stringthe acceptance criteria; empty on goals written before the field existed
iconstringadoptedstringadopted_daysnumbermomentuminteger or nullstatusstring or nullshift_daysintegerdays the rail has been pulled forward by finishing things early
marksarray of objectrequired42 fields
indexintegerrequiredposition on the rail; the identity every other field here keys on
keystring or nullwhat a write names this milestone by
namestringrequirednotestringsourcestring or nullblocksinteger or nullplan_isostring or nullthe stored date — what an edit writes to
plan_daysnumberat_daysnumberrequiredEffective position in float days since 1970-01-01. May be fractional, e.g. a mark seated just before a fixed-date mark.
at_isostringrequireddonebooleanrequiredcompleted_onstring or nullearned_daysintegerdays this completion pulled the rail forward
drift_daysintegerfixedstring or nullwhy this date is not the plan's to move
blockedstring or nullblocked_onstring or nullthe milestone's own raw block, empty when
blockedis a sentence about a sub-step — the revision payload carries this back verbatimblock_keystringblock_derivedbooleanheld because something earlier in the rail is, not on its own account
blocked_byarray or nullblocked_by_labelstring or nullfreestring or nullan unordered stretch this belongs to
own_blockedstring or nullpast_duebooleanstuckbooleanPast due, unmet and not on a fixed date; its position is carried forward to today. A fixed-date milestone can be
past_duewithout beingstuck. Always false on a parked or refused goal.wall_daysnumber or nullis_currentbooleansteps_donebooleantrue when every listed task is done but the milestone has not been marked reached. Informational: the milestone is never completed automatically.
subsarray of object15 fields
siintegerrequiredidstring or nulllabelstringrequirednotestringplan_isostring or nullplan_daysnumberat_daysnumberrequiredat_isostringdatedbooleanfalse when the task has no date of its own and its position is interpolated across its milestone's run-up in list order.
donebooleanlogged_daysnumber or nullDay the task was marked done (task
completed_on), in float days since 1970-01-01; a done task is positioned here rather than at its planned date. Null for tasks completed beforecompleted_onwas recorded.blockedstring or nullblock_keystringdrift_daysintegerstuckboolean
item_slotinteger or nullitem_donebooleanitem_blockedstring or nullitem_blocked_byarray or nullitem_block_keystringown_subsarray of object15 fields
siintegerrequiredidstring or nulllabelstringrequirednotestringplan_isostring or nullplan_daysnumberat_daysnumberrequiredat_isostringdatedbooleanfalse when the task has no date of its own and its position is interpolated across its milestone's run-up in list order.
donebooleanlogged_daysnumber or nullDay the task was marked done (task
completed_on), in float days since 1970-01-01; a done task is positioned here rather than at its planned date. Null for tasks completed beforecompleted_onwas recorded.blockedstring or nullblock_keystringdrift_daysintegerstuckboolean
free_sizeintegerfree_slotsarray of integerfill_byinteger or nullslot_labelstringslot_notestringnext_slotinteger or nullopen_itemsarray of object3 fields
indexintegerlabelstringblockedboolean
nintegerrequireddone_nintegerrequiredall_donebooleancoldbooleantrue when the goal's
momentumis below 20, i.e. little recent credited work, regardless of deadline.hotbooleanparkedbooleanparked_untilstring or nullheldarray of integerIndices into
marksof milestones that are past due and unmet (stuck: true).blockedarray of integernext_indexinteger or nulldest_indexinteger or nulldest_daysnumberdest_atstringdest_in_daysintegerends_statedbooleantrue when a milestone is marked
finishes, sodest_atis the goal's end date; false whendest_atis only the date of the last milestone and the goal has no stated end.next_in_daysintegerfailed_indexinteger or nulla fixed date that passed unmet, which seals the rail there
first_daysnumberfront_daysnumberlinestringrequiredwhere this goal stands, in one sentence
inkinteger or nullthe ink this goal wears everywhere
rhythmobjectwhat the goal asks for each week, and the record over the history window
4 fields
targetinteger or nullrequiredsessions a week its habits ask for; null for a goal with no habit
labelstringrequiredkeptintegerrequireddays kept in the history window
plannedintegerrequireddays planned in the history window
historyarray of objectThe 84 days ending on the requested date. Per day:
planned— a block for the goal (or one of its habits) was laid out;kept— a check-in credited it. Both true = kept,plannedonly = missed,keptonly = unplanned extra.3 fields
datestringrequiredplannedbooleanrequiredkeptbooleanrequired
weeksarray of objectone entry per cadence week from the goal's adoption to the week today is in (up to 52): days kept and planned, against the rhythm's target or, without one, the days planned
4 fields
endingstringrequiredkeptintegerrequiredplannedintegerrequiredtargetintegerrequired
choresarray of object11 fields
idstringrequiredlabelstringrequireddetailstringdue_datestring or nulldaysinteger or nullminutesinteger or nullprioritystringone of"high","normal","low"donebooleanparkedbooleanparked_untilstring or nullstatestringrequiredone of"done","parked","late","today","soon","later"
countsobjectrequired5 fields
goalsintegermarksintegermetintegerheldintegerblockedinteger
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/year \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Set a milestone task's status
Needs a token that can change thingsMarks one task under a goal's open milestones done or todo and returns the updated task. done stamps completed_on if not already set; todo clears it.
Task status is the user's own checklist: it records no check-in credit, changes no schedule and never completes the milestone, even when every task is done (the year view reports that case as steps_done).
Errors: 400 invalid_request for a missing or unknown status; 404 not_found if the interest has no open-milestone task with that id.
Path parameters
intereststringrequiredA goal, habit or chore id.
pattern^[a-z0-9][a-z0-9_]{0,63}$taskstringrequiredA milestone task id.
pattern^[a-z0-9][a-z0-9_]{0,63}$
Request body required
statusstringrequiredone of"todo","done"
Responses
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/interests/$INTEREST/tasks/$TASK \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status": "done"}'
Delete a milestone task
Needs a token that can change thingsRemoves a task from a goal's open milestones and returns 204, so the planner no longer schedules it. Removal rather than a status change: marking it done would record work that did not happen.
The task's title is also recorded as a refusal, so the planner and reports do not propose it again.
Errors: 404 not_found if the interest has no open-milestone task with that id.
Path parameters
intereststringrequiredA goal, habit or chore id.
pattern^[a-z0-9][a-z0-9_]{0,63}$taskstringrequiredA milestone task id.
pattern^[a-z0-9][a-z0-9_]{0,63}$
Responses
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X DELETE https://app.usesereo.com/v1/interests/$INTEREST/tasks/$TASK \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Create a dated job
Needs a token that can change thingsCreates a job — an interest of type chore with a deadline — from structured fields and returns 201 with its id. Jobs are scheduled by priority and then by deadline. The job is stored with origin: "user".
for_whom marks the job as a delivery for someone (a client, an editor) rather than an errand; it is shown with the job on the day, year and report views. priority defaults to normal.
Errors: 400 invalid_request for a missing label, a due that is not a valid date, or a non-positive minutes; 409 not_onboarded if the profile has no interests yet.
Request body required
labelstringrequiredwhat the job is
duestringrequiredformatdatefor_whomstringWho the job is for (e.g. a client or editor), if anyone. Shown with the job on the day, year and report views. Truncated to 32 characters.
minutesintegerEstimated minutes per work session, positive integer. If omitted, the planner chooses a duration.
min 1prioritystringone of"high","normal","low"detailstring
Responses
201 Created
idstringrequired
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/jobs \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label": "…", "due": "2026-11-12"}'
Update a goal
Needs a token that can change thingsApplies a partial update to one goal (an interest of type project) and returns {interest, changed}: the goal id and the names of the fields that changed. This is the same merge the goal architect's conversation commits through.
Top-level fields are merged: send only those that change. area sets the goal's area (null removes it); without area_rank it goes last in that area, and the area's other goals are renumbered. tag and done_when are also accepted.
milestones, when sent, replaces the goal's open milestone list: a hand-written open milestone left out of the array is removed. Already-completed milestones are kept. Milestone identity is id, else name; a matched milestone keeps unspecified target_date, blocks and task ids. A milestone sent with status: "done" moves to completed_milestones.
A milestone carrying source belongs to an integration (e.g. GitHub): it is kept unchanged when omitted, and any change to it is refused with 409 github_owned. A milestone sent with a source that matches no current milestone is also 409 github_owned.
The goal id never changes. Nothing here writes plans, check-ins or to-dos.
Errors: 404 not_found if no live interest has that id; 400 invalid_request for an empty body, a non-goal interest (habits, leisure and jobs cannot be patched here), or a revision that fails validation.
Path parameters
intereststringrequiredA goal, habit or chore id.
pattern^[a-z0-9][a-z0-9_]{0,63}$
Request body optional
labelstringdetailstringblocked_untilstring or nullblocked_onstring or nulladoptedstringareastring or nullthe area id to place the goal in; null takes it out
area_rankintegerits place in that area, 1 first; the rest renumber
min 1milestonesarray of object16 fields
namestringneeded unless
idnames a milestone it keepstarget_datestringYYYY-MM-DD; a kept milestone keeps its own
estimate_blocksintegeroptional: a kept milestone keeps its own, a new one gets one per step
min 1blocksintegerthe library's name for estimate_blocks; either is taken
min 1idstringkindstringone of"effort","outcome","adjudicated"statusstringphasestringfinishesbooleanthe checkpoint that reaches this goal's done_when; at most one per goal
blocked_onstringfixed_reasonstringfree_groupstringno_steps_becausestringwhy no separate work leads to this checkpoint
blocked_byarray of stringcompleted_onstringtasksarray of object3 fields
idstringoptional: a step with the same title keeps its id, a new one is given one
titlestringrequiredstatusstringone of"todo","doing","done"
Responses
200 OK
intereststringrequiredchangedarray of stringrequired
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X PATCH https://app.usesereo.com/v1/interests/$INTEREST \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
Delete an interest
Needs a token that can change thingsRemoves a goal, habit, leisure item or job from the profile and returns 204. Subsequent plans no longer include it; stored plans and check-ins are not changed.
The interest is kept, with any constraint whose applies_to named only it, in the profile's deleted list, shown under deleted in GET /v1/library, and can be restored with POST /v1/interests/{interest}/restore. Constraints that also apply to other interests stay, with this id removed. Records older than 30 days are pruned the next time an interest is deleted.
The interest's label is also recorded as a refusal, so the planner, reports and the goal architect do not propose it again; restoring it lifts the refusal.
To pause a goal without deleting it, set blocked_until with PATCH /v1/interests/{interest} (goals only).
Errors: 404 not_found if no live interest has that id; 409 last_interest if it is the only interest on the profile.
Path parameters
intereststringrequiredA goal, habit or chore id.
pattern^[a-z0-9][a-z0-9_]{0,63}$
Responses
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X DELETE https://app.usesereo.com/v1/interests/$INTEREST \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Restore a deleted interest
Needs a token that can change thingsRestores an interest removed with DELETE /v1/interests/{interest}: the interest as it was (milestones, tasks), plus the constraints that applied only to it. Lifts the refusal recorded on deletion, keyed by its label and tag. If it served a parent goal that is no longer on the profile, it is restored unattached.
Returns restored (the id), label, type, milestones (count of open milestones), scope (always every future day) and persisted.
Restorable records are those listed under deleted in GET /v1/library.
Errors: 404 not_found if there is no deleted record for that id, or an interest with that id is already on the profile; 409 not_onboarded if the profile has no live interests.
Path parameters
intereststringrequiredA goal, habit or chore id.
pattern^[a-z0-9][a-z0-9_]{0,63}$
Responses
200 OK
restoredstringrequiredlabelstring or nulltypestring or nullmilestonesintegerscopestringrequiredhow far this write reaches: today's plan only, this week, every future day, or nothing at all
one of"today","this week","every future day","nothing"persistedobjectrequiredwhat lasts beyond today, by kind; empty lists when nothing lasting changed
5 fields
goalsarray of stringrulesarray of stringsettingsarray of stringjobsarray of stringweekarray of string
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/interests/$INTEREST/restore \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Set a milestone's completion status
Needs a token that can change thingsMarks a milestone of a goal done or not done and returns the milestone object. The milestone is identified in the body by id or name, since names are user-written text.
done moves it from milestones to completed_milestones with completed_on set to on (default: the user's current date). Completed milestones are display-only and are no longer scheduled. todo moves it back to the open list and clears completed_on.
Marking the last open milestone done completes the goal: it moves from interests to the completed list (completed_goals in GET /v1/library). Reopening a milestone on a completed goal returns the goal to interests.
This does not record check-in credit: pressure, block credit and missed-day tracking change only through check-ins.
Errors: 400 invalid_request for a missing field, a status other than done/todo, an interest that is not a goal, or an invalid on; 404 not_found for an unknown interest or milestone; 409 github_owned for a milestone owned by an integration; 409 last_interest when completing the goal would leave the profile with no live interests.
Path parameters
intereststringrequiredA goal, habit or chore id.
pattern^[a-z0-9][a-z0-9_]{0,63}$
Request body required
milestonestringrequiredits id, or its name
statusstringrequiredone of"done","todo"onstringYYYY-MM-DD the milestone was reached, stored as
completed_on. Defaults to the user's current date. Ignored whenstatusistodo.
Responses
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/interests/$INTEREST/milestones/status \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"milestone": "…", "status": "done"}'
Answer a milestone review
Needs a token that can change thingsRecords the user's answer to whether a past-due milestone was reached. Pending reviews — at most one per goal, its earliest past-due open milestone, excluding fixed, adjudicated and integration-owned dates — are listed in milestone_reviews on GET /v1/day/{date} for the current date. Sereo never marks a milestone reached on its own. The milestone is identified in the body by id or name.
choice:
reached— marks the milestone done exactly asPOST /v1/interests/{interest}/milestones/statusdoes, clears the review, and returns{outcome: "reached", milestone}. -not_yet— storeswhyon the review record and returns{outcome: "not_yet", why, options: ["move_date", "supersede"]}. The goal is not modified; apply an option withPOST /v1/interests/{interest}/milestones/review/adjust. -later— hides the review until the day afteron(default: the user's current date) and returns{outcome: "later", until}. A storednot_yetreason is kept.
An optional on (YYYY-MM-DD) sets the date used for completed_on or the snooze.
Errors: 400 invalid_request for a missing field or unknown choice. With reached, also those of the milestone status endpoint: 404 not_found, 409 github_owned, 409 last_interest. not_yet and later do not check that the milestone exists.
Path parameters
intereststringrequiredA goal, habit or chore id.
pattern^[a-z0-9][a-z0-9_]{0,63}$
Request body required
milestonestringrequiredits id, or its name
choicestringrequiredreachedmarks the milestone complete;not_yetstoreswhyand returns the adjustment options;latersnoozes the review until the day afteron(default: the user's current date).one of"reached","not_yet","later"whystringWith
not_yet: text reason, stored on the review record and returned in the response.
Responses
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/interests/$INTEREST/milestones/review \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"milestone": "…", "choice": "reached"}'
Apply a milestone review adjustment
Needs a token that can change thingsApplies the adjustment chosen after a not_yet answer to a milestone review and clears the review.
move_date— sets this milestone'starget_datetonew_datethrough the same merge asPATCH /v1/interests/{interest}; other milestones are unchanged.new_datemust be later thanon(default: the user's current date). Returns{outcome: "moved", to, changed}. -supersede— retires the milestone by marking it done (it moves tocompleted_milestoneswithcompleted_onset), asPOST /v1/interests/{interest}/milestones/statusdoes. Returns{outcome: "superseded", milestone}.
Errors: 400 invalid_request for a missing field, an unknown action, a missing or non-future new_date, or a revision that fails validation; 404 not_found for an unknown goal (and, with supersede, an unknown milestone); 409 github_owned for an integration-owned milestone; 409 last_interest when superseding the last open milestone of the only live interest. With move_date, a milestone key that matches nothing changes nothing and is not an error.
Path parameters
intereststringrequiredA goal, habit or chore id.
pattern^[a-z0-9][a-z0-9_]{0,63}$
Request body required
milestonestringrequiredits id, or its name
actionstringrequiredone of"move_date","supersede"new_datestringWith
move_date: the new target date, YYYY-MM-DD. Must be after the user's current date (oron).
Responses
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/interests/$INTEREST/milestones/review/adjust \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"milestone": "…", "action": "move_date"}'
Import a sereo.import/1 bundle
Needs a token that can change thingsBuilds a profile from a sereo.import/1 bundle, saves it in place of the existing profile, and returns 201 with interests (the count imported) and report.
Destructive: the whole profile is replaced, including deleted-interest records. Plans, check-ins and other stored data are not touched. When the profile already has interests, replace: true is required; otherwise the call fails with 400 bad_bundle.
The account's anchor_date is set from the bundle and scheduled jobs are re-queued.
report lists counts per type, defaults (values the importer supplied), dropped (items it could not keep), overdue (items already past due on arrival) and carried (empty for an import). Surface defaults and dropped to the user.
Errors: 400 invalid_request if bundle is not a JSON object; 400 bad_bundle if the bundle fails validation or replace is needed.
Request body required
bundleobjectrequireda sereo.import/1 bundle
8 fields
schemastringrequiredalways"sereo.import/1"profileobjectrequiredavailabilityarray of anyper weekday:
busyblocks, and optionallyfreewindows that are subtracted from the calendarhabitsarray of anyleisurearray of anychoresarray of anygoalsarray of anyconstraintsarray of any
replaceboolean
Responses
201 Created
interestsintegerrequiredreportobjectrequired4 fields
countsobjectdefaultsarray of anydroppedarray of anyoverduearray of any
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/import \
-H "Authorization: Bearer $SEREO_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json
Export the profile
Any token · read only is enoughReturns the profile as a sereo.import/1 bundle — the inverse of POST /v1/import. Completed goals are included in goals, with completed milestones carrying status and completed_on. The bundle holds the profile only, not plans or check-ins.
format selects another representation:
ics— every placed block linked to an interest, across all stored plans, as an iCalendar file (text/calendar, attachmentsereo.ics). Times are floating local times. Breaks and calendar-event blocks are excluded. -account— the whole account assereo.account/1JSON (attachmentsereo-account.json): the bundle plus plans, check-ins, to-dos, retros, monthly reports, refusals, milestone reviews, plan traces, seen days, navigation records, the event log and the usage ledger.
Available to accounts that have not completed checkout. 409 not_onboarded if the profile has no interests.
Query parameters
formatstringicsfor a calendar file; omit for the JSON bundle.
Responses
200 OK
schemastringrequiredalways"sereo.import/1"profileobjectrequiredavailabilityarray of anyper weekday:
busyblocks, and optionallyfreewindows that are subtracted from the calendarhabitsarray of anyleisurearray of anychoresarray of anygoalsarray of anyconstraintsarray of any
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/export \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Goal conversation
Goal architect: a conversation, run by the language model with tools, that builds or revises the user's goals, milestones and tasks in a draft. Nothing is written to the profile until the user confirms and the draft is committed. These routes exist only on deployments that enable the feature (SEREO_GOAL_ARCHITECT=1).
Start or resume a goal-architect session
Needs a token that can change thingsOpens a goal-architect conversation, or resumes the one in progress, and returns the session step.
Modes: deepen (default without goal) builds or revises the whole set of goals in a draft seeded from the profile, starting empty on a new account. blueprint takes the complete plan in the user's first message and asks only about what is missing. talk (default when goal is given) revises one project goal, optionally anchored to one of its milestones by name or id.
An account has one session slot. A live (uncommitted) session is resumed when the request names the same conversation (same mode, goal and milestone) or sends resume: true; resuming invokes nothing and uses no turn. A request naming a different conversation is refused with 409 session_in_flight, whose message names the open one; discard it (DELETE /v1/architect/session) or resume it. A committed session is replaced by a new one.
A new session opens with fixed text and no model call; the model is first invoked on POST /v1/architect/turns. Nothing is written to the profile until POST /v1/architect/commit.
Errors: 400 for an unknown mode, talk without goal, or a non-object body; 404 no_such_goal; 404 no_such_milestone; 404 with resume: true and no live session; 409 not_onboarded (talk on an account with no goals); 409 not_a_project (talk on a habit or other non-project goal); 409 session_in_flight; 403 email_unverified; 402 subscription_lapsed or 402 spend_cap_reached (monthly usage limit reached); 429 rate_limited; 503 architect_unconfigured when the deployment has no model provider configured.
Request body optional
modestringdefaults to talk when a goal is given, else deepen
one of"deepen","talk","blueprint"goalstringinterest id to anchor talk mode
milestonestringmilestone name or id within the anchored goal
resumebooleancontinue the in-flight conversation whatever it is anchored to; 404 when there is none
Responses
200 OK
workingbooleanrequireda turn is running behind this answer. True with a 202 from POST /v1/architect/turns, and on any GET /v1/architect/session while that turn is still going. Poll the session until it is false rather than holding a request open
last_errorobject or nullwhy the last turn failed, when the request that would have carried it had already answered 202
2 fields
codestringmessagestring
statestringrequiredone of"interview","confirming","ready","committed"modestringrequiredone of"deepen","talk","blueprint"turnintegerrequiredmin 0messagestring or nullthe agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)
messagesarray of stringthe reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null
transcriptarray of array of stringthe conversation so far as [who, text] pairs, oldest first, where
whoisagentoruser. A client renders this rather than keeping its own copyanchorobject or null2 fields
goalstringmilestonestring or null
draft_summaryobjectrequired6 fields
goalsintegersupportingintegerstandaloneintegermilestonesintegertasksintegerunconfirmedarray of string
turn_decisionsarray of objectthe rounds of the assistant turn just executed: {turn, round, reasoning, calls, text?} — the model's reasoning and each tool decision, for a UI that shows the work
previewobject or nullthe commit's dry-run import report; non-null only in state
readyfor adeepenorblueprintsession5 fields
countsobjectdefaultsarray of stringdroppedarray of stringoverduearray of stringnotesarray of string
tracesarray of objectwhat each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked
6 fields
turnintegerrequired0 is the written opening
min 0user_indexintegerrequiredhow many of the person's messages came before this reply
min 0stepsarray of objectrequired6 fields
kindstringrequiredone of"think","search"textstringthink: one sentence, in Sereo's voice
sourceobjectthink: the page the answer came from, only when a search in the same turn cited it
3 fields
urlstringrequireddomainstringrequiredtitlestring
querystringerrorbooleansourcesarray of object3 fields
urlstringrequireddomainstringrequiredtitlestring
changesarray of objectrequiredone line per thing the turn changed, diffed from the draft by the server, never the model's account
4 fields
verbstringrequiredone of"Staged","Changed","Removed","Up next"kindstringrequiredone of"goal","rhythm","chore","up_next"labelstringrequiredfactsarray of objectrequired2 fields
textstringrequireddatestring or null
askobject or null3 fields
questionstringrequiredoptionsarray of objectrequired2 fields
labelstringrequireddetailstring
multibooleanrequiredseveral answers may be picked together
replyarray of stringpresent when
askis: the reply's messages as they read beside the question sheet, without a closing question the sheet already carries. The transcript keeps the reply whole
open_askobject or nullthe question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer
3 fields
questionstringrequiredoptionsarray of objectrequired2 fields
labelstringrequireddetailstring
multibooleanrequiredseveral answers may be picked together
setupobjectthe year as committing this draft would leave it:
stagedentries,buildinglines and the datewindow4 fields
stagedarray of objectrequiredwhat committing would put on the year
12 fields
titlestringrequiredthe state this goal reaches, which is its name
tagstring or nullwhat the user calls it, in their own words
done_whenarray of stringthe acceptance criteria; empty for a rhythm, which has no end
kindstringrequiredone of"project","habit","leisure","chore"kind_labelstringrequiredwhat the hub calls this kind
linestringrequiredhow the engine treats this kind — a claim about the type, never about the goal
monthsnumberrequiredhow far round the year the rail runs
min 1 · max 12beyondbooleanit ends past the one lap the dial shows, so the rail tapers off at the rim instead of sealing, and marks are placed against the year rather than its own span
datestring or nullwhere the rail ends; null for a rhythm, which has no end
formatdatenotestringmarksarray of objectrequired4 fields
atnumberrequiredmin 0 · max 1labelstringrequireddatestringformatdatefixedboolean
factsarray of object
buildingarray of objectrequireddisplay lines (
text,state) describing what committing this draft will build2 fields
textstringrequiredstatestringrequired
windowobjectrequired2 fields
fromstringformatdatetostringformatdate
up_nextarray of stringgoals the person named that the conversation has not reached yet, in the order it will take them
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
503 That integration is not configured on this deployment
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/architect/start \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Get the goal-architect session
Any token · read only is enoughReturns the account's current goal-architect session in the same step shape a turn returns, with message set to the agent's last reply.
Read-only and safe to poll: it uses no turn and adds nothing to the transcript. Use it to resume after a reload, and to follow a turn that answered 202: working stays true while the turn runs, and last_error reports a turn that failed after its request had already returned.
A committed session is still returned (with state: committed) until it is discarded or replaced.
Errors: 404 when there is no session.
Responses
200 OK
workingbooleanrequireda turn is running behind this answer. True with a 202 from POST /v1/architect/turns, and on any GET /v1/architect/session while that turn is still going. Poll the session until it is false rather than holding a request open
last_errorobject or nullwhy the last turn failed, when the request that would have carried it had already answered 202
2 fields
codestringmessagestring
statestringrequiredone of"interview","confirming","ready","committed"modestringrequiredone of"deepen","talk","blueprint"turnintegerrequiredmin 0messagestring or nullthe agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)
messagesarray of stringthe reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null
transcriptarray of array of stringthe conversation so far as [who, text] pairs, oldest first, where
whoisagentoruser. A client renders this rather than keeping its own copyanchorobject or null2 fields
goalstringmilestonestring or null
draft_summaryobjectrequired6 fields
goalsintegersupportingintegerstandaloneintegermilestonesintegertasksintegerunconfirmedarray of string
turn_decisionsarray of objectthe rounds of the assistant turn just executed: {turn, round, reasoning, calls, text?} — the model's reasoning and each tool decision, for a UI that shows the work
previewobject or nullthe commit's dry-run import report; non-null only in state
readyfor adeepenorblueprintsession5 fields
countsobjectdefaultsarray of stringdroppedarray of stringoverduearray of stringnotesarray of string
tracesarray of objectwhat each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked
6 fields
turnintegerrequired0 is the written opening
min 0user_indexintegerrequiredhow many of the person's messages came before this reply
min 0stepsarray of objectrequired6 fields
kindstringrequiredone of"think","search"textstringthink: one sentence, in Sereo's voice
sourceobjectthink: the page the answer came from, only when a search in the same turn cited it
3 fields
urlstringrequireddomainstringrequiredtitlestring
querystringerrorbooleansourcesarray of object3 fields
urlstringrequireddomainstringrequiredtitlestring
changesarray of objectrequiredone line per thing the turn changed, diffed from the draft by the server, never the model's account
4 fields
verbstringrequiredone of"Staged","Changed","Removed","Up next"kindstringrequiredone of"goal","rhythm","chore","up_next"labelstringrequiredfactsarray of objectrequired2 fields
textstringrequireddatestring or null
askobject or null3 fields
questionstringrequiredoptionsarray of objectrequired2 fields
labelstringrequireddetailstring
multibooleanrequiredseveral answers may be picked together
replyarray of stringpresent when
askis: the reply's messages as they read beside the question sheet, without a closing question the sheet already carries. The transcript keeps the reply whole
open_askobject or nullthe question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer
3 fields
questionstringrequiredoptionsarray of objectrequired2 fields
labelstringrequireddetailstring
multibooleanrequiredseveral answers may be picked together
setupobjectthe year as committing this draft would leave it:
stagedentries,buildinglines and the datewindow4 fields
stagedarray of objectrequiredwhat committing would put on the year
12 fields
titlestringrequiredthe state this goal reaches, which is its name
tagstring or nullwhat the user calls it, in their own words
done_whenarray of stringthe acceptance criteria; empty for a rhythm, which has no end
kindstringrequiredone of"project","habit","leisure","chore"kind_labelstringrequiredwhat the hub calls this kind
linestringrequiredhow the engine treats this kind — a claim about the type, never about the goal
monthsnumberrequiredhow far round the year the rail runs
min 1 · max 12beyondbooleanit ends past the one lap the dial shows, so the rail tapers off at the rim instead of sealing, and marks are placed against the year rather than its own span
datestring or nullwhere the rail ends; null for a rhythm, which has no end
formatdatenotestringmarksarray of objectrequired4 fields
atnumberrequiredmin 0 · max 1labelstringrequireddatestringformatdatefixedboolean
factsarray of object
buildingarray of objectrequireddisplay lines (
text,state) describing what committing this draft will build2 fields
textstringrequiredstatestringrequired
windowobjectrequired2 fields
fromstringformatdatetostringformatdate
up_nextarray of stringgoals the person named that the conversation has not reached yet, in the order it will take them
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/architect/session \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Discard the goal-architect session
Needs a token that can change thingsDeletes the account's goal-architect session and its draft. Returns 204 with no body.
Nothing is written to the profile; a session that was already committed leaves its committed goals in place. A turn still running when the session is discarded is not saved.
Errors: 404 when there is no session.
Responses
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X DELETE https://app.usesereo.com/v1/architect/session \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Stream goal-architect events
Any token · read only is enoughOpens a server-sent event stream (text/event-stream) of live events for the calling account.
Each event is one data: {json} frame with no event: line; the JSON's type field names it. During an architect turn: round (turn, round, reasoning, tools: the number of tool calls in the round), call (turn, round, tool, args, result, error), and done (turn) when the turn ends however it ended. The stream is the account's shared live channel and is not filtered, so it also carries plan_stage events from plan builds (also served, filtered by day, at GET /v1/plans/{date}/stream) and ask_stage events. Ignore types you do not handle.
A : keepalive comment frame is sent after 20 seconds without an event. The server closes the stream after 15 minutes, or earlier when the account opens a fifth stream (at most four are kept; the oldest is closed). Reconnect as needed.
The stream is advisory. Events are not replayed, are dropped when a reader falls behind, and duplicate what the turn's response carries in turn_decisions; a client that never opens the stream receives the same information when the turn completes.
Responses
# example
curl https://app.usesereo.com/v1/architect/stream \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Send a turn to the goal architect
Needs a token that can change thingsSubmits one user message to the goal-architect session and returns the resulting step.
A normal turn invokes the language model in a tool loop that can take over two minutes. The request waits up to about 25 seconds: a turn that finishes in time answers 200 with the reply; otherwise it answers 202 with working: true and no message, and the turn continues in the background. Poll GET /v1/architect/session until working is false, then read the reply and last_error. GET /v1/architect/stream reports progress while it runs.
Confirmation: when the step is awaiting confirmation (state confirming), confirm: true records the user's yes, and message becomes optional. A message recognised as a plain yes does the same. Either confirms every unconfirmed draft entry and moves the session to ready (or leaves it confirming if the draft is empty) without a model call. Any other reply returns the session to the interview and runs a normal turn.
When the session's turn budget is exhausted, no model call is made: the session moves to confirming with a fixed message, or stays where it is if the draft is unchanged.
Send the session's current turn number to turn a duplicate submit into a clean 409 stale_turn.
Errors: 400 when message is missing without confirm, or the body is not an object; 409 no_session; 409 already_complete (session committed); 409 turn_in_progress; 409 stale_turn; 409 not_confirmable (confirm sent when nothing awaits confirmation); 403 email_unverified; 402 subscription_lapsed or 402 spend_cap_reached (monthly usage limit reached); 429 rate_limited; 503 architect_unconfigured.
Request body optional
messagestringconfirmbooleanturnintegermin 0
Responses
200 OK
workingbooleanrequireda turn is running behind this answer. True with a 202 from POST /v1/architect/turns, and on any GET /v1/architect/session while that turn is still going. Poll the session until it is false rather than holding a request open
last_errorobject or nullwhy the last turn failed, when the request that would have carried it had already answered 202
2 fields
codestringmessagestring
statestringrequiredone of"interview","confirming","ready","committed"modestringrequiredone of"deepen","talk","blueprint"turnintegerrequiredmin 0messagestring or nullthe agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)
messagesarray of stringthe reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null
transcriptarray of array of stringthe conversation so far as [who, text] pairs, oldest first, where
whoisagentoruser. A client renders this rather than keeping its own copyanchorobject or null2 fields
goalstringmilestonestring or null
draft_summaryobjectrequired6 fields
goalsintegersupportingintegerstandaloneintegermilestonesintegertasksintegerunconfirmedarray of string
turn_decisionsarray of objectthe rounds of the assistant turn just executed: {turn, round, reasoning, calls, text?} — the model's reasoning and each tool decision, for a UI that shows the work
previewobject or nullthe commit's dry-run import report; non-null only in state
readyfor adeepenorblueprintsession5 fields
countsobjectdefaultsarray of stringdroppedarray of stringoverduearray of stringnotesarray of string
tracesarray of objectwhat each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked
6 fields
turnintegerrequired0 is the written opening
min 0user_indexintegerrequiredhow many of the person's messages came before this reply
min 0stepsarray of objectrequired6 fields
kindstringrequiredone of"think","search"textstringthink: one sentence, in Sereo's voice
sourceobjectthink: the page the answer came from, only when a search in the same turn cited it
3 fields
urlstringrequireddomainstringrequiredtitlestring
querystringerrorbooleansourcesarray of object3 fields
urlstringrequireddomainstringrequiredtitlestring
changesarray of objectrequiredone line per thing the turn changed, diffed from the draft by the server, never the model's account
4 fields
verbstringrequiredone of"Staged","Changed","Removed","Up next"kindstringrequiredone of"goal","rhythm","chore","up_next"labelstringrequiredfactsarray of objectrequired2 fields
textstringrequireddatestring or null
askobject or null3 fields
questionstringrequiredoptionsarray of objectrequired2 fields
labelstringrequireddetailstring
multibooleanrequiredseveral answers may be picked together
replyarray of stringpresent when
askis: the reply's messages as they read beside the question sheet, without a closing question the sheet already carries. The transcript keeps the reply whole
open_askobject or nullthe question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer
3 fields
questionstringrequiredoptionsarray of objectrequired2 fields
labelstringrequireddetailstring
multibooleanrequiredseveral answers may be picked together
setupobjectthe year as committing this draft would leave it:
stagedentries,buildinglines and the datewindow4 fields
stagedarray of objectrequiredwhat committing would put on the year
12 fields
titlestringrequiredthe state this goal reaches, which is its name
tagstring or nullwhat the user calls it, in their own words
done_whenarray of stringthe acceptance criteria; empty for a rhythm, which has no end
kindstringrequiredone of"project","habit","leisure","chore"kind_labelstringrequiredwhat the hub calls this kind
linestringrequiredhow the engine treats this kind — a claim about the type, never about the goal
monthsnumberrequiredhow far round the year the rail runs
min 1 · max 12beyondbooleanit ends past the one lap the dial shows, so the rail tapers off at the rim instead of sealing, and marks are placed against the year rather than its own span
datestring or nullwhere the rail ends; null for a rhythm, which has no end
formatdatenotestringmarksarray of objectrequired4 fields
atnumberrequiredmin 0 · max 1labelstringrequireddatestringformatdatefixedboolean
factsarray of object
buildingarray of objectrequireddisplay lines (
text,state) describing what committing this draft will build2 fields
textstringrequiredstatestringrequired
windowobjectrequired2 fields
fromstringformatdatetostringformatdate
up_nextarray of stringgoals the person named that the conversation has not reached yet, in the order it will take them
202 Accepted; anything further is sent to the address itself
workingbooleanrequireda turn is running behind this answer. True with a 202 from POST /v1/architect/turns, and on any GET /v1/architect/session while that turn is still going. Poll the session until it is false rather than holding a request open
last_errorobject or nullwhy the last turn failed, when the request that would have carried it had already answered 202
2 fields
codestringmessagestring
statestringrequiredone of"interview","confirming","ready","committed"modestringrequiredone of"deepen","talk","blueprint"turnintegerrequiredmin 0messagestring or nullthe agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)
messagesarray of stringthe reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null
transcriptarray of array of stringthe conversation so far as [who, text] pairs, oldest first, where
whoisagentoruser. A client renders this rather than keeping its own copyanchorobject or null2 fields
goalstringmilestonestring or null
draft_summaryobjectrequired6 fields
goalsintegersupportingintegerstandaloneintegermilestonesintegertasksintegerunconfirmedarray of string
turn_decisionsarray of objectthe rounds of the assistant turn just executed: {turn, round, reasoning, calls, text?} — the model's reasoning and each tool decision, for a UI that shows the work
previewobject or nullthe commit's dry-run import report; non-null only in state
readyfor adeepenorblueprintsession5 fields
countsobjectdefaultsarray of stringdroppedarray of stringoverduearray of stringnotesarray of string
tracesarray of objectwhat each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked
6 fields
turnintegerrequired0 is the written opening
min 0user_indexintegerrequiredhow many of the person's messages came before this reply
min 0stepsarray of objectrequired6 fields
kindstringrequiredone of"think","search"textstringthink: one sentence, in Sereo's voice
sourceobjectthink: the page the answer came from, only when a search in the same turn cited it
3 fields
urlstringrequireddomainstringrequiredtitlestring
querystringerrorbooleansourcesarray of object3 fields
urlstringrequireddomainstringrequiredtitlestring
changesarray of objectrequiredone line per thing the turn changed, diffed from the draft by the server, never the model's account
4 fields
verbstringrequiredone of"Staged","Changed","Removed","Up next"kindstringrequiredone of"goal","rhythm","chore","up_next"labelstringrequiredfactsarray of objectrequired2 fields
textstringrequireddatestring or null
askobject or null3 fields
questionstringrequiredoptionsarray of objectrequired2 fields
labelstringrequireddetailstring
multibooleanrequiredseveral answers may be picked together
replyarray of stringpresent when
askis: the reply's messages as they read beside the question sheet, without a closing question the sheet already carries. The transcript keeps the reply whole
open_askobject or nullthe question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer
3 fields
questionstringrequiredoptionsarray of objectrequired2 fields
labelstringrequireddetailstring
multibooleanrequiredseveral answers may be picked together
setupobjectthe year as committing this draft would leave it:
stagedentries,buildinglines and the datewindow4 fields
stagedarray of objectrequiredwhat committing would put on the year
12 fields
titlestringrequiredthe state this goal reaches, which is its name
tagstring or nullwhat the user calls it, in their own words
done_whenarray of stringthe acceptance criteria; empty for a rhythm, which has no end
kindstringrequiredone of"project","habit","leisure","chore"kind_labelstringrequiredwhat the hub calls this kind
linestringrequiredhow the engine treats this kind — a claim about the type, never about the goal
monthsnumberrequiredhow far round the year the rail runs
min 1 · max 12beyondbooleanit ends past the one lap the dial shows, so the rail tapers off at the rim instead of sealing, and marks are placed against the year rather than its own span
datestring or nullwhere the rail ends; null for a rhythm, which has no end
formatdatenotestringmarksarray of objectrequired4 fields
atnumberrequiredmin 0 · max 1labelstringrequireddatestringformatdatefixedboolean
factsarray of object
buildingarray of objectrequireddisplay lines (
text,state) describing what committing this draft will build2 fields
textstringrequiredstatestringrequired
windowobjectrequired2 fields
fromstringformatdatetostringformatdate
up_nextarray of stringgoals the person named that the conversation has not reached yet, in the order it will take them
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
503 That integration is not configured on this deployment
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/architect/turns \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Commit the goal-architect draft
Needs a token that can change thingsWrites the confirmed draft to the user's profile, marks the session committed, and returns a commit report.
The session must be in state ready, which only the user's confirmation sets (see confirm on POST /v1/architect/turns). accept: true records that confirmation and commits in one request; it is accepted only while the step is awaiting confirmation.
deepen and blueprint: the draft replaces the profile through the import path. Integration-owned data that changed since the draft was seeded is not reverted, and user changes made outside the conversation meanwhile are kept and listed in report.carried. The account's anchor_date is set and its scheduled jobs are rescheduled. The server then builds the first week plan (if the current week has none) and today's plan (if none exists), which invokes the language model when the account is verified, entitled and under its usage limit. The request waits up to about 25 seconds for that build: 200 with planned (the date planned, or null) when it finishes or is not started, otherwise 202 with working: true while it continues; follow it on GET /v1/plans/{date}/stream. The new plan is a proposal and is not accepted. A failure in the build never fails the commit.
talk: only the anchored goal is merged into the profile; milestones owned by an integration are left untouched. report.changed lists what changed and report.not_written names draft entries outside that goal that were not written. No model call.
Errors: 409 no_session; 409 already_complete; 409 not_confirmable; 409 turn_in_progress; 409 not_ready (draft not confirmed); 409 stale_draft; 409 bad_profile (draft fails import validation); 409 bad_revision and 409 github_owned (talk); 404 when the anchored goal no longer exists.
Request body optional
acceptboolean
Responses
200 OK
modestringrequiredone of"deepen","talk","blueprint"committedbooleanrequiredalwaystrueupdated_goalstring or nullanchor_datestring or nullformatdatereportobjectrequireddeepen/blueprint: the import report (
counts,defaults,dropped,overdue,notes) pluscarried, the user changes made outside the conversation while it was open that the commit kept. talk:changed,notesandnot_written, the draft entries outside the anchored goal that were not written.2 fields
carriedarray of stringnot_writtenarray of string
plannedstring or nulldeepen/blueprint: the date a plan was written for as part of committing; null when a plan already existed, the account may not invoke the model, the build failed, or it is still running (
working). A build failure never fails the commitformatdateworkingbooleandeepen/blueprint: true with a 202 while the first week and day are still being built; follow GET /v1/plans/{date}/stream
202 Accepted; anything further is sent to the address itself
modestringrequiredone of"deepen","talk","blueprint"committedbooleanrequiredalwaystrueupdated_goalstring or nullanchor_datestring or nullformatdatereportobjectrequireddeepen/blueprint: the import report (
counts,defaults,dropped,overdue,notes) pluscarried, the user changes made outside the conversation while it was open that the commit kept. talk:changed,notesandnot_written, the draft entries outside the anchored goal that were not written.2 fields
carriedarray of stringnot_writtenarray of string
plannedstring or nulldeepen/blueprint: the date a plan was written for as part of committing; null when a plan already existed, the account may not invoke the model, the build failed, or it is still running (
working). A build failure never fails the commitformatdateworkingbooleandeepen/blueprint: true with a 202 while the first week and day are still being built; follow GET /v1/plans/{date}/stream
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/architect/commit \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Weekly briefs
Weekly brief (older shape). Reads and writes the same stored document as /v1/reports/week/{date}.
Get a weekly brief
Any token · read only is enoughPath parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
404 No such thing, or it belongs to another account
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/retro/2026-11-12 \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Generate a weekly brief
Needs a token that can change thingsWrites the weekly brief for the week ending date if none exists, and returns it.
If a brief is already stored for date, it is returned unchanged in its stored form (as GET /v1/retro/{date}), with no model call; there is no way to force a rewrite.
Otherwise the week must have ended (date before today) and fall entirely after the account's anchor date. If it has not, nothing is written and the response is 200 with {"skipped": "not_ready", "readiness": {...}}; readiness.ready_on gives the first date it can be written. If it has, this invokes the language model once (the same call as POST /v1/reports/week/{date}), stores the result, and returns the full weekly report.
date is used exactly as given and is not snapped to a cadence-week boundary.
Errors: 409 not_onboarded when the account has no goals; 403 email_unverified; 402 subscription_lapsed or 402 spend_cap_reached (monthly usage limit reached); 429 rate_limited. These gates apply even when a stored brief would be returned.
Path parameters
datestringrequiredThe day, YYYY-MM-DD.
pattern^\d{4}-\d{2}-\d{2}$
Responses
400 The request was malformed; code says how
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
409 Refused because of the account's current state; branch on code
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/retro/2026-11-12 \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Calendar
Google Calendar connection. Read-only: busy time is read and no events are written.
Get Google Calendar connection status
Any token · read only is enoughResponses
200 OK
connectedbooleanrequiredoauthbooleanWhether this deployment has a Google OAuth client configured. When false the calendar cannot be connected on this server.
expires_atstring or nullscopestring or null
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/calendar/status \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Disconnect Google Calendar
Needs a token that can change thingsDeletes the user's stored Google Calendar tokens and cached calendar data and returns 204. Subsequent plans use only the profile's weekly busy pattern. The grant is not revoked with Google.
Idempotent: returns 204 when no calendar is connected. Allowed on a lapsed subscription.
Responses
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl -X DELETE https://app.usesereo.com/v1/calendar \
-H "Authorization: Bearer $SEREO_API_TOKEN"
Account
Accounts, sign-in and sessions, password reset, personal API tokens, and subscription status.
Get the authenticated account
Any token · read only is enoughResponses
200 OK
user_idstringrequiredemailstringrequiredtimezonestringrequired
401 Missing or invalid bearer token
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
402 No active subscription: the account has not been through Checkout (checkout_required), or its subscription has lapsed and this is not a read (subscription_lapsed); or the account's monthly usage limit is reached (spend_cap_reached)
errorobjectrequired3 fields
codestringrequiredmachine-readable; branch on this, not on prose
messagestringrequiredrequest_idstringrequired
# example
curl https://app.usesereo.com/v1/whoami \
-H "Authorization: Bearer $SEREO_API_TOKEN"