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.

Derived state comes from the server. Item status, ordering, risk and the user's current time are computed server-side. Read them from 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.

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

Treat a token as a password. Keep it in an environment variable or a secret store, never in source control or client-side code. Use a read-only token unless the integration needs to write. Revoking a token (same screen) takes effect immediately and does not end your other sessions.

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": "…" } }
  • 400 invalid_request: malformed body or parameter, or a value out of range.
  • 401 unauthorized: 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, GET routes keep working.
  • 403: read_only_token (a read-only token called a non-GET route), or email_unverified (a route that runs the model, before the account's email address is confirmed).
  • 404 not_found: the day, goal, item or route does not exist for this account.
  • 409 conflict: 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.
  • 429 rate_limited: too many requests. Wait for the number of seconds in Retry-After when present.
  • 503 busy: the model provider is temporarily rate-limiting. Retry after Retry-After seconds.

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/v1/status#

Get the account's current status

Any token · read only is enough

Returns 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

  • datestring

    Override today, YYYY-MM-DD.

Responses

200 OK
  • datestringrequired
  • onboardedbooleanrequired
  • interestsinteger
  • goalsinteger

    goals only (the projects), not the habits, leisure or chores under them — what the band counts so it agrees with the year wheel

  • plan_existsbooleanrequired
  • plan_acceptedboolean
  • awaiting_checkinboolean
  • gap_daysinteger or null

    workable 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 object
  • on_holdarray of object
  • calendar_connectedboolean
  • timezonestring

    the 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_tracedboolean

    this account's navigation is being recorded for the beta, and the screen says so

  • architectboolean

    whether 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_runningboolean

    a report for this account is being generated right now

  • report_writtenboolean

    whether 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 null

    the latest written report not yet marked read; cleared by POST /v1/reports/{period}/{date}/seen

    2 fields
    • periodstring
    • endingstring
  • email_verifiedboolean

    whether the address has answered. False means the account works, but routes that invoke the model answer 403 email_unverified.

  • energy_defaultinteger

    where the energy control starts

    min 1 · max 5
  • accessany

    the account's standing: full; checkout_first, which may only start a subscription, sign out or delete itself (everything else answers 402 checkout_required); or lapsed, which reads everything and changes nothing until it renews. Always full with billing off.

    one of "full", "checkout_first", "lapsed"
  • checkout_firstboolean

    a new account that has not been through checkout yet. Every route outside a small allowlist answers 402 checkout_required until it has. Always false with billing off.

  • walkthrough_owedboolean

    whether the first-run tutorial is still owed: true once a profile exists, while the account's standing is full, until POST /v1/walkthrough/seen

  • tutorialobject or null

    the 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) or skipped; current is the first step still to do, null once every step is done or skipped

    2 fields
    • stepsarray of object
      2 fields
      • keyanyrequired
        one of "goals", "calendar", "week", "today", "reports", "settings"
      • stateanyrequired
        one of "todo", "done", "skipped"
    • currentany
      one of "goals", "calendar", "week", "today", "reports", "settings", null
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/status \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/interests/{interest}/done#

Mark a chore done or not done

Needs a token that can change things

Records 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

  • intereststringrequired

    A goal, habit or chore id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$

Request body optional

  • doneboolean
    default true
  • datestring

    YYYY-MM-DD; today by default

Responses

200 OK
  • idstringrequired
  • donebooleanrequired
  • daystringrequired
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/interests/$INTEREST/done \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
GET/v1/day/{date}#

Get the day view

Any token · read only is enough

Returns 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
  • datestringrequired
  • weekdaystring
  • onboardedbooleanrequired
  • is_todayboolean
  • now_minutesinteger
    min 0 · max 2879
  • energyinteger or null
    min 1 · max 5
  • week_changed_since_planboolean

    the 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 null

    the 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
    • workingboolean
    • stepsarray of string
    • weekobject or null
    • endingstring
    • errorstring or null
  • energy_statedboolean

    whether that number is the user's own or the default the planner had to pick. The client must not infer this from energy being present — a planned day always has one

  • plan_existsbooleanrequired
  • week_plannedboolean or null

    whether 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 it

  • acceptedboolean
  • read_onlyboolean
  • influencesarray of object

    standing rules agreed in a report review that apply to planning (W19); revoke one with DELETE /v1/constraints/{id}

    3 fields
    • idstring
    • textstring
    • fromstring
  • milestone_reviewsarray of object

    milestones whose date has passed but which nobody has ticked reached: the day asks rather than guess, and answering feeds the review route. state is 'asked' for a fresh nudge, 'not_yet' once the user deferred and owes an adjustment

    7 fields
    • intereststring
    • interest_labelstring
    • milestonestring
    • milestone_namestring
    • was_duestring
    • whystring or null
    • statestring
      one of "asked", "not_yet"
  • settledboolean

    the 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 null
    one of "user", "scheduler", null
  • day_offboolean

    a weekday the user said they never work; generating it produces a day-off placeholder plan

  • reshapingboolean

    the day is being edited; server-held, so the state survives reloads and other clients

  • day_startstring
  • day_endstring
  • plans_betweenstring

    a server-written sentence describing when this day is planned: the day window and the unavailable hours inside it

  • day_wrapsboolean

    whether this day crosses midnight: day_end is then a next-morning hour

  • day_end_extendedinteger

    day_end in minutes since midnight on the extended axis (above 1439 when the day wraps)

    min 0 · max 2879
  • outside_hoursarray of object

    blocks the user placed outside their day window; they are kept, not refused

    4 fields
    • taskstringrequired
    • startstringrequired
    • endstringrequired
    • sidestringrequired
      one of "before", "after"
  • pushbackarray of object

    where Sereo would change one of the person's own blocks, and why; the block stays

    2 fields
    • taskstringrequired
    • reasonstringrequired
  • most_importantstring
  • coach_notestring
  • recoveryboolean
  • issuesarray of string
  • on_holdarray of object

    work deliberately not in the day, named here as {interest, label} — the plan file keeps bare ids

  • unfitarray of object

    blocks 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
    • taskstringrequired
    • goalstring or null
    • minutesinteger or null
    • askedboolean
    • whystringrequired
    • offersarray of object
      8 fields
      • kindstringrequired
        one of "move", "drop_habit"
      • textstringrequired
      • tostring
      • day_labelstring
      • effortstring
      • free_minutesinteger
      • taskstring
      • intereststring or null
  • committed_actionsarray of string

    a Day-0 plan whose calendar input was too thin to earn time blocks carries these instead (P13)

  • backupstring
  • pinsarray of object
  • solarobject or null

    local clock minutes for the day's solar events, or null when the profile has no location

    8 fields
    • placestring
    • latitudenumber
    • longitudenumber
    • dawninteger or null
    • riseinteger or null
    • nooninteger or null
    • setinteger or null
    • duskinteger or null
  • bandsarray of object

    the 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
    • namestringrequired
    • neverbooleanrequired

      a stretch wholly outside the hours Sereo plans: one of the hours it never touches

    • fromintegerrequired
      min 0 · max 2879
    • tointegerrequired

      inclusive: the last minute this stretch owns. Past 1439 = a wrapped day's small hours

      min 0 · max 2879
    • emptystringrequired

      what to say when nothing was placed here

    • coveredbooleanrequired

      whether 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

    • titlestringrequired

      where the sun stands over this stretch — empty when there is no location to say it from

  • rowsarray of objectrequired
    20 fields
    • idstringrequired
    • startstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • endstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • start_minutesinteger
    • end_minutesinteger
    • minutesinteger
    • taskstringrequired
    • kindstringrequired

      busy is a calendar event, not a plan block; break is a plan block with no interest behind it, so it is not work and never a to-do

      one of "goal", "rhythm", "leisure", "chore", "break", "busy"
    • iconstring
    • tagstring

      the goal or rhythm this hour serves

    • nodestring or null

      the milestone it serves, when there is one

    • intereststring or null
    • whystring

      why this hour is here — the model's own sentence for a plan block, and for a busy row 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 open

    • adaptboolean

      the day changed under the user here: a guard cut its length, or a replan moved its hour

    • extboolean

      owned by the calendar, not movable

    • riskobject or null
      2 fields
      • labelstring
      • levelstring
        one of "late", "soon"
    • keepobject or null
      2 fields
      • duestring
        format date
      • prioritystring
        one of "high", "normal", "low"
    • todo_idstring or null
    • task_idstring or null
    • statusstring or null

      the derived status — unreconciled is silence, never a miss

      one of "open", "done", "skipped", "unreconciled", null
  • goalsarray of object

    what 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
    • idstringrequired
    • tagstringrequired

      what the goal is called out loud — the one or two words a control can print

    • labelstringrequired
    • kindstringrequired
      one of "goal", "rhythm", "leisure", "chore"
    • nodestring or nullrequired

      the 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 null

      the ink this goal wears everywhere; a habit wears its goal's

  • countsobjectrequired
    5 fields
    • workinteger
    • doneinteger
    • openinteger
    • skippedinteger
    • unreconciledinteger
  • knowsarray of object

    server-written statements about the day (e.g. calendar and goal facts) for display when it has no plan

    2 fields
    • textstring
    • weightstring
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/day/2026-11-12 \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
GET/v1/weeks/{week}#

Get a cadence week

Any token · read only is enough

Returns 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

  • weekstringrequired

    A cadence week's ending date, or latest for the week you are in. Cadence weeks run from the account's signup day, not from a Monday, so latest saves a caller doing that arithmetic.

    pattern ^latest|\d{4}-\d{2}-\d{2}$

Responses

200 OK
  • endingstringrequired
  • fromstringrequired
  • tostringrequired
  • todaystring
  • currentboolean
  • overboolean

    its last day has gone by: replan and discuss answer 409 week_over

  • daysarray of objectrequired
    19 fields
    • datestringrequired
    • weekdaystringrequired
    • day_offboolean
    • pastboolean
    • is_todayboolean
    • plannedbooleanrequired

      a plan exists for this day

    • scheduledinteger

      realized work blocks on the day's plan

    • minutesinteger
    • acceptedboolean
    • recoveryboolean
    • effortstringrequired

      how heavy the day is, a readout of its abstract blocks — never a set cap

      one of "clear", "light", "normal", "heavy"
    • blocksarray of objectrequired

      the week's ABSTRACT, untimed blocks for this day; the day elaborates each into timed work. Distinct from items

      7 fields
      • idstringrequired
      • textstringrequired
      • goalstring or null
      • prioritystringrequired
        one of "high", "normal", "low"
      • sourcestring
        one of "agent", "user"
      • inkinteger or null
      • labelstring
    • intentstring

      what the week decided this day is for

    • goalsarray of string

      ids of the goals its blocks serve

    • itemsarray of object

      what is on the day, in order, each block naming and inking the goal it serves

      8 fields
      • startstringrequired
      • endstring
      • minutesinteger
      • taskstringrequired
      • goalstring
      • labelstring
      • inkintegerrequired
      • choreboolean
    • prioritystring
      one of "high", "normal", "low"
    • reasoningstring

      why the week put this here, in the words the user reads

    • releasedarray of string

      text of the week blocks for this day that the day plan left off at the user's request

    • tasksarray of string
  • duearray of object

    checkpoints landing in the week, and recent ones still owed

  • planobjectrequired

    note: the user's note, set by PATCH; summary: the weekly planner's closing text; written_at, by (agent or user), amendments

  • feedbackobject or null

    the last finished week's edition

  • countsobject
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/weeks/2026-11-12 \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
PATCH/v1/weeks/{week}#

Replace the week plan

Needs a token that can change things

Writes 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

  • weekstringrequired

    A cadence week's ending date, or latest for the week you are in. Cadence weeks run from the account's signup day, not from a Monday, so latest saves a caller doing that arithmetic.

    pattern ^latest|\d{4}-\d{2}-\d{2}$

Request body optional

  • daysobject

    date -> {intent, blocks:[{id, text, goal, priority, source}], reasoning}. Sent whole; this is how the weekly editor saves an accepted draft

  • notestring
    max length 400

Responses

200 OK
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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
POST/v1/weeks/{week}/discuss#

Discuss and revise a week draft

Needs a token that can change things

Sends 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

  • weekstringrequired

    A cadence week's ending date, or latest for the week you are in. Cadence weeks run from the account's signup day, not from a Monday, so latest saves a caller doing that arithmetic.

    pattern ^latest|\d{4}-\d{2}-\d{2}$

Request body required

  • messagesarray of objectrequired
    2 fields
    • whostring
    • textstring
  • draftobject or null

    the client's working week draft: {days: {date -> {intent, blocks, reasoning}}}

  • anchorstring or null

    the day being edited, or null for the whole week

  • proposeboolean

    ask the model for a revision this turn; it may still answer without one

Responses

200 OK
  • replystringrequired
  • changesarray of objectrequired
    5 fields
    • callstringrequired

      move_block | add_block | remove_block | reword | reprioritise | reword_day

    • taskstringrequired
    • wasstring
    • nowstring
    • notestring
  • draftobject or null

    the revised draft, or null when answering

400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
503 That integration is not configured on this deployment
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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
POST/v1/weeks/{week}/replan#

Run the weekly planner

Needs a token that can change things

Runs 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

  • weekstringrequired

    A cadence week's ending date, or latest for the week you are in. Cadence weeks run from the account's signup day, not from a Monday, so latest saves a caller doing that arithmetic.

    pattern ^latest|\d{4}-\d{2}-\d{2}$

Request body optional

  • briefobject

    {messages: [...], proposal: {days: {...}}}

Responses

200 OK
  • endingstring
  • workingboolean
  • plannedboolean

    whether a plan was written; false with refused when the guard would not sign off

  • refusedarray of string
  • daysarray of object
202 Accepted; anything further is sent to the address itself
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
429 Too many attempts; wait and retry — retry-after says how long
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/weeks/2026-11-12/replan \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/weeks/{week}/amend#

Apply an amendment to the week plan

Needs a token that can change things

Merges 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

  • weekstringrequired

    A cadence week's ending date, or latest for the week you are in. Cadence weeks run from the account's signup day, not from a Monday, so latest saves 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

  • whystring
    max length 400
  • fromstring

Responses

200 OK
  • today_affectedbooleanrequired

    today is among days_affected, so today's plan predates the change; consider offering POST /v1/plans/{date}/replan

  • days_affectedarray of stringrequired
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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/v1/months/{month}#

Get a four-week month block

Any token · read only is enough

Returns 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

  • monthstringrequired

    A four-week block's ending date, or latest for 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
  • endingstringrequired
  • fromstring or null
  • tostring or null
  • todaystring
  • currentboolean
  • weeksarray of objectrequired
    10 fields
    • endingstringrequired
    • fromstring
    • tostring
    • plannedintegerrequired

      days of this week that have a plan. A structural count, never a grade

    • ofintegerrequired
    • pastboolean
    • currentboolean
    • shapedboolean

      somebody has said what this week is for

    • minutesinteger

      work laid out across the week, in minutes — planned, never kept

    • daysarray of object
      7 fields
      • datestringrequired
      • weekdaystringrequired
      • is_todayboolean
      • pastboolean
      • plannedboolean
      • minutesintegerrequired
      • goalsarray of objectrequired
        3 fields
        • idstringrequired
        • inkinteger or nullrequired

          which 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
  • reportobjectrequired
    3 fields
    • statestringrequired
      one of "written", "running", "not_yet"
    • endingstringrequired
    • headlinestring
  • countsobject
  • weekdaysarray of string
  • goalsarray of object
    3 fields
    • idstringrequired
    • labelstringrequired
    • inkintegerrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/months/2026-11-12 \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
GET/v1/home#

List the openable days, weeks and months

Any token · read only is enough

Returns 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
  • todaystringrequired
  • daysobjectrequired
    2 fields
    • firststring or nullrequired
    • laststring or nullrequired
  • weeksarray of objectrequired
    10 fields
    • endingstringrequired
    • fromstring
    • tostring
    • plannedintegerrequired

      days of this week that have a plan. A structural count, never a grade

    • ofintegerrequired
    • pastboolean
    • currentboolean
    • shapedboolean

      somebody has said what this week is for

    • minutesinteger

      work laid out across the week, in minutes — planned, never kept

    • daysarray of object
      7 fields
      • datestringrequired
      • weekdaystringrequired
      • is_todayboolean
      • pastboolean
      • plannedboolean
      • minutesintegerrequired
      • goalsarray of objectrequired
        3 fields
        • idstringrequired
        • inkinteger or nullrequired

          which 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 objectrequired

    twelve slots, newest first, once the account has an anchor date (empty before); slots before the anchor are available: false with no ending

    8 fields
    • availablebooleanrequired

      true for a block within the account's lifetime; false for a placeholder before the anchor date

    • endingstring

      absent on an unavailable slot

    • fromstringrequired
    • tostringrequired
    • currentboolean
    • pastboolean
    • minutesinteger
    • reportobject
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/home \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
GET/v1/plans/{date}#

Get a day's stored plan

Any token · read only is enough

Path parameters

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
  • blocksarray of objectrequired
    6 fields
    • startstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • endstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • taskstringrequired
      max length 120
    • intereststring or nullrequired

      null for a chore or a break — see chore, which tells the two apart

    • whystringrequired
      max length 200
    • choreboolean

      work that serves no tracked goal. A block with no interest and no chore is a break: not work, and never a to-do item. Send it on PUT /v1/plans/{date} for work with no goal, or the block is stored as a break

  • laidarray of object

    the blocks the user laid out themselves, held at their hours through a rebuild

  • pushbackarray of object

    where Sereo would change one of the user's own blocks, and why. Advice only: the block stays

    2 fields
    • taskstringrequired
    • reasonstringrequired
  • outside_hoursarray of object

    on a day the user laid out: the work blocks running outside the hours they keep, kept and named

    4 fields
    • taskstringrequired
    • startstringrequired
    • endstringrequired
    • sidestringrequired
      one of "before", "after"
  • most_importantstringrequired
  • coach_notestringrequired
  • generated_atstring
  • energyinteger or null
    min 1 · max 5
  • energy_statedboolean

    true 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 charts

  • recoveryboolean
  • recovery_gapinteger or null

    days 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 string

    what 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 reason

  • releasedarray of object

    week-plan blocks for this day that the planner left off at the user's request: block is the week block id, text its text. Only written when the user's own words asked for it

    4 fields
    • blockstringrequired
    • textstring
    • whystringrequired
    • atstring
  • sourcestring
    one of "user", "scheduler"
  • accepted_atstring

    present once accepted; also counts as the user showing up for gap detection

  • on_holdarray of string
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/plans/2026-11-12 \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
PUT/v1/plans/{date}#

Save a user-laid-out day plan

Needs a token that can change things

Replaces 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body required

  • blocksarray of objectrequired
    6 fields
    • startstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • endstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • taskstringrequired
      max length 120
    • intereststring or nullrequired

      null for a chore or a break — see chore, which tells the two apart

    • whystringrequired
      max length 200
    • choreboolean

      work that serves no tracked goal. A block with no interest and no chore is a break: not work, and never a to-do item. Send it on PUT /v1/plans/{date} for work with no goal, or the block is stored as a break

  • pinsarray of object

    blocks the user has pinned to their time, matched by start and task; pins that match no saved block are dropped

    3 fields
    • startstring
    • endstring
    • taskstring
  • most_importantstring
  • coach_notestring
  • fixedarray of object

    the 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
    • startstringrequired
    • endstringrequired
    • titlestringrequired
  • acceptboolean

    also accept the day in this request; ignored if any block is refused (W8)

  • if_removesstring

    refuse, writing nothing, a save that would remove a block

    one of "refuse"
  • strictboolean

    a block whose times cannot be read fails the save (400 unreadable_blocks) instead of being left out

Responses

200 OK
  • scopestring

    how 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"
  • persistedobject

    what lasts beyond today, by kind; empty lists when nothing lasting changed

    5 fields
    • goalsarray of string
    • rulesarray of string
    • settingsarray of string
    • jobsarray of string
    • weekarray of string
  • changedobjectrequired

    what 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 string
    • addedarray of string
    • removedarray of string
    • keptarray of string
  • week_checkobject or null

    whether the rest of the week is being re-read against the day as it now stands: started, the displaced week work, or a reason it was not. The proposal lands on the day as ask.week

  • planobjectrequired
    16 fields
    • blocksarray of objectrequired
      6 fields
      • startstringrequired
        pattern ^[0-9]{2}:[0-9]{2}$
      • endstringrequired
        pattern ^[0-9]{2}:[0-9]{2}$
      • taskstringrequired
        max length 120
      • intereststring or nullrequired

        null for a chore or a break — see chore, which tells the two apart

      • whystringrequired
        max length 200
      • choreboolean

        work that serves no tracked goal. A block with no interest and no chore is a break: not work, and never a to-do item. Send it on PUT /v1/plans/{date} for work with no goal, or the block is stored as a break

    • laidarray of object

      the blocks the user laid out themselves, held at their hours through a rebuild

    • pushbackarray of object

      where Sereo would change one of the user's own blocks, and why. Advice only: the block stays

      2 fields
      • taskstringrequired
      • reasonstringrequired
    • outside_hoursarray of object

      on a day the user laid out: the work blocks running outside the hours they keep, kept and named

      4 fields
      • taskstringrequired
      • startstringrequired
      • endstringrequired
      • sidestringrequired
        one of "before", "after"
    • most_importantstringrequired
    • coach_notestringrequired
    • generated_atstring
    • energyinteger or null
      min 1 · max 5
    • energy_statedboolean

      true 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 charts

    • recoveryboolean
    • recovery_gapinteger or null

      days 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 string

      what 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 reason

    • releasedarray of object

      week-plan blocks for this day that the planner left off at the user's request: block is the week block id, text its text. Only written when the user's own words asked for it

      4 fields
      • blockstringrequired
      • textstring
      • whystringrequired
      • atstring
    • sourcestring
      one of "user", "scheduler"
    • accepted_atstring

      present once accepted; also counts as the user showing up for gap detection

    • on_holdarray of string
  • fixedarray of object

    the day's fixed times as they now stand

    3 fields
    • startstringrequired
    • endstringrequired
    • titlestringrequired
  • acceptedboolean

    whether the day is taken after this save

  • issuesarray of string
  • refusedarray of objectrequired
    4 fields
    • taskstringrequired
    • startstring or null
    • endstring or null
    • reasonstringrequired
  • rebuildobject or null
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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/v1/plans/{date}/reasoning#

Get the generation trace for a day's plan

Any token · read only is enough

Returns 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
  • daystring
  • energyinteger
  • guard_issuesarray of any
  • pressureobject
  • constraints_appliedarray of any
  • reasoningstring or null
  • promptstring
  • modelstring
  • latency_snumber
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/plans/2026-11-12/reasoning \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/plans/{date}/generate#

Generate a day's plan

Needs a token that can change things

Runs 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body optional

  • energyinteger

    a 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 5
  • moodstring
  • what_happenedstring

    the user's account of a gap, if they are returning

  • notestring

    what 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

  • forceboolean

    discard an existing plan

Responses

200 OK
  • scopestring

    how 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"
  • persistedobject

    what lasts beyond today, by kind; empty lists when nothing lasting changed

    5 fields
    • goalsarray of string
    • rulesarray of string
    • settingsarray of string
    • jobsarray of string
    • weekarray of string
  • planobjectrequired
    16 fields
    • blocksarray of objectrequired
      6 fields
      • startstringrequired
        pattern ^[0-9]{2}:[0-9]{2}$
      • endstringrequired
        pattern ^[0-9]{2}:[0-9]{2}$
      • taskstringrequired
        max length 120
      • intereststring or nullrequired

        null for a chore or a break — see chore, which tells the two apart

      • whystringrequired
        max length 200
      • choreboolean

        work that serves no tracked goal. A block with no interest and no chore is a break: not work, and never a to-do item. Send it on PUT /v1/plans/{date} for work with no goal, or the block is stored as a break

    • laidarray of object

      the blocks the user laid out themselves, held at their hours through a rebuild

    • pushbackarray of object

      where Sereo would change one of the user's own blocks, and why. Advice only: the block stays

      2 fields
      • taskstringrequired
      • reasonstringrequired
    • outside_hoursarray of object

      on a day the user laid out: the work blocks running outside the hours they keep, kept and named

      4 fields
      • taskstringrequired
      • startstringrequired
      • endstringrequired
      • sidestringrequired
        one of "before", "after"
    • most_importantstringrequired
    • coach_notestringrequired
    • generated_atstring
    • energyinteger or null
      min 1 · max 5
    • energy_statedboolean

      true 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 charts

    • recoveryboolean
    • recovery_gapinteger or null

      days 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 string

      what 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 reason

    • releasedarray of object

      week-plan blocks for this day that the planner left off at the user's request: block is the week block id, text its text. Only written when the user's own words asked for it

      4 fields
      • blockstringrequired
      • textstring
      • whystringrequired
      • atstring
    • sourcestring
      one of "user", "scheduler"
    • accepted_atstring

      present once accepted; also counts as the user showing up for gap detection

    • on_holdarray of string
  • recovery_gapinteger or null
  • acceptedboolean

    always false: a generated plan is a proposal until accepted

  • rebuildobject or null
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/generate \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
GET/v1/plans/{date}/stream#

Stream plan-build progress events

Any token · read only is enough

Opens 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/plans/2026-11-12/stream \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/plans/{date}/replan#

Regenerate a day's plan from user feedback

Needs a token that can change things

Rebuilds 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body optional

  • notestring

    the user's feedback, verbatim

  • askboolean

    the caller can relay a clarifying question to the user. Without it an unclear part is passed to the planner in the note

  • energyinteger
    min 1 · max 5
  • moodstring
  • freshboolean

    start 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
  • scopestring

    how 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"
  • persistedobject

    what lasts beyond today, by kind; empty lists when nothing lasting changed

    5 fields
    • goalsarray of string
    • rulesarray of string
    • settingsarray of string
    • jobsarray of string
    • weekarray of string
  • week_checkobject or null

    whether the rest of the week is being re-read against the day as it now stands: started, the displaced week work, or a reason it was not. The proposal lands on the day as ask.week

  • planobjectrequired
    16 fields
    • blocksarray of objectrequired
      6 fields
      • startstringrequired
        pattern ^[0-9]{2}:[0-9]{2}$
      • endstringrequired
        pattern ^[0-9]{2}:[0-9]{2}$
      • taskstringrequired
        max length 120
      • intereststring or nullrequired

        null for a chore or a break — see chore, which tells the two apart

      • whystringrequired
        max length 200
      • choreboolean

        work that serves no tracked goal. A block with no interest and no chore is a break: not work, and never a to-do item. Send it on PUT /v1/plans/{date} for work with no goal, or the block is stored as a break

    • laidarray of object

      the blocks the user laid out themselves, held at their hours through a rebuild

    • pushbackarray of object

      where Sereo would change one of the user's own blocks, and why. Advice only: the block stays

      2 fields
      • taskstringrequired
      • reasonstringrequired
    • outside_hoursarray of object

      on a day the user laid out: the work blocks running outside the hours they keep, kept and named

      4 fields
      • taskstringrequired
      • startstringrequired
      • endstringrequired
      • sidestringrequired
        one of "before", "after"
    • most_importantstringrequired
    • coach_notestringrequired
    • generated_atstring
    • energyinteger or null
      min 1 · max 5
    • energy_statedboolean

      true 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 charts

    • recoveryboolean
    • recovery_gapinteger or null

      days 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 string

      what 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 reason

    • releasedarray of object

      week-plan blocks for this day that the planner left off at the user's request: block is the week block id, text its text. Only written when the user's own words asked for it

      4 fields
      • blockstringrequired
      • textstring
      • whystringrequired
      • atstring
    • sourcestring
      one of "user", "scheduler"
    • accepted_atstring

      present once accepted; also counts as the user showing up for gap detection

    • on_holdarray of string
  • stabilitynumberrequired

    share of the previous plan unchanged; cannot show removals, use changed

    min 0 · max 1
  • movedintegerrequired

    length of changed.moved

    min 0
  • changedobjectrequired

    the 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's no_room: issues and unfit. Display this rather than any model-written summary.

    4 fields
    • movedarray of stringrequired

      on the day before and after, at a different hour

    • addedarray of stringrequired
    • removedarray of stringrequired

      was on the day and is not. Never fold this into a count — name them

    • keptarray of stringrequired

      same task, same hour

  • previousobject or null
  • acceptedboolean
  • rebuildobject or null
  • questionobject or null

    set when the note needs an answer first; nothing was written or rebuilt

    2 fields
    • textstring
    • optionsarray of string
  • understoodarray of object

    what became of each part of the note

    3 fields
    • kindstringrequired
    • saysstringrequired
    • appliedstringrequired
  • proposalsarray of object

    lasting changes found in the note; not written. Apply one with POST /v1/lasting when the user agrees

    10 fields
    • kindstringrequired
      one of "weekly", "rule", "hours"
    • titlestring
    • daysarray of integer
    • startstring
    • endstring
    • textstring
    • day_startstring
    • day_endstring
    • forstring

      a habit or goal id: the weekly time is reserved for it, not busy

    • saysstring
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/replan \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/plans/{date}/suggest#

Suggest tasks for an open time slot

Needs a token that can change things

Returns 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body optional

  • atstring

    HH:MM the stretch begins

  • minutesinteger

    how long it is; 0 for no limit

  • notestring

    anything the user said they want there

  • askboolean

    have the model choose from the ranking; invokes the model once. Absent or false: deterministic ranking, no model call

  • dayarray of object

    the client's unsaved draft of the day, used only with ask to describe the neighbouring blocks to the model. Never stored

    6 fields
    • startstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • endstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • taskstringrequired
      max length 120
    • intereststring or nullrequired

      null for a chore or a break — see chore, which tells the two apart

    • whystringrequired
      max length 200
    • choreboolean

      work that serves no tracked goal. A block with no interest and no chore is a break: not work, and never a to-do item. Send it on PUT /v1/plans/{date} for work with no goal, or the block is stored as a break

Responses

200 OK
  • modestringrequired

    how this answer was arrived at

    one of "ranked", "reasoned"
  • notestring or null

    why it is ranked rather than reasoned, when it is

  • picksarray of objectrequired
    8 fields
    • taskstringrequired
    • intereststring or nullrequired

      null when it serves no goal, which only an off-list pick does

    • registeredbooleanrequired

      true for a tracked interest; false for the single off-list pick a reasoned answer may add

    • kindstring
    • tagstring
    • nodestring or null
    • minutesintegerrequired
    • whystringrequired
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/suggest \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/plans/{date}/discuss#

Discuss a draft day with the planner

Needs a token that can change things

Sends 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body required

  • messagesarray of objectrequired

    The client-held transcript, oldest first; the last entry must have who: "user". Only the last 12 entries are used, each truncated to 1000 characters; any who other than user is treated as the planner.

    2 fields
    • whostring
      one of "user", "planner"
    • textstring
  • blocksarray of objectrequired

    the editor's working copy

    6 fields
    • startstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • endstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • taskstringrequired
      max length 120
    • intereststring or nullrequired

      null for a chore or a break — see chore, which tells the two apart

    • whystringrequired
      max length 200
    • choreboolean

      work that serves no tracked goal. A block with no interest and no chore is a break: not work, and never a to-do item. Send it on PUT /v1/plans/{date} for work with no goal, or the block is stored as a break

  • anchorobject or null

    Restricts the revision to one block, matched on task and start. Changes the model makes to any other block are discarded and reported in issues as outside_anchor:<task>.

    2 fields
    • startstring
    • taskstring
  • pinsarray of string

    Task 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 issues as pinned_block_kept:<task>.

  • proposeboolean

    When true, the model is instructed to return a revised block list this turn.

Responses

200 OK
  • replystringrequired
  • blocksarray or null

    the working copy's replacement, or null when the day stands

    6 fields
    • startstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • endstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • taskstringrequired
      max length 120
    • intereststring or nullrequired

      null for a chore or a break — see chore, which tells the two apart

    • whystringrequired
      max length 200
    • choreboolean

      work that serves no tracked goal. A block with no interest and no chore is a break: not work, and never a to-do item. Send it on PUT /v1/plans/{date} for work with no goal, or the block is stored as a break

  • changesarray of object

    Per-block differences between the submitted blocks and the returned ones, computed by the server (never the model's own account). call is added, removed, moved (start changed, possibly also length) or resized (same start, different length); was/now carry {start, end}.

    5 fields
    • callstring
      one of "added", "removed", "moved", "resized"
    • taskstring
    • wasobject or null
    • nowobject or null
    • notestring
  • issuesarray of string
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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
POST/v1/plans/{date}/escalate#

Send a message about a day

Needs a token that can change things

Interprets 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. changed holds moved/added/removed/kept, plan the new plan, accepted/rebuild the re-acceptance of an already accepted day's to-do list, unfit blocks that no longer fit, and pushback objections 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 with working: true; the resulting proposal appears on GET /v1/day/{date} under ask and is applied only by POST /v1/weeks/{week}/amend or 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.week names the weekdays; today_affected is 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 and working is 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body required

  • questionstringrequired
  • messagesarray of object

Responses

200 OK
  • scopestring

    how 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"
  • persistedobject

    what lasts beyond today, by kind; empty lists when nothing lasting changed

    5 fields
    • goalsarray of string
    • rulesarray of string
    • settingsarray of string
    • jobsarray of string
    • weekarray of string
  • answerstringrequired
  • pushbackarray of object

    The user's own blocks the planner would have changed, each with its reason. These blocks are left as they are.

    2 fields
    • taskstringrequired
    • reasonstringrequired
  • didstringrequired
    one of "answered", "changed", "escalated", "finished", "held", "ruled", "adjusted", "week_changed", "unruled", "hours_changed", "reranked", "goal_added", "job_removed"
  • overrideboolean

    True when the user's words were read as an explicit override of the planner's objection: the request was carried out and no pushback is returned.

  • today_affectedboolean
  • escalatedbooleanrequired
  • workingboolean

    A background week re-read is running for this day. Poll GET /v1/day/{date}: its ask field carries the steps and, when finished, the proposed week change.

  • ceiling_reachedboolean
  • changedobject
  • planobject
  • acceptedboolean
  • rebuildobject or null
  • driftarray of object
  • stalearray of string
  • endingstring
  • unfitarray of object
    6 fields
    • taskstringrequired
    • goalstring or null
    • minutesinteger or null
    • askedboolean
    • whystringrequired
    • offersarray of object
      8 fields
      • kindstringrequired
        one of "move", "drop_habit"
      • textstringrequired
      • tostring
      • day_labelstring
      • effortstring
      • free_minutesinteger
      • taskstring
      • intereststring or null
  • weekobject
    4 fields
    • answerstringrequired
    • reasoningstring
    • amendmentobject or nullrequired

      the proposed days, {days: {date: entry}}, in the week plan's own shape; null when the week would stand

    • refusedarray of object
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
429 Too many attempts; wait and retry — retry-after says how long
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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": "…"}'
POST/v1/conversation#

Send a message to the account conversation

Needs a token that can change things

Same 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

  • messagestringrequired
  • datestring
  • messagesarray of object

Responses

200 OK
  • scopestring

    how 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"
  • persistedobject

    what lasts beyond today, by kind; empty lists when nothing lasting changed

    5 fields
    • goalsarray of string
    • rulesarray of string
    • settingsarray of string
    • jobsarray of string
    • weekarray of string
  • answerstringrequired
  • pushbackarray of object

    The user's own blocks the planner would have changed, each with its reason. These blocks are left as they are.

    2 fields
    • taskstringrequired
    • reasonstringrequired
  • didstringrequired
    one of "answered", "changed", "escalated", "finished", "held", "ruled", "adjusted", "week_changed", "unruled", "hours_changed", "reranked", "goal_added", "job_removed"
  • overrideboolean

    True when the user's words were read as an explicit override of the planner's objection: the request was carried out and no pushback is returned.

  • today_affectedboolean
  • escalatedbooleanrequired
  • workingboolean

    A background week re-read is running for this day. Poll GET /v1/day/{date}: its ask field carries the steps and, when finished, the proposed week change.

  • ceiling_reachedboolean
  • changedobject
  • planobject
  • acceptedboolean
  • rebuildobject or null
  • driftarray of object
  • stalearray of string
  • endingstring
  • unfitarray of object
    6 fields
    • taskstringrequired
    • goalstring or null
    • minutesinteger or null
    • askedboolean
    • whystringrequired
    • offersarray of object
      8 fields
      • kindstringrequired
        one of "move", "drop_habit"
      • textstringrequired
      • tostring
      • day_labelstring
      • effortstring
      • free_minutesinteger
      • taskstring
      • intereststring or null
  • weekobject
    4 fields
    • answerstringrequired
    • reasoningstring
    • amendmentobject or nullrequired

      the proposed days, {days: {date: entry}}, in the week plan's own shape; null when the week would stand

    • refusedarray of object
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
429 Too many attempts; wait and retry — retry-after says how long
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/conversation \
  -H "Authorization: Bearer $SEREO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "…"}'
POST/v1/plans/{date}/unfit#

Resolve a block that did not fit the day

Needs a token that can change things

Applies 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's to, through the week-amendment writer, and removes the entry from today's unfit. 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body required

  • taskstringrequired
  • choicestringrequired
    one of "move", "drop_habit"

Responses

200 OK
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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"}'
POST/v1/plans/{date}/week-proposal/leave#

Dismiss a pending week proposal for a day

Needs a token that can change things

Dismisses 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
  • leftbooleanrequired
  • scopestring
  • persistedobject
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/week-proposal/leave \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
PUT/v1/plans/{date}/fixed#

Replace a day's fixed busy times

Needs a token that can change things

Replaces 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body required

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

Responses

200 OK
  • fixedarray of objectrequired
    3 fields
    • startstringrequired
    • endstringrequired
    • titlestringrequired
  • scopestring

    how 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"
  • persistedobject

    what lasts beyond today, by kind; empty lists when nothing lasting changed

    5 fields
    • goalsarray of string
    • rulesarray of string
    • settingsarray of string
    • jobsarray of string
    • weekarray of string
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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
POST/v1/constraints#

Create a standing rule

Needs a token that can change things

Adds 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

  • textstringrequired
    max length 300
  • kindstring

    defaults to scheduling

    one of "gate", "scheduling", "content"
  • applies_toarray of string

    interest ids, or ["all"] (the default)

Responses

200 OK
  • idstringrequired
  • textstringrequired
  • kindstringrequired
  • priorityintegerrequired
  • applies_toarray of stringrequired
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/constraints \
  -H "Authorization: Bearer $SEREO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "…"}'
POST/v1/lasting#

Save a lasting change proposed by a replan

Needs a token that can change things

Writes 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 weekdays days (0 = Monday) from start to end (HH:MM, start before end), titled title (default "Not available"). Added to hours_off, replacing any window it overlaps on those weekdays. With for (a goal or habit id) it is added to free_by_weekday instead, as time reserved for that interest. The response returns the updated map. - rule — text becomes a standing rule, as with POST /v1/constraints and kind: "scheduling"; returned as rule. - hours — sets day_start and/or day_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

  • proposalobjectrequired
    10 fields
    • kindstringrequired
      one of "weekly", "rule", "hours"
    • titlestring
    • daysarray of integer
    • startstring
    • endstring
    • textstring
    • day_startstring
    • day_endstring
    • forstring

      a habit or goal id: the weekly time is reserved for it, not busy

    • saysstring

Responses

200 OK
  • keptstringrequired
    one of "weekly", "rule", "hours"
  • hours_offobject
  • free_by_weekdayobject
  • ruleobject
  • day_startstring
  • day_endstring
  • scopestring

    how 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"
  • persistedobject

    what lasts beyond today, by kind; empty lists when nothing lasting changed

    5 fields
    • goalsarray of string
    • rulesarray of string
    • settingsarray of string
    • jobsarray of string
    • weekarray of string
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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/v1/constraints/{constraint}#

Delete a standing rule

Needs a token that can change things

Removes 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

  • constraintstringrequired

    A 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
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X DELETE https://app.usesereo.com/v1/constraints/$CONSTRAINT \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/plans/{date}/keep#

Keep a chore the planner suggested

Needs a token that can change things

Turns 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body required

  • taskstringrequired

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

Responses

200 OK
  • keptstring or nullrequired

    The 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
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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": "…"}'
POST/v1/plans/{date}/energy#

Set the energy level for a planned day

Needs a token that can change things

Records 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body required

  • energyintegerrequired
    min 1 · max 5

Responses

200 OK
  • datestringrequired
  • energyintegerrequired
  • energy_statedbooleanrequired
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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}'
POST/v1/plans/{date}/reshape#

Set a day's editing state

Needs a token that can change things

Sets 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body required

  • onbooleanrequired

Responses

200 OK
  • datestringrequired
  • reshapingbooleanrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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/v1/reports/{period}/{date}#

Get a weekly or monthly report

Any token · read only is enough

Returns 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

  • periodstringrequired

    week or month.

    pattern ^week|month$
  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
  • periodstringrequired
    one of "week", "month"
  • endingstringrequired
  • fromstring
  • tostring
  • weekinteger

    ISO week number of ending

  • labelstring

    what 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 null

    the weeks a monthly period actually covers, to run under its name; null for a week

  • issueobject

    the 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
    • nointeger
    • yearinteger
  • writtenboolean

    whether the prose has been generated yet

  • readinessobjectrequired
    5 fields
    • readybooleanrequired
    • on_recordintegerrequired
    • ofintegerrequired
    • unitstring
    • ready_onstring or null

      the 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 null

    of what was ANSWERED, not of what was planned — null when nothing was answered, because silence is not nought per cent

  • plannedinteger
  • keptinteger
  • tracksarray of objectrequired
    23 fields
    • idstringrequired
    • labelstringrequired
    • inkinteger or null

      the ink this goal wears everywhere

    • unitstring
    • totalintegerrequired
    • doneintegerrequired

      everything behind them

    • addedinteger

      what this period added

    • shouldintegerrequired

      the 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

    • floorinteger

      what stands whatever the current milestone's date does — the bar position where its window begins

    • current_blocksinteger

      the current milestone's own size; with window_days, what a preview needs to re-run the pacing exactly

    • window_daysinteger

      how long the current milestone's own stretch of the goal runs

    • statestring

      the 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 shortfall

      one of "behind_plan", "behind_date", "not_due_yet", "kept"
    • plan_shortinteger

      blocks short of the period's plan (prescribed - done), never negative

      min 0
    • date_shortinteger

      blocks short of the date mark, whole-block floored, never negative

      min 0
    • date_fixedboolean

      the current milestone's date is not the plan's to move — fixed_reason, an integration's, or adjudicated by somebody else

    • behindinteger

      blocks short of the date mark — the bar's gap piece; same number as date_short

      min 0
    • daysinteger or null
    • statusstring or null
    • milestonestring or null
    • milestone_duestring or null

      the date the pace line answers to

    • askedinteger

      blocks this period's plans prescribed for the goal

    • prescribedinteger

      the PLAN line: where the bar would sit had every block the period's plans prescribed landed

    • pacenumber

      the 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 object

    per 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
    • daystring
    • datestring
    • valueinteger or null

      null when nobody said

      min 1 · max 5
    • hardboolean

      the plan was rebuilt after a gap

    • plannedinteger
    • keptinteger
  • blockedobject
    3 fields
    • plannedinteger
    • splitarray of object
    • causesarray of object

      days that lost blocks, with what the user wrote on that day's check-in. Refusals only, and nobody's words but theirs

  • daysarray of object
  • parkedarray of object

    what 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 prose

    4 fields
    • idstring
    • labelstring
    • untilstring or null
    • whystring or null
  • weekday_profilearray of object

    one entry per weekday: blocks on an average Monday, an average Tuesday, across the period

    6 fields
    • daystring
    • plannednumber

      blocks planned into an average one of these

    • keptnumber

      and blocks kept — the page used to derive this from the share

    • kept_sharenumber or null
    • low_daysinteger
    • daysinteger
  • goal_hoursarray of object
  • streaksarray of object
  • energy_outarray of object
  • archivearray of objectrequired

    The account's last 32 cadence weeks, ending at the newest finished week (or at the requested ending if later), each with ending, ISO week, kept share, had_days and written. Independent of which issue is requested.

  • archive_monthsarray of object

    The 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 null

    The next weekly report: its period ending and the date and time it is due to be written, computed from the account's cadence and the current date, independent of the requested ending. Null when it cannot be computed.

    3 fields
    • endingstring
    • datestring
    • timestring
  • latestobject

    Per period, the newest ending that has a written report, or null. Use it to open the latest issue instead of computing a cadence-week ending.

    2 fields
    • weekstring or null
    • monthstring or null
  • arrivesobject

    present only while a period is unfinished: when it will be written

    2 fields
    • datestring
    • timestring
  • headlinestring
  • findingsarray of object
  • proposal_introstring
  • proposalsarray of object
    13 fields
    • kindstringrequired
      one of "Move a date", "Protect hours", "Do it now", "Drop a goal", "Schedule less"
    • goalstring
    • goal_idstring or null
    • titlestringrequired
    • whystring
    • effectstring
    • shift_daysinteger
    • park_daysinteger

      "Drop a goal" only: how long the goal is parked if agreed, in days, clamped to 14–56.

    • gain_blocksinteger
    • answerstring or null
      one of "yes", "argue", "no", null
    • notestring
    • appliedobject
    • previewobject or null

      What agreeing would do, per kind, computed from the same tracks the report returns. Only a "Move a date" preview carries mark positions (should, done, total, ...); for other kinds line describes the effect.

      14 fields
      • goal_idstring or null
      • labelstring or null
      • effect_kindstring or null
        one of "move", "park", "free", "protect", "now", null
      • linestring or null

        The preview sentence, written server-side.

      • shouldnumber

        Move only: the expected-by-now mark if agreed, unrounded.every realistic shift)

      • should_nownumber

        move only: the mark as it stands, exact

      • donenumber
      • done_nownumber
      • totalnumber
      • new_duestring or null

        move only: where the current milestone's date would land

      • still_lateboolean

        move only: the shifted date is still behind you

      • park_untilstring

        park only

      • park_weeksinteger

        park only

      • freedinteger

        free only: blocks a week bought back

  • generated_atstring
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/reports/week/2026-11-12 \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/reports/{period}/{date}#

Generate a report's prose and proposals

Needs a token that can change things

Generates 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

  • periodstringrequired

    week or month.

    pattern ^week|month$
  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
  • periodstringrequired
    one of "week", "month"
  • endingstringrequired
  • fromstring
  • tostring
  • weekinteger

    ISO week number of ending

  • labelstring

    what 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 null

    the weeks a monthly period actually covers, to run under its name; null for a week

  • issueobject

    the 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
    • nointeger
    • yearinteger
  • writtenboolean

    whether the prose has been generated yet

  • readinessobjectrequired
    5 fields
    • readybooleanrequired
    • on_recordintegerrequired
    • ofintegerrequired
    • unitstring
    • ready_onstring or null

      the 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 null

    of what was ANSWERED, not of what was planned — null when nothing was answered, because silence is not nought per cent

  • plannedinteger
  • keptinteger
  • tracksarray of objectrequired
    23 fields
    • idstringrequired
    • labelstringrequired
    • inkinteger or null

      the ink this goal wears everywhere

    • unitstring
    • totalintegerrequired
    • doneintegerrequired

      everything behind them

    • addedinteger

      what this period added

    • shouldintegerrequired

      the 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

    • floorinteger

      what stands whatever the current milestone's date does — the bar position where its window begins

    • current_blocksinteger

      the current milestone's own size; with window_days, what a preview needs to re-run the pacing exactly

    • window_daysinteger

      how long the current milestone's own stretch of the goal runs

    • statestring

      the 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 shortfall

      one of "behind_plan", "behind_date", "not_due_yet", "kept"
    • plan_shortinteger

      blocks short of the period's plan (prescribed - done), never negative

      min 0
    • date_shortinteger

      blocks short of the date mark, whole-block floored, never negative

      min 0
    • date_fixedboolean

      the current milestone's date is not the plan's to move — fixed_reason, an integration's, or adjudicated by somebody else

    • behindinteger

      blocks short of the date mark — the bar's gap piece; same number as date_short

      min 0
    • daysinteger or null
    • statusstring or null
    • milestonestring or null
    • milestone_duestring or null

      the date the pace line answers to

    • askedinteger

      blocks this period's plans prescribed for the goal

    • prescribedinteger

      the PLAN line: where the bar would sit had every block the period's plans prescribed landed

    • pacenumber

      the 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 object

    per 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
    • daystring
    • datestring
    • valueinteger or null

      null when nobody said

      min 1 · max 5
    • hardboolean

      the plan was rebuilt after a gap

    • plannedinteger
    • keptinteger
  • blockedobject
    3 fields
    • plannedinteger
    • splitarray of object
    • causesarray of object

      days that lost blocks, with what the user wrote on that day's check-in. Refusals only, and nobody's words but theirs

  • daysarray of object
  • parkedarray of object

    what 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 prose

    4 fields
    • idstring
    • labelstring
    • untilstring or null
    • whystring or null
  • weekday_profilearray of object

    one entry per weekday: blocks on an average Monday, an average Tuesday, across the period

    6 fields
    • daystring
    • plannednumber

      blocks planned into an average one of these

    • keptnumber

      and blocks kept — the page used to derive this from the share

    • kept_sharenumber or null
    • low_daysinteger
    • daysinteger
  • goal_hoursarray of object
  • streaksarray of object
  • energy_outarray of object
  • archivearray of objectrequired

    The account's last 32 cadence weeks, ending at the newest finished week (or at the requested ending if later), each with ending, ISO week, kept share, had_days and written. Independent of which issue is requested.

  • archive_monthsarray of object

    The 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 null

    The next weekly report: its period ending and the date and time it is due to be written, computed from the account's cadence and the current date, independent of the requested ending. Null when it cannot be computed.

    3 fields
    • endingstring
    • datestring
    • timestring
  • latestobject

    Per period, the newest ending that has a written report, or null. Use it to open the latest issue instead of computing a cadence-week ending.

    2 fields
    • weekstring or null
    • monthstring or null
  • arrivesobject

    present only while a period is unfinished: when it will be written

    2 fields
    • datestring
    • timestring
  • headlinestring
  • findingsarray of object
  • proposal_introstring
  • proposalsarray of object
    13 fields
    • kindstringrequired
      one of "Move a date", "Protect hours", "Do it now", "Drop a goal", "Schedule less"
    • goalstring
    • goal_idstring or null
    • titlestringrequired
    • whystring
    • effectstring
    • shift_daysinteger
    • park_daysinteger

      "Drop a goal" only: how long the goal is parked if agreed, in days, clamped to 14–56.

    • gain_blocksinteger
    • answerstring or null
      one of "yes", "argue", "no", null
    • notestring
    • appliedobject
    • previewobject or null

      What agreeing would do, per kind, computed from the same tracks the report returns. Only a "Move a date" preview carries mark positions (should, done, total, ...); for other kinds line describes the effect.

      14 fields
      • goal_idstring or null
      • labelstring or null
      • effect_kindstring or null
        one of "move", "park", "free", "protect", "now", null
      • linestring or null

        The preview sentence, written server-side.

      • shouldnumber

        Move only: the expected-by-now mark if agreed, unrounded.every realistic shift)

      • should_nownumber

        move only: the mark as it stands, exact

      • donenumber
      • done_nownumber
      • totalnumber
      • new_duestring or null

        move only: where the current milestone's date would land

      • still_lateboolean

        move only: the shifted date is still behind you

      • park_untilstring

        park only

      • park_weeksinteger

        park only

      • freedinteger

        free only: blocks a week bought back

  • generated_atstring
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/reports/week/2026-11-12 \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/reports/{period}/{date}/seen#

Mark a report as read

Needs a token that can change things

Sets 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

  • periodstringrequired

    week or month.

    pattern ^week|month$
  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
  • seenboolean
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/reports/week/2026-11-12/seen \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/reports/{period}/{date}/proposals/{index}/discuss#

Discuss a report proposal with the model

Needs a token that can change things

Sends 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

  • periodstringrequired

    week or month.

    pattern ^week|month$
  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$
  • indexstringrequired

    Which proposal, counting from zero.

    pattern ^[0-9]{1,2}$

Request body required

  • messagesarray of objectrequired
    2 fields
    • whostring
    • textstring

Responses

200 OK
  • replystringrequired
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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
POST/v1/reports/{period}/{date}/proposals/{index}#

Answer a report proposal

Needs a token that can change things

Records 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 by shift_days. Milestones with a fixed date or owned by an integration are not moved and are named in applied.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 with kind: "gate". - Drop a goal — parks the goal until park_days after 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

  • periodstringrequired

    week or month.

    pattern ^week|month$
  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$
  • indexstringrequired

    Which proposal, counting from zero.

    pattern ^[0-9]{1,2}$

Request body required

  • answerstringrequired
    one of "yes", "argue", "no"
  • for_goodboolean

    Only 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
  • proposalobjectrequired
    13 fields
    • kindstringrequired
      one of "Move a date", "Protect hours", "Do it now", "Drop a goal", "Schedule less"
    • goalstring
    • goal_idstring or null
    • titlestringrequired
    • whystring
    • effectstring
    • shift_daysinteger
    • park_daysinteger

      "Drop a goal" only: how long the goal is parked if agreed, in days, clamped to 14–56.

    • gain_blocksinteger
    • answerstring or null
      one of "yes", "argue", "no", null
    • notestring
    • appliedobject
    • previewobject or null

      What agreeing would do, per kind, computed from the same tracks the report returns. Only a "Move a date" preview carries mark positions (should, done, total, ...); for other kinds line describes the effect.

      14 fields
      • goal_idstring or null
      • labelstring or null
      • effect_kindstring or null
        one of "move", "park", "free", "protect", "now", null
      • linestring or null

        The preview sentence, written server-side.

      • shouldnumber

        Move only: the expected-by-now mark if agreed, unrounded.every realistic shift)

      • should_nownumber

        move only: the mark as it stands, exact

      • donenumber
      • done_nownumber
      • totalnumber
      • new_duestring or null

        move only: where the current milestone's date would land

      • still_lateboolean

        move only: the shifted date is still behind you

      • park_untilstring

        park only

      • park_weeksinteger

        park only

      • freedinteger

        free only: blocks a week bought back

  • appliedobject or null
  • refusedboolean

    whether this answer was recorded as a refusal for good

400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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.

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

Accept a day's plan

Needs a token that can change things

Accepts 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
  • todosobjectrequired
    10 fields
    • datestringrequired
    • accepted_atstring or null
    • acceptedboolean
    • read_onlybooleanrequired

      true 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 objectrequired
      12 fields
      • idstringrequired
        pattern ^t_[a-f0-9]+$
      • startstring or null
      • endstring or null
      • titlestringrequired
      • whystring
      • intereststringrequired
      • statusstringrequired

        the stored status. Display derived_status instead

        one of "open", "done", "skipped"
      • derived_statusstring

        what to display. unreconciled means 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 null
      • off_planboolean

        true for an answered item whose block is no longer in the plan; kept so the answer is not lost

      • commentsarray of object
        3 fields
        • tsstring
        • textstring
        • external_idstring
      • todoistobject
    • openintegerrequired
    • doneintegerrequired
    • skippedintegerrequired
    • unreconciledintegerrequired
    • pending_reconciliationarray of object

      past days within the last two days that still have stored-open items

      2 fields
      • datestring
      • countinteger
  • rebuildobjectrequired
    4 fields
    • carried_overarray of any
    • kept_off_planarray of any

      titles of answered items no longer in the plan, kept with off_plan: true

    • droppedarray of any

      always empty; answered items are never dropped

    • rebuilt_atstring
  • todoistobject
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/accept \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/plans/{date}/checkin#

Record a check-in by block number

Needs a token that can change things

Writes 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Request body optional

  • donestring

    comma-separated 1-based block numbers as a string, e.g. "1,3"

  • skippedstring

    comma-separated 1-based block numbers, as for done

  • notestring

Responses

200 OK
  • done_tasksarray of string
  • skipped_tasksarray of string
  • unreconciled_tasksarray of string

    titles of items still open more than two days after their day. Never included in skipped_tasks: an unanswered item is not a miss

  • done_interestsarray of string

    duplicates are meaningful: membership credits a habit's weekly cadence once, while each occurrence credits one block of a project's milestone

  • notestring or null
  • tsstring
  • sourcestring

    todos when rebuilt from an accepted to-do list; absent on a block-number check-in

400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/plans/2026-11-12/checkin \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
GET/v1/todos#

Get a day's to-do list

Any token · read only is enough

Returns 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

  • datestring

    The day, YYYY-MM-DD. Defaults to today.

Responses

200 OK
  • datestringrequired
  • accepted_atstring or null
  • acceptedboolean
  • read_onlybooleanrequired

    true 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 objectrequired
    12 fields
    • idstringrequired
      pattern ^t_[a-f0-9]+$
    • startstring or null
    • endstring or null
    • titlestringrequired
    • whystring
    • intereststringrequired
    • statusstringrequired

      the stored status. Display derived_status instead

      one of "open", "done", "skipped"
    • derived_statusstring

      what to display. unreconciled means 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 null
    • off_planboolean

      true for an answered item whose block is no longer in the plan; kept so the answer is not lost

    • commentsarray of object
      3 fields
      • tsstring
      • textstring
      • external_idstring
    • todoistobject
  • openintegerrequired
  • doneintegerrequired
  • skippedintegerrequired
  • unreconciledintegerrequired
  • pending_reconciliationarray of object

    past days within the last two days that still have stored-open items

    2 fields
    • datestring
    • countinteger
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/todos \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/todos/{todo}/status#

Set a to-do's status

Needs a token that can change things

Sets 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

  • todostringrequired

    A to-do id from GET /v1/todos.

    pattern ^t_[a-f0-9]{6,32}$

Request body required

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

Responses

200 OK
  • idstringrequired
    pattern ^t_[a-f0-9]+$
  • startstring or null
  • endstring or null
  • titlestringrequired
  • whystring
  • intereststringrequired
  • statusstringrequired

    the stored status. Display derived_status instead

    one of "open", "done", "skipped"
  • derived_statusstring

    what to display. unreconciled means 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 null
  • off_planboolean

    true for an answered item whose block is no longer in the plan; kept so the answer is not lost

  • commentsarray of object
    3 fields
    • tsstring
    • textstring
    • external_idstring
  • todoistobject
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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"}'
POST/v1/todos/{todo}/comments#

Add a comment to a to-do

Needs a token that can change things

Appends 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

  • todostringrequired

    A to-do id from GET /v1/todos.

    pattern ^t_[a-f0-9]{6,32}$

Request body required

  • textstringrequired
  • datestring

Responses

201 Created
  • tsstringrequired
  • textstringrequired
  • external_idstring
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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/v1/profile#

Get the profile

Any token · read only is enough

Returns 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 *_from is stated, sleep or default. Read this rather than day_start/day_end, which are absent when the window follows sleep. - never — the unavailable hours as [{label, start, end, days}] rows, the shape PATCH /v1/profile accepts. With no sleep stated, the edges of the day window in force (defaults included) appear as rows. - never_stated — whether any of sleep, day_start, day_end or hours_off is set. - never_suggested — a default sleep row for a first-run form.

For interests with derived state, use GET /v1/library.

Responses

200 OK
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/profile \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
PATCH/v1/profile#

Update profile settings

Needs a token that can change things

Updates 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

  • timezonestring

    IANA name

  • neverarray or null

    The complete set of unavailable hours, as rows; replaces sleep, hours_off, day_start and day_end. null or [] clears them all

    4 fields
    • labelstring
    • startstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • endstringrequired
      pattern ^[0-9]{2}:[0-9]{2}$
    • daysarray or null
  • day_startstring or null
    pattern ^[0-9]{2}:[0-9]{2}$
  • day_endstring or null
    pattern ^[0-9]{2}:[0-9]{2}$
  • days_offarray or null

    Weekdays 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 null

    Recurring 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_off covers whole days; this field covers hours within a day. Replaced wholesale when never is sent.

  • placestring or null
  • latitudenumber or null
    min -90 · max 90
  • longitudenumber or null
    min -180 · max 180
  • default_energyinteger or null
    min 1 · max 5
  • buffer_after_shift_minutesinteger or null
  • sleepobject 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 changed

    2 fields
    • startstring
    • endstring
  • quiet_hoursobject or null
    2 fields
    • startstring
    • endstring
  • morning_plan_timestring or null
  • evening_checkin_timestring or null
  • miss_sweep_timestring or null
  • weekly_retro_timestring or null
  • todoist_sync_minutesinteger or null
  • auto_planboolean or null

    whether Sereo may pre-build days — the morning plan and the post-absence re-entry day. Off by default

  • evening_checkinboolean or null

    whether the evening check-in is asked for. Absent or true: on; false: no check-in and no nudge

Responses

200 OK
  • changedarray of stringrequired
  • profileobjectrequired
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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
GET/v1/library#

List interests with derived state

Any token · read only is enough

Returns 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

  • datestring

    Compute derived state for this day instead of today.

Responses

200 OK
  • onboardedbooleanrequired
  • datestring
  • completed_goalsarray of object

    Goals with every milestone complete. A goal moves here from goals when its last open milestone is marked done (POST /v1/interests/{interest}/milestones/status) and back if one is reopened.

    16 fields
    • idstringrequired
    • labelstringrequired
    • detailstring
    • done_whenarray of string

      Acceptance 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 null
    • cadence_per_weekinteger
      min 1 · max 7
    • due_datestring
    • blocked_untilstring or null
    • blocked_onstring or null
    • originstring
      one of "user", "confirmed", "integration", "model"
    • refusedboolean
    • areastring or null
    • area_rankinteger or null
      min 1
    • milestonesarray of object
    • completed_milestonesarray of object
    • derivedobjectrequired

      Sereo's inference, not anything the user said

      3 fields
      • statusstring or null
        one of "on_track", "due", "overdue", "satisfied", "starving", null
      • days_since_scheduledinteger or null
      • days_since_completedinteger or null
  • deletedarray of object

    Interests removed with DELETE /v1/interests/{interest} and restorable with POST /v1/interests/{interest}/restore. Records older than 30 days are pruned when another interest is deleted, so an entry past restorable_until can still be listed.

    5 fields
    • idstringrequired
    • labelstring or null
    • typestring or null
    • deleted_atstringrequired
    • restorable_untilstringrequired
  • areasarray of object

    The user's grouping of goals into ranked areas, most important first. Each goal references its area with area and its position within it with area_rank. Used as planning emphasis, not as a hard constraint.

    4 fields
    • idstringrequired
    • namestringrequired
    • whystring
    • rankintegerrequired
      min 1
  • goalsarray of object
    16 fields
    • idstringrequired
    • labelstringrequired
    • detailstring
    • done_whenarray of string

      Acceptance 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 null
    • cadence_per_weekinteger
      min 1 · max 7
    • due_datestring
    • blocked_untilstring or null
    • blocked_onstring or null
    • originstring
      one of "user", "confirmed", "integration", "model"
    • refusedboolean
    • areastring or null
    • area_rankinteger or null
      min 1
    • milestonesarray of object
    • completed_milestonesarray of object
    • derivedobjectrequired

      Sereo's inference, not anything the user said

      3 fields
      • statusstring or null
        one of "on_track", "due", "overdue", "satisfied", "starving", null
      • days_since_scheduledinteger or null
      • days_since_completedinteger or null
  • habitsarray of object
    16 fields
    • idstringrequired
    • labelstringrequired
    • detailstring
    • done_whenarray of string

      Acceptance 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 null
    • cadence_per_weekinteger
      min 1 · max 7
    • due_datestring
    • blocked_untilstring or null
    • blocked_onstring or null
    • originstring
      one of "user", "confirmed", "integration", "model"
    • refusedboolean
    • areastring or null
    • area_rankinteger or null
      min 1
    • milestonesarray of object
    • completed_milestonesarray of object
    • derivedobjectrequired

      Sereo's inference, not anything the user said

      3 fields
      • statusstring or null
        one of "on_track", "due", "overdue", "satisfied", "starving", null
      • days_since_scheduledinteger or null
      • days_since_completedinteger or null
  • leisurearray of object
    16 fields
    • idstringrequired
    • labelstringrequired
    • detailstring
    • done_whenarray of string

      Acceptance 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 null
    • cadence_per_weekinteger
      min 1 · max 7
    • due_datestring
    • blocked_untilstring or null
    • blocked_onstring or null
    • originstring
      one of "user", "confirmed", "integration", "model"
    • refusedboolean
    • areastring or null
    • area_rankinteger or null
      min 1
    • milestonesarray of object
    • completed_milestonesarray of object
    • derivedobjectrequired

      Sereo's inference, not anything the user said

      3 fields
      • statusstring or null
        one of "on_track", "due", "overdue", "satisfied", "starving", null
      • days_since_scheduledinteger or null
      • days_since_completedinteger or null
  • choresarray of object
    16 fields
    • idstringrequired
    • labelstringrequired
    • detailstring
    • done_whenarray of string

      Acceptance 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 null
    • cadence_per_weekinteger
      min 1 · max 7
    • due_datestring
    • blocked_untilstring or null
    • blocked_onstring or null
    • originstring
      one of "user", "confirmed", "integration", "model"
    • refusedboolean
    • areastring or null
    • area_rankinteger or null
      min 1
    • milestonesarray of object
    • completed_milestonesarray of object
    • derivedobjectrequired

      Sereo's inference, not anything the user said

      3 fields
      • statusstring or null
        one of "on_track", "due", "overdue", "satisfied", "starving", null
      • days_since_scheduledinteger or null
      • days_since_completedinteger or null
  • constraintsarray of object
    5 fields
    • idstringrequired
    • textstringrequired
    • kindstringrequired
      one of "gate", "scheduling", "content"
    • priorityinteger
      min 1 · max 3
    • applies_toarray of string
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/library \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
GET/v1/year#

Get goals as year-view rails

Any token · read only is enough

Returns 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

  • datestring

    Draw the year as of this day instead of today.

Responses

200 OK
  • datestringrequired
  • yearinteger
  • today_daysnumber
  • railsarray of objectrequired
    36 fields
    • idstringrequired
    • labelstringrequired
    • tagstringrequired

      Short display name for the goal, a word or two.

    • detailstring
    • done_whenarray of string

      the acceptance criteria; empty on goals written before the field existed

    • iconstring
    • adoptedstring
    • adopted_daysnumber
    • momentuminteger or null
    • statusstring or null
    • shift_daysinteger

      days the rail has been pulled forward by finishing things early

    • marksarray of objectrequired
      42 fields
      • indexintegerrequired

        position on the rail; the identity every other field here keys on

      • keystring or null

        what a write names this milestone by

      • namestringrequired
      • notestring
      • sourcestring or null
      • blocksinteger or null
      • plan_isostring or null

        the stored date — what an edit writes to

      • plan_daysnumber
      • at_daysnumberrequired

        Effective position in float days since 1970-01-01. May be fractional, e.g. a mark seated just before a fixed-date mark.

      • at_isostringrequired
      • donebooleanrequired
      • completed_onstring or null
      • earned_daysinteger

        days this completion pulled the rail forward

      • drift_daysinteger
      • fixedstring or null

        why this date is not the plan's to move

      • blockedstring or null
      • blocked_onstring or null

        the milestone's own raw block, empty when blocked is a sentence about a sub-step — the revision payload carries this back verbatim

      • block_keystring
      • block_derivedboolean

        held because something earlier in the rail is, not on its own account

      • blocked_byarray or null
      • blocked_by_labelstring or null
      • freestring or null

        an unordered stretch this belongs to

      • own_blockedstring or null
      • past_dueboolean
      • stuckboolean

        Past due, unmet and not on a fixed date; its position is carried forward to today. A fixed-date milestone can be past_due without being stuck. Always false on a parked or refused goal.

      • wall_daysnumber or null
      • is_currentboolean
      • steps_doneboolean

        true when every listed task is done but the milestone has not been marked reached. Informational: the milestone is never completed automatically.

      • subsarray of object
        15 fields
        • siintegerrequired
        • idstring or null
        • labelstringrequired
        • notestring
        • plan_isostring or null
        • plan_daysnumber
        • at_daysnumberrequired
        • at_isostring
        • datedboolean

          false when the task has no date of its own and its position is interpolated across its milestone's run-up in list order.

        • doneboolean
        • logged_daysnumber or null

          Day 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 before completed_on was recorded.

        • blockedstring or null
        • block_keystring
        • drift_daysinteger
        • stuckboolean
      • item_slotinteger or null
      • item_doneboolean
      • item_blockedstring or null
      • item_blocked_byarray or null
      • item_block_keystring
      • own_subsarray of object
        15 fields
        • siintegerrequired
        • idstring or null
        • labelstringrequired
        • notestring
        • plan_isostring or null
        • plan_daysnumber
        • at_daysnumberrequired
        • at_isostring
        • datedboolean

          false when the task has no date of its own and its position is interpolated across its milestone's run-up in list order.

        • doneboolean
        • logged_daysnumber or null

          Day 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 before completed_on was recorded.

        • blockedstring or null
        • block_keystring
        • drift_daysinteger
        • stuckboolean
      • free_sizeinteger
      • free_slotsarray of integer
      • fill_byinteger or null
      • slot_labelstring
      • slot_notestring
      • next_slotinteger or null
      • open_itemsarray of object
        3 fields
        • indexinteger
        • labelstring
        • blockedboolean
    • nintegerrequired
    • done_nintegerrequired
    • all_doneboolean
    • coldboolean

      true when the goal's momentum is below 20, i.e. little recent credited work, regardless of deadline.

    • hotboolean
    • parkedboolean
    • parked_untilstring or null
    • heldarray of integer

      Indices into marks of milestones that are past due and unmet (stuck: true).

    • blockedarray of integer
    • next_indexinteger or null
    • dest_indexinteger or null
    • dest_daysnumber
    • dest_atstring
    • dest_in_daysinteger
    • ends_statedboolean

      true when a milestone is marked finishes, so dest_at is the goal's end date; false when dest_at is only the date of the last milestone and the goal has no stated end.

    • next_in_daysinteger
    • failed_indexinteger or null

      a fixed date that passed unmet, which seals the rail there

    • first_daysnumber
    • front_daysnumber
    • linestringrequired

      where this goal stands, in one sentence

    • inkinteger or null

      the ink this goal wears everywhere

    • rhythmobject

      what the goal asks for each week, and the record over the history window

      4 fields
      • targetinteger or nullrequired

        sessions a week its habits ask for; null for a goal with no habit

      • labelstringrequired
      • keptintegerrequired

        days kept in the history window

      • plannedintegerrequired

        days planned in the history window

    • historyarray of object

      The 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, planned only = missed, kept only = unplanned extra.

      3 fields
      • datestringrequired
      • plannedbooleanrequired
      • keptbooleanrequired
    • weeksarray of object

      one 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
      • endingstringrequired
      • keptintegerrequired
      • plannedintegerrequired
      • targetintegerrequired
  • choresarray of object
    11 fields
    • idstringrequired
    • labelstringrequired
    • detailstring
    • due_datestring or null
    • daysinteger or null
    • minutesinteger or null
    • prioritystring
      one of "high", "normal", "low"
    • doneboolean
    • parkedboolean
    • parked_untilstring or null
    • statestringrequired
      one of "done", "parked", "late", "today", "soon", "later"
  • countsobjectrequired
    5 fields
    • goalsinteger
    • marksinteger
    • metinteger
    • heldinteger
    • blockedinteger
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/year \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/interests/{interest}/tasks/{task}#

Set a milestone task's status

Needs a token that can change things

Marks 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

  • intereststringrequired

    A goal, habit or chore id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$
  • taskstringrequired

    A milestone task id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$

Request body required

  • statusstringrequired
    one of "todo", "done"

Responses

200 OK
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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/v1/interests/{interest}/tasks/{task}#

Delete a milestone task

Needs a token that can change things

Removes 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

  • intereststringrequired

    A goal, habit or chore id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$
  • taskstringrequired

    A milestone task id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$

Responses

204 No content
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X DELETE https://app.usesereo.com/v1/interests/$INTEREST/tasks/$TASK \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/jobs#

Create a dated job

Needs a token that can change things

Creates 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

  • labelstringrequired

    what the job is

  • duestringrequired
    format date
  • for_whomstring

    Who 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.

  • minutesinteger

    Estimated minutes per work session, positive integer. If omitted, the planner chooses a duration.

    min 1
  • prioritystring
    one of "high", "normal", "low"
  • detailstring

Responses

201 Created
  • idstringrequired
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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"}'
PATCH/v1/interests/{interest}#

Update a goal

Needs a token that can change things

Applies 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

  • intereststringrequired

    A goal, habit or chore id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$

Request body optional

  • labelstring
  • detailstring
  • blocked_untilstring or null
  • blocked_onstring or null
  • adoptedstring
  • areastring or null

    the area id to place the goal in; null takes it out

  • area_rankinteger

    its place in that area, 1 first; the rest renumber

    min 1
  • milestonesarray of object
    16 fields
    • namestring

      needed unless id names a milestone it keeps

    • target_datestring

      YYYY-MM-DD; a kept milestone keeps its own

    • estimate_blocksinteger

      optional: a kept milestone keeps its own, a new one gets one per step

      min 1
    • blocksinteger

      the library's name for estimate_blocks; either is taken

      min 1
    • idstring
    • kindstring
      one of "effort", "outcome", "adjudicated"
    • statusstring
    • phasestring
    • finishesboolean

      the checkpoint that reaches this goal's done_when; at most one per goal

    • blocked_onstring
    • fixed_reasonstring
    • free_groupstring
    • no_steps_becausestring

      why no separate work leads to this checkpoint

    • blocked_byarray of string
    • completed_onstring
    • tasksarray of object
      3 fields
      • idstring

        optional: a step with the same title keeps its id, a new one is given one

      • titlestringrequired
      • statusstring
        one of "todo", "doing", "done"

Responses

200 OK
  • intereststringrequired
  • changedarray of stringrequired
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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/v1/interests/{interest}#

Delete an interest

Needs a token that can change things

Removes 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

  • intereststringrequired

    A goal, habit or chore id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$

Responses

204 No content
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X DELETE https://app.usesereo.com/v1/interests/$INTEREST \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/interests/{interest}/restore#

Restore a deleted interest

Needs a token that can change things

Restores 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

  • intereststringrequired

    A goal, habit or chore id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$

Responses

200 OK
  • restoredstringrequired
  • labelstring or null
  • typestring or null
  • milestonesinteger
  • scopestringrequired

    how 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"
  • persistedobjectrequired

    what lasts beyond today, by kind; empty lists when nothing lasting changed

    5 fields
    • goalsarray of string
    • rulesarray of string
    • settingsarray of string
    • jobsarray of string
    • weekarray of string
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/interests/$INTEREST/restore \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/interests/{interest}/milestones/status#

Set a milestone's completion status

Needs a token that can change things

Marks 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

  • intereststringrequired

    A goal, habit or chore id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$

Request body required

  • milestonestringrequired

    its id, or its name

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

    YYYY-MM-DD the milestone was reached, stored as completed_on. Defaults to the user's current date. Ignored when status is todo.

Responses

200 OK
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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"}'
POST/v1/interests/{interest}/milestones/review#

Answer a milestone review

Needs a token that can change things

Records 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 as POST /v1/interests/{interest}/milestones/status does, clears the review, and returns {outcome: "reached", milestone}. - not_yet — stores why on the review record and returns {outcome: "not_yet", why, options: ["move_date", "supersede"]}. The goal is not modified; apply an option with POST /v1/interests/{interest}/milestones/review/adjust. - later — hides the review until the day after on (default: the user's current date) and returns {outcome: "later", until}. A stored not_yet reason 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

  • intereststringrequired

    A goal, habit or chore id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$

Request body required

  • milestonestringrequired

    its id, or its name

  • choicestringrequired

    reached marks the milestone complete; not_yet stores why and returns the adjustment options; later snoozes the review until the day after on (default: the user's current date).

    one of "reached", "not_yet", "later"
  • whystring

    With not_yet: text reason, stored on the review record and returned in the response.

Responses

200 OK
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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"}'
POST/v1/interests/{interest}/milestones/review/adjust#

Apply a milestone review adjustment

Needs a token that can change things

Applies the adjustment chosen after a not_yet answer to a milestone review and clears the review.

  • move_date — sets this milestone's target_date to new_date through the same merge as PATCH /v1/interests/{interest}; other milestones are unchanged. new_date must be later than on (default: the user's current date). Returns {outcome: "moved", to, changed}. - supersede — retires the milestone by marking it done (it moves to completed_milestones with completed_on set), as POST /v1/interests/{interest}/milestones/status does. 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

  • intereststringrequired

    A goal, habit or chore id.

    pattern ^[a-z0-9][a-z0-9_]{0,63}$

Request body required

  • milestonestringrequired

    its id, or its name

  • actionstringrequired
    one of "move_date", "supersede"
  • new_datestring

    With move_date: the new target date, YYYY-MM-DD. Must be after the user's current date (or on).

Responses

200 OK
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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"}'
POST/v1/import#

Import a sereo.import/1 bundle

Needs a token that can change things

Builds 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

  • bundleobjectrequired

    a sereo.import/1 bundle

    8 fields
    • schemastringrequired
      always "sereo.import/1"
    • profileobjectrequired
    • availabilityarray of any

      per weekday: busy blocks, and optionally free windows that are subtracted from the calendar

    • habitsarray of any
    • leisurearray of any
    • choresarray of any
    • goalsarray of any
    • constraintsarray of any
  • replaceboolean

Responses

201 Created
  • interestsintegerrequired
  • reportobjectrequired
    4 fields
    • countsobject
    • defaultsarray of any
    • droppedarray of any
    • overduearray of any
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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
GET/v1/export#

Export the profile

Any token · read only is enough

Returns 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, attachment sereo.ics). Times are floating local times. Breaks and calendar-event blocks are excluded. - account — the whole account as sereo.account/1 JSON (attachment sereo-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

  • formatstring

    ics for a calendar file; omit for the JSON bundle.

Responses

200 OK
  • schemastringrequired
    always "sereo.import/1"
  • profileobjectrequired
  • availabilityarray of any

    per weekday: busy blocks, and optionally free windows that are subtracted from the calendar

  • habitsarray of any
  • leisurearray of any
  • choresarray of any
  • goalsarray of any
  • constraintsarray of any
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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).

POST/v1/architect/start#

Start or resume a goal-architect session

Needs a token that can change things

Opens 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

  • modestring

    defaults to talk when a goal is given, else deepen

    one of "deepen", "talk", "blueprint"
  • goalstring

    interest id to anchor talk mode

  • milestonestring

    milestone name or id within the anchored goal

  • resumeboolean

    continue the in-flight conversation whatever it is anchored to; 404 when there is none

Responses

200 OK
  • workingbooleanrequired

    a 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 null

    why the last turn failed, when the request that would have carried it had already answered 202

    2 fields
    • codestring
    • messagestring
  • statestringrequired
    one of "interview", "confirming", "ready", "committed"
  • modestringrequired
    one of "deepen", "talk", "blueprint"
  • turnintegerrequired
    min 0
  • messagestring or null

    the agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)

  • messagesarray of string

    the reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null

  • transcriptarray of array of string

    the conversation so far as [who, text] pairs, oldest first, where who is agent or user. A client renders this rather than keeping its own copy

  • anchorobject or null
    2 fields
    • goalstring
    • milestonestring or null
  • draft_summaryobjectrequired
    6 fields
    • goalsinteger
    • supportinginteger
    • standaloneinteger
    • milestonesinteger
    • tasksinteger
    • unconfirmedarray of string
  • turn_decisionsarray of object

    the 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 null

    the commit's dry-run import report; non-null only in state ready for a deepen or blueprint session

    5 fields
    • countsobject
    • defaultsarray of string
    • droppedarray of string
    • overduearray of string
    • notesarray of string
  • tracesarray of object

    what each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked

    6 fields
    • turnintegerrequired

      0 is the written opening

      min 0
    • user_indexintegerrequired

      how many of the person's messages came before this reply

      min 0
    • stepsarray of objectrequired
      6 fields
      • kindstringrequired
        one of "think", "search"
      • textstring

        think: one sentence, in Sereo's voice

      • sourceobject

        think: the page the answer came from, only when a search in the same turn cited it

        3 fields
        • urlstringrequired
        • domainstringrequired
        • titlestring
      • querystring
      • errorboolean
      • sourcesarray of object
        3 fields
        • urlstringrequired
        • domainstringrequired
        • titlestring
    • changesarray of objectrequired

      one line per thing the turn changed, diffed from the draft by the server, never the model's account

      4 fields
      • verbstringrequired
        one of "Staged", "Changed", "Removed", "Up next"
      • kindstringrequired
        one of "goal", "rhythm", "chore", "up_next"
      • labelstringrequired
      • factsarray of objectrequired
        2 fields
        • textstringrequired
        • datestring or null
    • askobject or null
      3 fields
      • questionstringrequired
      • optionsarray of objectrequired
        2 fields
        • labelstringrequired
        • detailstring
      • multibooleanrequired

        several answers may be picked together

    • replyarray of string

      present when ask is: 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 null

    the question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer

    3 fields
    • questionstringrequired
    • optionsarray of objectrequired
      2 fields
      • labelstringrequired
      • detailstring
    • multibooleanrequired

      several answers may be picked together

  • setupobject

    the year as committing this draft would leave it: staged entries, building lines and the date window

    4 fields
    • stagedarray of objectrequired

      what committing would put on the year

      12 fields
      • titlestringrequired

        the state this goal reaches, which is its name

      • tagstring or null

        what the user calls it, in their own words

      • done_whenarray of string

        the acceptance criteria; empty for a rhythm, which has no end

      • kindstringrequired
        one of "project", "habit", "leisure", "chore"
      • kind_labelstringrequired

        what the hub calls this kind

      • linestringrequired

        how the engine treats this kind — a claim about the type, never about the goal

      • monthsnumberrequired

        how far round the year the rail runs

        min 1 · max 12
      • beyondboolean

        it 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 null

        where the rail ends; null for a rhythm, which has no end

        format date
      • notestring
      • marksarray of objectrequired
        4 fields
        • atnumberrequired
          min 0 · max 1
        • labelstringrequired
        • datestring
          format date
        • fixedboolean
      • factsarray of object
    • buildingarray of objectrequired

      display lines (text, state) describing what committing this draft will build

      2 fields
      • textstringrequired
      • statestringrequired
    • windowobjectrequired
      2 fields
      • fromstring
        format date
      • tostring
        format date
    • up_nextarray of string

      goals 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
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
503 That integration is not configured on this deployment
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/architect/start \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
GET/v1/architect/session#

Get the goal-architect session

Any token · read only is enough

Returns 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
  • workingbooleanrequired

    a 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 null

    why the last turn failed, when the request that would have carried it had already answered 202

    2 fields
    • codestring
    • messagestring
  • statestringrequired
    one of "interview", "confirming", "ready", "committed"
  • modestringrequired
    one of "deepen", "talk", "blueprint"
  • turnintegerrequired
    min 0
  • messagestring or null

    the agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)

  • messagesarray of string

    the reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null

  • transcriptarray of array of string

    the conversation so far as [who, text] pairs, oldest first, where who is agent or user. A client renders this rather than keeping its own copy

  • anchorobject or null
    2 fields
    • goalstring
    • milestonestring or null
  • draft_summaryobjectrequired
    6 fields
    • goalsinteger
    • supportinginteger
    • standaloneinteger
    • milestonesinteger
    • tasksinteger
    • unconfirmedarray of string
  • turn_decisionsarray of object

    the 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 null

    the commit's dry-run import report; non-null only in state ready for a deepen or blueprint session

    5 fields
    • countsobject
    • defaultsarray of string
    • droppedarray of string
    • overduearray of string
    • notesarray of string
  • tracesarray of object

    what each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked

    6 fields
    • turnintegerrequired

      0 is the written opening

      min 0
    • user_indexintegerrequired

      how many of the person's messages came before this reply

      min 0
    • stepsarray of objectrequired
      6 fields
      • kindstringrequired
        one of "think", "search"
      • textstring

        think: one sentence, in Sereo's voice

      • sourceobject

        think: the page the answer came from, only when a search in the same turn cited it

        3 fields
        • urlstringrequired
        • domainstringrequired
        • titlestring
      • querystring
      • errorboolean
      • sourcesarray of object
        3 fields
        • urlstringrequired
        • domainstringrequired
        • titlestring
    • changesarray of objectrequired

      one line per thing the turn changed, diffed from the draft by the server, never the model's account

      4 fields
      • verbstringrequired
        one of "Staged", "Changed", "Removed", "Up next"
      • kindstringrequired
        one of "goal", "rhythm", "chore", "up_next"
      • labelstringrequired
      • factsarray of objectrequired
        2 fields
        • textstringrequired
        • datestring or null
    • askobject or null
      3 fields
      • questionstringrequired
      • optionsarray of objectrequired
        2 fields
        • labelstringrequired
        • detailstring
      • multibooleanrequired

        several answers may be picked together

    • replyarray of string

      present when ask is: 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 null

    the question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer

    3 fields
    • questionstringrequired
    • optionsarray of objectrequired
      2 fields
      • labelstringrequired
      • detailstring
    • multibooleanrequired

      several answers may be picked together

  • setupobject

    the year as committing this draft would leave it: staged entries, building lines and the date window

    4 fields
    • stagedarray of objectrequired

      what committing would put on the year

      12 fields
      • titlestringrequired

        the state this goal reaches, which is its name

      • tagstring or null

        what the user calls it, in their own words

      • done_whenarray of string

        the acceptance criteria; empty for a rhythm, which has no end

      • kindstringrequired
        one of "project", "habit", "leisure", "chore"
      • kind_labelstringrequired

        what the hub calls this kind

      • linestringrequired

        how the engine treats this kind — a claim about the type, never about the goal

      • monthsnumberrequired

        how far round the year the rail runs

        min 1 · max 12
      • beyondboolean

        it 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 null

        where the rail ends; null for a rhythm, which has no end

        format date
      • notestring
      • marksarray of objectrequired
        4 fields
        • atnumberrequired
          min 0 · max 1
        • labelstringrequired
        • datestring
          format date
        • fixedboolean
      • factsarray of object
    • buildingarray of objectrequired

      display lines (text, state) describing what committing this draft will build

      2 fields
      • textstringrequired
      • statestringrequired
    • windowobjectrequired
      2 fields
      • fromstring
        format date
      • tostring
        format date
    • up_nextarray of string

      goals the person named that the conversation has not reached yet, in the order it will take them

401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/architect/session \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
DELETE/v1/architect/session#

Discard the goal-architect session

Needs a token that can change things

Deletes 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

204 No content
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X DELETE https://app.usesereo.com/v1/architect/session \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
GET/v1/architect/stream#

Stream goal-architect events

Any token · read only is enough

Opens 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

200 OK
401 Missing or invalid bearer token
# example
curl https://app.usesereo.com/v1/architect/stream \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/architect/turns#

Send a turn to the goal architect

Needs a token that can change things

Submits 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

  • messagestring
  • confirmboolean
  • turninteger
    min 0

Responses

200 OK
  • workingbooleanrequired

    a 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 null

    why the last turn failed, when the request that would have carried it had already answered 202

    2 fields
    • codestring
    • messagestring
  • statestringrequired
    one of "interview", "confirming", "ready", "committed"
  • modestringrequired
    one of "deepen", "talk", "blueprint"
  • turnintegerrequired
    min 0
  • messagestring or null

    the agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)

  • messagesarray of string

    the reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null

  • transcriptarray of array of string

    the conversation so far as [who, text] pairs, oldest first, where who is agent or user. A client renders this rather than keeping its own copy

  • anchorobject or null
    2 fields
    • goalstring
    • milestonestring or null
  • draft_summaryobjectrequired
    6 fields
    • goalsinteger
    • supportinginteger
    • standaloneinteger
    • milestonesinteger
    • tasksinteger
    • unconfirmedarray of string
  • turn_decisionsarray of object

    the 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 null

    the commit's dry-run import report; non-null only in state ready for a deepen or blueprint session

    5 fields
    • countsobject
    • defaultsarray of string
    • droppedarray of string
    • overduearray of string
    • notesarray of string
  • tracesarray of object

    what each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked

    6 fields
    • turnintegerrequired

      0 is the written opening

      min 0
    • user_indexintegerrequired

      how many of the person's messages came before this reply

      min 0
    • stepsarray of objectrequired
      6 fields
      • kindstringrequired
        one of "think", "search"
      • textstring

        think: one sentence, in Sereo's voice

      • sourceobject

        think: the page the answer came from, only when a search in the same turn cited it

        3 fields
        • urlstringrequired
        • domainstringrequired
        • titlestring
      • querystring
      • errorboolean
      • sourcesarray of object
        3 fields
        • urlstringrequired
        • domainstringrequired
        • titlestring
    • changesarray of objectrequired

      one line per thing the turn changed, diffed from the draft by the server, never the model's account

      4 fields
      • verbstringrequired
        one of "Staged", "Changed", "Removed", "Up next"
      • kindstringrequired
        one of "goal", "rhythm", "chore", "up_next"
      • labelstringrequired
      • factsarray of objectrequired
        2 fields
        • textstringrequired
        • datestring or null
    • askobject or null
      3 fields
      • questionstringrequired
      • optionsarray of objectrequired
        2 fields
        • labelstringrequired
        • detailstring
      • multibooleanrequired

        several answers may be picked together

    • replyarray of string

      present when ask is: 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 null

    the question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer

    3 fields
    • questionstringrequired
    • optionsarray of objectrequired
      2 fields
      • labelstringrequired
      • detailstring
    • multibooleanrequired

      several answers may be picked together

  • setupobject

    the year as committing this draft would leave it: staged entries, building lines and the date window

    4 fields
    • stagedarray of objectrequired

      what committing would put on the year

      12 fields
      • titlestringrequired

        the state this goal reaches, which is its name

      • tagstring or null

        what the user calls it, in their own words

      • done_whenarray of string

        the acceptance criteria; empty for a rhythm, which has no end

      • kindstringrequired
        one of "project", "habit", "leisure", "chore"
      • kind_labelstringrequired

        what the hub calls this kind

      • linestringrequired

        how the engine treats this kind — a claim about the type, never about the goal

      • monthsnumberrequired

        how far round the year the rail runs

        min 1 · max 12
      • beyondboolean

        it 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 null

        where the rail ends; null for a rhythm, which has no end

        format date
      • notestring
      • marksarray of objectrequired
        4 fields
        • atnumberrequired
          min 0 · max 1
        • labelstringrequired
        • datestring
          format date
        • fixedboolean
      • factsarray of object
    • buildingarray of objectrequired

      display lines (text, state) describing what committing this draft will build

      2 fields
      • textstringrequired
      • statestringrequired
    • windowobjectrequired
      2 fields
      • fromstring
        format date
      • tostring
        format date
    • up_nextarray of string

      goals 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
  • workingbooleanrequired

    a 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 null

    why the last turn failed, when the request that would have carried it had already answered 202

    2 fields
    • codestring
    • messagestring
  • statestringrequired
    one of "interview", "confirming", "ready", "committed"
  • modestringrequired
    one of "deepen", "talk", "blueprint"
  • turnintegerrequired
    min 0
  • messagestring or null

    the agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)

  • messagesarray of string

    the reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null

  • transcriptarray of array of string

    the conversation so far as [who, text] pairs, oldest first, where who is agent or user. A client renders this rather than keeping its own copy

  • anchorobject or null
    2 fields
    • goalstring
    • milestonestring or null
  • draft_summaryobjectrequired
    6 fields
    • goalsinteger
    • supportinginteger
    • standaloneinteger
    • milestonesinteger
    • tasksinteger
    • unconfirmedarray of string
  • turn_decisionsarray of object

    the 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 null

    the commit's dry-run import report; non-null only in state ready for a deepen or blueprint session

    5 fields
    • countsobject
    • defaultsarray of string
    • droppedarray of string
    • overduearray of string
    • notesarray of string
  • tracesarray of object

    what each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked

    6 fields
    • turnintegerrequired

      0 is the written opening

      min 0
    • user_indexintegerrequired

      how many of the person's messages came before this reply

      min 0
    • stepsarray of objectrequired
      6 fields
      • kindstringrequired
        one of "think", "search"
      • textstring

        think: one sentence, in Sereo's voice

      • sourceobject

        think: the page the answer came from, only when a search in the same turn cited it

        3 fields
        • urlstringrequired
        • domainstringrequired
        • titlestring
      • querystring
      • errorboolean
      • sourcesarray of object
        3 fields
        • urlstringrequired
        • domainstringrequired
        • titlestring
    • changesarray of objectrequired

      one line per thing the turn changed, diffed from the draft by the server, never the model's account

      4 fields
      • verbstringrequired
        one of "Staged", "Changed", "Removed", "Up next"
      • kindstringrequired
        one of "goal", "rhythm", "chore", "up_next"
      • labelstringrequired
      • factsarray of objectrequired
        2 fields
        • textstringrequired
        • datestring or null
    • askobject or null
      3 fields
      • questionstringrequired
      • optionsarray of objectrequired
        2 fields
        • labelstringrequired
        • detailstring
      • multibooleanrequired

        several answers may be picked together

    • replyarray of string

      present when ask is: 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 null

    the question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer

    3 fields
    • questionstringrequired
    • optionsarray of objectrequired
      2 fields
      • labelstringrequired
      • detailstring
    • multibooleanrequired

      several answers may be picked together

  • setupobject

    the year as committing this draft would leave it: staged entries, building lines and the date window

    4 fields
    • stagedarray of objectrequired

      what committing would put on the year

      12 fields
      • titlestringrequired

        the state this goal reaches, which is its name

      • tagstring or null

        what the user calls it, in their own words

      • done_whenarray of string

        the acceptance criteria; empty for a rhythm, which has no end

      • kindstringrequired
        one of "project", "habit", "leisure", "chore"
      • kind_labelstringrequired

        what the hub calls this kind

      • linestringrequired

        how the engine treats this kind — a claim about the type, never about the goal

      • monthsnumberrequired

        how far round the year the rail runs

        min 1 · max 12
      • beyondboolean

        it 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 null

        where the rail ends; null for a rhythm, which has no end

        format date
      • notestring
      • marksarray of objectrequired
        4 fields
        • atnumberrequired
          min 0 · max 1
        • labelstringrequired
        • datestring
          format date
        • fixedboolean
      • factsarray of object
    • buildingarray of objectrequired

      display lines (text, state) describing what committing this draft will build

      2 fields
      • textstringrequired
      • statestringrequired
    • windowobjectrequired
      2 fields
      • fromstring
        format date
      • tostring
        format date
    • up_nextarray of string

      goals 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
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
503 That integration is not configured on this deployment
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl -X POST https://app.usesereo.com/v1/architect/turns \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/architect/commit#

Commit the goal-architect draft

Needs a token that can change things

Writes 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
  • modestringrequired
    one of "deepen", "talk", "blueprint"
  • committedbooleanrequired
    always true
  • updated_goalstring or null
  • anchor_datestring or null
    format date
  • reportobjectrequired

    deepen/blueprint: the import report (counts, defaults, dropped, overdue, notes) plus carried, the user changes made outside the conversation while it was open that the commit kept. talk: changed, notes and not_written, the draft entries outside the anchored goal that were not written.

    2 fields
    • carriedarray of string
    • not_writtenarray of string
  • plannedstring or null

    deepen/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 commit

    format date
  • workingboolean

    deepen/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
  • modestringrequired
    one of "deepen", "talk", "blueprint"
  • committedbooleanrequired
    always true
  • updated_goalstring or null
  • anchor_datestring or null
    format date
  • reportobjectrequired

    deepen/blueprint: the import report (counts, defaults, dropped, overdue, notes) plus carried, the user changes made outside the conversation while it was open that the commit kept. talk: changed, notes and not_written, the draft entries outside the anchored goal that were not written.

    2 fields
    • carriedarray of string
    • not_writtenarray of string
  • plannedstring or null

    deepen/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 commit

    format date
  • workingboolean

    deepen/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
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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/v1/retro/{date}#

Get a weekly brief

Any token · read only is enough

Path parameters

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
404 No such thing, or it belongs to another account
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/retro/2026-11-12 \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
POST/v1/retro/{date}#

Generate a weekly brief

Needs a token that can change things

Writes 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

  • datestringrequired

    The day, YYYY-MM-DD.

    pattern ^\d{4}-\d{2}-\d{2}$

Responses

200 OK
400 The request was malformed; code says how
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
409 Refused because of the account's current state; branch on code
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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/v1/calendar/status#

Get Google Calendar connection status

Any token · read only is enough

Responses

200 OK
  • connectedbooleanrequired
  • oauthboolean

    Whether this deployment has a Google OAuth client configured. When false the calendar cannot be connected on this server.

  • expires_atstring or null
  • scopestring or null
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/calendar/status \
  -H "Authorization: Bearer $SEREO_API_TOKEN"
DELETE/v1/calendar#

Disconnect Google Calendar

Needs a token that can change things

Deletes 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

204 No content
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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/v1/whoami#

Get the authenticated account

Any token · read only is enough

Responses

200 OK
  • user_idstringrequired
  • emailstringrequired
  • timezonestringrequired
401 Missing or invalid bearer token
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_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)
  • errorobjectrequired
    3 fields
    • codestringrequired

      machine-readable; branch on this, not on prose

    • messagestringrequired
    • request_idstringrequired
# example
curl https://app.usesereo.com/v1/whoami \
  -H "Authorization: Bearer $SEREO_API_TOKEN"