{"openapi": "3.1.0", "info": {"title": "Sereo", "version": "1.0.0", "description": "A planner that adapts when you fall off.\n\nThe loop is: generate a day, push back on it in plain language, accept it \u2014\nwhich turns its blocks into a to-do list \u2014 then tick items off.\n\nTwo behaviours are easy to get wrong from the outside:\n\n* **Silence is not a miss.** An item nobody answered is `unreconciled`, never\n  `skipped`. It is reported separately everywhere and must never be presented\n  as a failure.\n* **One writer per day.** Once a plan is accepted, its to-do list owns that\n  day's completion record and `POST /v1/plans/{date}/checkin` refuses. If\n  Todoist is connected, it owns completion instead and the to-do write routes\n  refuse.\n\nAuthentication is a bearer token, presented as `Authorization: Bearer ...`.\nThere are two kinds and the API tells them apart by which store the digest is\nin, not by the prefix:\n\n* a **session**, from `/v1/auth/login` or \u2014 for an account that signs in with\n  Google or GitHub \u2014 from `/v1/auth/session`, valid until it goes 30 days unused (ADR-0176);\n* an **API token**, from `/v1/auth/tokens`, for a machine: named, revocable on\n  its own, optionally read-only, and by default it does not expire (ADR-0099).\n  A read-only one may call GET routes and nothing else, which also means it\n  cannot invoke the model.\n\nSeventeen routes need no token: health, the spec itself, register, login,\nverify, the signup claim, the provider list, the two provider sign-in routes,\nthe session exchange, both password-reset routes, the three integration OAuth\ncallbacks, and the static UI. Everything else requires one.\n", "license": {"name": "Proprietary", "identifier": "LicenseRef-Proprietary"}}, "servers": [{"url": "https://app.usesereo.com", "description": "A single-node deployment. Sereo binds to loopback; TLS terminates at a proxy."}], "tags": [{"name": "system", "description": "Health."}, {"name": "auth", "description": "Accounts, sign-in and sessions, password reset, personal API tokens, and subscription status."}, {"name": "goals", "description": "The profile and goals: interests, milestones and tasks, the year view, and import/export."}, {"name": "planning", "description": "Day and week plans: generating, editing, replanning and discussing them, standing constraints, and periodic reports."}, {"name": "todos", "description": "Accepting a day's plan as a to-do list, and recording completion against it."}, {"name": "retro", "description": "Weekly brief (older shape). Reads and writes the same stored document as /v1/reports/week/{date}."}, {"name": "calendar", "description": "Google Calendar connection. Read-only: busy time is read and no events are written."}, {"name": "todoist", "description": "Todoist two-way sync."}, {"name": "github", "description": "GitHub Projects v2 as a read-only milestone source."}, {"name": "ui", "description": "The served web client."}, {"name": "push", "description": "Nudges to the native app: fixed sentences over APNs, sent only to a phone the account registered (ADR-0140)."}, {"name": "architect", "description": "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)."}], "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "description": "Either a session or an API token. A session comes from /v1/auth/login, or from /v1/auth/session when the account signs in with a provider; it lives until 30 days unused and /v1/auth/logout revokes it. /v1/auth/register does NOT return one \u2014 it answers 202 and mails a link (ADR-0093). An API token comes from POST /v1/auth/tokens, is revoked on its own, and is what a script or an MCP server should hold."}}, "schemas": {"Error": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}, "Plan": {"type": "object", "required": ["blocks", "most_important", "coach_note"], "properties": {"blocks": {"type": "array", "items": {"type": "object", "required": ["start", "end", "task", "interest", "why"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "task": {"type": "string", "maxLength": 120}, "interest": {"type": ["string", "null"], "description": "null for a chore or a break \u2014 see `chore`, which tells the two apart"}, "why": {"type": "string", "maxLength": 200}, "chore": {"type": "boolean", "description": "work that serves no tracked goal (ADR-0055). 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 (ADR-0064)"}}}}, "laid": {"type": "array", "items": {"type": "object"}, "description": "the blocks the user laid out themselves (ADR-0157), held at their hours through a rebuild"}, "pushback": {"type": "array", "items": {"type": "object", "required": ["task", "reason"], "properties": {"task": {"type": "string"}, "reason": {"type": "string"}}}, "description": "where Sereo would change one of the user's own blocks, and why. Advice only: the block stays (ADR-0157)"}, "outside_hours": {"type": "array", "items": {"type": "object", "required": ["task", "start", "end", "side"], "properties": {"task": {"type": "string"}, "start": {"type": "string"}, "end": {"type": "string"}, "side": {"type": "string", "enum": ["before", "after"]}}}, "description": "on a day the user laid out: the work blocks running outside the hours they keep, kept and named (ADR-0155)"}, "most_important": {"type": "string"}, "coach_note": {"type": "string"}, "generated_at": {"type": "string"}, "energy": {"type": ["integer", "null"], "minimum": 1, "maximum": 5}, "energy_stated": {"type": "boolean", "description": "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 (ADR-0059)"}, "recovery": {"type": "boolean"}, "recovery_gap": {"type": ["integer", "null"], "description": "days away the day was planned to recover from; a replan of the day keeps it, so a rebuilt recovery day is still one"}, "issues": {"type": "array", "items": {"type": "string"}, "description": "what the guards changed, as `kind:subject` \u2014 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 (ADR-0139)"}, "released": {"type": "array", "description": "week-plan blocks for this day that the planner left off at the user's request (ADR-0109): `block` is the week block id, `text` its text. Only written when the user's own words asked for it", "items": {"type": "object", "required": ["block", "why"], "properties": {"block": {"type": "string"}, "text": {"type": "string"}, "why": {"type": "string"}, "at": {"type": "string"}}}}, "source": {"type": "string", "enum": ["user", "scheduler"]}, "accepted_at": {"type": "string", "description": "present once accepted; also counts as the user showing up for gap detection"}, "on_hold": {"type": "array", "items": {"type": "string"}}}}, "Block": {"type": "object", "required": ["start", "end", "task", "interest", "why"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "task": {"type": "string", "maxLength": 120}, "interest": {"type": ["string", "null"], "description": "null for a chore or a break \u2014 see `chore`, which tells the two apart"}, "why": {"type": "string", "maxLength": 200}, "chore": {"type": "boolean", "description": "work that serves no tracked goal (ADR-0055). 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 (ADR-0064)"}}}, "TodoItem": {"type": "object", "required": ["id", "title", "status", "interest"], "properties": {"id": {"type": "string", "pattern": "^t_[a-f0-9]+$"}, "start": {"type": ["string", "null"]}, "end": {"type": ["string", "null"]}, "title": {"type": "string"}, "why": {"type": "string"}, "interest": {"type": "string"}, "status": {"type": "string", "enum": ["open", "done", "skipped"], "description": "the stored status. Display `derived_status` instead"}, "derived_status": {"type": "string", "enum": ["open", "done", "skipped", "unreconciled"], "description": "what to display. `unreconciled` means still open and the day has passed \u2014 the user never answered. It is NOT a miss and must not be shown as one."}, "done_at": {"type": ["string", "null"]}, "off_plan": {"type": "boolean", "description": "true for an answered item whose block is no longer in the plan; kept so the answer is not lost"}, "comments": {"type": "array", "items": {"type": "object", "properties": {"ts": {"type": "string"}, "text": {"type": "string"}, "external_id": {"type": "string"}}}}, "todoist": {"type": "object"}}}, "Todos": {"type": "object", "required": ["date", "items", "open", "done", "skipped", "unreconciled", "read_only"], "properties": {"date": {"type": "string"}, "accepted_at": {"type": ["string", "null"]}, "accepted": {"type": "boolean"}, "read_only": {"type": "boolean", "description": "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 \u2014 this is the same condition the write routes enforce."}, "items": {"type": "array", "items": {"type": "object", "required": ["id", "title", "status", "interest"], "properties": {"id": {"type": "string", "pattern": "^t_[a-f0-9]+$"}, "start": {"type": ["string", "null"]}, "end": {"type": ["string", "null"]}, "title": {"type": "string"}, "why": {"type": "string"}, "interest": {"type": "string"}, "status": {"type": "string", "enum": ["open", "done", "skipped"], "description": "the stored status. Display `derived_status` instead"}, "derived_status": {"type": "string", "enum": ["open", "done", "skipped", "unreconciled"], "description": "what to display. `unreconciled` means still open and the day has passed \u2014 the user never answered. It is NOT a miss and must not be shown as one."}, "done_at": {"type": ["string", "null"]}, "off_plan": {"type": "boolean", "description": "true for an answered item whose block is no longer in the plan; kept so the answer is not lost"}, "comments": {"type": "array", "items": {"type": "object", "properties": {"ts": {"type": "string"}, "text": {"type": "string"}, "external_id": {"type": "string"}}}}, "todoist": {"type": "object"}}}}, "open": {"type": "integer"}, "done": {"type": "integer"}, "skipped": {"type": "integer"}, "unreconciled": {"type": "integer"}, "pending_reconciliation": {"type": "array", "description": "past days within the last two days that still have stored-`open` items", "items": {"type": "object", "properties": {"date": {"type": "string"}, "count": {"type": "integer"}}}}}}, "Library": {"type": "object", "required": ["onboarded"], "properties": {"onboarded": {"type": "boolean"}, "date": {"type": "string"}, "completed_goals": {"type": "array", "items": {"type": "object", "required": ["id", "label", "derived"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "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."}, "minutes": {"type": ["integer", "null"]}, "cadence_per_week": {"type": "integer", "minimum": 1, "maximum": 7}, "due_date": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "origin": {"type": "string", "enum": ["user", "confirmed", "integration", "model"]}, "refused": {"type": "boolean"}, "area": {"type": ["string", "null"]}, "area_rank": {"type": ["integer", "null"], "minimum": 1}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed_milestones": {"type": "array", "items": {"type": "object"}}, "derived": {"type": "object", "description": "Sereo's inference, not anything the user said", "properties": {"status": {"type": ["string", "null"], "enum": ["on_track", "due", "overdue", "satisfied", "starving", null]}, "days_since_scheduled": {"type": ["integer", "null"]}, "days_since_completed": {"type": ["integer", "null"]}}}}}, "description": "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."}, "deleted": {"type": "array", "items": {"type": "object", "required": ["id", "deleted_at", "restorable_until"], "properties": {"id": {"type": "string"}, "label": {"type": ["string", "null"]}, "type": {"type": ["string", "null"]}, "deleted_at": {"type": "string"}, "restorable_until": {"type": "string"}}}, "description": "Interests removed with `DELETE /v1/interests/{interest}` and restorable with `POST /v1/interests/{interest}/restore` (ADR-0164). Records older than 30 days are pruned when another interest is deleted, so an entry past `restorable_until` can still be listed."}, "areas": {"type": "array", "items": {"type": "object", "required": ["id", "name", "rank"], "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "why": {"type": "string"}, "rank": {"type": "integer", "minimum": 1}}}, "description": "The user's grouping of goals into ranked areas, most important first (ADR-0163). Each goal references its area with `area` and its position within it with `area_rank`. Used as planning emphasis, not as a hard constraint."}, "goals": {"type": "array", "items": {"type": "object", "required": ["id", "label", "derived"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "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."}, "minutes": {"type": ["integer", "null"]}, "cadence_per_week": {"type": "integer", "minimum": 1, "maximum": 7}, "due_date": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "origin": {"type": "string", "enum": ["user", "confirmed", "integration", "model"]}, "refused": {"type": "boolean"}, "area": {"type": ["string", "null"]}, "area_rank": {"type": ["integer", "null"], "minimum": 1}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed_milestones": {"type": "array", "items": {"type": "object"}}, "derived": {"type": "object", "description": "Sereo's inference, not anything the user said", "properties": {"status": {"type": ["string", "null"], "enum": ["on_track", "due", "overdue", "satisfied", "starving", null]}, "days_since_scheduled": {"type": ["integer", "null"]}, "days_since_completed": {"type": ["integer", "null"]}}}}}}, "habits": {"type": "array", "items": {"type": "object", "required": ["id", "label", "derived"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "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."}, "minutes": {"type": ["integer", "null"]}, "cadence_per_week": {"type": "integer", "minimum": 1, "maximum": 7}, "due_date": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "origin": {"type": "string", "enum": ["user", "confirmed", "integration", "model"]}, "refused": {"type": "boolean"}, "area": {"type": ["string", "null"]}, "area_rank": {"type": ["integer", "null"], "minimum": 1}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed_milestones": {"type": "array", "items": {"type": "object"}}, "derived": {"type": "object", "description": "Sereo's inference, not anything the user said", "properties": {"status": {"type": ["string", "null"], "enum": ["on_track", "due", "overdue", "satisfied", "starving", null]}, "days_since_scheduled": {"type": ["integer", "null"]}, "days_since_completed": {"type": ["integer", "null"]}}}}}}, "leisure": {"type": "array", "items": {"type": "object", "required": ["id", "label", "derived"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "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."}, "minutes": {"type": ["integer", "null"]}, "cadence_per_week": {"type": "integer", "minimum": 1, "maximum": 7}, "due_date": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "origin": {"type": "string", "enum": ["user", "confirmed", "integration", "model"]}, "refused": {"type": "boolean"}, "area": {"type": ["string", "null"]}, "area_rank": {"type": ["integer", "null"], "minimum": 1}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed_milestones": {"type": "array", "items": {"type": "object"}}, "derived": {"type": "object", "description": "Sereo's inference, not anything the user said", "properties": {"status": {"type": ["string", "null"], "enum": ["on_track", "due", "overdue", "satisfied", "starving", null]}, "days_since_scheduled": {"type": ["integer", "null"]}, "days_since_completed": {"type": ["integer", "null"]}}}}}}, "chores": {"type": "array", "items": {"type": "object", "required": ["id", "label", "derived"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "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."}, "minutes": {"type": ["integer", "null"]}, "cadence_per_week": {"type": "integer", "minimum": 1, "maximum": 7}, "due_date": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "origin": {"type": "string", "enum": ["user", "confirmed", "integration", "model"]}, "refused": {"type": "boolean"}, "area": {"type": ["string", "null"]}, "area_rank": {"type": ["integer", "null"], "minimum": 1}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed_milestones": {"type": "array", "items": {"type": "object"}}, "derived": {"type": "object", "description": "Sereo's inference, not anything the user said", "properties": {"status": {"type": ["string", "null"], "enum": ["on_track", "due", "overdue", "satisfied", "starving", null]}, "days_since_scheduled": {"type": ["integer", "null"]}, "days_since_completed": {"type": ["integer", "null"]}}}}}}, "constraints": {"type": "array", "items": {"type": "object", "required": ["id", "text", "kind"], "properties": {"id": {"type": "string"}, "text": {"type": "string"}, "kind": {"type": "string", "enum": ["gate", "scheduling", "content"]}, "priority": {"type": "integer", "minimum": 1, "maximum": 3}, "applies_to": {"type": "array", "items": {"type": "string"}}}}}}}, "Status": {"type": "object", "required": ["date", "onboarded", "plan_exists"], "properties": {"date": {"type": "string"}, "onboarded": {"type": "boolean"}, "interests": {"type": "integer"}, "goals": {"type": "integer", "description": "goals only (the projects), not the habits, leisure or chores under them \u2014 what the band counts so it agrees with the year wheel (ADR-0124)"}, "plan_exists": {"type": "boolean"}, "plan_accepted": {"type": "boolean"}, "awaiting_checkin": {"type": "boolean"}, "gap_days": {"type": ["integer", "null"], "description": "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_reconciling": {"type": "array", "items": {"type": "object"}}, "on_hold": {"type": "array", "items": {"type": "object"}}, "calendar_connected": {"type": "boolean"}, "timezone": {"type": "string", "description": "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 (ADR-0101)"}, "navigation_traced": {"type": "boolean", "description": "this account's navigation is being recorded for the beta, and the screen says so (ADR-0102)"}, "architect": {"type": "boolean", "description": "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_running": {"type": "boolean", "description": "a report for this account is being generated right now"}, "report_written": {"type": "boolean", "description": "whether any report has been written for this account, read or not \u2014 the tour's Reports page has steps about one only when it does"}, "unread_report": {"type": ["object", "null"], "properties": {"period": {"type": "string"}, "ending": {"type": "string"}}, "description": "the latest written report not yet marked read; cleared by `POST /v1/reports/{period}/{date}/seen`"}, "email_verified": {"type": "boolean", "description": "whether the address has answered (ADR-0029). False means the account works, but routes that invoke the model answer 403 `email_unverified`."}, "energy_default": {"type": "integer", "minimum": 1, "maximum": 5, "description": "where the energy control starts"}, "access": {"enum": ["full", "checkout_first", "lapsed"], "description": "the account's standing (ADR-0188): `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."}, "checkout_first": {"type": "boolean", "description": "a new account that has not been through checkout yet (ADR-0186). Every route outside a small allowlist answers 402 `checkout_required` until it has. Always false with billing off."}, "walkthrough_owed": {"type": "boolean", "description": "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 (ADR-0190)"}, "tutorial": {"type": ["object", "null"], "properties": {"steps": {"type": "array", "items": {"type": "object", "required": ["key", "state"], "properties": {"key": {"enum": ["goals", "calendar", "week", "today", "reports", "settings"]}, "state": {"enum": ["todo", "done", "skipped"]}}}}, "current": {"enum": ["goals", "calendar", "week", "today", "reports", "settings", null]}}, "description": "the tutorial's progress while it is owed, else null (ADR-0190, ADR-0195): 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"}}}, "Token": {"type": "object", "required": ["user_id", "token", "expires_at"], "properties": {"user_id": {"type": "string"}, "token": {"type": "string"}, "expires_at": {"type": "string"}}}, "Checkin": {"type": "object", "properties": {"done_tasks": {"type": "array", "items": {"type": "string"}}, "skipped_tasks": {"type": "array", "items": {"type": "string"}}, "unreconciled_tasks": {"type": "array", "items": {"type": "string"}, "description": "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_interests": {"type": "array", "items": {"type": "string"}, "description": "duplicates are meaningful: membership credits a habit's weekly cadence once, while each occurrence credits one block of a project's milestone"}, "note": {"type": ["string", "null"]}, "ts": {"type": "string"}, "source": {"type": "string", "description": "`todos` when rebuilt from an accepted to-do list; absent on a block-number check-in"}}}, "ImportBundle": {"type": "object", "description": "a sereo.import/1 bundle", "required": ["schema", "profile"], "properties": {"schema": {"type": "string", "const": "sereo.import/1"}, "profile": {"type": "object"}, "availability": {"type": "array", "description": "per weekday: `busy` blocks, and optionally `free` windows that are subtracted from the calendar (ADR-0012)"}, "habits": {"type": "array"}, "leisure": {"type": "array"}, "chores": {"type": "array"}, "goals": {"type": "array"}, "constraints": {"type": "array"}}}}}, "paths": {"/healthz": {"get": {"operationId": "healthz", "summary": "Liveness", "tags": ["system"], "description": "Returns immediately. No authentication, no side effects.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string"}}}}}}}, "security": []}}, "/openapi.json": {"get": {"operationId": "openapi_spec", "summary": "This document", "tags": ["system"], "description": "The API's own OpenAPI description, generated from the live route table rather than maintained by hand \u2014 so it cannot describe a route that does not exist, or miss one that does. Reflects this deployment: the goal-architect routes appear only where they are served.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["openapi", "info", "paths"], "properties": {"openapi": {"type": "string"}, "info": {"type": "object"}, "paths": {"type": "object"}, "components": {"type": "object"}}}}}}}, "security": []}}, "/v1/auth/register": {"post": {"operationId": "register", "summary": "Ask for an account", "tags": ["auth"], "description": "**202 to every address**, with no body (ADR-0093). Nothing is created here: the address, the scrypt-hashed password and the timezone are held as a pending signup, and the account is written only when the link mailed to that address is opened at `/v1/auth/signup/claim`. Whether the address is invited, and whether it already has an account, are told to the mailbox and never to the caller \u2014 answering either here enumerated the invitation list, and the old 201 handed the invitation to whoever asked first. A malformed address or a password under 12 characters is still a 400: both are properties of what was typed and reveal nothing about who is invited. A deployment with pre-verified addresses configured (`SEREO_VERIFIED_EMAILS`, development only) answers 201 with a token for those, as before.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["email", "password"], "properties": {"email": {"type": "string"}, "password": {"type": "string", "description": "12 characters or more"}, "timezone": {"type": "string", "description": "IANA name, default UTC"}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "required": ["user_id", "token", "expires_at"], "properties": {"user_id": {"type": "string"}, "token": {"type": "string"}, "expires_at": {"type": "string"}, "email_verified": {"type": "boolean"}}}}}}, "202": {"description": "Accepted; anything further is sent to the address itself"}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/v1/auth/login": {"post": {"operationId": "login", "summary": "Sign in", "tags": ["auth"], "description": "Exchanges email and password for a bearer token that lives until it goes 30 days unused: each use moves `expires_at` on, so a person who comes back daily is never signed out by the calendar (ADR-0176). Wrong credentials are a 401 whether or not the account exists.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["email", "password"], "properties": {"email": {"type": "string"}, "password": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["user_id", "token", "expires_at"], "properties": {"user_id": {"type": "string"}, "token": {"type": "string"}, "expires_at": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/v1/auth/logout": {"post": {"operationId": "logout", "summary": "Revoke this token", "tags": ["auth"], "description": "Revokes the presented token immediately. Other sessions keep working.", "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/auth/verify": {"post": {"operationId": "verify_email", "summary": "Prove an address", "tags": ["auth"], "description": "Redeems a verification link. Single use, 24 hours, and tied to the address it was minted for \u2014 an address changed since cannot be proven by the old link. Public, because the token in the link is the proof and the mail is often opened on another device.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["token"], "properties": {"token": {"type": "string"}}}}}}, "responses": {"204": {"description": "No content"}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/v1/auth/signup/claim": {"post": {"operationId": "claim_signup", "summary": "Open a signup link and become an account", "tags": ["auth"], "description": "Redeems the link registration mailed, and this is where the account is actually created (ADR-0093). Single use, 24 hours. The invitation is re-checked here rather than trusted from when the link was minted, because the list can change in between and the check that matters is the one at the write. Returns no session: the front end sends you to the sign-in screen, the same way a password reset does, because a bearer token delivered through a URL lives on in history and referrers. Public, because there is no account yet to authenticate as.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["token"], "properties": {"token": {"type": "string"}}}}}}, "responses": {"204": {"description": "No content"}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/v1/auth/providers": {"get": {"operationId": "signin_providers", "summary": "Which sign-in buttons to draw", "tags": ["auth"], "description": "Public, because the gate asks while signed out \u2014 which is the situation it describes. Says what this deployment is configured to offer and nothing per-account; the alternative is drawing a button that answers 503.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["providers"], "properties": {"providers": {"type": "array", "items": {"type": "string"}}, "password": {"type": "boolean"}, "support_email": {"type": ["string", "null"], "description": "where to write when the product is the problem (SEREO_SUPPORT_EMAIL); null when the deployment names none, and the gate then draws nothing"}}}}}}}, "security": []}}, "/v1/admin/allowlist": {"get": {"operationId": "allowlist_read", "summary": "Who may have an account here", "tags": ["auth"], "description": "Owner-only. A non-owner gets 404 rather than 403: the existence of this surface is not something an ordinary account needs to learn about. Owners are named in the environment and are not rows here, so no request can promote anybody or remove the person who has to fix a bad list.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["invite_only", "entries"], "properties": {"invite_only": {"type": "boolean"}, "owners": {"type": "array", "items": {"type": "string"}}, "entries": {"type": "array", "items": {"type": "object", "properties": {"pattern": {"type": "string"}, "note": {"type": ["string", "null"]}, "added_by": {"type": ["string", "null"]}, "created_at": {"type": "string"}}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "post": {"operationId": "allowlist_add", "summary": "Invite an address or a domain", "tags": ["auth"], "description": "A whole address, or a domain written with a leading dot (`.acme.com`) covering everything under it. Idempotent: re-adding updates the note. Owner-only.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["pattern"], "properties": {"pattern": {"type": "string"}, "note": {"type": "string"}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "properties": {"pattern": {"type": "string"}, "entries": {"type": "array"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/admin/allowlist/remove": {"post": {"operationId": "allowlist_remove", "summary": "Take an address off the list", "tags": ["auth"], "description": "Ends every session the entry was keeping alive, because removing somebody has to actually remove them \u2014 a live token outliving the removal would leave them signed in for up to thirty days. The pattern is named in the body: an address is not something that belongs in a path.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["pattern"], "properties": {"pattern": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"removed": {"type": "string"}, "entries": {"type": "array"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/admin/funnel": {"get": {"operationId": "funnel_read", "summary": "Signup, activation, retention \u2014 as counts", "tags": ["auth"], "description": "Owner-only; a non-owner gets 404, like the allowlist. Per signup month: accounts made, accounts that accepted a first day (activated), accounts that accepted or checked in at least a week after signup (retained). Counts only \u2014 no addresses, no events, no IPs; the three stamps live beside the account in its own database (`sereo.funnel`).", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["months", "totals"], "properties": {"months": {"type": "array", "items": {"type": "object", "properties": {"month": {"type": "string"}, "signed_up": {"type": "integer"}, "activated": {"type": "integer"}, "retained": {"type": "integer"}, "activation_rate": {"type": ["number", "null"]}, "retention_rate": {"type": ["number", "null"]}}}}, "totals": {"type": "object", "properties": {"signed_up": {"type": "integer"}, "activated": {"type": "integer"}, "retained": {"type": "integer"}, "activation_rate": {"type": ["number", "null"]}, "retention_rate": {"type": ["number", "null"]}}}, "retained_after_days": {"type": "integer"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/auth/{provider}/start": {"post": {"operationId": "signin_start", "summary": "Begin signing in with a provider", "tags": ["auth"], "description": "Returns a consent URL to navigate to. PKCE, with an opaque single-use state carrying the provider it was minted for \u2014 one cannot be redeemed at the other's callback. Public: the whole point is having no session. 503 where that provider is not configured here. Send `native: true` from an app that captures the callback on the `sereo://` scheme (ADR-0142); the web omits the body.", "parameters": [{"name": "provider", "in": "path", "required": true, "description": "google or github.", "schema": {"type": "string", "pattern": "^[a-z]{1,16}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"native": {"type": "boolean", "description": "Hand the single-use code back on the app's fixed sereo:// scheme instead of the web UI."}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["authorize_url", "state"], "properties": {"authorize_url": {"type": "string"}, "state": {"type": "string"}, "provider": {"type": "string"}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "429": {"description": "Too many attempts; wait and retry \u2014 `retry-after` says how long", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/v1/auth/{provider}/callback": {"get": {"operationId": "signin_callback", "summary": "A provider's redirect target", "tags": ["auth"], "description": "Where the account is opened, linked or created. A known subject signs in; an unknown one with an address the provider has verified links to a local account that has confirmed the same address, and otherwise makes a new one with no usable password. An unverified address links to nothing \u2014 anyone can put any address on an account at some provider. Redirects into the UI carrying a single-use handoff code, never a session token.", "parameters": [{"name": "provider", "in": "path", "required": true, "description": "google or github.", "schema": {"type": "string", "pattern": "^[a-z]{1,16}$"}}, {"name": "state", "in": "query", "required": false, "description": "The opaque state issued by start.", "schema": {"type": "string"}}, {"name": "code", "in": "query", "required": false, "description": "The provider's authorization code.", "schema": {"type": "string"}}, {"name": "error", "in": "query", "required": false, "description": "Set if the user cancelled.", "schema": {"type": "string"}}], "responses": {"302": {"description": "Redirect back into the app", "content": {"text/html": {"schema": {"type": "string"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"text/html": {"schema": {"type": "string"}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"text/html": {"schema": {"type": "string"}}}}}, "security": []}, "post": {"operationId": "signin_callback_form", "summary": "A provider's redirect target, posted", "tags": ["auth"], "description": "Apple's callback arrives as a POST with the same three fields form-encoded (response_mode=form_post, ADR-0143). The same rules and the same redirects as the GET.", "parameters": [{"name": "provider", "in": "path", "required": true, "description": "google or github.", "schema": {"type": "string", "pattern": "^[a-z]{1,16}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"state": {"type": "string"}, "code": {"type": "string"}, "error": {"type": "string"}, "user": {"type": "string", "description": "Apple's first-sign-in name blob; not stored."}}}}}}, "responses": {"302": {"description": "Redirect back into the app", "content": {"text/html": {"schema": {"type": "string"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"text/html": {"schema": {"type": "string"}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"text/html": {"schema": {"type": "string"}}}}}, "security": []}}, "/v1/auth/apple/native": {"post": {"operationId": "signin_apple_native", "summary": "Finish the app's own Sign in with Apple", "tags": ["auth"], "description": "The system sheet hands the app an authorization code for the bundle id; the app sends that code and nothing else, and the server exchanges it with Apple using a secret signed for the bundle id \u2014 the same trust as the web callback (ADR-0143). An id_token from the client is never accepted. Public, bounded like the callback, and answers in the /v1/auth/session shape. 503 where Apple sign-in is not configured here.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["code"], "properties": {"code": {"type": "string"}, "timezone": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["user_id", "token", "expires_at"], "properties": {"user_id": {"type": "string"}, "token": {"type": "string"}, "expires_at": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "429": {"description": "Too many attempts; wait and retry \u2014 `retry-after` says how long", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/v1/auth/session": {"post": {"operationId": "signin_session", "summary": "Trade a handoff code for a session", "tags": ["auth"], "description": "The token comes back in the body rather than in the redirect, which is why the handoff exists at all: a session credential in a URL lands in browser history and in every proxy log on the way. Single use, two minutes.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["code"], "properties": {"code": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["user_id", "token", "expires_at"], "properties": {"user_id": {"type": "string"}, "token": {"type": "string"}, "expires_at": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "429": {"description": "Too many attempts; wait and retry \u2014 `retry-after` says how long", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/v1/walkthrough/seen": {"post": {"operationId": "walkthrough_seen", "summary": "The first-run cards have been read", "tags": ["auth"], "description": "Stamps the account once; a second press changes nothing. `GET /v1/status` then answers `walkthrough_owed: false` on every client.", "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/walkthrough/steps": {"post": {"operationId": "walkthrough_step", "summary": "Skip a tutorial section, or say one was seen", "tags": ["auth"], "description": "`{key, outcome}`: `skipped` for any section, `visited` for `goals`, `calendar`, `reports` and `settings` \u2014 the week and today are done by doing them (ADR-0190, ADR-0195). 400 `bad_step` otherwise. Answers `{walkthrough_owed, tutorial}` as GET /v1/status would.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["key", "outcome"], "properties": {"key": {"type": "string"}, "outcome": {"enum": ["visited", "skipped"]}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["walkthrough_owed", "tutorial"], "properties": {"walkthrough_owed": {"type": "boolean"}, "tutorial": {"type": ["object", "null"], "properties": {"steps": {"type": "array", "items": {"type": "object", "required": ["key", "state"], "properties": {"key": {"enum": ["goals", "calendar", "week", "today", "reports", "settings"]}, "state": {"enum": ["todo", "done", "skipped"]}}}}, "current": {"enum": ["goals", "calendar", "week", "today", "reports", "settings", null]}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/walkthrough/restart": {"post": {"operationId": "walkthrough_restart", "summary": "Run the first-run tutorial again", "tags": ["auth"], "description": "Clears the end stamp and what was skipped or visited (ADR-0190). What the person has already done stays done, because those steps read the product.", "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/billing": {"get": {"operationId": "billing_status", "summary": "Whether this account may spend, and until when", "tags": ["auth"], "description": "Billing (ADR-0144). `enabled` false means the deployment is not taking money and everyone is entitled. Otherwise `entitled` is the one fact the spend gate reads \u2014 true while now is before `entitled_until` \u2014 and `status` is the last thing Stripe said (trial, active, past_due, canceled, none). `customer` says whether a Stripe customer exists, i.e. whether the portal can open. `checkout_first` is a new account that has never been entitled and never reached Stripe (ADR-0186): its Checkout takes a card and defers the first charge by the trial's days. `renew_with` names the way back (ADR-0188): `portal` while Stripe holds a subscription it can act on (active, trialing, past_due, unpaid, paused), `checkout` otherwise \u2014 the portal cannot start one, so a subscription that has ended comes back through Checkout. Null with billing off. `owner` is an account named in SEREO_OWNER_EMAILS, which is never billed: always entitled, never `checkout_first`, never lapsed (ADR-0189).", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["enabled", "entitled"], "properties": {"enabled": {"type": "boolean"}, "entitled": {"type": "boolean"}, "checkout_first": {"type": "boolean"}, "status": {"type": ["string", "null"]}, "entitled_until": {"type": ["string", "null"]}, "customer": {"type": "boolean"}, "renew_with": {"enum": ["checkout", "portal", null]}, "owner": {"type": "boolean"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/billing/checkout": {"post": {"operationId": "billing_checkout", "summary": "Open Stripe Checkout for the monthly price", "tags": ["auth"], "description": "Answers a URL to navigate to; the subscription is made there and reported back on the webhook. Web only \u2014 the phone links out to Settings on the web. 503 where billing is off; 403 until the address is confirmed; 409 `already_subscribed` while Stripe holds a live subscription (`renew_with` is `portal`, ADR-0188); 502 when Stripe cannot be reached.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["url"], "properties": {"url": {"type": "string"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "502": {"description": "Stripe could not be reached or refused; try again (`billing_unavailable`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/billing/portal": {"post": {"operationId": "billing_portal", "summary": "Open the Stripe customer portal", "tags": ["auth"], "description": "Change the card, cancel, see invoices. 409 for an account that never checked out; 503 where billing is off.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["url"], "properties": {"url": {"type": "string"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "502": {"description": "Stripe could not be reached or refused; try again (`billing_unavailable`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/billing/webhook": {"post": {"operationId": "billing_webhook", "summary": "Stripe's events", "tags": ["auth"], "description": "Public: Stripe has no session. Verified with `Stripe-Signature` over the body's exact bytes and a five-minute tolerance; a bad or stale signature is 400 and changes nothing. Each event writes at most one entitlement stamp, and replaying one writes the same stamp. 404 where billing is off.", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object"}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["received"], "properties": {"received": {"type": "boolean"}, "handled": {"type": "boolean"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/v1/auth/reset/request": {"post": {"operationId": "request_password_reset", "summary": "Ask for a reset link", "tags": ["auth"], "description": "Answers 204 for every address, whether or not it has an account: anything else is an enumeration oracle that needs no password to work. Which of the two happened is told to the mailbox instead, since that is the one place it helps the person who forgot which address they used. Public, because somebody who cannot sign in has no token.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["email"], "properties": {"email": {"type": "string"}}}}}}, "responses": {"204": {"description": "No content"}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "429": {"description": "Too many attempts; wait and retry \u2014 `retry-after` says how long", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/v1/auth/reset": {"post": {"operationId": "perform_password_reset", "summary": "Set a new password", "tags": ["auth"], "description": "Redeems a reset link. Single use, one hour, tied to the address it was minted for, and it revokes every session on the account \u2014 including any this request had, so the answer is to sign in again rather than a fresh token. A bad link and an expired one answer identically.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["token", "password"], "properties": {"token": {"type": "string"}, "password": {"type": "string"}}}}}}, "responses": {"204": {"description": "No content"}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "429": {"description": "Too many attempts; wait and retry \u2014 `retry-after` says how long", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/v1/auth/verify/resend": {"post": {"operationId": "resend_verification", "summary": "Send the link again", "tags": ["auth"], "description": "Answers 204 whether or not anything was sent, so it says nothing about the account's state.", "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/auth/tokens": {"get": {"operationId": "list_api_tokens", "summary": "Every API token this account has minted", "tags": ["auth"], "description": "Credentials for a machine \u2014 the CLI, the MCP server, a script. Never returns a token's value: only the digest is stored, so it cannot be shown again even to the account that made it (ADR-0099). Not reachable with an API token, whatever its scope.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["tokens"], "properties": {"tokens": {"type": "array", "items": {"type": "object", "required": ["id", "name", "scope", "created_at"], "properties": {"id": {"type": "string", "description": "what revoke takes"}, "name": {"type": "string"}, "scope": {"type": "string", "enum": ["full", "read"]}, "created_at": {"type": "string"}, "last_used_at": {"type": ["string", "null"]}, "expires_at": {"type": ["string", "null"], "description": "null means it does not expire"}, "revoked_at": {"type": ["string", "null"]}}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "post": {"operationId": "create_api_token", "summary": "Mint an API token", "tags": ["auth"], "description": "Returns the token once, in `token`, and never again. `scope` is `full` or `read`; a read token may call GET routes only, which also means it cannot reach anything that spends money, because every model-touching route is a POST. Omit `ttl_days` and it does not expire \u2014 the point of it, against a 30-day session that leaves an automation dead with no refresh path. Not reachable with an API token: a credential that can mint credentials cannot be revoked.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string", "maxLength": 64}, "scope": {"type": "string", "enum": ["full", "read"]}, "ttl_days": {"type": ["integer", "null"], "minimum": 1}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "required": ["id", "name", "scope", "token"], "properties": {"id": {"type": "string", "description": "what revoke takes"}, "name": {"type": "string"}, "scope": {"type": "string", "enum": ["full", "read"]}, "created_at": {"type": "string"}, "last_used_at": {"type": ["string", "null"]}, "expires_at": {"type": ["string", "null"], "description": "null means it does not expire"}, "revoked_at": {"type": ["string", "null"]}, "token": {"type": "string", "description": "the credential, shown this once"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/auth/tokens/{token}": {"delete": {"operationId": "revoke_api_token", "summary": "Revoke one API token", "tags": ["auth"], "description": "Immediate: the next request presenting it is a 401. Keyed on the account as well as the id, so one account cannot revoke another's.", "parameters": [{"name": "token", "in": "path", "required": true, "description": "An API token's id, from GET /v1/auth/tokens. Not the token.", "schema": {"type": "string", "pattern": "^sat_[a-f0-9]{12}$"}}], "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/navigation": {"post": {"operationId": "record_navigation", "summary": "Record what a traced account pressed", "tags": ["auth"], "description": "Beta instrumentation (ADR-0102). Answers 404 unless the deployment named this account in SEREO_TRACE_ACCOUNTS, so it is not an ambient telemetry endpoint. Records where somebody pressed and which view they were on \u2014 never what they typed. Kept beside the planner's working notes and deleted on the same 30-day sweep, and the account is told it is being recorded via GET /v1/status.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["events"], "properties": {"events": {"type": "array", "items": {"type": "object", "properties": {"at": {"type": "string"}, "kind": {"type": "string"}, "what": {"type": "string"}, "view": {"type": "string"}}}}}}}}}, "responses": {"202": {"description": "Accepted; anything further is sent to the address itself", "content": {"application/json": {"schema": {"type": "object", "required": ["kept"], "properties": {"kept": {"type": "integer"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/whoami": {"get": {"operationId": "whoami", "summary": "Get the authenticated account", "tags": ["auth"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["user_id", "email", "timezone"], "properties": {"user_id": {"type": "string"}, "email": {"type": "string"}, "timezone": {"type": "string"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/architect/start": {"post": {"operationId": "architect_start", "summary": "Start or resume a goal-architect session", "tags": ["architect"], "description": "Opens a goal-architect conversation, or resumes the one in progress, and returns the session step.\n\nModes: `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.\n\nAn 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.\n\nA 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`.\n\nErrors: `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.", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"mode": {"type": "string", "enum": ["deepen", "talk", "blueprint"], "description": "defaults to talk when a goal is given, else deepen"}, "goal": {"type": "string", "description": "interest id to anchor talk mode"}, "milestone": {"type": "string", "description": "milestone name or id within the anchored goal"}, "resume": {"type": "boolean", "description": "continue the in-flight conversation whatever it is anchored to; 404 when there is none"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["state", "mode", "turn", "draft_summary", "working"], "properties": {"working": {"type": "boolean", "description": "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 (ADR-0097)"}, "last_error": {"type": ["object", "null"], "description": "why the last turn failed, when the request that would have carried it had already answered 202", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}, "state": {"type": "string", "enum": ["interview", "confirming", "ready", "committed"]}, "mode": {"type": "string", "enum": ["deepen", "talk", "blueprint"]}, "turn": {"type": "integer", "minimum": 0}, "message": {"type": ["string", "null"], "description": "the agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)"}, "messages": {"type": "array", "items": {"type": "string"}, "description": "the reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null"}, "transcript": {"type": "array", "items": {"type": "array", "items": {"type": "string"}}, "description": "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"}, "anchor": {"type": ["object", "null"], "properties": {"goal": {"type": "string"}, "milestone": {"type": ["string", "null"]}}}, "draft_summary": {"type": "object", "properties": {"goals": {"type": "integer"}, "supporting": {"type": "integer"}, "standalone": {"type": "integer"}, "milestones": {"type": "integer"}, "tasks": {"type": "integer"}, "unconfirmed": {"type": "array", "items": {"type": "string"}}}}, "turn_decisions": {"type": "array", "items": {"type": "object"}, "description": "the rounds of the assistant turn just executed: {turn, round, reasoning, calls, text?} \u2014 the model's reasoning and each tool decision, for a UI that shows the work (ADR-0024)"}, "preview": {"type": ["object", "null"], "properties": {"counts": {"type": "object"}, "defaults": {"type": "array", "items": {"type": "string"}}, "dropped": {"type": "array", "items": {"type": "string"}}, "overdue": {"type": "array", "items": {"type": "string"}}, "notes": {"type": "array", "items": {"type": "string"}}}, "description": "the commit's dry-run import report; non-null only in state `ready` for a `deepen` or `blueprint` session"}, "traces": {"type": "array", "items": {"type": "object", "required": ["turn", "user_index", "steps", "changes"], "properties": {"turn": {"type": "integer", "minimum": 0, "description": "0 is the written opening"}, "user_index": {"type": "integer", "minimum": 0, "description": "how many of the person's messages came before this reply"}, "steps": {"type": "array", "items": {"type": "object", "required": ["kind"], "properties": {"kind": {"type": "string", "enum": ["think", "search"]}, "text": {"type": "string", "description": "think: one sentence, in Sereo's voice"}, "source": {"type": "object", "required": ["url", "domain"], "properties": {"url": {"type": "string"}, "domain": {"type": "string"}, "title": {"type": "string"}}, "description": "think: the page the answer came from, only when a search in the same turn cited it"}, "query": {"type": "string"}, "error": {"type": "boolean"}, "sources": {"type": "array", "items": {"type": "object", "required": ["url", "domain"], "properties": {"url": {"type": "string"}, "domain": {"type": "string"}, "title": {"type": "string"}}}}}}}, "changes": {"type": "array", "items": {"type": "object", "required": ["verb", "kind", "label", "facts"], "properties": {"verb": {"type": "string", "enum": ["Staged", "Changed", "Removed", "Up next"]}, "kind": {"type": "string", "enum": ["goal", "rhythm", "chore", "up_next"]}, "label": {"type": "string"}, "facts": {"type": "array", "items": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string"}, "date": {"type": ["string", "null"]}}}}}}, "description": "one line per thing the turn changed, diffed from the draft by the server, never the model's account"}, "ask": {"type": ["object", "null"], "required": ["question", "options", "multi"], "properties": {"question": {"type": "string"}, "options": {"type": "array", "items": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}, "detail": {"type": "string"}}}}, "multi": {"type": "boolean", "description": "several answers may be picked together"}}}, "reply": {"type": "array", "items": {"type": "string"}, "description": "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"}}}, "description": "what each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked (ADR-0197)"}, "open_ask": {"type": ["object", "null"], "required": ["question", "options", "multi"], "properties": {"question": {"type": "string"}, "options": {"type": "array", "items": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}, "detail": {"type": "string"}}}}, "multi": {"type": "boolean", "description": "several answers may be picked together"}}, "description": "the question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer"}, "setup": {"type": "object", "required": ["staged", "building", "window"], "properties": {"staged": {"type": "array", "items": {"type": "object", "required": ["title", "kind", "kind_label", "line", "months", "marks"], "properties": {"title": {"type": "string", "description": "the state this goal reaches, which is its name"}, "tag": {"type": ["string", "null"], "description": "what the user calls it, in their own words"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "the acceptance criteria; empty for a rhythm, which has no end"}, "kind": {"type": "string", "enum": ["project", "habit", "leisure", "chore"]}, "kind_label": {"type": "string", "description": "what the hub calls this kind"}, "line": {"type": "string", "description": "how the engine treats this kind \u2014 a claim about the type, never about the goal"}, "months": {"type": "number", "minimum": 1, "maximum": 12, "description": "how far round the year the rail runs"}, "beyond": {"type": "boolean", "description": "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"}, "date": {"type": ["string", "null"], "format": "date", "description": "where the rail ends; null for a rhythm, which has no end"}, "note": {"type": "string"}, "marks": {"type": "array", "items": {"type": "object", "required": ["at", "label"], "properties": {"at": {"type": "number", "minimum": 0, "maximum": 1}, "label": {"type": "string"}, "date": {"type": "string", "format": "date"}, "fixed": {"type": "boolean"}}}}, "facts": {"type": "array", "items": {"type": "object"}}}}, "description": "what committing would put on the year"}, "building": {"type": "array", "items": {"type": "object", "required": ["text", "state"], "properties": {"text": {"type": "string"}, "state": {"type": "string"}}}, "description": "display lines (`text`, `state`) describing what committing this draft will build"}, "window": {"type": "object", "properties": {"from": {"type": "string", "format": "date"}, "to": {"type": "string", "format": "date"}}}, "up_next": {"type": "array", "items": {"type": "string"}, "description": "goals the person named that the conversation has not reached yet, in the order it will take them (ADR-0197)"}}, "description": "the year as committing this draft would leave it: `staged` entries, `building` lines and the date `window`"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/architect/session": {"get": {"operationId": "architect_session", "summary": "Get the goal-architect session", "tags": ["architect"], "description": "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.\n\nRead-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.\n\nA committed session is still returned (with `state: committed`) until it is discarded or replaced.\n\nErrors: `404` when there is no session.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["state", "mode", "turn", "draft_summary", "working"], "properties": {"working": {"type": "boolean", "description": "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 (ADR-0097)"}, "last_error": {"type": ["object", "null"], "description": "why the last turn failed, when the request that would have carried it had already answered 202", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}, "state": {"type": "string", "enum": ["interview", "confirming", "ready", "committed"]}, "mode": {"type": "string", "enum": ["deepen", "talk", "blueprint"]}, "turn": {"type": "integer", "minimum": 0}, "message": {"type": ["string", "null"], "description": "the agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)"}, "messages": {"type": "array", "items": {"type": "string"}, "description": "the reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null"}, "transcript": {"type": "array", "items": {"type": "array", "items": {"type": "string"}}, "description": "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"}, "anchor": {"type": ["object", "null"], "properties": {"goal": {"type": "string"}, "milestone": {"type": ["string", "null"]}}}, "draft_summary": {"type": "object", "properties": {"goals": {"type": "integer"}, "supporting": {"type": "integer"}, "standalone": {"type": "integer"}, "milestones": {"type": "integer"}, "tasks": {"type": "integer"}, "unconfirmed": {"type": "array", "items": {"type": "string"}}}}, "turn_decisions": {"type": "array", "items": {"type": "object"}, "description": "the rounds of the assistant turn just executed: {turn, round, reasoning, calls, text?} \u2014 the model's reasoning and each tool decision, for a UI that shows the work (ADR-0024)"}, "preview": {"type": ["object", "null"], "properties": {"counts": {"type": "object"}, "defaults": {"type": "array", "items": {"type": "string"}}, "dropped": {"type": "array", "items": {"type": "string"}}, "overdue": {"type": "array", "items": {"type": "string"}}, "notes": {"type": "array", "items": {"type": "string"}}}, "description": "the commit's dry-run import report; non-null only in state `ready` for a `deepen` or `blueprint` session"}, "traces": {"type": "array", "items": {"type": "object", "required": ["turn", "user_index", "steps", "changes"], "properties": {"turn": {"type": "integer", "minimum": 0, "description": "0 is the written opening"}, "user_index": {"type": "integer", "minimum": 0, "description": "how many of the person's messages came before this reply"}, "steps": {"type": "array", "items": {"type": "object", "required": ["kind"], "properties": {"kind": {"type": "string", "enum": ["think", "search"]}, "text": {"type": "string", "description": "think: one sentence, in Sereo's voice"}, "source": {"type": "object", "required": ["url", "domain"], "properties": {"url": {"type": "string"}, "domain": {"type": "string"}, "title": {"type": "string"}}, "description": "think: the page the answer came from, only when a search in the same turn cited it"}, "query": {"type": "string"}, "error": {"type": "boolean"}, "sources": {"type": "array", "items": {"type": "object", "required": ["url", "domain"], "properties": {"url": {"type": "string"}, "domain": {"type": "string"}, "title": {"type": "string"}}}}}}}, "changes": {"type": "array", "items": {"type": "object", "required": ["verb", "kind", "label", "facts"], "properties": {"verb": {"type": "string", "enum": ["Staged", "Changed", "Removed", "Up next"]}, "kind": {"type": "string", "enum": ["goal", "rhythm", "chore", "up_next"]}, "label": {"type": "string"}, "facts": {"type": "array", "items": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string"}, "date": {"type": ["string", "null"]}}}}}}, "description": "one line per thing the turn changed, diffed from the draft by the server, never the model's account"}, "ask": {"type": ["object", "null"], "required": ["question", "options", "multi"], "properties": {"question": {"type": "string"}, "options": {"type": "array", "items": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}, "detail": {"type": "string"}}}}, "multi": {"type": "boolean", "description": "several answers may be picked together"}}}, "reply": {"type": "array", "items": {"type": "string"}, "description": "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"}}}, "description": "what each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked (ADR-0197)"}, "open_ask": {"type": ["object", "null"], "required": ["question", "options", "multi"], "properties": {"question": {"type": "string"}, "options": {"type": "array", "items": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}, "detail": {"type": "string"}}}}, "multi": {"type": "boolean", "description": "several answers may be picked together"}}, "description": "the question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer"}, "setup": {"type": "object", "required": ["staged", "building", "window"], "properties": {"staged": {"type": "array", "items": {"type": "object", "required": ["title", "kind", "kind_label", "line", "months", "marks"], "properties": {"title": {"type": "string", "description": "the state this goal reaches, which is its name"}, "tag": {"type": ["string", "null"], "description": "what the user calls it, in their own words"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "the acceptance criteria; empty for a rhythm, which has no end"}, "kind": {"type": "string", "enum": ["project", "habit", "leisure", "chore"]}, "kind_label": {"type": "string", "description": "what the hub calls this kind"}, "line": {"type": "string", "description": "how the engine treats this kind \u2014 a claim about the type, never about the goal"}, "months": {"type": "number", "minimum": 1, "maximum": 12, "description": "how far round the year the rail runs"}, "beyond": {"type": "boolean", "description": "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"}, "date": {"type": ["string", "null"], "format": "date", "description": "where the rail ends; null for a rhythm, which has no end"}, "note": {"type": "string"}, "marks": {"type": "array", "items": {"type": "object", "required": ["at", "label"], "properties": {"at": {"type": "number", "minimum": 0, "maximum": 1}, "label": {"type": "string"}, "date": {"type": "string", "format": "date"}, "fixed": {"type": "boolean"}}}}, "facts": {"type": "array", "items": {"type": "object"}}}}, "description": "what committing would put on the year"}, "building": {"type": "array", "items": {"type": "object", "required": ["text", "state"], "properties": {"text": {"type": "string"}, "state": {"type": "string"}}}, "description": "display lines (`text`, `state`) describing what committing this draft will build"}, "window": {"type": "object", "properties": {"from": {"type": "string", "format": "date"}, "to": {"type": "string", "format": "date"}}}, "up_next": {"type": "array", "items": {"type": "string"}, "description": "goals the person named that the conversation has not reached yet, in the order it will take them (ADR-0197)"}}, "description": "the year as committing this draft would leave it: `staged` entries, `building` lines and the date `window`"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "delete": {"operationId": "architect_discard", "summary": "Discard the goal-architect session", "tags": ["architect"], "description": "Deletes the account's goal-architect session and its draft. Returns `204` with no body.\n\nNothing 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.\n\nErrors: `404` when there is no session.", "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/architect/stream": {"get": {"operationId": "architect_stream", "summary": "Stream goal-architect events", "tags": ["architect"], "description": "Opens a server-sent event stream (`text/event-stream`) of live events for the calling account.\n\nEach 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.\n\nA `: 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.\n\nThe 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": {"description": "OK", "content": {"text/event-stream": {"schema": {"type": "string"}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"text/event-stream": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/architect/turns": {"post": {"operationId": "architect_turn", "summary": "Send a turn to the goal architect", "tags": ["architect"], "description": "Submits one user message to the goal-architect session and returns the resulting step.\n\nA 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.\n\nConfirmation: 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.\n\nWhen 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.\n\nSend the session's current `turn` number to turn a duplicate submit into a clean `409 stale_turn`.\n\nErrors: `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`.", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"message": {"type": "string"}, "confirm": {"type": "boolean"}, "turn": {"type": "integer", "minimum": 0}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["state", "mode", "turn", "draft_summary", "working"], "properties": {"working": {"type": "boolean", "description": "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 (ADR-0097)"}, "last_error": {"type": ["object", "null"], "description": "why the last turn failed, when the request that would have carried it had already answered 202", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}, "state": {"type": "string", "enum": ["interview", "confirming", "ready", "committed"]}, "mode": {"type": "string", "enum": ["deepen", "talk", "blueprint"]}, "turn": {"type": "integer", "minimum": 0}, "message": {"type": ["string", "null"], "description": "the agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)"}, "messages": {"type": "array", "items": {"type": "string"}, "description": "the reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null"}, "transcript": {"type": "array", "items": {"type": "array", "items": {"type": "string"}}, "description": "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"}, "anchor": {"type": ["object", "null"], "properties": {"goal": {"type": "string"}, "milestone": {"type": ["string", "null"]}}}, "draft_summary": {"type": "object", "properties": {"goals": {"type": "integer"}, "supporting": {"type": "integer"}, "standalone": {"type": "integer"}, "milestones": {"type": "integer"}, "tasks": {"type": "integer"}, "unconfirmed": {"type": "array", "items": {"type": "string"}}}}, "turn_decisions": {"type": "array", "items": {"type": "object"}, "description": "the rounds of the assistant turn just executed: {turn, round, reasoning, calls, text?} \u2014 the model's reasoning and each tool decision, for a UI that shows the work (ADR-0024)"}, "preview": {"type": ["object", "null"], "properties": {"counts": {"type": "object"}, "defaults": {"type": "array", "items": {"type": "string"}}, "dropped": {"type": "array", "items": {"type": "string"}}, "overdue": {"type": "array", "items": {"type": "string"}}, "notes": {"type": "array", "items": {"type": "string"}}}, "description": "the commit's dry-run import report; non-null only in state `ready` for a `deepen` or `blueprint` session"}, "traces": {"type": "array", "items": {"type": "object", "required": ["turn", "user_index", "steps", "changes"], "properties": {"turn": {"type": "integer", "minimum": 0, "description": "0 is the written opening"}, "user_index": {"type": "integer", "minimum": 0, "description": "how many of the person's messages came before this reply"}, "steps": {"type": "array", "items": {"type": "object", "required": ["kind"], "properties": {"kind": {"type": "string", "enum": ["think", "search"]}, "text": {"type": "string", "description": "think: one sentence, in Sereo's voice"}, "source": {"type": "object", "required": ["url", "domain"], "properties": {"url": {"type": "string"}, "domain": {"type": "string"}, "title": {"type": "string"}}, "description": "think: the page the answer came from, only when a search in the same turn cited it"}, "query": {"type": "string"}, "error": {"type": "boolean"}, "sources": {"type": "array", "items": {"type": "object", "required": ["url", "domain"], "properties": {"url": {"type": "string"}, "domain": {"type": "string"}, "title": {"type": "string"}}}}}}}, "changes": {"type": "array", "items": {"type": "object", "required": ["verb", "kind", "label", "facts"], "properties": {"verb": {"type": "string", "enum": ["Staged", "Changed", "Removed", "Up next"]}, "kind": {"type": "string", "enum": ["goal", "rhythm", "chore", "up_next"]}, "label": {"type": "string"}, "facts": {"type": "array", "items": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string"}, "date": {"type": ["string", "null"]}}}}}}, "description": "one line per thing the turn changed, diffed from the draft by the server, never the model's account"}, "ask": {"type": ["object", "null"], "required": ["question", "options", "multi"], "properties": {"question": {"type": "string"}, "options": {"type": "array", "items": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}, "detail": {"type": "string"}}}}, "multi": {"type": "boolean", "description": "several answers may be picked together"}}}, "reply": {"type": "array", "items": {"type": "string"}, "description": "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"}}}, "description": "what each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked (ADR-0197)"}, "open_ask": {"type": ["object", "null"], "required": ["question", "options", "multi"], "properties": {"question": {"type": "string"}, "options": {"type": "array", "items": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}, "detail": {"type": "string"}}}}, "multi": {"type": "boolean", "description": "several answers may be picked together"}}, "description": "the question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer"}, "setup": {"type": "object", "required": ["staged", "building", "window"], "properties": {"staged": {"type": "array", "items": {"type": "object", "required": ["title", "kind", "kind_label", "line", "months", "marks"], "properties": {"title": {"type": "string", "description": "the state this goal reaches, which is its name"}, "tag": {"type": ["string", "null"], "description": "what the user calls it, in their own words"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "the acceptance criteria; empty for a rhythm, which has no end"}, "kind": {"type": "string", "enum": ["project", "habit", "leisure", "chore"]}, "kind_label": {"type": "string", "description": "what the hub calls this kind"}, "line": {"type": "string", "description": "how the engine treats this kind \u2014 a claim about the type, never about the goal"}, "months": {"type": "number", "minimum": 1, "maximum": 12, "description": "how far round the year the rail runs"}, "beyond": {"type": "boolean", "description": "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"}, "date": {"type": ["string", "null"], "format": "date", "description": "where the rail ends; null for a rhythm, which has no end"}, "note": {"type": "string"}, "marks": {"type": "array", "items": {"type": "object", "required": ["at", "label"], "properties": {"at": {"type": "number", "minimum": 0, "maximum": 1}, "label": {"type": "string"}, "date": {"type": "string", "format": "date"}, "fixed": {"type": "boolean"}}}}, "facts": {"type": "array", "items": {"type": "object"}}}}, "description": "what committing would put on the year"}, "building": {"type": "array", "items": {"type": "object", "required": ["text", "state"], "properties": {"text": {"type": "string"}, "state": {"type": "string"}}}, "description": "display lines (`text`, `state`) describing what committing this draft will build"}, "window": {"type": "object", "properties": {"from": {"type": "string", "format": "date"}, "to": {"type": "string", "format": "date"}}}, "up_next": {"type": "array", "items": {"type": "string"}, "description": "goals the person named that the conversation has not reached yet, in the order it will take them (ADR-0197)"}}, "description": "the year as committing this draft would leave it: `staged` entries, `building` lines and the date `window`"}}}}}}, "202": {"description": "Accepted; anything further is sent to the address itself", "content": {"application/json": {"schema": {"type": "object", "required": ["state", "mode", "turn", "draft_summary", "working"], "properties": {"working": {"type": "boolean", "description": "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 (ADR-0097)"}, "last_error": {"type": ["object", "null"], "description": "why the last turn failed, when the request that would have carried it had already answered 202", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}}, "state": {"type": "string", "enum": ["interview", "confirming", "ready", "committed"]}, "mode": {"type": "string", "enum": ["deepen", "talk", "blueprint"]}, "turn": {"type": "integer", "minimum": 0}, "message": {"type": ["string", "null"], "description": "the agent's reply; null when there is none, e.g. a recorded confirmation or a turn still running (202)"}, "messages": {"type": "array", "items": {"type": "string"}, "description": "the reply split at its blank-line seams: each element is one chat bubble, in order; empty when message is null"}, "transcript": {"type": "array", "items": {"type": "array", "items": {"type": "string"}}, "description": "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"}, "anchor": {"type": ["object", "null"], "properties": {"goal": {"type": "string"}, "milestone": {"type": ["string", "null"]}}}, "draft_summary": {"type": "object", "properties": {"goals": {"type": "integer"}, "supporting": {"type": "integer"}, "standalone": {"type": "integer"}, "milestones": {"type": "integer"}, "tasks": {"type": "integer"}, "unconfirmed": {"type": "array", "items": {"type": "string"}}}}, "turn_decisions": {"type": "array", "items": {"type": "object"}, "description": "the rounds of the assistant turn just executed: {turn, round, reasoning, calls, text?} \u2014 the model's reasoning and each tool decision, for a UI that shows the work (ADR-0024)"}, "preview": {"type": ["object", "null"], "properties": {"counts": {"type": "object"}, "defaults": {"type": "array", "items": {"type": "string"}}, "dropped": {"type": "array", "items": {"type": "string"}}, "overdue": {"type": "array", "items": {"type": "string"}}, "notes": {"type": "array", "items": {"type": "string"}}}, "description": "the commit's dry-run import report; non-null only in state `ready` for a `deepen` or `blueprint` session"}, "traces": {"type": "array", "items": {"type": "object", "required": ["turn", "user_index", "steps", "changes"], "properties": {"turn": {"type": "integer", "minimum": 0, "description": "0 is the written opening"}, "user_index": {"type": "integer", "minimum": 0, "description": "how many of the person's messages came before this reply"}, "steps": {"type": "array", "items": {"type": "object", "required": ["kind"], "properties": {"kind": {"type": "string", "enum": ["think", "search"]}, "text": {"type": "string", "description": "think: one sentence, in Sereo's voice"}, "source": {"type": "object", "required": ["url", "domain"], "properties": {"url": {"type": "string"}, "domain": {"type": "string"}, "title": {"type": "string"}}, "description": "think: the page the answer came from, only when a search in the same turn cited it"}, "query": {"type": "string"}, "error": {"type": "boolean"}, "sources": {"type": "array", "items": {"type": "object", "required": ["url", "domain"], "properties": {"url": {"type": "string"}, "domain": {"type": "string"}, "title": {"type": "string"}}}}}}}, "changes": {"type": "array", "items": {"type": "object", "required": ["verb", "kind", "label", "facts"], "properties": {"verb": {"type": "string", "enum": ["Staged", "Changed", "Removed", "Up next"]}, "kind": {"type": "string", "enum": ["goal", "rhythm", "chore", "up_next"]}, "label": {"type": "string"}, "facts": {"type": "array", "items": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string"}, "date": {"type": ["string", "null"]}}}}}}, "description": "one line per thing the turn changed, diffed from the draft by the server, never the model's account"}, "ask": {"type": ["object", "null"], "required": ["question", "options", "multi"], "properties": {"question": {"type": "string"}, "options": {"type": "array", "items": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}, "detail": {"type": "string"}}}}, "multi": {"type": "boolean", "description": "several answers may be picked together"}}}, "reply": {"type": "array", "items": {"type": "string"}, "description": "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"}}}, "description": "what each reply showed of the work, oldest first: narrated steps, searches with the pages they cited, the changes, the question it asked (ADR-0197)"}, "open_ask": {"type": ["object", "null"], "required": ["question", "options", "multi"], "properties": {"question": {"type": "string"}, "options": {"type": "array", "items": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}, "detail": {"type": "string"}}}}, "multi": {"type": "boolean", "description": "several answers may be picked together"}}, "description": "the question waiting on the person, or null: decided by the server, never while a turn runs or a plan is on offer"}, "setup": {"type": "object", "required": ["staged", "building", "window"], "properties": {"staged": {"type": "array", "items": {"type": "object", "required": ["title", "kind", "kind_label", "line", "months", "marks"], "properties": {"title": {"type": "string", "description": "the state this goal reaches, which is its name"}, "tag": {"type": ["string", "null"], "description": "what the user calls it, in their own words"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "the acceptance criteria; empty for a rhythm, which has no end"}, "kind": {"type": "string", "enum": ["project", "habit", "leisure", "chore"]}, "kind_label": {"type": "string", "description": "what the hub calls this kind"}, "line": {"type": "string", "description": "how the engine treats this kind \u2014 a claim about the type, never about the goal"}, "months": {"type": "number", "minimum": 1, "maximum": 12, "description": "how far round the year the rail runs"}, "beyond": {"type": "boolean", "description": "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"}, "date": {"type": ["string", "null"], "format": "date", "description": "where the rail ends; null for a rhythm, which has no end"}, "note": {"type": "string"}, "marks": {"type": "array", "items": {"type": "object", "required": ["at", "label"], "properties": {"at": {"type": "number", "minimum": 0, "maximum": 1}, "label": {"type": "string"}, "date": {"type": "string", "format": "date"}, "fixed": {"type": "boolean"}}}}, "facts": {"type": "array", "items": {"type": "object"}}}}, "description": "what committing would put on the year"}, "building": {"type": "array", "items": {"type": "object", "required": ["text", "state"], "properties": {"text": {"type": "string"}, "state": {"type": "string"}}}, "description": "display lines (`text`, `state`) describing what committing this draft will build"}, "window": {"type": "object", "properties": {"from": {"type": "string", "format": "date"}, "to": {"type": "string", "format": "date"}}}, "up_next": {"type": "array", "items": {"type": "string"}, "description": "goals the person named that the conversation has not reached yet, in the order it will take them (ADR-0197)"}}, "description": "the year as committing this draft would leave it: `staged` entries, `building` lines and the date `window`"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/architect/commit": {"post": {"operationId": "architect_commit", "summary": "Commit the goal-architect draft", "tags": ["architect"], "description": "Writes the confirmed draft to the user's profile, marks the session `committed`, and returns a commit report.\n\nThe 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.\n\n`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.\n\n`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.\n\nErrors: `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.", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"accept": {"type": "boolean"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["mode", "committed", "report"], "properties": {"mode": {"type": "string", "enum": ["deepen", "talk", "blueprint"]}, "committed": {"type": "boolean", "const": true}, "updated_goal": {"type": ["string", "null"]}, "anchor_date": {"type": ["string", "null"], "format": "date"}, "report": {"type": "object", "description": "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.", "properties": {"carried": {"type": "array", "items": {"type": "string"}}, "not_written": {"type": "array", "items": {"type": "string"}}}}, "planned": {"type": ["string", "null"], "format": "date", "description": "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"}, "working": {"type": "boolean", "description": "deepen/blueprint: true with a 202 while the first week and day are still being built; follow GET /v1/plans/{date}/stream"}}}}}}, "202": {"description": "Accepted; anything further is sent to the address itself", "content": {"application/json": {"schema": {"type": "object", "required": ["mode", "committed", "report"], "properties": {"mode": {"type": "string", "enum": ["deepen", "talk", "blueprint"]}, "committed": {"type": "boolean", "const": true}, "updated_goal": {"type": ["string", "null"]}, "anchor_date": {"type": ["string", "null"], "format": "date"}, "report": {"type": "object", "description": "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.", "properties": {"carried": {"type": "array", "items": {"type": "string"}}, "not_written": {"type": "array", "items": {"type": "string"}}}}, "planned": {"type": ["string", "null"], "format": "date", "description": "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"}, "working": {"type": "boolean", "description": "deepen/blueprint: true with a 202 while the first week and day are still being built; follow GET /v1/plans/{date}/stream"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/profile": {"get": {"operationId": "get_profile", "summary": "Get the profile", "tags": ["goals"], "description": "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.\n\nFour fields are computed on read and are never written back:\n\n- `day_window` \u2014 the hours in force, `{start, end, start_from, end_from, wraps}`; each `*_from` is `stated`, `sleep` or `default` (ADR-0177). Read this rather than `day_start`/`day_end`, which are absent when the window follows `sleep`. - `never` \u2014 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` \u2014 whether any of `sleep`, `day_start`, `day_end` or `hours_off` is set. - `never_suggested` \u2014 a default sleep row for a first-run form.\n\nFor interests with derived state, use `GET /v1/library`.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "patch": {"operationId": "patch_profile", "summary": "Update profile settings", "tags": ["goals"], "description": "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.\n\nSend 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 \u2014 use `POST /v1/import`, `POST /v1/jobs` and the `/v1/interests` routes. `timezone` is also written to the account; `timezone: null` is ignored.\n\n`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.\n\n`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`.\n\n`place`, `latitude` and `longitude` are optional; without them daylight times are not shown.\n\nChanging any `*_time` or `*_minutes` field re-queues the user's scheduled jobs so the new time applies the same day.\n\nErrors: `400 invalid_request` for unknown fields or values that fail validation; `400 never_hours` as above.", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"timezone": {"type": "string", "description": "IANA name"}, "never": {"type": ["array", "null"], "description": "The complete set of unavailable hours, as rows; replaces `sleep`, `hours_off`, `day_start` and `day_end`. null or [] clears them all", "items": {"type": "object", "required": ["start", "end"], "properties": {"label": {"type": "string"}, "start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "days": {"type": ["array", "null"], "items": {"type": "integer", "minimum": 0, "maximum": 6}}}}}, "day_start": {"type": ["string", "null"], "pattern": "^[0-9]{2}:[0-9]{2}$"}, "day_end": {"type": ["string", "null"], "pattern": "^[0-9]{2}:[0-9]{2}$"}, "days_off": {"type": ["array", "null"], "items": {"type": "integer", "minimum": 0, "maximum": 6}, "description": "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 (ADR-0061). Cannot list all seven days."}, "hours_off": {"type": ["object", "null"], "description": "Recurring unavailable windows per weekday, keyed \"0\"\u2013\"6\" (Monday 0); each value is a list of `{start, end, title?}` in HH:MM. Merged into the calendar as busy time (ADR-0012), so nothing is placed inside them. `days_off` covers whole days; this field covers hours within a day. Replaced wholesale when `never` is sent.", "additionalProperties": {"type": "array", "items": {"type": "object", "required": ["start", "end"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "title": {"type": "string"}}}}}, "place": {"type": ["string", "null"]}, "latitude": {"type": ["number", "null"], "minimum": -90, "maximum": 90}, "longitude": {"type": ["number", "null"], "minimum": -180, "maximum": 180}, "default_energy": {"type": ["integer", "null"], "minimum": 1, "maximum": 5}, "buffer_after_shift_minutes": {"type": ["integer", "null"]}, "sleep": {"type": ["object", "null"], "description": "{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`", "properties": {"start": {"type": "string"}, "end": {"type": "string"}}}, "quiet_hours": {"type": ["object", "null"], "properties": {"start": {"type": "string"}, "end": {"type": "string"}}}, "morning_plan_time": {"type": ["string", "null"]}, "evening_checkin_time": {"type": ["string", "null"]}, "miss_sweep_time": {"type": ["string", "null"]}, "weekly_retro_time": {"type": ["string", "null"]}, "todoist_sync_minutes": {"type": ["integer", "null"]}, "auto_plan": {"type": ["boolean", "null"], "description": "whether Sereo may pre-build days \u2014 the morning plan and the post-absence re-entry day (ADR-0138). Off by default"}, "evening_checkin": {"type": ["boolean", "null"], "description": "whether the evening check-in is asked for. Absent or true: on; false: no check-in and no nudge"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["changed", "profile"], "properties": {"changed": {"type": "array", "items": {"type": "string"}}, "profile": {"type": "object"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/account": {"delete": {"operationId": "delete_account", "summary": "Delete the account and everything under it", "tags": ["auth"], "description": "Irreversible. The user's whole data directory is removed, every session is revoked, and any queued job goes with it.\n\nThe account's own email address must be sent back as confirmation: this is the one action in the product with nothing behind it, and a misfired click should not be able to reach it.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["email"], "properties": {"email": {"type": "string"}}}}}}, "responses": {"204": {"description": "No content"}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/status": {"get": {"operationId": "status", "summary": "Get the account's current status", "tags": ["planning"], "description": "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.\n\n`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.\n\nAnswers for an account in any standing, including `checkout_first`, so a client can use it to decide what to offer next.", "parameters": [{"name": "date", "in": "query", "required": false, "description": "Override today, YYYY-MM-DD.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["date", "onboarded", "plan_exists"], "properties": {"date": {"type": "string"}, "onboarded": {"type": "boolean"}, "interests": {"type": "integer"}, "goals": {"type": "integer", "description": "goals only (the projects), not the habits, leisure or chores under them \u2014 what the band counts so it agrees with the year wheel (ADR-0124)"}, "plan_exists": {"type": "boolean"}, "plan_accepted": {"type": "boolean"}, "awaiting_checkin": {"type": "boolean"}, "gap_days": {"type": ["integer", "null"], "description": "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_reconciling": {"type": "array", "items": {"type": "object"}}, "on_hold": {"type": "array", "items": {"type": "object"}}, "calendar_connected": {"type": "boolean"}, "timezone": {"type": "string", "description": "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 (ADR-0101)"}, "navigation_traced": {"type": "boolean", "description": "this account's navigation is being recorded for the beta, and the screen says so (ADR-0102)"}, "architect": {"type": "boolean", "description": "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_running": {"type": "boolean", "description": "a report for this account is being generated right now"}, "report_written": {"type": "boolean", "description": "whether any report has been written for this account, read or not \u2014 the tour's Reports page has steps about one only when it does"}, "unread_report": {"type": ["object", "null"], "properties": {"period": {"type": "string"}, "ending": {"type": "string"}}, "description": "the latest written report not yet marked read; cleared by `POST /v1/reports/{period}/{date}/seen`"}, "email_verified": {"type": "boolean", "description": "whether the address has answered (ADR-0029). False means the account works, but routes that invoke the model answer 403 `email_unverified`."}, "energy_default": {"type": "integer", "minimum": 1, "maximum": 5, "description": "where the energy control starts"}, "access": {"enum": ["full", "checkout_first", "lapsed"], "description": "the account's standing (ADR-0188): `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."}, "checkout_first": {"type": "boolean", "description": "a new account that has not been through checkout yet (ADR-0186). Every route outside a small allowlist answers 402 `checkout_required` until it has. Always false with billing off."}, "walkthrough_owed": {"type": "boolean", "description": "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 (ADR-0190)"}, "tutorial": {"type": ["object", "null"], "properties": {"steps": {"type": "array", "items": {"type": "object", "required": ["key", "state"], "properties": {"key": {"enum": ["goals", "calendar", "week", "today", "reports", "settings"]}, "state": {"enum": ["todo", "done", "skipped"]}}}}, "current": {"enum": ["goals", "calendar", "week", "today", "reports", "settings", null]}}, "description": "the tutorial's progress while it is owed, else null (ADR-0190, ADR-0195): 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"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/spend": {"get": {"operationId": "spend_summary", "summary": "What this account has cost", "tags": ["auth"], "description": "Folded out of the per-user cost ledger every model call already writes to. `month_usd` is the calendar month to date and is what a cap is measured against; `cap_usd` is null where the deployment sets none. `unreadable` counts ledger lines that could not be parsed \u2014 a crash mid-append leaves a partial one, and a summary that hid it would quietly under-report (ADR-0030).", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["month", "month_usd", "today_usd", "calls"], "properties": {"month": {"type": "string", "pattern": "^\\d{4}-\\d{2}$"}, "month_usd": {"type": "number"}, "today_usd": {"type": "number"}, "calls": {"type": "integer"}, "cap_usd": {"type": ["number", "null"]}, "over_cap": {"type": "boolean"}, "unreadable": {"type": "integer"}, "unpriced": {"type": "integer", "description": "calls on a model with no price in the table, recorded at $0.00 \u2014 a cap cannot see these"}, "by_purpose": {"type": "object"}, "by_model": {"type": "object"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/library": {"get": {"operationId": "get_library", "summary": "List interests with derived state", "tags": ["goals"], "description": "Returns every interest on the profile grouped by type \u2014 `goals`, `habits`, `leisure`, `chores` \u2014 plus `constraints`, `areas`, `completed_goals` and `deleted` (interests restorable with `POST /v1/interests/{interest}/restore`).\n\nEach 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.\n\n`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.\n\nBefore onboarding the response is `onboarded: false` with empty lists.", "parameters": [{"name": "date", "in": "query", "required": false, "description": "Compute derived state for this day instead of today.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["onboarded"], "properties": {"onboarded": {"type": "boolean"}, "date": {"type": "string"}, "completed_goals": {"type": "array", "items": {"type": "object", "required": ["id", "label", "derived"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "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."}, "minutes": {"type": ["integer", "null"]}, "cadence_per_week": {"type": "integer", "minimum": 1, "maximum": 7}, "due_date": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "origin": {"type": "string", "enum": ["user", "confirmed", "integration", "model"]}, "refused": {"type": "boolean"}, "area": {"type": ["string", "null"]}, "area_rank": {"type": ["integer", "null"], "minimum": 1}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed_milestones": {"type": "array", "items": {"type": "object"}}, "derived": {"type": "object", "description": "Sereo's inference, not anything the user said", "properties": {"status": {"type": ["string", "null"], "enum": ["on_track", "due", "overdue", "satisfied", "starving", null]}, "days_since_scheduled": {"type": ["integer", "null"]}, "days_since_completed": {"type": ["integer", "null"]}}}}}, "description": "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."}, "deleted": {"type": "array", "items": {"type": "object", "required": ["id", "deleted_at", "restorable_until"], "properties": {"id": {"type": "string"}, "label": {"type": ["string", "null"]}, "type": {"type": ["string", "null"]}, "deleted_at": {"type": "string"}, "restorable_until": {"type": "string"}}}, "description": "Interests removed with `DELETE /v1/interests/{interest}` and restorable with `POST /v1/interests/{interest}/restore` (ADR-0164). Records older than 30 days are pruned when another interest is deleted, so an entry past `restorable_until` can still be listed."}, "areas": {"type": "array", "items": {"type": "object", "required": ["id", "name", "rank"], "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "why": {"type": "string"}, "rank": {"type": "integer", "minimum": 1}}}, "description": "The user's grouping of goals into ranked areas, most important first (ADR-0163). Each goal references its area with `area` and its position within it with `area_rank`. Used as planning emphasis, not as a hard constraint."}, "goals": {"type": "array", "items": {"type": "object", "required": ["id", "label", "derived"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "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."}, "minutes": {"type": ["integer", "null"]}, "cadence_per_week": {"type": "integer", "minimum": 1, "maximum": 7}, "due_date": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "origin": {"type": "string", "enum": ["user", "confirmed", "integration", "model"]}, "refused": {"type": "boolean"}, "area": {"type": ["string", "null"]}, "area_rank": {"type": ["integer", "null"], "minimum": 1}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed_milestones": {"type": "array", "items": {"type": "object"}}, "derived": {"type": "object", "description": "Sereo's inference, not anything the user said", "properties": {"status": {"type": ["string", "null"], "enum": ["on_track", "due", "overdue", "satisfied", "starving", null]}, "days_since_scheduled": {"type": ["integer", "null"]}, "days_since_completed": {"type": ["integer", "null"]}}}}}}, "habits": {"type": "array", "items": {"type": "object", "required": ["id", "label", "derived"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "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."}, "minutes": {"type": ["integer", "null"]}, "cadence_per_week": {"type": "integer", "minimum": 1, "maximum": 7}, "due_date": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "origin": {"type": "string", "enum": ["user", "confirmed", "integration", "model"]}, "refused": {"type": "boolean"}, "area": {"type": ["string", "null"]}, "area_rank": {"type": ["integer", "null"], "minimum": 1}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed_milestones": {"type": "array", "items": {"type": "object"}}, "derived": {"type": "object", "description": "Sereo's inference, not anything the user said", "properties": {"status": {"type": ["string", "null"], "enum": ["on_track", "due", "overdue", "satisfied", "starving", null]}, "days_since_scheduled": {"type": ["integer", "null"]}, "days_since_completed": {"type": ["integer", "null"]}}}}}}, "leisure": {"type": "array", "items": {"type": "object", "required": ["id", "label", "derived"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "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."}, "minutes": {"type": ["integer", "null"]}, "cadence_per_week": {"type": "integer", "minimum": 1, "maximum": 7}, "due_date": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "origin": {"type": "string", "enum": ["user", "confirmed", "integration", "model"]}, "refused": {"type": "boolean"}, "area": {"type": ["string", "null"]}, "area_rank": {"type": ["integer", "null"], "minimum": 1}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed_milestones": {"type": "array", "items": {"type": "object"}}, "derived": {"type": "object", "description": "Sereo's inference, not anything the user said", "properties": {"status": {"type": ["string", "null"], "enum": ["on_track", "due", "overdue", "satisfied", "starving", null]}, "days_since_scheduled": {"type": ["integer", "null"]}, "days_since_completed": {"type": ["integer", "null"]}}}}}}, "chores": {"type": "array", "items": {"type": "object", "required": ["id", "label", "derived"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "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."}, "minutes": {"type": ["integer", "null"]}, "cadence_per_week": {"type": "integer", "minimum": 1, "maximum": 7}, "due_date": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "origin": {"type": "string", "enum": ["user", "confirmed", "integration", "model"]}, "refused": {"type": "boolean"}, "area": {"type": ["string", "null"]}, "area_rank": {"type": ["integer", "null"], "minimum": 1}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed_milestones": {"type": "array", "items": {"type": "object"}}, "derived": {"type": "object", "description": "Sereo's inference, not anything the user said", "properties": {"status": {"type": ["string", "null"], "enum": ["on_track", "due", "overdue", "satisfied", "starving", null]}, "days_since_scheduled": {"type": ["integer", "null"]}, "days_since_completed": {"type": ["integer", "null"]}}}}}}, "constraints": {"type": "array", "items": {"type": "object", "required": ["id", "text", "kind"], "properties": {"id": {"type": "string"}, "text": {"type": "string"}, "kind": {"type": "string", "enum": ["gate", "scheduling", "content"]}, "priority": {"type": "integer", "minimum": 1, "maximum": 3}, "applies_to": {"type": "array", "items": {"type": "string"}}}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/year": {"get": {"operationId": "get_year", "summary": "Get goals as year-view rails", "tags": ["goals"], "description": "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.\n\nFor 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 (ADR-0023).\n\nPositions 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.\n\nEach rail also carries `history` (the 84 days ending on `date`) and `weeks` (one entry per cadence week since adoption, up to 52).\n\n`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.", "parameters": [{"name": "date", "in": "query", "required": false, "description": "Draw the year as of this day instead of today.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["date", "rails", "counts"], "properties": {"date": {"type": "string"}, "year": {"type": "integer"}, "today_days": {"type": "number"}, "rails": {"type": "array", "items": {"type": "object", "required": ["id", "label", "tag", "marks", "n", "done_n", "line"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "tag": {"type": "string", "description": "Short display name for the goal, a word or two."}, "detail": {"type": "string"}, "done_when": {"type": "array", "items": {"type": "string"}, "description": "the acceptance criteria; empty on goals written before the field existed"}, "icon": {"type": "string"}, "adopted": {"type": "string"}, "adopted_days": {"type": "number"}, "momentum": {"type": ["integer", "null"]}, "status": {"type": ["string", "null"]}, "shift_days": {"type": "integer", "description": "days the rail has been pulled forward by finishing things early"}, "marks": {"type": "array", "items": {"type": "object", "required": ["index", "name", "at_days", "at_iso", "done"], "properties": {"index": {"type": "integer", "description": "position on the rail; the identity every other field here keys on"}, "key": {"type": ["string", "null"], "description": "what a write names this milestone by"}, "name": {"type": "string"}, "note": {"type": "string"}, "source": {"type": ["string", "null"]}, "blocks": {"type": ["integer", "null"]}, "plan_iso": {"type": ["string", "null"], "description": "the stored date \u2014 what an edit writes to"}, "plan_days": {"type": "number"}, "at_days": {"type": "number", "description": "Effective position in float days since 1970-01-01. May be fractional, e.g. a mark seated just before a fixed-date mark."}, "at_iso": {"type": "string"}, "done": {"type": "boolean"}, "completed_on": {"type": ["string", "null"]}, "earned_days": {"type": "integer", "description": "days this completion pulled the rail forward"}, "drift_days": {"type": "integer"}, "fixed": {"type": ["string", "null"], "description": "why this date is not the plan's to move"}, "blocked": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"], "description": "the milestone's own raw block, empty when `blocked` is a sentence about a sub-step \u2014 the revision payload carries this back verbatim"}, "block_key": {"type": "string"}, "block_derived": {"type": "boolean", "description": "held because something earlier in the rail is, not on its own account"}, "blocked_by": {"type": ["array", "null"], "items": {"type": "string"}}, "blocked_by_label": {"type": ["string", "null"]}, "free": {"type": ["string", "null"], "description": "an unordered stretch this belongs to"}, "own_blocked": {"type": ["string", "null"]}, "past_due": {"type": "boolean"}, "stuck": {"type": "boolean", "description": "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_days": {"type": ["number", "null"]}, "is_current": {"type": "boolean"}, "steps_done": {"type": "boolean", "description": "true when every listed task is done but the milestone has not been marked reached. Informational: the milestone is never completed automatically (ADR-0081)."}, "subs": {"type": "array", "items": {"type": "object", "required": ["si", "label", "at_days"], "properties": {"si": {"type": "integer"}, "id": {"type": ["string", "null"]}, "label": {"type": "string"}, "note": {"type": "string"}, "plan_iso": {"type": ["string", "null"]}, "plan_days": {"type": "number"}, "at_days": {"type": "number"}, "at_iso": {"type": "string"}, "dated": {"type": "boolean", "description": "false when the task has no date of its own and its position is interpolated across its milestone's run-up in list order."}, "done": {"type": "boolean"}, "logged_days": {"type": ["number", "null"], "description": "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."}, "blocked": {"type": ["string", "null"]}, "block_key": {"type": "string"}, "drift_days": {"type": "integer"}, "stuck": {"type": "boolean"}}}}, "item_slot": {"type": ["integer", "null"]}, "item_done": {"type": "boolean"}, "item_blocked": {"type": ["string", "null"]}, "item_blocked_by": {"type": ["array", "null"], "items": {"type": "string"}}, "item_block_key": {"type": "string"}, "own_subs": {"type": "array", "items": {"type": "object", "required": ["si", "label", "at_days"], "properties": {"si": {"type": "integer"}, "id": {"type": ["string", "null"]}, "label": {"type": "string"}, "note": {"type": "string"}, "plan_iso": {"type": ["string", "null"]}, "plan_days": {"type": "number"}, "at_days": {"type": "number"}, "at_iso": {"type": "string"}, "dated": {"type": "boolean", "description": "false when the task has no date of its own and its position is interpolated across its milestone's run-up in list order."}, "done": {"type": "boolean"}, "logged_days": {"type": ["number", "null"], "description": "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."}, "blocked": {"type": ["string", "null"]}, "block_key": {"type": "string"}, "drift_days": {"type": "integer"}, "stuck": {"type": "boolean"}}}}, "free_size": {"type": "integer"}, "free_slots": {"type": "array", "items": {"type": "integer"}}, "fill_by": {"type": ["integer", "null"]}, "slot_label": {"type": "string"}, "slot_note": {"type": "string"}, "next_slot": {"type": ["integer", "null"]}, "open_items": {"type": "array", "items": {"type": "object", "properties": {"index": {"type": "integer"}, "label": {"type": "string"}, "blocked": {"type": "boolean"}}}}}}}, "n": {"type": "integer"}, "done_n": {"type": "integer"}, "all_done": {"type": "boolean"}, "cold": {"type": "boolean", "description": "true when the goal's `momentum` is below 20, i.e. little recent credited work, regardless of deadline."}, "hot": {"type": "boolean"}, "parked": {"type": "boolean"}, "parked_until": {"type": ["string", "null"]}, "held": {"type": "array", "items": {"type": "integer"}, "description": "Indices into `marks` of milestones that are past due and unmet (`stuck: true`)."}, "blocked": {"type": "array", "items": {"type": "integer"}}, "next_index": {"type": ["integer", "null"]}, "dest_index": {"type": ["integer", "null"]}, "dest_days": {"type": "number"}, "dest_at": {"type": "string"}, "dest_in_days": {"type": "integer"}, "ends_stated": {"type": "boolean", "description": "true when a milestone is marked `finishes` (ADR-0065), 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_days": {"type": "integer"}, "failed_index": {"type": ["integer", "null"], "description": "a fixed date that passed unmet, which seals the rail there"}, "first_days": {"type": "number"}, "front_days": {"type": "number"}, "line": {"type": "string", "description": "where this goal stands, in one sentence"}, "ink": {"type": ["integer", "null"], "description": "the ink this goal wears everywhere (ADR-0145)"}, "rhythm": {"type": "object", "required": ["target", "label", "kept", "planned"], "description": "what the goal asks for each week, and the record over the history window (ADR-0145)", "properties": {"target": {"type": ["integer", "null"], "description": "sessions a week its habits ask for; null for a goal with no habit"}, "label": {"type": "string"}, "kept": {"type": "integer", "description": "days kept in the history window"}, "planned": {"type": "integer", "description": "days planned in the history window"}}}, "history": {"type": "array", "description": "The 84 days ending on the requested date. Per day: `planned` \u2014 a block for the goal (or one of its habits) was laid out; `kept` \u2014 a check-in credited it. Both true = kept, `planned` only = missed, `kept` only = unplanned extra.", "items": {"type": "object", "required": ["date", "planned", "kept"], "properties": {"date": {"type": "string"}, "planned": {"type": "boolean"}, "kept": {"type": "boolean"}}}}, "weeks": {"type": "array", "description": "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", "items": {"type": "object", "required": ["ending", "kept", "planned", "target"], "properties": {"ending": {"type": "string"}, "kept": {"type": "integer"}, "planned": {"type": "integer"}, "target": {"type": "integer"}}}}}}}, "chores": {"type": "array", "items": {"type": "object", "required": ["id", "label", "state"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "detail": {"type": "string"}, "due_date": {"type": ["string", "null"]}, "days": {"type": ["integer", "null"]}, "minutes": {"type": ["integer", "null"]}, "priority": {"type": "string", "enum": ["high", "normal", "low"]}, "done": {"type": "boolean"}, "parked": {"type": "boolean"}, "parked_until": {"type": ["string", "null"]}, "state": {"type": "string", "enum": ["done", "parked", "late", "today", "soon", "later"]}}}}, "counts": {"type": "object", "properties": {"goals": {"type": "integer"}, "marks": {"type": "integer"}, "met": {"type": "integer"}, "held": {"type": "integer"}, "blocked": {"type": "integer"}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/interests/{interest}/tasks/{task}": {"post": {"operationId": "set_task", "summary": "Set a milestone task's status", "tags": ["goals"], "description": "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.\n\nTask 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`).\n\nErrors: `400 invalid_request` for a missing or unknown `status`; `404 not_found` if the interest has no open-milestone task with that id.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}, {"name": "task", "in": "path", "required": true, "description": "A milestone task id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["status"], "properties": {"status": {"type": "string", "enum": ["todo", "done"]}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "delete": {"operationId": "drop_task", "summary": "Delete a milestone task", "tags": ["goals"], "description": "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 (ADR-0057).\n\nThe task's title is also recorded as a refusal, so the planner and reports do not propose it again (ADR-0060).\n\nErrors: `404 not_found` if the interest has no open-milestone task with that id.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}, {"name": "task", "in": "path", "required": true, "description": "A milestone task id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}], "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/jobs": {"post": {"operationId": "add_job", "summary": "Create a dated job", "tags": ["goals"], "description": "Creates a job \u2014 an interest of type `chore` with a deadline \u2014 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\"`.\n\n`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 (ADR-0061). `priority` defaults to `normal`.\n\nErrors: `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.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["label", "due"], "properties": {"label": {"type": "string", "description": "what the job is"}, "due": {"type": "string", "format": "date"}, "for_whom": {"type": "string", "description": "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."}, "minutes": {"type": "integer", "minimum": 1, "description": "Estimated minutes per work session, positive integer. If omitted, the planner chooses a duration."}, "priority": {"type": "string", "enum": ["high", "normal", "low"]}, "detail": {"type": "string"}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "required": ["id"], "properties": {"id": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/interests/{interest}": {"patch": {"operationId": "patch_interest", "summary": "Update a goal", "tags": ["goals"], "description": "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.\n\nTop-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.\n\n`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`.\n\nA 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`.\n\nThe goal id never changes. Nothing here writes plans, check-ins or to-dos.\n\nErrors: `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.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"label": {"type": "string"}, "detail": {"type": "string"}, "blocked_until": {"type": ["string", "null"]}, "blocked_on": {"type": ["string", "null"]}, "adopted": {"type": "string"}, "area": {"type": ["string", "null"], "description": "the area id to place the goal in (ADR-0163); null takes it out"}, "area_rank": {"type": "integer", "minimum": 1, "description": "its place in that area, 1 first; the rest renumber"}, "milestones": {"type": "array", "items": {"type": "object", "properties": {"name": {"type": "string", "description": "needed unless `id` names a milestone it keeps"}, "target_date": {"type": "string", "description": "YYYY-MM-DD; a kept milestone keeps its own"}, "estimate_blocks": {"type": "integer", "minimum": 1, "description": "optional: a kept milestone keeps its own, a new one gets one per step"}, "blocks": {"type": "integer", "minimum": 1, "description": "the library's name for estimate_blocks; either is taken"}, "id": {"type": "string"}, "kind": {"type": "string", "enum": ["effort", "outcome", "adjudicated"]}, "status": {"type": "string"}, "phase": {"type": "string"}, "finishes": {"type": "boolean", "description": "the checkpoint that reaches this goal's done_when; at most one per goal (ADR-0065)"}, "blocked_on": {"type": "string"}, "fixed_reason": {"type": "string"}, "free_group": {"type": "string"}, "no_steps_because": {"type": "string", "description": "why no separate work leads to this checkpoint (ADR-0161)"}, "blocked_by": {"type": "array", "items": {"type": "string"}}, "completed_on": {"type": "string"}, "tasks": {"type": "array", "items": {"type": "object", "required": ["title"], "properties": {"id": {"type": "string", "description": "optional: a step with the same title keeps its id, a new one is given one"}, "title": {"type": "string"}, "status": {"type": "string", "enum": ["todo", "doing", "done"]}}}}}}}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["interest", "changed"], "properties": {"interest": {"type": "string"}, "changed": {"type": "array", "items": {"type": "string"}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "delete": {"operationId": "delete_interest", "summary": "Delete an interest", "tags": ["goals"], "description": "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.\n\nThe 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` (ADR-0164). 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.\n\nThe 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.\n\nTo pause a goal without deleting it, set `blocked_until` with `PATCH /v1/interests/{interest}` (goals only).\n\nErrors: `404 not_found` if no live interest has that id; `409 last_interest` if it is the only interest on the profile.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}], "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/interests/{interest}/restore": {"post": {"operationId": "restore_interest", "summary": "Restore a deleted interest", "tags": ["goals"], "description": "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 (ADR-0164).\n\nReturns `restored` (the id), `label`, `type`, `milestones` (count of open milestones), `scope` (always `every future day`) and `persisted`.\n\nRestorable records are those listed under `deleted` in `GET /v1/library`.\n\nErrors: `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.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["restored", "scope", "persisted"], "properties": {"restored": {"type": "string"}, "label": {"type": ["string", "null"]}, "type": {"type": ["string", "null"]}, "milestones": {"type": "integer"}, "scope": {"type": "string", "enum": ["today", "this week", "every future day", "nothing"], "description": "how far this write reaches: today's plan only, this week, every future day, or nothing at all"}, "persisted": {"type": "object", "description": "what lasts beyond today, by kind; empty lists when nothing lasting changed", "properties": {"goals": {"type": "array", "items": {"type": "string"}}, "rules": {"type": "array", "items": {"type": "string"}}, "settings": {"type": "array", "items": {"type": "string"}}, "jobs": {"type": "array", "items": {"type": "string"}}, "week": {"type": "array", "items": {"type": "string"}}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/interests/{interest}/done": {"post": {"operationId": "finish_chore", "summary": "Mark a chore done or not done", "tags": ["planning"], "description": "Records that the user finished a chore (an interest of type `chore`), or reverses that with `done: false`, and returns `{id, done, day}`.\n\nThe 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.\n\nErrors: `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.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"done": {"type": "boolean", "default": true}, "date": {"type": "string", "description": "YYYY-MM-DD; today by default"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["id", "done", "day"], "properties": {"id": {"type": "string"}, "done": {"type": "boolean"}, "day": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/interests/{interest}/milestones/status": {"post": {"operationId": "set_milestone", "summary": "Set a milestone's completion status", "tags": ["goals"], "description": "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.\n\n`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`.\n\nMarking 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`.\n\nThis does not record check-in credit: pressure, block credit and missed-day tracking change only through check-ins.\n\nErrors: `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.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["milestone", "status"], "properties": {"milestone": {"type": "string", "description": "its id, or its name"}, "status": {"type": "string", "enum": ["done", "todo"]}, "on": {"type": "string", "description": "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": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/interests/{interest}/milestones/review": {"post": {"operationId": "milestone_review", "summary": "Answer a milestone review", "tags": ["goals"], "description": "Records the user's answer to whether a past-due milestone was reached (ADR-0116). Pending reviews \u2014 at most one per goal, its earliest past-due open milestone, excluding fixed, adjudicated and integration-owned dates \u2014 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`.\n\n`choice`:\n\n- `reached` \u2014 marks the milestone done exactly as `POST /v1/interests/{interest}/milestones/status` does, clears the review, and returns `{outcome: \"reached\", milestone}`. - `not_yet` \u2014 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` \u2014 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 (ADR-0170).\n\nAn optional `on` (YYYY-MM-DD) sets the date used for `completed_on` or the snooze.\n\nErrors: `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.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["milestone", "choice"], "properties": {"milestone": {"type": "string", "description": "its id, or its name"}, "choice": {"type": "string", "enum": ["reached", "not_yet", "later"], "description": "`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) (ADR-0170)."}, "why": {"type": "string", "description": "With `not_yet`: text reason, stored on the review record and returned in the response."}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/interests/{interest}/milestones/review/adjust": {"post": {"operationId": "milestone_review_adjust", "summary": "Apply a milestone review adjustment", "tags": ["goals"], "description": "Applies the adjustment chosen after a `not_yet` answer to a milestone review (ADR-0116) and clears the review.\n\n- `move_date` \u2014 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` \u2014 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}`.\n\nErrors: `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.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9][a-z0-9_]{0,63}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["milestone", "action"], "properties": {"milestone": {"type": "string", "description": "its id, or its name"}, "action": {"type": "string", "enum": ["move_date", "supersede"]}, "new_date": {"type": "string", "description": "With `move_date`: the new target date, YYYY-MM-DD. Must be after the user's current date (or `on`)."}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/import": {"post": {"operationId": "import_bundle", "summary": "Import a sereo.import/1 bundle", "tags": ["goals"], "description": "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`.\n\n**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`.\n\nThe account's `anchor_date` is set from the bundle and scheduled jobs are re-queued.\n\n`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.\n\nErrors: `400 invalid_request` if `bundle` is not a JSON object; `400 bad_bundle` if the bundle fails validation or `replace` is needed.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["bundle"], "properties": {"bundle": {"type": "object", "description": "a sereo.import/1 bundle", "required": ["schema", "profile"], "properties": {"schema": {"type": "string", "const": "sereo.import/1"}, "profile": {"type": "object"}, "availability": {"type": "array", "description": "per weekday: `busy` blocks, and optionally `free` windows that are subtracted from the calendar (ADR-0012)"}, "habits": {"type": "array"}, "leisure": {"type": "array"}, "chores": {"type": "array"}, "goals": {"type": "array"}, "constraints": {"type": "array"}}}, "replace": {"type": "boolean"}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "required": ["report", "interests"], "properties": {"interests": {"type": "integer"}, "report": {"type": "object", "properties": {"counts": {"type": "object"}, "defaults": {"type": "array"}, "dropped": {"type": "array"}, "overdue": {"type": "array"}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/export": {"get": {"operationId": "export_bundle", "summary": "Export the profile", "tags": ["goals"], "description": "Returns the profile as a `sereo.import/1` bundle \u2014 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.\n\n`format` selects another representation:\n\n- `ics` \u2014 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` \u2014 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 (ADR-0073).\n\nAvailable to accounts that have not completed checkout. `409 not_onboarded` if the profile has no interests.", "parameters": [{"name": "format", "in": "query", "required": false, "description": "`ics` for a calendar file; omit for the JSON bundle.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "description": "a sereo.import/1 bundle", "required": ["schema", "profile"], "properties": {"schema": {"type": "string", "const": "sereo.import/1"}, "profile": {"type": "object"}, "availability": {"type": "array", "description": "per weekday: `busy` blocks, and optionally `free` windows that are subtracted from the calendar (ADR-0012)"}, "habits": {"type": "array"}, "leisure": {"type": "array"}, "chores": {"type": "array"}, "goals": {"type": "array"}, "constraints": {"type": "array"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/day/{date}": {"get": {"operationId": "get_day", "summary": "Get the day view", "tags": ["planning"], "description": "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.\n\nUse this for display. `GET /v1/plans/{date}` returns the raw stored plan in the engine's fixed shape.\n\nAnswers 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.\n\nSide effect: reading **today** records the user as present, which counts as activity for gap detection. Reading any other date writes nothing. Invokes no model.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["date", "rows", "counts", "plan_exists", "onboarded"], "properties": {"date": {"type": "string"}, "weekday": {"type": "string"}, "onboarded": {"type": "boolean"}, "is_today": {"type": "boolean"}, "now_minutes": {"type": "integer", "minimum": 0, "maximum": 2879}, "energy": {"type": ["integer", "null"], "minimum": 1, "maximum": 5}, "week_changed_since_plan": {"type": "boolean", "description": "the week's decision for this day moved after the day was planned \u2014 a replan of the week or an amendment naming the day (ADR-0150). Not premise drift, which is `week_plan_stale`."}, "ask": {"type": ["object", "null"], "description": "the week's re-read behind the last ask on this day (ADR-0150), while it runs and once done; null when there is none or the process has forgotten it", "properties": {"working": {"type": "boolean"}, "steps": {"type": "array", "items": {"type": "string"}}, "week": {"type": ["object", "null"]}, "ending": {"type": "string"}, "error": {"type": ["string", "null"]}}}, "energy_stated": {"type": "boolean", "description": "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 \u2014 a planned day always has one (ADR-0064)"}, "plan_exists": {"type": "boolean"}, "week_planned": {"type": ["boolean", "null"], "description": "whether this day's cadence week has been planned (ADR-0136). 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 (ADR-0107)"}, "accepted": {"type": "boolean"}, "read_only": {"type": "boolean"}, "influences": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "text": {"type": "string"}, "from": {"type": "string"}}}, "description": "standing rules agreed in a report review that apply to planning (W19); revoke one with `DELETE /v1/constraints/{id}`"}, "milestone_reviews": {"type": "array", "items": {"type": "object", "properties": {"interest": {"type": "string"}, "interest_label": {"type": "string"}, "milestone": {"type": "string"}, "milestone_name": {"type": "string"}, "was_due": {"type": "string"}, "why": {"type": ["string", "null"]}, "state": {"type": "string", "enum": ["asked", "not_yet"]}}}, "description": "milestones whose date has passed but which nobody has ticked reached (ADR-0116): 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"}, "settled": {"type": "boolean", "description": "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"}, "source": {"type": ["string", "null"], "enum": ["user", "scheduler", null]}, "day_off": {"type": "boolean", "description": "a weekday the user said they never work (ADR-0061); generating it produces a day-off placeholder plan"}, "reshaping": {"type": "boolean", "description": "the day is being edited (ADR-0081); server-held, so the state survives reloads and other clients"}, "day_start": {"type": "string"}, "day_end": {"type": "string"}, "plans_between": {"type": "string", "description": "a server-written sentence describing when this day is planned: the day window and the unavailable hours inside it"}, "day_wraps": {"type": "boolean", "description": "whether this day crosses midnight (ADR-0137): day_end is then a next-morning hour"}, "day_end_extended": {"type": "integer", "minimum": 0, "maximum": 2879, "description": "day_end in minutes since midnight on the extended axis (above 1439 when the day wraps)"}, "outside_hours": {"type": "array", "items": {"type": "object", "required": ["task", "start", "end", "side"], "properties": {"task": {"type": "string"}, "start": {"type": "string"}, "end": {"type": "string"}, "side": {"type": "string", "enum": ["before", "after"]}}}, "description": "blocks the user placed outside their day window (ADR-0155); they are kept, not refused"}, "pushback": {"type": "array", "items": {"type": "object", "required": ["task", "reason"], "properties": {"task": {"type": "string"}, "reason": {"type": "string"}}}, "description": "where Sereo would change one of the person's own blocks, and why; the block stays (ADR-0157)"}, "most_important": {"type": "string"}, "coach_note": {"type": "string"}, "recovery": {"type": "boolean"}, "issues": {"type": "array", "items": {"type": "string"}}, "on_hold": {"type": "array", "items": {"type": "object"}, "description": "work deliberately not in the day, named here as {interest, label} \u2014 the plan file keeps bare ids"}, "unfit": {"type": "array", "items": {"type": "object", "required": ["task", "why"], "properties": {"task": {"type": "string"}, "goal": {"type": ["string", "null"]}, "minutes": {"type": ["integer", "null"]}, "asked": {"type": "boolean"}, "why": {"type": "string"}, "offers": {"type": "array", "items": {"type": "object", "required": ["kind", "text"], "properties": {"kind": {"type": "string", "enum": ["move", "drop_habit"]}, "text": {"type": "string"}, "to": {"type": "string"}, "day_label": {"type": "string"}, "effort": {"type": "string"}, "free_minutes": {"type": "integer"}, "task": {"type": "string"}, "interest": {"type": ["string", "null"]}}}}}}, "description": "blocks placement could not fit today (no_room), each with the two ways out \u2014 move to a day with room, or drop the habit in the way (ADR-0112)"}, "committed_actions": {"type": "array", "items": {"type": "string"}, "description": "a Day-0 plan whose calendar input was too thin to earn time blocks carries these instead (P13)"}, "backup": {"type": "string"}, "pins": {"type": "array", "items": {"type": "object"}}, "solar": {"type": ["object", "null"], "description": "local clock minutes for the day's solar events, or null when the profile has no location", "properties": {"place": {"type": "string"}, "latitude": {"type": "number"}, "longitude": {"type": "number"}, "dawn": {"type": ["integer", "null"]}, "rise": {"type": ["integer", "null"]}, "noon": {"type": ["integer", "null"]}, "set": {"type": ["integer", "null"]}, "dusk": {"type": ["integer", "null"]}}}, "bands": {"type": "array", "items": {"type": "object", "required": ["name", "from", "to", "empty", "covered", "never", "title"], "properties": {"name": {"type": "string"}, "never": {"type": "boolean", "description": "a stretch wholly outside the hours Sereo plans: one of the hours it never touches"}, "from": {"type": "integer", "minimum": 0, "maximum": 2879}, "to": {"type": "integer", "minimum": 0, "maximum": 2879, "description": "inclusive: the last minute this stretch owns. Past 1439 = a wrapped day's small hours (ADR-0137)"}, "empty": {"type": "string", "description": "what to say when nothing was placed here"}, "covered": {"type": "boolean", "description": "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 \u2014 never the drawing (ADR-0065's sibling finding)"}, "title": {"type": "string", "description": "where the sun stands over this stretch \u2014 empty when there is no location to say it from"}}}, "description": "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"}, "rows": {"type": "array", "items": {"type": "object", "required": ["id", "start", "end", "task", "kind"], "properties": {"id": {"type": "string"}, "start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "start_minutes": {"type": "integer"}, "end_minutes": {"type": "integer"}, "minutes": {"type": "integer"}, "task": {"type": "string"}, "kind": {"type": "string", "enum": ["goal", "rhythm", "leisure", "chore", "break", "busy"], "description": "`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"}, "icon": {"type": "string"}, "tag": {"type": "string", "description": "the goal or rhythm this hour serves"}, "node": {"type": ["string", "null"], "description": "the milestone it serves, when there is one"}, "interest": {"type": ["string", "null"]}, "why": {"type": "string", "description": "why this hour is here \u2014 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"}, "adapt": {"type": "boolean", "description": "the day changed under the user here: a guard cut its length, or a replan moved its hour"}, "ext": {"type": "boolean", "description": "owned by the calendar, not movable"}, "risk": {"type": ["object", "null"], "properties": {"label": {"type": "string"}, "level": {"type": "string", "enum": ["late", "soon"]}}}, "keep": {"type": ["object", "null"], "properties": {"due": {"type": "string", "format": "date"}, "priority": {"type": "string", "enum": ["high", "normal", "low"]}}}, "todo_id": {"type": ["string", "null"]}, "task_id": {"type": ["string", "null"]}, "status": {"type": ["string", "null"], "enum": ["open", "done", "skipped", "unreconciled", null], "description": "the derived status \u2014 `unreconciled` is silence, never a miss"}}}}, "goals": {"type": "array", "items": {"type": "object", "required": ["id", "tag", "label", "kind", "node"], "properties": {"id": {"type": "string"}, "tag": {"type": "string", "description": "what the goal is called out loud \u2014 the one or two words a control can print"}, "label": {"type": "string"}, "kind": {"type": "string", "enum": ["goal", "rhythm", "leisure", "chore"]}, "node": {"type": ["string", "null"], "description": "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"}, "ink": {"type": ["integer", "null"], "description": "the ink this goal wears everywhere (weekview.goal_inks, ADR-0145); a habit wears its goal's"}}}, "description": "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"}, "counts": {"type": "object", "properties": {"work": {"type": "integer"}, "done": {"type": "integer"}, "open": {"type": "integer"}, "skipped": {"type": "integer"}, "unreconciled": {"type": "integer"}}}, "knows": {"type": "array", "items": {"type": "object", "properties": {"text": {"type": "string"}, "weight": {"type": "string"}}}, "description": "server-written statements about the day (e.g. calendar and goal facts) for display when it has no plan"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/weeks/{week}": {"get": {"operationId": "get_week", "summary": "Get a cadence week", "tags": ["planning"], "description": "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).\n\n`{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 (ADR-0004).\n\nNo 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.\n\nAnswers 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.", "parameters": [{"name": "week", "in": "path", "required": true, "description": "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.", "schema": {"type": "string", "pattern": "^latest|\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["ending", "from", "to", "days", "plan"], "properties": {"ending": {"type": "string"}, "from": {"type": "string"}, "to": {"type": "string"}, "today": {"type": "string"}, "current": {"type": "boolean"}, "over": {"type": "boolean", "description": "its last day has gone by: replan and discuss answer 409 week_over (ADR-0196)"}, "days": {"type": "array", "items": {"type": "object", "required": ["date", "weekday", "planned", "effort", "blocks"], "properties": {"date": {"type": "string"}, "weekday": {"type": "string"}, "day_off": {"type": "boolean"}, "past": {"type": "boolean"}, "is_today": {"type": "boolean"}, "planned": {"type": "boolean", "description": "a plan exists for this day"}, "scheduled": {"type": "integer", "description": "realized work blocks on the day's plan"}, "minutes": {"type": "integer"}, "accepted": {"type": "boolean"}, "recovery": {"type": "boolean"}, "effort": {"type": "string", "enum": ["clear", "light", "normal", "heavy"], "description": "how heavy the day is, a readout of its abstract blocks \u2014 never a set cap (ADR-0111)"}, "blocks": {"type": "array", "description": "the week's ABSTRACT, untimed blocks for this day (ADR-0111); the day elaborates each into timed work. Distinct from `items`", "items": {"type": "object", "required": ["id", "text", "priority"], "properties": {"id": {"type": "string"}, "text": {"type": "string"}, "goal": {"type": ["string", "null"]}, "priority": {"type": "string", "enum": ["high", "normal", "low"]}, "source": {"type": "string", "enum": ["agent", "user"]}, "ink": {"type": ["integer", "null"]}, "label": {"type": "string"}}}}, "intent": {"type": "string", "description": "what the week decided this day is for"}, "goals": {"type": "array", "items": {"type": "string"}, "description": "ids of the goals its blocks serve"}, "items": {"type": "array", "description": "what is on the day, in order, each block naming and inking the goal it serves", "items": {"type": "object", "required": ["start", "task", "ink"], "properties": {"start": {"type": "string"}, "end": {"type": "string"}, "minutes": {"type": "integer"}, "task": {"type": "string"}, "goal": {"type": "string"}, "label": {"type": "string"}, "ink": {"type": "integer"}, "chore": {"type": "boolean"}}}}, "priority": {"type": "string", "enum": ["high", "normal", "low"]}, "reasoning": {"type": "string", "description": "why the week put this here, in the words the user reads"}, "released": {"type": "array", "items": {"type": "string"}, "description": "text of the week blocks for this day that the day plan left off at the user's request (ADR-0109)"}, "tasks": {"type": "array", "items": {"type": "string"}}}}}, "due": {"type": "array", "items": {"type": "object"}, "description": "checkpoints landing in the week, and recent ones still owed"}, "plan": {"type": "object", "description": "`note`: the user's note, set by PATCH; `summary`: the weekly planner's closing text; `written_at`, `by` (`agent` or `user`), `amendments` (ADR-0109)"}, "feedback": {"type": ["object", "null"], "description": "the last finished week's edition"}, "counts": {"type": "object"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "patch": {"operationId": "set_week_plan", "summary": "Replace the week plan", "tags": ["planning"], "description": "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.\n\n`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\"`).\n\nValidation 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`.\n\n`409 week_not_started` if the week's first day is in the future; `409 not_onboarded` before any goals exist. Invokes no model.", "parameters": [{"name": "week", "in": "path", "required": true, "description": "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.", "schema": {"type": "string", "pattern": "^latest|\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"days": {"type": "object", "description": "date -> {intent, blocks:[{id, text, goal, priority, source}], reasoning} (ADR-0111). Sent whole; this is how the weekly editor saves an accepted draft (ADR-0113)"}, "note": {"type": "string", "maxLength": 400}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/weeks/{week}/discuss": {"post": {"operationId": "discuss_week", "summary": "Discuss and revise a week draft", "tags": ["planning"], "description": "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`.\n\n`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.\n\nWhen 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.\n\nNothing is persisted except a diagnostic trace. To keep a revision, send it with `PATCH /v1/weeks/{week}`.\n\nInvokes 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.", "parameters": [{"name": "week", "in": "path", "required": true, "description": "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.", "schema": {"type": "string", "pattern": "^latest|\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["messages"], "properties": {"messages": {"type": "array", "items": {"type": "object", "properties": {"who": {"type": "string"}, "text": {"type": "string"}}}}, "draft": {"type": ["object", "null"], "description": "the client's working week draft: {days: {date -> {intent, blocks, reasoning}}}"}, "anchor": {"type": ["string", "null"], "description": "the day being edited, or null for the whole week"}, "propose": {"type": "boolean", "description": "ask the model for a revision this turn; it may still answer without one"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["reply", "changes"], "properties": {"reply": {"type": "string"}, "changes": {"type": "array", "items": {"type": "object", "required": ["call", "task"], "properties": {"call": {"type": "string", "description": "move_block | add_block | remove_block | reword | reprioritise | reword_day"}, "task": {"type": "string"}, "was": {"type": "string"}, "now": {"type": "string"}, "note": {"type": "string"}}}}, "draft": {"type": ["object", "null"], "description": "the revised draft, or null when answering"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/weeks/{week}/replan": {"post": {"operationId": "replan_week", "summary": "Run the weekly planner", "tags": ["planning"], "description": "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`.\n\nAn 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.\n\n`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.\n\n**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`.\n\nInvokes 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`.", "parameters": [{"name": "week", "in": "path", "required": true, "description": "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.", "schema": {"type": "string", "pattern": "^latest|\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"brief": {"type": "object", "description": "{messages: [...], proposal: {days: {...}}}"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"ending": {"type": "string"}, "working": {"type": "boolean"}, "planned": {"type": "boolean", "description": "whether a plan was written; false with `refused` when the guard would not sign off"}, "refused": {"type": "array", "items": {"type": "string"}}, "days": {"type": "array", "items": {"type": "object"}}}}}}}, "202": {"description": "Accepted; anything further is sent to the address itself", "content": {"application/json": {"schema": {"type": "object"}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "429": {"description": "Too many attempts; wait and retry \u2014 `retry-after` says how long", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/weeks/{week}/amend": {"post": {"operationId": "amend_week", "summary": "Apply an amendment to the week plan", "tags": ["planning"], "description": "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.\n\n`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.\n\nThe 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.\n\n`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.", "parameters": [{"name": "week", "in": "path", "required": true, "description": "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.", "schema": {"type": "string", "pattern": "^latest|\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["amendment"], "properties": {"amendment": {"type": "object", "description": "{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"}, "why": {"type": "string", "maxLength": 400}, "from": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["today_affected", "days_affected"], "properties": {"today_affected": {"type": "boolean", "description": "today is among `days_affected`, so today's plan predates the change (ADR-0150); consider offering POST /v1/plans/{date}/replan"}, "days_affected": {"type": "array", "items": {"type": "string"}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/months/{month}": {"get": {"operationId": "get_month", "summary": "Get a four-week month block", "tags": ["planning"], "description": "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`).\n\nA 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.\n\nNo 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.", "parameters": [{"name": "month", "in": "path", "required": true, "description": "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 \u2014 the grid a monthly report is written over \u2014 never a calendar month (ADR-0104).", "schema": {"type": "string", "pattern": "^latest|\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["ending", "weeks", "report"], "properties": {"ending": {"type": "string"}, "from": {"type": ["string", "null"]}, "to": {"type": ["string", "null"]}, "today": {"type": "string"}, "current": {"type": "boolean"}, "weeks": {"type": "array", "items": {"type": "object", "required": ["ending", "planned", "of"], "properties": {"ending": {"type": "string"}, "from": {"type": "string"}, "to": {"type": "string"}, "planned": {"type": "integer", "description": "days of this week that have a plan. A structural count, never a grade"}, "of": {"type": "integer"}, "past": {"type": "boolean"}, "current": {"type": "boolean"}, "shaped": {"type": "boolean", "description": "somebody has said what this week is for"}, "minutes": {"type": "integer", "description": "work laid out across the week, in minutes \u2014 planned, never kept"}, "days": {"type": "array", "items": {"type": "object", "required": ["date", "weekday", "minutes", "goals"], "properties": {"date": {"type": "string"}, "weekday": {"type": "string"}, "is_today": {"type": "boolean"}, "past": {"type": "boolean"}, "planned": {"type": "boolean"}, "minutes": {"type": "integer"}, "goals": {"type": "array", "items": {"type": "object", "required": ["id", "ink", "minutes"], "properties": {"id": {"type": "string"}, "ink": {"type": ["integer", "null"], "description": "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 (ADR-0152)"}, "minutes": {"type": "integer"}}}}}}}}}}, "report": {"type": "object", "required": ["state", "ending"], "properties": {"state": {"type": "string", "enum": ["written", "running", "not_yet"]}, "ending": {"type": "string"}, "headline": {"type": "string"}}}, "counts": {"type": "object"}, "weekdays": {"type": "array", "items": {"type": "string"}}, "goals": {"type": "array", "items": {"type": "object", "required": ["id", "label", "ink"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "ink": {"type": "integer"}}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/home": {"get": {"operationId": "get_home", "summary": "List the openable days, weeks and months", "tags": ["planning"], "description": "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.\n\nNothing 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": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["today", "days", "weeks", "months"], "properties": {"today": {"type": "string"}, "days": {"type": "object", "required": ["first", "last"], "properties": {"first": {"type": ["string", "null"]}, "last": {"type": ["string", "null"]}}}, "weeks": {"type": "array", "items": {"type": "object", "required": ["ending", "planned", "of"], "properties": {"ending": {"type": "string"}, "from": {"type": "string"}, "to": {"type": "string"}, "planned": {"type": "integer", "description": "days of this week that have a plan. A structural count, never a grade"}, "of": {"type": "integer"}, "past": {"type": "boolean"}, "current": {"type": "boolean"}, "shaped": {"type": "boolean", "description": "somebody has said what this week is for"}, "minutes": {"type": "integer", "description": "work laid out across the week, in minutes \u2014 planned, never kept"}, "days": {"type": "array", "items": {"type": "object", "required": ["date", "weekday", "minutes", "goals"], "properties": {"date": {"type": "string"}, "weekday": {"type": "string"}, "is_today": {"type": "boolean"}, "past": {"type": "boolean"}, "planned": {"type": "boolean"}, "minutes": {"type": "integer"}, "goals": {"type": "array", "items": {"type": "object", "required": ["id", "ink", "minutes"], "properties": {"id": {"type": "string"}, "ink": {"type": ["integer", "null"], "description": "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 (ADR-0152)"}, "minutes": {"type": "integer"}}}}}}}}}}, "months": {"type": "array", "description": "twelve slots, newest first, once the account has an anchor date (empty before); slots before the anchor are `available: false` with no `ending` (ADR-0104)", "items": {"type": "object", "required": ["available", "from", "to"], "properties": {"available": {"type": "boolean", "description": "true for a block within the account's lifetime; false for a placeholder before the anchor date"}, "ending": {"type": "string", "description": "absent on an unavailable slot"}, "from": {"type": "string"}, "to": {"type": "string"}, "current": {"type": "boolean"}, "past": {"type": "boolean"}, "minutes": {"type": "integer"}, "report": {"type": "object"}}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}": {"get": {"operationId": "get_plan", "summary": "Get a day's stored plan", "tags": ["planning"], "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["blocks", "most_important", "coach_note"], "properties": {"blocks": {"type": "array", "items": {"type": "object", "required": ["start", "end", "task", "interest", "why"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "task": {"type": "string", "maxLength": 120}, "interest": {"type": ["string", "null"], "description": "null for a chore or a break \u2014 see `chore`, which tells the two apart"}, "why": {"type": "string", "maxLength": 200}, "chore": {"type": "boolean", "description": "work that serves no tracked goal (ADR-0055). 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 (ADR-0064)"}}}}, "laid": {"type": "array", "items": {"type": "object"}, "description": "the blocks the user laid out themselves (ADR-0157), held at their hours through a rebuild"}, "pushback": {"type": "array", "items": {"type": "object", "required": ["task", "reason"], "properties": {"task": {"type": "string"}, "reason": {"type": "string"}}}, "description": "where Sereo would change one of the user's own blocks, and why. Advice only: the block stays (ADR-0157)"}, "outside_hours": {"type": "array", "items": {"type": "object", "required": ["task", "start", "end", "side"], "properties": {"task": {"type": "string"}, "start": {"type": "string"}, "end": {"type": "string"}, "side": {"type": "string", "enum": ["before", "after"]}}}, "description": "on a day the user laid out: the work blocks running outside the hours they keep, kept and named (ADR-0155)"}, "most_important": {"type": "string"}, "coach_note": {"type": "string"}, "generated_at": {"type": "string"}, "energy": {"type": ["integer", "null"], "minimum": 1, "maximum": 5}, "energy_stated": {"type": "boolean", "description": "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 (ADR-0059)"}, "recovery": {"type": "boolean"}, "recovery_gap": {"type": ["integer", "null"], "description": "days away the day was planned to recover from; a replan of the day keeps it, so a rebuilt recovery day is still one"}, "issues": {"type": "array", "items": {"type": "string"}, "description": "what the guards changed, as `kind:subject` \u2014 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 (ADR-0139)"}, "released": {"type": "array", "description": "week-plan blocks for this day that the planner left off at the user's request (ADR-0109): `block` is the week block id, `text` its text. Only written when the user's own words asked for it", "items": {"type": "object", "required": ["block", "why"], "properties": {"block": {"type": "string"}, "text": {"type": "string"}, "why": {"type": "string"}, "at": {"type": "string"}}}}, "source": {"type": "string", "enum": ["user", "scheduler"]}, "accepted_at": {"type": "string", "description": "present once accepted; also counts as the user showing up for gap detection"}, "on_hold": {"type": "array", "items": {"type": "string"}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "put": {"operationId": "put_plan", "summary": "Save a user-laid-out day plan", "tags": ["planning"], "description": "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.\n\n**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.\n\n**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`.\n\n**Fixed times.** `fixed` replaces the day's fixed (busy) times before the save; `[]` clears them and omitting the field leaves them unchanged.\n\n**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.\n\n**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`.\n\nErrors: `400 invalid_request` (`blocks` not a list, or invalid `fixed`); `409 not_onboarded`.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["blocks"], "properties": {"blocks": {"type": "array", "items": {"type": "object", "required": ["start", "end", "task", "interest", "why"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "task": {"type": "string", "maxLength": 120}, "interest": {"type": ["string", "null"], "description": "null for a chore or a break \u2014 see `chore`, which tells the two apart"}, "why": {"type": "string", "maxLength": 200}, "chore": {"type": "boolean", "description": "work that serves no tracked goal (ADR-0055). 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 (ADR-0064)"}}}}, "pins": {"type": "array", "items": {"type": "object", "properties": {"start": {"type": "string"}, "end": {"type": "string"}, "task": {"type": "string"}}}, "description": "blocks the user has pinned to their time, matched by `start` and `task`; pins that match no saved block are dropped"}, "most_important": {"type": "string"}, "coach_note": {"type": "string"}, "fixed": {"type": "array", "items": {"type": "object", "required": ["start", "end", "title"], "properties": {"start": {"type": "string"}, "end": {"type": "string"}, "title": {"type": "string"}}}, "description": "the day's fixed times (ADR-0156), replacing the existing list; [] clears it, absent leaves it unchanged. Treated as busy time like a calendar event; not tracked as work"}, "accept": {"type": "boolean", "description": "also accept the day in this request; ignored if any block is refused (W8)"}, "if_removes": {"type": "string", "enum": ["refuse"], "description": "refuse, writing nothing, a save that would remove a block (409 would_remove; ADR-0171)"}, "strict": {"type": "boolean", "description": "a block whose times cannot be read fails the save (400 unreadable_blocks) instead of being left out (ADR-0171)"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["plan", "refused", "changed"], "properties": {"scope": {"type": "string", "enum": ["today", "this week", "every future day", "nothing"], "description": "how far this write reaches: today's plan only, this week, every future day, or nothing at all"}, "persisted": {"type": "object", "description": "what lasts beyond today, by kind; empty lists when nothing lasting changed", "properties": {"goals": {"type": "array", "items": {"type": "string"}}, "rules": {"type": "array", "items": {"type": "string"}}, "settings": {"type": "array", "items": {"type": "string"}}, "jobs": {"type": "array", "items": {"type": "string"}}, "week": {"type": "array", "items": {"type": "string"}}}}, "changed": {"type": "object", "description": "what the day gained, lost, moved and kept, from the state before and after \u2014 the server's account, not the editor's prediction (ADR-0062, ADR-0064)", "properties": {"moved": {"type": "array", "items": {"type": "string"}}, "added": {"type": "array", "items": {"type": "string"}}, "removed": {"type": "array", "items": {"type": "string"}}, "kept": {"type": "array", "items": {"type": "string"}}}}, "week_check": {"type": ["object", "null"], "description": "whether the rest of the week is being re-read against the day as it now stands (ADR-0157): `started`, the `displaced` week work, or a `reason` it was not. The proposal lands on the day as `ask.week`"}, "plan": {"type": "object", "required": ["blocks", "most_important", "coach_note"], "properties": {"blocks": {"type": "array", "items": {"type": "object", "required": ["start", "end", "task", "interest", "why"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "task": {"type": "string", "maxLength": 120}, "interest": {"type": ["string", "null"], "description": "null for a chore or a break \u2014 see `chore`, which tells the two apart"}, "why": {"type": "string", "maxLength": 200}, "chore": {"type": "boolean", "description": "work that serves no tracked goal (ADR-0055). 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 (ADR-0064)"}}}}, "laid": {"type": "array", "items": {"type": "object"}, "description": "the blocks the user laid out themselves (ADR-0157), held at their hours through a rebuild"}, "pushback": {"type": "array", "items": {"type": "object", "required": ["task", "reason"], "properties": {"task": {"type": "string"}, "reason": {"type": "string"}}}, "description": "where Sereo would change one of the user's own blocks, and why. Advice only: the block stays (ADR-0157)"}, "outside_hours": {"type": "array", "items": {"type": "object", "required": ["task", "start", "end", "side"], "properties": {"task": {"type": "string"}, "start": {"type": "string"}, "end": {"type": "string"}, "side": {"type": "string", "enum": ["before", "after"]}}}, "description": "on a day the user laid out: the work blocks running outside the hours they keep, kept and named (ADR-0155)"}, "most_important": {"type": "string"}, "coach_note": {"type": "string"}, "generated_at": {"type": "string"}, "energy": {"type": ["integer", "null"], "minimum": 1, "maximum": 5}, "energy_stated": {"type": "boolean", "description": "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 (ADR-0059)"}, "recovery": {"type": "boolean"}, "recovery_gap": {"type": ["integer", "null"], "description": "days away the day was planned to recover from; a replan of the day keeps it, so a rebuilt recovery day is still one"}, "issues": {"type": "array", "items": {"type": "string"}, "description": "what the guards changed, as `kind:subject` \u2014 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 (ADR-0139)"}, "released": {"type": "array", "description": "week-plan blocks for this day that the planner left off at the user's request (ADR-0109): `block` is the week block id, `text` its text. Only written when the user's own words asked for it", "items": {"type": "object", "required": ["block", "why"], "properties": {"block": {"type": "string"}, "text": {"type": "string"}, "why": {"type": "string"}, "at": {"type": "string"}}}}, "source": {"type": "string", "enum": ["user", "scheduler"]}, "accepted_at": {"type": "string", "description": "present once accepted; also counts as the user showing up for gap detection"}, "on_hold": {"type": "array", "items": {"type": "string"}}}}, "fixed": {"type": "array", "items": {"type": "object", "required": ["start", "end", "title"], "properties": {"start": {"type": "string"}, "end": {"type": "string"}, "title": {"type": "string"}}}, "description": "the day's fixed times as they now stand"}, "accepted": {"type": "boolean", "description": "whether the day is taken after this save"}, "issues": {"type": "array", "items": {"type": "string"}}, "refused": {"type": "array", "items": {"type": "object", "required": ["task", "reason"], "properties": {"task": {"type": "string"}, "start": {"type": ["string", "null"]}, "end": {"type": ["string", "null"]}, "reason": {"type": "string"}}}}, "rebuild": {"type": ["object", "null"]}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/reasoning": {"get": {"operationId": "get_reasoning", "summary": "Get the generation trace for a day's plan", "tags": ["planning"], "description": "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}`.\n\nA 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.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"day": {"type": "string"}, "energy": {"type": "integer"}, "guard_issues": {"type": "array"}, "pressure": {"type": "object"}, "constraints_applied": {"type": "array"}, "reasoning": {"type": ["string", "null"]}, "prompt": {"type": "string"}, "model": {"type": "string"}, "cost_usd": {"type": "number"}, "latency_s": {"type": "number"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/generate": {"post": {"operationId": "generate", "summary": "Generate a day's plan", "tags": ["planning"], "description": "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.\n\nBody: 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.\n\nInvokes 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.\n\nErrors: `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`.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"energy": {"type": "integer", "minimum": 1, "maximum": 5, "description": "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 \u2014 omitted, the profile default plans the day and the day records that nobody said it (ADR-0059)"}, "mood": {"type": "string"}, "what_happened": {"type": "string", "description": "the user's account of a gap, if they are returning"}, "note": {"type": "string", "description": "what the user said about today when they asked for the plan \u2014 their own words, honoured over any general pattern, spent with this one day (W1). Clipped to 500 characters"}, "force": {"type": "boolean", "description": "discard an existing plan"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["plan"], "properties": {"scope": {"type": "string", "enum": ["today", "this week", "every future day", "nothing"], "description": "how far this write reaches: today's plan only, this week, every future day, or nothing at all"}, "persisted": {"type": "object", "description": "what lasts beyond today, by kind; empty lists when nothing lasting changed", "properties": {"goals": {"type": "array", "items": {"type": "string"}}, "rules": {"type": "array", "items": {"type": "string"}}, "settings": {"type": "array", "items": {"type": "string"}}, "jobs": {"type": "array", "items": {"type": "string"}}, "week": {"type": "array", "items": {"type": "string"}}}}, "plan": {"type": "object", "required": ["blocks", "most_important", "coach_note"], "properties": {"blocks": {"type": "array", "items": {"type": "object", "required": ["start", "end", "task", "interest", "why"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "task": {"type": "string", "maxLength": 120}, "interest": {"type": ["string", "null"], "description": "null for a chore or a break \u2014 see `chore`, which tells the two apart"}, "why": {"type": "string", "maxLength": 200}, "chore": {"type": "boolean", "description": "work that serves no tracked goal (ADR-0055). 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 (ADR-0064)"}}}}, "laid": {"type": "array", "items": {"type": "object"}, "description": "the blocks the user laid out themselves (ADR-0157), held at their hours through a rebuild"}, "pushback": {"type": "array", "items": {"type": "object", "required": ["task", "reason"], "properties": {"task": {"type": "string"}, "reason": {"type": "string"}}}, "description": "where Sereo would change one of the user's own blocks, and why. Advice only: the block stays (ADR-0157)"}, "outside_hours": {"type": "array", "items": {"type": "object", "required": ["task", "start", "end", "side"], "properties": {"task": {"type": "string"}, "start": {"type": "string"}, "end": {"type": "string"}, "side": {"type": "string", "enum": ["before", "after"]}}}, "description": "on a day the user laid out: the work blocks running outside the hours they keep, kept and named (ADR-0155)"}, "most_important": {"type": "string"}, "coach_note": {"type": "string"}, "generated_at": {"type": "string"}, "energy": {"type": ["integer", "null"], "minimum": 1, "maximum": 5}, "energy_stated": {"type": "boolean", "description": "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 (ADR-0059)"}, "recovery": {"type": "boolean"}, "recovery_gap": {"type": ["integer", "null"], "description": "days away the day was planned to recover from; a replan of the day keeps it, so a rebuilt recovery day is still one"}, "issues": {"type": "array", "items": {"type": "string"}, "description": "what the guards changed, as `kind:subject` \u2014 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 (ADR-0139)"}, "released": {"type": "array", "description": "week-plan blocks for this day that the planner left off at the user's request (ADR-0109): `block` is the week block id, `text` its text. Only written when the user's own words asked for it", "items": {"type": "object", "required": ["block", "why"], "properties": {"block": {"type": "string"}, "text": {"type": "string"}, "why": {"type": "string"}, "at": {"type": "string"}}}}, "source": {"type": "string", "enum": ["user", "scheduler"]}, "accepted_at": {"type": "string", "description": "present once accepted; also counts as the user showing up for gap detection"}, "on_hold": {"type": "array", "items": {"type": "string"}}}}, "recovery_gap": {"type": ["integer", "null"]}, "accepted": {"type": "boolean", "description": "always false: a generated plan is a proposal until accepted (ADR-0066)"}, "rebuild": {"type": ["object", "null"]}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/stream": {"get": {"operationId": "plan_stream", "summary": "Stream plan-build progress events", "tags": ["planning"], "description": "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.\n\nEvents 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}`.\n\nThe 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.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "string", "description": "text/event-stream frames: data: {type: \"plan_stage\", day, stage, ...}, plus `: keepalive` comments"}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/replan": {"post": {"operationId": "replan", "summary": "Regenerate a day's plan from user feedback", "tags": ["planning"], "description": "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`.\n\nPass 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.\n\n**The note is parsed before planning** (ADR-0173). 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.\n\n**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`.\n\nAn 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`).\n\nInvokes 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`.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "description": "the user's feedback, verbatim"}, "ask": {"type": "boolean", "description": "the caller can relay a clarifying `question` to the user (ADR-0173). Without it an unclear part is passed to the planner in the note"}, "energy": {"type": "integer", "minimum": 1, "maximum": 5}, "mood": {"type": "string"}, "fresh": {"type": "boolean", "description": "start the day over (ADR-0157). 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": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["plan", "stability", "moved", "changed"], "properties": {"scope": {"type": "string", "enum": ["today", "this week", "every future day", "nothing"], "description": "how far this write reaches: today's plan only, this week, every future day, or nothing at all"}, "persisted": {"type": "object", "description": "what lasts beyond today, by kind; empty lists when nothing lasting changed", "properties": {"goals": {"type": "array", "items": {"type": "string"}}, "rules": {"type": "array", "items": {"type": "string"}}, "settings": {"type": "array", "items": {"type": "string"}}, "jobs": {"type": "array", "items": {"type": "string"}}, "week": {"type": "array", "items": {"type": "string"}}}}, "week_check": {"type": ["object", "null"], "description": "whether the rest of the week is being re-read against the day as it now stands (ADR-0157): `started`, the `displaced` week work, or a `reason` it was not. The proposal lands on the day as `ask.week`"}, "plan": {"type": "object", "required": ["blocks", "most_important", "coach_note"], "properties": {"blocks": {"type": "array", "items": {"type": "object", "required": ["start", "end", "task", "interest", "why"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "task": {"type": "string", "maxLength": 120}, "interest": {"type": ["string", "null"], "description": "null for a chore or a break \u2014 see `chore`, which tells the two apart"}, "why": {"type": "string", "maxLength": 200}, "chore": {"type": "boolean", "description": "work that serves no tracked goal (ADR-0055). 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 (ADR-0064)"}}}}, "laid": {"type": "array", "items": {"type": "object"}, "description": "the blocks the user laid out themselves (ADR-0157), held at their hours through a rebuild"}, "pushback": {"type": "array", "items": {"type": "object", "required": ["task", "reason"], "properties": {"task": {"type": "string"}, "reason": {"type": "string"}}}, "description": "where Sereo would change one of the user's own blocks, and why. Advice only: the block stays (ADR-0157)"}, "outside_hours": {"type": "array", "items": {"type": "object", "required": ["task", "start", "end", "side"], "properties": {"task": {"type": "string"}, "start": {"type": "string"}, "end": {"type": "string"}, "side": {"type": "string", "enum": ["before", "after"]}}}, "description": "on a day the user laid out: the work blocks running outside the hours they keep, kept and named (ADR-0155)"}, "most_important": {"type": "string"}, "coach_note": {"type": "string"}, "generated_at": {"type": "string"}, "energy": {"type": ["integer", "null"], "minimum": 1, "maximum": 5}, "energy_stated": {"type": "boolean", "description": "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 (ADR-0059)"}, "recovery": {"type": "boolean"}, "recovery_gap": {"type": ["integer", "null"], "description": "days away the day was planned to recover from; a replan of the day keeps it, so a rebuilt recovery day is still one"}, "issues": {"type": "array", "items": {"type": "string"}, "description": "what the guards changed, as `kind:subject` \u2014 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 (ADR-0139)"}, "released": {"type": "array", "description": "week-plan blocks for this day that the planner left off at the user's request (ADR-0109): `block` is the week block id, `text` its text. Only written when the user's own words asked for it", "items": {"type": "object", "required": ["block", "why"], "properties": {"block": {"type": "string"}, "text": {"type": "string"}, "why": {"type": "string"}, "at": {"type": "string"}}}}, "source": {"type": "string", "enum": ["user", "scheduler"]}, "accepted_at": {"type": "string", "description": "present once accepted; also counts as the user showing up for gap detection"}, "on_hold": {"type": "array", "items": {"type": "string"}}}}, "stability": {"type": "number", "minimum": 0, "maximum": 1, "description": "share of the previous plan unchanged; cannot show removals, use `changed`"}, "moved": {"type": "integer", "minimum": 0, "description": "length of `changed.moved`"}, "changed": {"type": "object", "required": ["moved", "added", "removed", "kept"], "description": "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.", "properties": {"moved": {"type": "array", "items": {"type": "string"}, "description": "on the day before and after, at a different hour"}, "added": {"type": "array", "items": {"type": "string"}}, "removed": {"type": "array", "items": {"type": "string"}, "description": "was on the day and is not. Never fold this into a count \u2014 name them"}, "kept": {"type": "array", "items": {"type": "string"}, "description": "same task, same hour"}}}, "previous": {"type": ["object", "null"]}, "accepted": {"type": "boolean"}, "rebuild": {"type": ["object", "null"]}, "question": {"type": ["object", "null"], "description": "set when the note needs an answer first; nothing was written or rebuilt", "properties": {"text": {"type": "string"}, "options": {"type": "array", "items": {"type": "string"}}}}, "understood": {"type": "array", "description": "what became of each part of the note", "items": {"type": "object", "required": ["kind", "says", "applied"], "properties": {"kind": {"type": "string"}, "says": {"type": "string"}, "applied": {"type": "string"}}}}, "proposals": {"type": "array", "description": "lasting changes found in the note; not written. Apply one with POST /v1/lasting when the user agrees", "items": {"type": "object", "required": ["kind"], "properties": {"kind": {"type": "string", "enum": ["weekly", "rule", "hours"]}, "title": {"type": "string"}, "days": {"type": "array", "items": {"type": "integer", "minimum": 0, "maximum": 6}}, "start": {"type": "string"}, "end": {"type": "string"}, "text": {"type": "string"}, "day_start": {"type": "string"}, "day_end": {"type": "string"}, "for": {"type": "string", "description": "a habit or goal id: the weekly time is reserved for it (ADR-0121), not busy"}, "says": {"type": "string"}}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/suggest": {"post": {"operationId": "suggest", "summary": "Suggest tasks for an open time slot", "tags": ["planning"], "description": "Returns up to three suggestions for an empty stretch of a day as `{picks, mode, note}`. Nothing is written.\n\nBy 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.\n\nWith `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.\n\n`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`.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"at": {"type": "string", "description": "HH:MM the stretch begins"}, "minutes": {"type": "integer", "description": "how long it is; 0 for no limit"}, "note": {"type": "string", "description": "anything the user said they want there"}, "ask": {"type": "boolean", "description": "have the model choose from the ranking; invokes the model once. Absent or false: deterministic ranking, no model call"}, "day": {"type": "array", "items": {"type": "object", "required": ["start", "end", "task", "interest", "why"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "task": {"type": "string", "maxLength": 120}, "interest": {"type": ["string", "null"], "description": "null for a chore or a break \u2014 see `chore`, which tells the two apart"}, "why": {"type": "string", "maxLength": 200}, "chore": {"type": "boolean", "description": "work that serves no tracked goal (ADR-0055). 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 (ADR-0064)"}}}, "description": "the client's unsaved draft of the day, used only with `ask` to describe the neighbouring blocks to the model. Never stored"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["picks", "mode"], "properties": {"mode": {"type": "string", "enum": ["ranked", "reasoned"], "description": "how this answer was arrived at"}, "note": {"type": ["string", "null"], "description": "why it is ranked rather than reasoned, when it is"}, "picks": {"type": "array", "items": {"type": "object", "required": ["task", "interest", "minutes", "why", "registered"], "properties": {"task": {"type": "string"}, "interest": {"type": ["string", "null"], "description": "null when it serves no goal, which only an off-list pick does"}, "registered": {"type": "boolean", "description": "true for a tracked interest; false for the single off-list pick a reasoned answer may add"}, "kind": {"type": "string"}, "tag": {"type": "string"}, "node": {"type": ["string", "null"]}, "minutes": {"type": "integer"}, "why": {"type": "string"}}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/discuss": {"post": {"operationId": "discuss_plan", "summary": "Discuss a draft day with the planner", "tags": ["planning"], "description": "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}`.\n\nThe 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 (ADR-0010). 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.\n\nInvokes 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.\n\nErrors: `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`.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["messages", "blocks"], "properties": {"messages": {"type": "array", "items": {"type": "object", "properties": {"who": {"type": "string", "enum": ["user", "planner"]}, "text": {"type": "string"}}}, "description": "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."}, "blocks": {"type": "array", "items": {"type": "object", "required": ["start", "end", "task", "interest", "why"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "task": {"type": "string", "maxLength": 120}, "interest": {"type": ["string", "null"], "description": "null for a chore or a break \u2014 see `chore`, which tells the two apart"}, "why": {"type": "string", "maxLength": 200}, "chore": {"type": "boolean", "description": "work that serves no tracked goal (ADR-0055). 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 (ADR-0064)"}}}, "description": "the editor's working copy"}, "anchor": {"type": ["object", "null"], "properties": {"start": {"type": "string"}, "task": {"type": "string"}}, "description": "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>`."}, "pins": {"type": "array", "items": {"type": "string"}, "description": "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>`."}, "propose": {"type": "boolean", "description": "When true, the model is instructed to return a revised block list this turn."}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["reply"], "properties": {"reply": {"type": "string"}, "blocks": {"type": ["array", "null"], "items": {"type": "object", "required": ["start", "end", "task", "interest", "why"], "properties": {"start": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "end": {"type": "string", "pattern": "^[0-9]{2}:[0-9]{2}$"}, "task": {"type": "string", "maxLength": 120}, "interest": {"type": ["string", "null"], "description": "null for a chore or a break \u2014 see `chore`, which tells the two apart"}, "why": {"type": "string", "maxLength": 200}, "chore": {"type": "boolean", "description": "work that serves no tracked goal (ADR-0055). 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 (ADR-0064)"}}}, "description": "the working copy's replacement, or null when the day stands"}, "changes": {"type": "array", "items": {"type": "object", "properties": {"call": {"type": "string", "enum": ["added", "removed", "moved", "resized"]}, "task": {"type": "string"}, "was": {"type": ["object", "null"]}, "now": {"type": ["object", "null"]}, "note": {"type": "string"}}}, "description": "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}`."}, "issues": {"type": "array", "items": {"type": "string"}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/escalate": {"post": {"operationId": "escalate_day", "summary": "Send a message about a day", "tags": ["planning"], "description": "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.\n\n`did` values:\n\n- `answered` \u2014 explained only; nothing written. Also returned when the words did not name a valid target for the act the model chose. - `changed` \u2014 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` \u2014 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` \u2014 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` \u2014 a job was marked done (ADR-0148/0149), or a milestone step named in the words (`changed.finished`, ADR-0151). Goals and habits are never marked finished this way; the answer says how they finish. - `held` \u2014 a goal, job or habit was paused (until a date or indefinitely) or resumed (`changed.held` / `changed.released`, ADR-0150). If the week plan still relies on it, a week re-read starts and `working` is true. - `adjusted` \u2014 goal fields were changed (`changed.goals`, ADR-0158). - `ruled` / `unruled` \u2014 a standing rule was added in the user's words, or removed (`changed.rules` / `changed.rules_removed`, ADR-0162). - `hours_changed` \u2014 the day window or the recurring unavailable hours changed (`changed.hours`). - `goal_added` \u2014 a goal was created with checkpoints and steps (`changed.goals`, ADR-0165). - `job_removed` \u2014 a job was removed, restorable for at least 30 days (`changed.removed`). - `reranked` \u2014 goal priority or areas were reordered (`changed.areas`, ADR-0163).\n\nWhen 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.\n\nSend 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.\n\n`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.\n\nWeek 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.\n\nWith `proposals: true`, a change to today is **proposed, not made** (ADR-0203): `did` is `proposed` and `proposal` carries the day as it would be (`blocks`) and what would change, block by block (`rows`). Nothing is written until the blocks are sent to `POST /v1/plans/{date}/take`. A day with no blocks has nothing to revise and is rebuilt at once (`changed`).\n\nInvokes the planner model (fast tier, 60 s timeout per call); a `proposed` 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.\n\nErrors: `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`.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["question"], "properties": {"question": {"type": "string"}, "messages": {"type": "array", "items": {"type": "object"}}, "proposals": {"type": "boolean", "description": "True when the client can show a proposal and a choice sheet (ADR-0203). Without it a change to today is made on this turn, as before."}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["answer", "escalated", "did"], "properties": {"scope": {"type": "string", "enum": ["today", "this week", "every future day", "nothing"], "description": "how far this write reaches: today's plan only, this week, every future day, or nothing at all"}, "persisted": {"type": "object", "description": "what lasts beyond today, by kind; empty lists when nothing lasting changed", "properties": {"goals": {"type": "array", "items": {"type": "string"}}, "rules": {"type": "array", "items": {"type": "string"}}, "settings": {"type": "array", "items": {"type": "string"}}, "jobs": {"type": "array", "items": {"type": "string"}}, "week": {"type": "array", "items": {"type": "string"}}}}, "answer": {"type": "string"}, "pushback": {"type": "array", "items": {"type": "object", "required": ["task", "reason"], "properties": {"task": {"type": "string"}, "reason": {"type": "string"}}}, "description": "The user's own blocks the planner would have changed, each with its reason. These blocks are left as they are (ADR-0157)."}, "did": {"type": "string", "enum": ["answered", "changed", "proposed", "escalated", "finished", "held", "ruled", "adjusted", "week_changed", "unruled", "hours_changed", "reranked", "goal_added", "job_removed"]}, "override": {"type": "boolean", "description": "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 (ADR-0159)."}, "proposal": {"type": "object", "required": ["blocks", "rows"], "description": "A change to today, worked out and not made. Send `blocks` to `POST /v1/plans/{date}/take` to take it (ADR-0203).", "properties": {"blocks": {"type": "array", "items": {"type": "object"}}, "rows": {"type": "array", "items": {"type": "object", "required": ["kind", "task"], "properties": {"kind": {"type": "string", "enum": ["added", "removed", "moved", "resized"]}, "task": {"type": "string"}, "start": {"type": ["string", "null"]}, "end": {"type": ["string", "null"]}, "was_start": {"type": ["string", "null"]}, "was_end": {"type": ["string", "null"]}}}}}}, "ask": {"type": "object", "required": ["question", "options"], "description": "A question with two to four short answers, on a turn that changed nothing. Answer by sending one as the next `question`, or any other words (ADR-0203).", "properties": {"question": {"type": "string"}, "options": {"type": "array", "items": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}}}}}}, "today_affected": {"type": "boolean"}, "escalated": {"type": "boolean"}, "working": {"type": "boolean", "description": "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 (ADR-0150)."}, "ceiling_reached": {"type": "boolean"}, "changed": {"type": "object"}, "plan": {"type": "object"}, "accepted": {"type": "boolean"}, "rebuild": {"type": ["object", "null"]}, "drift": {"type": "array", "items": {"type": "object"}}, "stale": {"type": "array", "items": {"type": "string"}}, "ending": {"type": "string"}, "unfit": {"type": "array", "items": {"type": "object", "required": ["task", "why"], "properties": {"task": {"type": "string"}, "goal": {"type": ["string", "null"]}, "minutes": {"type": ["integer", "null"]}, "asked": {"type": "boolean"}, "why": {"type": "string"}, "offers": {"type": "array", "items": {"type": "object", "required": ["kind", "text"], "properties": {"kind": {"type": "string", "enum": ["move", "drop_habit"]}, "text": {"type": "string"}, "to": {"type": "string"}, "day_label": {"type": "string"}, "effort": {"type": "string"}, "free_minutes": {"type": "integer"}, "task": {"type": "string"}, "interest": {"type": ["string", "null"]}}}}}}}, "week": {"type": "object", "required": ["answer", "amendment"], "properties": {"answer": {"type": "string"}, "reasoning": {"type": "string"}, "amendment": {"type": ["object", "null"], "description": "the proposed days, `{days: {date: entry}}`, in the week plan's own shape; null when the week would stand"}, "refused": {"type": "array", "items": {"type": "object"}}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "429": {"description": "Too many attempts; wait and retry \u2014 `retry-after` says how long", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/take": {"post": {"operationId": "take_day_proposal", "summary": "Take a change proposed for a day", "tags": ["planning"], "description": "The yes to a `proposal` from `POST /v1/plans/{date}/escalate` (ADR-0203). Send the proposal's `blocks` back as they came. They are saved through the same path as a day laid out by hand, so the calendar and day-window guards run and anything they refuse is named in `refused`. `changed` is the server's account of what moved, was added and was removed; `rows` is the same block by block, including a block made shorter or longer where it stands. A day that was already accepted stays accepted. Not offered for a day that is over.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["blocks"], "properties": {"blocks": {"type": "array", "items": {"type": "object"}}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["did", "changed", "rows", "plan"], "properties": {"scope": {"type": "string", "enum": ["today", "this week", "every future day", "nothing"], "description": "how far this write reaches: today's plan only, this week, every future day, or nothing at all"}, "persisted": {"type": "object", "description": "what lasts beyond today, by kind; empty lists when nothing lasting changed", "properties": {"goals": {"type": "array", "items": {"type": "string"}}, "rules": {"type": "array", "items": {"type": "string"}}, "settings": {"type": "array", "items": {"type": "string"}}, "jobs": {"type": "array", "items": {"type": "string"}}, "week": {"type": "array", "items": {"type": "string"}}}}, "did": {"type": "string", "enum": ["changed"]}, "changed": {"type": "object"}, "rows": {"type": "array", "items": {"type": "object", "required": ["kind", "task"], "properties": {"kind": {"type": "string", "enum": ["added", "removed", "moved", "resized"]}, "task": {"type": "string"}, "start": {"type": ["string", "null"]}, "end": {"type": ["string", "null"]}, "was_start": {"type": ["string", "null"]}, "was_end": {"type": ["string", "null"]}}}}, "plan": {"type": "object"}, "accepted": {"type": "boolean"}, "rebuild": {"type": ["object", "null"]}, "refused": {"type": "array", "items": {"type": "object"}}, "unfit": {"type": "array", "items": {"type": "object", "required": ["task", "why"], "properties": {"task": {"type": "string"}, "goal": {"type": ["string", "null"]}, "minutes": {"type": ["integer", "null"]}, "asked": {"type": "boolean"}, "why": {"type": "string"}, "offers": {"type": "array", "items": {"type": "object", "required": ["kind", "text"], "properties": {"kind": {"type": "string", "enum": ["move", "drop_habit"]}, "text": {"type": "string"}, "to": {"type": "string"}, "day_label": {"type": "string"}, "effort": {"type": "string"}, "free_minutes": {"type": "integer"}, "task": {"type": "string"}, "interest": {"type": ["string", "null"]}}}}}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/conversation": {"post": {"operationId": "converse", "summary": "Send a message to the account conversation", "tags": ["planning"], "description": "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.\n\nThe planner may object to a request; a message that explicitly overrides the objection is carried out and the response sets `override: true` (ADR-0159). Pass earlier turns in `messages` so a confirmation reaches the offer it answers. `question` is accepted as an alias for `message`.\n\nInvokes the planner model.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["message"], "properties": {"message": {"type": "string"}, "date": {"type": "string"}, "messages": {"type": "array", "items": {"type": "object"}}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["answer", "escalated", "did"], "properties": {"scope": {"type": "string", "enum": ["today", "this week", "every future day", "nothing"], "description": "how far this write reaches: today's plan only, this week, every future day, or nothing at all"}, "persisted": {"type": "object", "description": "what lasts beyond today, by kind; empty lists when nothing lasting changed", "properties": {"goals": {"type": "array", "items": {"type": "string"}}, "rules": {"type": "array", "items": {"type": "string"}}, "settings": {"type": "array", "items": {"type": "string"}}, "jobs": {"type": "array", "items": {"type": "string"}}, "week": {"type": "array", "items": {"type": "string"}}}}, "answer": {"type": "string"}, "pushback": {"type": "array", "items": {"type": "object", "required": ["task", "reason"], "properties": {"task": {"type": "string"}, "reason": {"type": "string"}}}, "description": "The user's own blocks the planner would have changed, each with its reason. These blocks are left as they are (ADR-0157)."}, "did": {"type": "string", "enum": ["answered", "changed", "proposed", "escalated", "finished", "held", "ruled", "adjusted", "week_changed", "unruled", "hours_changed", "reranked", "goal_added", "job_removed"]}, "override": {"type": "boolean", "description": "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 (ADR-0159)."}, "proposal": {"type": "object", "required": ["blocks", "rows"], "description": "A change to today, worked out and not made. Send `blocks` to `POST /v1/plans/{date}/take` to take it (ADR-0203).", "properties": {"blocks": {"type": "array", "items": {"type": "object"}}, "rows": {"type": "array", "items": {"type": "object", "required": ["kind", "task"], "properties": {"kind": {"type": "string", "enum": ["added", "removed", "moved", "resized"]}, "task": {"type": "string"}, "start": {"type": ["string", "null"]}, "end": {"type": ["string", "null"]}, "was_start": {"type": ["string", "null"]}, "was_end": {"type": ["string", "null"]}}}}}}, "ask": {"type": "object", "required": ["question", "options"], "description": "A question with two to four short answers, on a turn that changed nothing. Answer by sending one as the next `question`, or any other words (ADR-0203).", "properties": {"question": {"type": "string"}, "options": {"type": "array", "items": {"type": "object", "required": ["label"], "properties": {"label": {"type": "string"}}}}}}, "today_affected": {"type": "boolean"}, "escalated": {"type": "boolean"}, "working": {"type": "boolean", "description": "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 (ADR-0150)."}, "ceiling_reached": {"type": "boolean"}, "changed": {"type": "object"}, "plan": {"type": "object"}, "accepted": {"type": "boolean"}, "rebuild": {"type": ["object", "null"]}, "drift": {"type": "array", "items": {"type": "object"}}, "stale": {"type": "array", "items": {"type": "string"}}, "ending": {"type": "string"}, "unfit": {"type": "array", "items": {"type": "object", "required": ["task", "why"], "properties": {"task": {"type": "string"}, "goal": {"type": ["string", "null"]}, "minutes": {"type": ["integer", "null"]}, "asked": {"type": "boolean"}, "why": {"type": "string"}, "offers": {"type": "array", "items": {"type": "object", "required": ["kind", "text"], "properties": {"kind": {"type": "string", "enum": ["move", "drop_habit"]}, "text": {"type": "string"}, "to": {"type": "string"}, "day_label": {"type": "string"}, "effort": {"type": "string"}, "free_minutes": {"type": "integer"}, "task": {"type": "string"}, "interest": {"type": ["string", "null"]}}}}}}}, "week": {"type": "object", "required": ["answer", "amendment"], "properties": {"answer": {"type": "string"}, "reasoning": {"type": "string"}, "amendment": {"type": ["object", "null"], "description": "the proposed days, `{days: {date: entry}}`, in the week plan's own shape; null when the week would stand"}, "refused": {"type": "array", "items": {"type": "object"}}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "429": {"description": "Too many attempts; wait and retry \u2014 `retry-after` says how long", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/unfit": {"post": {"operationId": "accept_unfit", "summary": "Resolve a block that did not fit the day", "tags": ["planning"], "description": "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 (ADR-0112).\n\n- `move` \u2014 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` \u2014 rebuilds today without the habit named in the offer (`task` / `interest`) so the block can be placed. Invokes the planner model.\n\nErrors: `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).", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["task", "choice"], "properties": {"task": {"type": "string"}, "choice": {"type": "string", "enum": ["move", "drop_habit"]}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/week-proposal/leave": {"post": {"operationId": "leave_week_proposal", "summary": "Dismiss a pending week proposal for a day", "tags": ["planning"], "description": "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: {}}`.\n\nIdempotent: 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 (ADR-0169). No model call.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["left"], "properties": {"left": {"type": "boolean"}, "scope": {"type": "string"}, "persisted": {"type": "object"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/fixed": {"put": {"operationId": "put_fixed_times", "summary": "Replace a day's fixed busy times", "tags": ["planning"], "description": "Replaces the fixed busy times for one date (for example dinner, working hours, a pickup) and returns the list as stored (ADR-0156/0174). 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.\n\nFixed 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`.\n\nErrors: `400` when `fixed` is not a list or an entry is invalid; `409` `not_onboarded`.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["fixed"], "properties": {"fixed": {"type": "array", "items": {"type": "object", "required": ["start", "end", "title"], "properties": {"start": {"type": "string"}, "end": {"type": "string"}, "title": {"type": "string"}}}}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["fixed"], "properties": {"fixed": {"type": "array", "items": {"type": "object", "required": ["start", "end", "title"], "properties": {"start": {"type": "string"}, "end": {"type": "string"}, "title": {"type": "string"}}}}, "scope": {"type": "string", "enum": ["today", "this week", "every future day", "nothing"], "description": "how far this write reaches: today's plan only, this week, every future day, or nothing at all"}, "persisted": {"type": "object", "description": "what lasts beyond today, by kind; empty lists when nothing lasting changed", "properties": {"goals": {"type": "array", "items": {"type": "string"}}, "rules": {"type": "array", "items": {"type": "string"}}, "settings": {"type": "array", "items": {"type": "string"}}, "jobs": {"type": "array", "items": {"type": "string"}}, "week": {"type": "array", "items": {"type": "string"}}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/constraints": {"post": {"operationId": "create_constraint", "summary": "Create a standing rule", "tags": ["planning"], "description": "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.\n\n`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}`.\n\nErrors: `400` for empty `text`, an unknown `kind` or an unknown interest id in `applies_to`; `409` `not_onboarded`.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string", "maxLength": 300}, "kind": {"type": "string", "enum": ["gate", "scheduling", "content"], "description": "defaults to scheduling"}, "applies_to": {"type": "array", "items": {"type": "string"}, "description": "interest ids, or [\"all\"] (the default)"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["id", "text", "kind", "priority", "applies_to"], "properties": {"id": {"type": "string"}, "text": {"type": "string"}, "kind": {"type": "string"}, "priority": {"type": "integer"}, "applies_to": {"type": "array", "items": {"type": "string"}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/lasting": {"post": {"operationId": "keep_lasting", "summary": "Save a lasting change proposed by a replan", "tags": ["planning"], "description": "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 (ADR-0173). By `kind`:\n\n- `weekly` \u2014 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 (ADR-0121). The response returns the updated map. - `rule` \u2014 `text` becomes a standing rule, as with `POST /v1/constraints` and `kind: \"scheduling\"`; returned as `rule`. - `hours` \u2014 sets `day_start` and/or `day_end` (`HH:MM`).\n\nApplies to later plans; existing plans are not rebuilt. `kept` names the kind written and `scope` is `every future day`. No model call.\n\nErrors: `400` for an unknown `kind`, missing or malformed fields, or an unknown `for` id; `409` `not_onboarded`.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["proposal"], "properties": {"proposal": {"type": "object", "required": ["kind"], "properties": {"kind": {"type": "string", "enum": ["weekly", "rule", "hours"]}, "title": {"type": "string"}, "days": {"type": "array", "items": {"type": "integer", "minimum": 0, "maximum": 6}}, "start": {"type": "string"}, "end": {"type": "string"}, "text": {"type": "string"}, "day_start": {"type": "string"}, "day_end": {"type": "string"}, "for": {"type": "string", "description": "a habit or goal id: the weekly time is reserved for it (ADR-0121), not busy"}, "says": {"type": "string"}}}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["kept"], "properties": {"kept": {"type": "string", "enum": ["weekly", "rule", "hours"]}, "hours_off": {"type": "object"}, "free_by_weekday": {"type": "object"}, "rule": {"type": "object"}, "day_start": {"type": "string"}, "day_end": {"type": "string"}, "scope": {"type": "string", "enum": ["today", "this week", "every future day", "nothing"], "description": "how far this write reaches: today's plan only, this week, every future day, or nothing at all"}, "persisted": {"type": "object", "description": "what lasts beyond today, by kind; empty lists when nothing lasting changed", "properties": {"goals": {"type": "array", "items": {"type": "string"}}, "rules": {"type": "array", "items": {"type": "string"}}, "settings": {"type": "array", "items": {"type": "string"}}, "jobs": {"type": "array", "items": {"type": "string"}}, "week": {"type": "array", "items": {"type": "string"}}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/constraints/{constraint}": {"delete": {"operationId": "delete_constraint", "summary": "Delete a standing rule", "tags": ["planning"], "description": "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_\u2026`) or it came from an agreed report proposal (`report_\u2026`). Later plans no longer include it; existing plans are unchanged. No model call.\n\nErrors: `404` when no rule has that id (including a repeated delete); `409` `not_onboarded`.", "parameters": [{"name": "constraint", "in": "path", "required": true, "description": "A standing rule's id, from the day's own influences list.", "schema": {"type": "string", "pattern": "^[a-z0-9_]+$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"removed": {"type": "string"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/keep": {"post": {"operationId": "keep_chore", "summary": "Keep a chore the planner suggested", "tags": ["planning"], "description": "Turns a dated chore the planner suggested on a day into a chore on the user's profile (ADR-0059). 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.\n\nThe 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.\n\nErrors: `400` when `task` is missing or empty; `404` when the day has no dated chore block with that task; `409` `not_onboarded`.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["task"], "properties": {"task": {"type": "string", "description": "the block's task text, exactly as the day carries it"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["kept", "task"], "properties": {"kept": {"type": ["string", "null"], "description": "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."}, "task": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/accept": {"post": {"operationId": "accept", "summary": "Accept a day's plan", "tags": ["todos"], "description": "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.\n\nOne 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.\n\nAccepting 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`.\n\nIdempotent, 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.\n\nWhen 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).\n\nErrors: `404` when there is no plan for `date`; `400` for a malformed date. No model call.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["todos", "rebuild"], "properties": {"todos": {"type": "object", "required": ["date", "items", "open", "done", "skipped", "unreconciled", "read_only"], "properties": {"date": {"type": "string"}, "accepted_at": {"type": ["string", "null"]}, "accepted": {"type": "boolean"}, "read_only": {"type": "boolean", "description": "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 \u2014 this is the same condition the write routes enforce."}, "items": {"type": "array", "items": {"type": "object", "required": ["id", "title", "status", "interest"], "properties": {"id": {"type": "string", "pattern": "^t_[a-f0-9]+$"}, "start": {"type": ["string", "null"]}, "end": {"type": ["string", "null"]}, "title": {"type": "string"}, "why": {"type": "string"}, "interest": {"type": "string"}, "status": {"type": "string", "enum": ["open", "done", "skipped"], "description": "the stored status. Display `derived_status` instead"}, "derived_status": {"type": "string", "enum": ["open", "done", "skipped", "unreconciled"], "description": "what to display. `unreconciled` means still open and the day has passed \u2014 the user never answered. It is NOT a miss and must not be shown as one."}, "done_at": {"type": ["string", "null"]}, "off_plan": {"type": "boolean", "description": "true for an answered item whose block is no longer in the plan; kept so the answer is not lost"}, "comments": {"type": "array", "items": {"type": "object", "properties": {"ts": {"type": "string"}, "text": {"type": "string"}, "external_id": {"type": "string"}}}}, "todoist": {"type": "object"}}}}, "open": {"type": "integer"}, "done": {"type": "integer"}, "skipped": {"type": "integer"}, "unreconciled": {"type": "integer"}, "pending_reconciliation": {"type": "array", "description": "past days within the last two days that still have stored-`open` items", "items": {"type": "object", "properties": {"date": {"type": "string"}, "count": {"type": "integer"}}}}}}, "rebuild": {"type": "object", "properties": {"carried_over": {"type": "array"}, "kept_off_plan": {"type": "array", "description": "titles of answered items no longer in the plan, kept with `off_plan: true`"}, "dropped": {"type": "array", "description": "always empty; answered items are never dropped"}, "rebuilt_at": {"type": "string"}}}, "todoist": {"type": "object"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/energy": {"post": {"operationId": "state_energy", "summary": "Set the energy level for a planned day", "tags": ["planning"], "description": "Records the user's stated energy (integer 1\u20135) 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 (ADR-0059). Intended for plans the scheduler generated; `POST /v1/plans/{date}/generate` takes `energy` directly.\n\nErrors: `400` when `energy` is not an integer from 1 to 5; `404` when the date has no plan; `409` `not_onboarded`.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["energy"], "properties": {"energy": {"type": "integer", "minimum": 1, "maximum": 5}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["date", "energy", "energy_stated"], "properties": {"date": {"type": "string"}, "energy": {"type": "integer"}, "energy_stated": {"type": "boolean"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/reshape": {"post": {"operationId": "set_reshaping", "summary": "Set a day's editing state", "tags": ["planning"], "description": "Sets or clears the `reshaping` flag on a day's stored plan and returns `{date, reshaping}` (ADR-0081). 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`.\n\nThe 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.\n\nErrors: `404` when the date has no plan; `409` `not_onboarded`.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["on"], "properties": {"on": {"type": "boolean"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["date", "reshaping"], "properties": {"date": {"type": "string"}, "reshaping": {"type": "boolean"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/plans/{date}/checkin": {"post": {"operationId": "checkin", "summary": "Record a check-in by block number", "tags": ["todos"], "description": "Writes the day's check-in record from 1-based block numbers in the plan, and returns the record.\n\n`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.\n\nApplies 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.\n\nErrors: `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.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"done": {"type": "string", "description": "comma-separated 1-based block numbers as a string, e.g. \"1,3\""}, "skipped": {"type": "string", "description": "comma-separated 1-based block numbers, as for `done`"}, "note": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"done_tasks": {"type": "array", "items": {"type": "string"}}, "skipped_tasks": {"type": "array", "items": {"type": "string"}}, "unreconciled_tasks": {"type": "array", "items": {"type": "string"}, "description": "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_interests": {"type": "array", "items": {"type": "string"}, "description": "duplicates are meaningful: membership credits a habit's weekly cadence once, while each occurrence credits one block of a project's milestone"}, "note": {"type": ["string", "null"]}, "ts": {"type": "string"}, "source": {"type": "string", "description": "`todos` when rebuilt from an accepted to-do list; absent on a block-number check-in"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/todos": {"get": {"operationId": "get_todos", "summary": "Get a day's to-do list", "tags": ["todos"], "description": "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.\n\nA day that was never accepted returns an empty `items` list with `accepted: false`, not `404`.\n\nEach 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`.\n\n`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.\n\nErrors: `400` for a malformed date.", "parameters": [{"name": "date", "in": "query", "required": false, "description": "The day, YYYY-MM-DD. Defaults to today.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["date", "items", "open", "done", "skipped", "unreconciled", "read_only"], "properties": {"date": {"type": "string"}, "accepted_at": {"type": ["string", "null"]}, "accepted": {"type": "boolean"}, "read_only": {"type": "boolean", "description": "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 \u2014 this is the same condition the write routes enforce."}, "items": {"type": "array", "items": {"type": "object", "required": ["id", "title", "status", "interest"], "properties": {"id": {"type": "string", "pattern": "^t_[a-f0-9]+$"}, "start": {"type": ["string", "null"]}, "end": {"type": ["string", "null"]}, "title": {"type": "string"}, "why": {"type": "string"}, "interest": {"type": "string"}, "status": {"type": "string", "enum": ["open", "done", "skipped"], "description": "the stored status. Display `derived_status` instead"}, "derived_status": {"type": "string", "enum": ["open", "done", "skipped", "unreconciled"], "description": "what to display. `unreconciled` means still open and the day has passed \u2014 the user never answered. It is NOT a miss and must not be shown as one."}, "done_at": {"type": ["string", "null"]}, "off_plan": {"type": "boolean", "description": "true for an answered item whose block is no longer in the plan; kept so the answer is not lost"}, "comments": {"type": "array", "items": {"type": "object", "properties": {"ts": {"type": "string"}, "text": {"type": "string"}, "external_id": {"type": "string"}}}}, "todoist": {"type": "object"}}}}, "open": {"type": "integer"}, "done": {"type": "integer"}, "skipped": {"type": "integer"}, "unreconciled": {"type": "integer"}, "pending_reconciliation": {"type": "array", "description": "past days within the last two days that still have stored-`open` items", "items": {"type": "object", "properties": {"date": {"type": "string"}, "count": {"type": "integer"}}}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/todos/{todo}/status": {"post": {"operationId": "set_todo", "summary": "Set a to-do's status", "tags": ["todos"], "description": "Sets one item's status to `open`, `done` or `skipped` and returns the updated item as stored (without `derived_status`).\n\nThe day is taken from `date` in the body or query string, default today. Any accepted day can be edited, including past days.\n\n`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.\n\nSide 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.\n\nErrors: `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.", "parameters": [{"name": "todo", "in": "path", "required": true, "description": "A to-do id from GET /v1/todos.", "schema": {"type": "string", "pattern": "^t_[a-f0-9]{6,32}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["status"], "properties": {"status": {"type": "string", "enum": ["open", "done", "skipped"]}, "date": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["id", "title", "status", "interest"], "properties": {"id": {"type": "string", "pattern": "^t_[a-f0-9]+$"}, "start": {"type": ["string", "null"]}, "end": {"type": ["string", "null"]}, "title": {"type": "string"}, "why": {"type": "string"}, "interest": {"type": "string"}, "status": {"type": "string", "enum": ["open", "done", "skipped"], "description": "the stored status. Display `derived_status` instead"}, "derived_status": {"type": "string", "enum": ["open", "done", "skipped", "unreconciled"], "description": "what to display. `unreconciled` means still open and the day has passed \u2014 the user never answered. It is NOT a miss and must not be shown as one."}, "done_at": {"type": ["string", "null"]}, "off_plan": {"type": "boolean", "description": "true for an answered item whose block is no longer in the plan; kept so the answer is not lost"}, "comments": {"type": "array", "items": {"type": "object", "properties": {"ts": {"type": "string"}, "text": {"type": "string"}, "external_id": {"type": "string"}}}}, "todoist": {"type": "object"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/todos/{todo}/comments": {"post": {"operationId": "comment_todo", "summary": "Add a comment to a to-do", "tags": ["todos"], "description": "Appends a comment to one item and returns the comment (`ts`, `text`) with status `201`.\n\nThe 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.\n\nErrors: `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.", "parameters": [{"name": "todo", "in": "path", "required": true, "description": "A to-do id from GET /v1/todos.", "schema": {"type": "string", "pattern": "^t_[a-f0-9]{6,32}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["text"], "properties": {"text": {"type": "string"}, "date": {"type": "string"}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "required": ["ts", "text"], "properties": {"ts": {"type": "string"}, "text": {"type": "string"}, "external_id": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/reports/{period}/{date}": {"get": {"operationId": "get_report", "summary": "Get a weekly or monthly report", "tags": ["planning"], "description": "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.\n\n`{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.\n\nAn 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`.\n\nErrors: `400` for an invalid period or date; `409` `not_onboarded`.", "parameters": [{"name": "period", "in": "path", "required": true, "description": "week or month.", "schema": {"type": "string", "pattern": "^week|month$"}}, {"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["period", "ending", "readiness", "tracks", "archive"], "properties": {"period": {"type": "string", "enum": ["week", "month"]}, "ending": {"type": "string"}, "from": {"type": "string"}, "to": {"type": "string"}, "week": {"type": "integer", "description": "ISO week number of `ending`"}, "label": {"type": "string", "description": "what to call this period on a page \u2014 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"}, "span": {"type": ["string", "null"], "description": "the weeks a monthly period actually covers, to run under its name; null for a week"}, "issue": {"type": "object", "description": "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", "properties": {"no": {"type": "integer"}, "year": {"type": "integer"}}}, "written": {"type": "boolean", "description": "whether the prose has been generated yet"}, "readiness": {"type": "object", "required": ["ready", "on_record", "of"], "properties": {"ready": {"type": "boolean"}, "on_record": {"type": "integer"}, "of": {"type": "integer"}, "unit": {"type": "string"}, "ready_on": {"type": ["string", "null"], "description": "the date this issue can first be written, if the user keeps planning. A horizon, not a promise \u2014 but \"a pattern needs four weeks\" with no date on it reads as never (ADR-0064)"}}}, "kept_share": {"type": ["number", "null"], "description": "of what was ANSWERED, not of what was planned \u2014 null when nothing was answered, because silence is not nought per cent"}, "planned": {"type": "integer"}, "kept": {"type": "integer"}, "tracks": {"type": "array", "items": {"type": "object", "required": ["id", "label", "total", "done", "should"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "ink": {"type": ["integer", "null"], "description": "the ink this goal wears everywhere (ADR-0145)"}, "unit": {"type": "string"}, "total": {"type": "integer"}, "done": {"type": "integer", "description": "everything behind them"}, "added": {"type": "integer", "description": "what this period added"}, "should": {"type": "integer", "description": "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 (ADR-0083: it used to count only explicitly ticked milestones as behind you, so any goal past its first unticked milestone graded at the mark forever)"}, "floor": {"type": "integer", "description": "what stands whatever the current milestone's date does \u2014 the bar position where its window begins"}, "current_blocks": {"type": "integer", "description": "the current milestone's own size; with window_days, what a preview needs to re-run the pacing exactly"}, "window_days": {"type": "integer", "description": "how long the current milestone's own stretch of the goal runs"}, "state": {"type": "string", "enum": ["behind_plan", "behind_date", "not_due_yet", "kept"], "description": "the grade, decided here \u2014 the plan first, the date second (ADR-0083: \"at or past the mark\" graded one broken date sum and ignored the week's plan). `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"}, "plan_short": {"type": "integer", "minimum": 0, "description": "blocks short of the period's plan (prescribed - done), never negative"}, "date_short": {"type": "integer", "minimum": 0, "description": "blocks short of the date mark, whole-block floored, never negative"}, "date_fixed": {"type": "boolean", "description": "the current milestone's date is not the plan's to move \u2014 fixed_reason, an integration's, or adjudicated by somebody else (ADR-0083)"}, "behind": {"type": "integer", "minimum": 0, "description": "blocks short of the date mark \u2014 the bar's gap piece; same number as `date_short`"}, "days": {"type": ["integer", "null"]}, "status": {"type": ["string", "null"]}, "milestone": {"type": ["string", "null"]}, "milestone_due": {"type": ["string", "null"], "description": "the date the pace line answers to"}, "asked": {"type": "integer", "description": "blocks this period's plans prescribed for the goal"}, "prescribed": {"type": "integer", "description": "the PLAN line (ADR-0082): where the bar would sit had every block the period's plans prescribed landed"}, "pace": {"type": "number", "description": "the DATE line: the mark's exact position before the grade's whole-block floor \u2014 where you must be to make the current milestone on time"}}}}, "energy": {"type": "array", "description": "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 (ADR-0086)", "items": {"type": "object", "properties": {"day": {"type": "string"}, "date": {"type": "string"}, "value": {"type": ["integer", "null"], "minimum": 1, "maximum": 5, "description": "null when nobody said"}, "hard": {"type": "boolean", "description": "the plan was rebuilt after a gap"}, "planned": {"type": "integer"}, "kept": {"type": "integer"}}}}, "blocked": {"type": "object", "properties": {"planned": {"type": "integer"}, "split": {"type": "array", "items": {"type": "object"}}, "causes": {"type": "array", "description": "days that lost blocks, with what the user wrote on that day's check-in. Refusals only, and nobody's words but theirs", "items": {"type": "object"}}}}, "days": {"type": "array", "items": {"type": "object"}}, "parked": {"type": "array", "description": "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 (ADR-0059)", "items": {"type": "object", "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "until": {"type": ["string", "null"]}, "why": {"type": ["string", "null"]}}}}, "weekday_profile": {"type": "array", "description": "one entry per weekday: blocks on an average Monday, an average Tuesday, across the period", "items": {"type": "object", "properties": {"day": {"type": "string"}, "planned": {"type": "number", "description": "blocks planned into an average one of these"}, "kept": {"type": "number", "description": "and blocks kept \u2014 the page used to derive this from the share (ADR-0086)"}, "kept_share": {"type": ["number", "null"]}, "low_days": {"type": "integer"}, "days": {"type": "integer"}}}}, "goal_hours": {"type": "array", "items": {"type": "object"}}, "streaks": {"type": "array", "items": {"type": "object"}}, "energy_out": {"type": "array", "items": {"type": "object"}}, "archive": {"type": "array", "items": {"type": "object"}, "description": "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_months": {"type": "array", "items": {"type": "object"}, "description": "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_issue": {"type": ["object", "null"], "description": "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.", "properties": {"ending": {"type": "string"}, "date": {"type": "string"}, "time": {"type": "string"}}}, "latest": {"type": "object", "description": "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.", "properties": {"week": {"type": ["string", "null"]}, "month": {"type": ["string", "null"]}}}, "arrives": {"type": "object", "description": "present only while a period is unfinished: when it will be written", "properties": {"date": {"type": "string"}, "time": {"type": "string"}}}, "headline": {"type": "string"}, "findings": {"type": "array", "items": {"type": "object"}}, "proposal_intro": {"type": "string"}, "proposals": {"type": "array", "items": {"type": "object", "required": ["kind", "title"], "properties": {"kind": {"type": "string", "enum": ["Move a date", "Protect hours", "Do it now", "Drop a goal", "Schedule less"]}, "goal": {"type": "string"}, "goal_id": {"type": ["string", "null"]}, "title": {"type": "string"}, "why": {"type": "string"}, "effect": {"type": "string"}, "shift_days": {"type": "integer"}, "park_days": {"type": "integer", "description": "\"Drop a goal\" only: how long the goal is parked if agreed, in days, clamped to 14\u201356."}, "gain_blocks": {"type": "integer"}, "answer": {"type": ["string", "null"], "enum": ["yes", "argue", "no", null]}, "note": {"type": "string"}, "applied": {"type": "object"}, "preview": {"type": ["object", "null"], "description": "What agreeing would do, per kind, computed from the same `tracks` the report returns (ADR-0083). Only a \"Move a date\" preview carries mark positions (`should`, `done`, `total`, ...); for other kinds `line` describes the effect.", "properties": {"goal_id": {"type": ["string", "null"]}, "label": {"type": ["string", "null"]}, "effect_kind": {"type": ["string", "null"], "enum": ["move", "park", "free", "protect", "now", null]}, "line": {"type": ["string", "null"], "description": "The preview sentence, written server-side."}, "should": {"type": "number", "description": "Move only: the expected-by-now mark if agreed, unrounded.every realistic shift)"}, "should_now": {"type": "number", "description": "move only: the mark as it stands, exact"}, "done": {"type": "number"}, "done_now": {"type": "number"}, "total": {"type": "number"}, "new_due": {"type": ["string", "null"], "description": "move only: where the current milestone's date would land"}, "still_late": {"type": "boolean", "description": "move only: the shifted date is still behind you"}, "park_until": {"type": "string", "description": "park only"}, "park_weeks": {"type": "integer", "description": "park only"}, "freed": {"type": "integer", "description": "free only: blocks a week bought back"}}}}}}, "generated_at": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "post": {"operationId": "make_report", "summary": "Generate a report's prose and proposals", "tags": ["planning"], "description": "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.\n\nInvokes 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 (ADR-0062/0064). Answers already given to proposals with the same title are carried over.\n\nErrors: `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.", "parameters": [{"name": "period", "in": "path", "required": true, "description": "week or month.", "schema": {"type": "string", "pattern": "^week|month$"}}, {"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["period", "ending", "readiness", "tracks", "archive"], "properties": {"period": {"type": "string", "enum": ["week", "month"]}, "ending": {"type": "string"}, "from": {"type": "string"}, "to": {"type": "string"}, "week": {"type": "integer", "description": "ISO week number of `ending`"}, "label": {"type": "string", "description": "what to call this period on a page \u2014 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"}, "span": {"type": ["string", "null"], "description": "the weeks a monthly period actually covers, to run under its name; null for a week"}, "issue": {"type": "object", "description": "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", "properties": {"no": {"type": "integer"}, "year": {"type": "integer"}}}, "written": {"type": "boolean", "description": "whether the prose has been generated yet"}, "readiness": {"type": "object", "required": ["ready", "on_record", "of"], "properties": {"ready": {"type": "boolean"}, "on_record": {"type": "integer"}, "of": {"type": "integer"}, "unit": {"type": "string"}, "ready_on": {"type": ["string", "null"], "description": "the date this issue can first be written, if the user keeps planning. A horizon, not a promise \u2014 but \"a pattern needs four weeks\" with no date on it reads as never (ADR-0064)"}}}, "kept_share": {"type": ["number", "null"], "description": "of what was ANSWERED, not of what was planned \u2014 null when nothing was answered, because silence is not nought per cent"}, "planned": {"type": "integer"}, "kept": {"type": "integer"}, "tracks": {"type": "array", "items": {"type": "object", "required": ["id", "label", "total", "done", "should"], "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "ink": {"type": ["integer", "null"], "description": "the ink this goal wears everywhere (ADR-0145)"}, "unit": {"type": "string"}, "total": {"type": "integer"}, "done": {"type": "integer", "description": "everything behind them"}, "added": {"type": "integer", "description": "what this period added"}, "should": {"type": "integer", "description": "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 (ADR-0083: it used to count only explicitly ticked milestones as behind you, so any goal past its first unticked milestone graded at the mark forever)"}, "floor": {"type": "integer", "description": "what stands whatever the current milestone's date does \u2014 the bar position where its window begins"}, "current_blocks": {"type": "integer", "description": "the current milestone's own size; with window_days, what a preview needs to re-run the pacing exactly"}, "window_days": {"type": "integer", "description": "how long the current milestone's own stretch of the goal runs"}, "state": {"type": "string", "enum": ["behind_plan", "behind_date", "not_due_yet", "kept"], "description": "the grade, decided here \u2014 the plan first, the date second (ADR-0083: \"at or past the mark\" graded one broken date sum and ignored the week's plan). `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"}, "plan_short": {"type": "integer", "minimum": 0, "description": "blocks short of the period's plan (prescribed - done), never negative"}, "date_short": {"type": "integer", "minimum": 0, "description": "blocks short of the date mark, whole-block floored, never negative"}, "date_fixed": {"type": "boolean", "description": "the current milestone's date is not the plan's to move \u2014 fixed_reason, an integration's, or adjudicated by somebody else (ADR-0083)"}, "behind": {"type": "integer", "minimum": 0, "description": "blocks short of the date mark \u2014 the bar's gap piece; same number as `date_short`"}, "days": {"type": ["integer", "null"]}, "status": {"type": ["string", "null"]}, "milestone": {"type": ["string", "null"]}, "milestone_due": {"type": ["string", "null"], "description": "the date the pace line answers to"}, "asked": {"type": "integer", "description": "blocks this period's plans prescribed for the goal"}, "prescribed": {"type": "integer", "description": "the PLAN line (ADR-0082): where the bar would sit had every block the period's plans prescribed landed"}, "pace": {"type": "number", "description": "the DATE line: the mark's exact position before the grade's whole-block floor \u2014 where you must be to make the current milestone on time"}}}}, "energy": {"type": "array", "description": "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 (ADR-0086)", "items": {"type": "object", "properties": {"day": {"type": "string"}, "date": {"type": "string"}, "value": {"type": ["integer", "null"], "minimum": 1, "maximum": 5, "description": "null when nobody said"}, "hard": {"type": "boolean", "description": "the plan was rebuilt after a gap"}, "planned": {"type": "integer"}, "kept": {"type": "integer"}}}}, "blocked": {"type": "object", "properties": {"planned": {"type": "integer"}, "split": {"type": "array", "items": {"type": "object"}}, "causes": {"type": "array", "description": "days that lost blocks, with what the user wrote on that day's check-in. Refusals only, and nobody's words but theirs", "items": {"type": "object"}}}}, "days": {"type": "array", "items": {"type": "object"}}, "parked": {"type": "array", "description": "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 (ADR-0059)", "items": {"type": "object", "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "until": {"type": ["string", "null"]}, "why": {"type": ["string", "null"]}}}}, "weekday_profile": {"type": "array", "description": "one entry per weekday: blocks on an average Monday, an average Tuesday, across the period", "items": {"type": "object", "properties": {"day": {"type": "string"}, "planned": {"type": "number", "description": "blocks planned into an average one of these"}, "kept": {"type": "number", "description": "and blocks kept \u2014 the page used to derive this from the share (ADR-0086)"}, "kept_share": {"type": ["number", "null"]}, "low_days": {"type": "integer"}, "days": {"type": "integer"}}}}, "goal_hours": {"type": "array", "items": {"type": "object"}}, "streaks": {"type": "array", "items": {"type": "object"}}, "energy_out": {"type": "array", "items": {"type": "object"}}, "archive": {"type": "array", "items": {"type": "object"}, "description": "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_months": {"type": "array", "items": {"type": "object"}, "description": "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_issue": {"type": ["object", "null"], "description": "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.", "properties": {"ending": {"type": "string"}, "date": {"type": "string"}, "time": {"type": "string"}}}, "latest": {"type": "object", "description": "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.", "properties": {"week": {"type": ["string", "null"]}, "month": {"type": ["string", "null"]}}}, "arrives": {"type": "object", "description": "present only while a period is unfinished: when it will be written", "properties": {"date": {"type": "string"}, "time": {"type": "string"}}}, "headline": {"type": "string"}, "findings": {"type": "array", "items": {"type": "object"}}, "proposal_intro": {"type": "string"}, "proposals": {"type": "array", "items": {"type": "object", "required": ["kind", "title"], "properties": {"kind": {"type": "string", "enum": ["Move a date", "Protect hours", "Do it now", "Drop a goal", "Schedule less"]}, "goal": {"type": "string"}, "goal_id": {"type": ["string", "null"]}, "title": {"type": "string"}, "why": {"type": "string"}, "effect": {"type": "string"}, "shift_days": {"type": "integer"}, "park_days": {"type": "integer", "description": "\"Drop a goal\" only: how long the goal is parked if agreed, in days, clamped to 14\u201356."}, "gain_blocks": {"type": "integer"}, "answer": {"type": ["string", "null"], "enum": ["yes", "argue", "no", null]}, "note": {"type": "string"}, "applied": {"type": "object"}, "preview": {"type": ["object", "null"], "description": "What agreeing would do, per kind, computed from the same `tracks` the report returns (ADR-0083). Only a \"Move a date\" preview carries mark positions (`should`, `done`, `total`, ...); for other kinds `line` describes the effect.", "properties": {"goal_id": {"type": ["string", "null"]}, "label": {"type": ["string", "null"]}, "effect_kind": {"type": ["string", "null"], "enum": ["move", "park", "free", "protect", "now", null]}, "line": {"type": ["string", "null"], "description": "The preview sentence, written server-side."}, "should": {"type": "number", "description": "Move only: the expected-by-now mark if agreed, unrounded.every realistic shift)"}, "should_now": {"type": "number", "description": "move only: the mark as it stands, exact"}, "done": {"type": "number"}, "done_now": {"type": "number"}, "total": {"type": "number"}, "new_due": {"type": ["string", "null"], "description": "move only: where the current milestone's date would land"}, "still_late": {"type": "boolean", "description": "move only: the shifted date is still behind you"}, "park_until": {"type": "string", "description": "park only"}, "park_weeks": {"type": "integer", "description": "park only"}, "freed": {"type": "integer", "description": "free only: blocks a week bought back"}}}}}}, "generated_at": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/reports/{period}/{date}/seen": {"post": {"operationId": "report_seen", "summary": "Mark a report as read", "tags": ["planning"], "description": "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}`.\n\nIdempotent: 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.\n\nErrors: `400` for an invalid period or date; `409` `not_onboarded`.", "parameters": [{"name": "period", "in": "path", "required": true, "description": "week or month.", "schema": {"type": "string", "pattern": "^week|month$"}}, {"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"seen": {"type": "boolean"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/reports/{period}/{date}/proposals/{index}/discuss": {"post": {"operationId": "discuss_proposal", "summary": "Discuss a report proposal with the model", "tags": ["planning"], "description": "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).\n\nNothing 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 (ADR-0060).\n\nInvokes 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`.\n\nErrors: `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`.", "parameters": [{"name": "period", "in": "path", "required": true, "description": "week or month.", "schema": {"type": "string", "pattern": "^week|month$"}}, {"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}, {"name": "index", "in": "path", "required": true, "description": "Which proposal, counting from zero.", "schema": {"type": "string", "pattern": "^[0-9]{1,2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["messages"], "properties": {"messages": {"type": "array", "items": {"type": "object", "properties": {"who": {"type": "string"}, "text": {"type": "string"}}}}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["reply"], "properties": {"reply": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "403": {"description": "The account's email address is not confirmed (`email_unverified`), or a read-only token called a non-GET route (`read_only_token`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/reports/{period}/{date}/proposals/{index}": {"post": {"operationId": "answer_proposal", "summary": "Answer a report proposal", "tags": ["planning"], "description": "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.\n\n`answer: \"yes\"` applies the proposal by `kind`:\n\n- `Move a date` \u2014 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` \u2014 adds a standing rule (`kind: \"scheduling\"`) from the proposal's title, with clock times clamped to the user's day window. - `Schedule less` \u2014 adds a standing rule with `kind: \"gate\"`. - `Drop a goal` \u2014 parks the goal until `park_days` after the period's end. - `Do it now` \u2014 changes nothing.\n\n`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 (ADR-0060). Titles of proposals answered `no` or `argue` are given to the next report's prompt as not to be proposed again.\n\n`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.\n\nErrors: `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`.", "parameters": [{"name": "period", "in": "path", "required": true, "description": "week or month.", "schema": {"type": "string", "pattern": "^week|month$"}}, {"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}, {"name": "index", "in": "path", "required": true, "description": "Which proposal, counting from zero.", "schema": {"type": "string", "pattern": "^[0-9]{1,2}$"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["answer"], "properties": {"answer": {"type": "string", "enum": ["yes", "argue", "no"]}, "for_good": {"type": "boolean", "description": "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 (ADR-0060)."}, "note": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["proposal"], "properties": {"proposal": {"type": "object", "required": ["kind", "title"], "properties": {"kind": {"type": "string", "enum": ["Move a date", "Protect hours", "Do it now", "Drop a goal", "Schedule less"]}, "goal": {"type": "string"}, "goal_id": {"type": ["string", "null"]}, "title": {"type": "string"}, "why": {"type": "string"}, "effect": {"type": "string"}, "shift_days": {"type": "integer"}, "park_days": {"type": "integer", "description": "\"Drop a goal\" only: how long the goal is parked if agreed, in days, clamped to 14\u201356."}, "gain_blocks": {"type": "integer"}, "answer": {"type": ["string", "null"], "enum": ["yes", "argue", "no", null]}, "note": {"type": "string"}, "applied": {"type": "object"}, "preview": {"type": ["object", "null"], "description": "What agreeing would do, per kind, computed from the same `tracks` the report returns (ADR-0083). Only a \"Move a date\" preview carries mark positions (`should`, `done`, `total`, ...); for other kinds `line` describes the effect.", "properties": {"goal_id": {"type": ["string", "null"]}, "label": {"type": ["string", "null"]}, "effect_kind": {"type": ["string", "null"], "enum": ["move", "park", "free", "protect", "now", null]}, "line": {"type": ["string", "null"], "description": "The preview sentence, written server-side."}, "should": {"type": "number", "description": "Move only: the expected-by-now mark if agreed, unrounded.every realistic shift)"}, "should_now": {"type": "number", "description": "move only: the mark as it stands, exact"}, "done": {"type": "number"}, "done_now": {"type": "number"}, "total": {"type": "number"}, "new_due": {"type": ["string", "null"], "description": "move only: where the current milestone's date would land"}, "still_late": {"type": "boolean", "description": "move only: the shifted date is still behind you"}, "park_until": {"type": "string", "description": "park only"}, "park_weeks": {"type": "integer", "description": "park only"}, "freed": {"type": "integer", "description": "free only: blocks a week bought back"}}}}}, "applied": {"type": ["object", "null"]}, "refused": {"type": "boolean", "description": "whether this answer was recorded as a refusal for good"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/retro/{date}": {"get": {"operationId": "get_retro", "summary": "Get a weekly brief", "tags": ["retro"], "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "post": {"operationId": "make_retro", "summary": "Generate a weekly brief", "tags": ["retro"], "description": "Writes the weekly brief for the week ending `date` if none exists, and returns it.\n\nIf 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.\n\nOtherwise 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.\n\n`date` is used exactly as given and is not snapped to a cadence-week boundary.\n\nErrors: `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.", "parameters": [{"name": "date", "in": "path", "required": true, "description": "The day, YYYY-MM-DD.", "schema": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/calendar/auth/start": {"post": {"operationId": "calendar_auth_start", "summary": "Begin the Google Calendar connection", "tags": ["calendar"], "description": "Returns a Google consent URL to navigate to. PKCE, with an opaque single-use state binding the callback to this user. 503 if the deployment has no Google client configured.", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"purpose": {"type": "string", "enum": ["projects", "issues"], "description": "Which registration to use. `projects` is the OAuth App, asking for `read:project` \u2014 the user-owned board. `issues` is the GitHub App, whose Issues: Read-only permission is the only way to read a private repository's issues without granting write access to all the user's code. Neither can do the other's job, so both registrations exist. 503 `github_app_unconfigured` if no App is registered."}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["authorize_url", "state"], "properties": {"authorize_url": {"type": "string"}, "state": {"type": "string"}, "scope": {"type": ["string", "null"], "description": "null for the GitHub App: its permissions live on the app"}, "purpose": {"type": "string"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/calendar/oauth/callback": {"get": {"operationId": "calendar_callback", "summary": "Google's redirect target", "tags": ["calendar"], "description": "Unauthenticated by necessity \u2014 a browser redirect carries no bearer header, and the single-use `state` is what binds it to a user. Returns HTML, not JSON.", "parameters": [{"name": "state", "in": "query", "required": false, "description": "The opaque state issued by auth/start.", "schema": {"type": "string"}}, {"name": "code", "in": "query", "required": false, "description": "Google's authorization code.", "schema": {"type": "string"}}, {"name": "error", "in": "query", "required": false, "description": "Set if the user declined.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"text/html": {"schema": {"type": "string"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"text/html": {"schema": {"type": "string"}}}}}, "security": []}}, "/v1/calendar/tokens": {"post": {"operationId": "calendar_tokens", "summary": "Upload tokens from the CLI loopback flow", "tags": ["calendar"], "description": "The CLI's local consent flow posts its tokens here, because the scheduler needs them when the laptop is closed.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["access_token", "refresh_token"], "properties": {"access_token": {"type": "string"}, "refresh_token": {"type": "string"}, "expires_in": {"type": "integer"}, "scope": {"type": "string"}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"connected": {"type": "boolean"}, "expires_at": {"type": "string"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/calendar/status": {"get": {"operationId": "calendar_status", "summary": "Get Google Calendar connection status", "tags": ["calendar"], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["connected"], "properties": {"connected": {"type": "boolean"}, "oauth": {"type": "boolean", "description": "Whether this deployment has a Google OAuth client configured. When false the calendar cannot be connected on this server."}, "expires_at": {"type": ["string", "null"]}, "scope": {"type": ["string", "null"]}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/calendar": {"delete": {"operationId": "calendar_disconnect", "summary": "Disconnect Google Calendar", "tags": ["calendar"], "description": "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.\n\nIdempotent: returns `204` when no calendar is connected. Allowed on a lapsed subscription.", "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/todoist/status": {"get": {"operationId": "todoist_status", "summary": "Is Todoist connected", "tags": ["todoist"], "description": "`pending_writes` above zero means changes are queued because Todoist was unreachable \u2014 they are not lost.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["connected", "enabled", "oauth", "token_paste"], "properties": {"connected": {"type": "boolean"}, "enabled": {"type": "boolean", "description": "this deployment serves Todoist. False (the default, ADR-0193): every acting route is absent and the client draws it as coming soon"}, "oauth": {"type": "boolean", "description": "the one-click route exists on this deployment"}, "token_paste": {"type": "boolean", "description": "POST /v1/todoist/token is served. False where an OAuth app is registered: the route is absent, not merely discouraged (ADR-0095)"}, "project_id": {"type": ["string", "null"]}, "connected_at": {"type": ["string", "null"]}, "synced_at": {"type": ["string", "null"]}, "pending_writes": {"type": "integer"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/todoist/auth/start": {"post": {"operationId": "todoist_auth_start", "summary": "Begin the Todoist connection", "tags": ["todoist"], "description": "Returns a Todoist consent URL to navigate to. An opaque single-use state binds the callback to this user, and it is the whole of that binding: Todoist supports no PKCE. The scope asked for is `data:read_write`, because this is the one integration that writes \u2014 `data:delete` is deliberately not requested. 503 if no Todoist OAuth app is configured \u2014 and that is exactly when `POST /v1/todoist/token` is served instead, since a deployment with an app withholds the paste route (ADR-0095).", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["authorize_url", "state"], "properties": {"authorize_url": {"type": "string"}, "state": {"type": "string"}, "scope": {"type": "string"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/todoist/oauth/callback": {"get": {"operationId": "todoist_callback", "summary": "Todoist's redirect target", "tags": ["todoist"], "description": "Unauthenticated by necessity \u2014 a browser redirect carries no bearer header, and the single-use `state` is what binds it to a user. Returns HTML, not JSON. A read-only grant is refused rather than stored: it would fail on the first push and look like a Sereo bug. A decline arrives as `error` on this redirect rather than from the token endpoint.", "parameters": [{"name": "state", "in": "query", "required": false, "description": "The opaque state issued by auth/start.", "schema": {"type": "string"}}, {"name": "code", "in": "query", "required": false, "description": "Todoist's authorization code.", "schema": {"type": "string"}}, {"name": "error", "in": "query", "required": false, "description": "Set if the user declined.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"text/html": {"schema": {"type": "string"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"text/html": {"schema": {"type": "string"}}}}}, "security": []}}, "/v1/todoist/token": {"post": {"operationId": "todoist_connect", "summary": "Connect Todoist with a personal API token", "tags": ["todoist"], "description": "Once connected, Todoist owns completion: the to-do write routes refuse and Sereo follows what Todoist reports. The token is never echoed back or logged.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["token"], "properties": {"token": {"type": "string", "description": "a Todoist personal API token"}, "project_id": {"type": "string"}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "properties": {"connected": {"type": "boolean"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/todoist/sync": {"post": {"operationId": "todoist_sync_now", "summary": "Sync with Todoist now", "tags": ["todoist"], "description": "Drains queued writes, pulls what changed, applies it. The scheduler does this every 15 minutes; this forces it.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"source": {"type": "string"}, "sent": {"type": "integer"}, "applied": {"type": "integer"}, "pending": {"type": "integer"}, "days": {"type": "array"}, "synced_at": {"type": ["string", "null"]}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/todoist": {"delete": {"operationId": "todoist_disconnect", "summary": "Disconnect Todoist", "tags": ["todoist"], "description": "Forgets the token; the to-do to Todoist id map is kept and marked detached, because dropping it would orphan real tasks and duplicate them on reconnect.", "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/github/status": {"get": {"operationId": "github_status", "summary": "Is GitHub connected, and what is linked", "tags": ["github"], "description": "Several GitHub accounts may be connected at once \u2014 a personal and a work one are the common case \u2014 and a goal may draw from more than one source. Each link names the goal, the account, and whether the source is a Projects v2 board or a repository's issues.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["connected", "enabled", "accounts", "links"], "properties": {"connected": {"type": "boolean"}, "enabled": {"type": "boolean", "description": "this deployment serves GitHub at all. False means every other /v1/github route is absent, not merely unconfigured (ADR-0094)"}, "oauth": {"type": "boolean", "description": "this deployment has a GitHub OAuth app; a pasted token works without one"}, "app": {"type": "boolean", "description": "a GitHub App is registered, which is the read-only route to private-repo issues"}, "accounts": {"type": "array", "items": {"type": "object"}, "description": "each with `account` (the GitHub login), `purposes` (projects/issues), `scopes` and `connected_at`"}, "links": {"type": "array", "items": {"type": "object"}, "description": "each with `interest_id`, `account`, `kind` (board|repo) and `ref`"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/github/auth/start": {"post": {"operationId": "github_auth_start", "summary": "Begin the GitHub connection", "tags": ["github"], "description": "Returns a GitHub consent URL to navigate to. PKCE, with an opaque single-use state binding the callback to this user \u2014 the same shape as the Google Calendar flow, and the same endpoints for both registrations. No path here grants write access. 503 if the relevant registration is absent, in which case `POST /v1/github/token` still works with a pasted token.", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"purpose": {"type": "string", "enum": ["projects", "issues"], "description": "Which registration to use. `projects` is the OAuth App, asking for `read:project` \u2014 the user-owned board. `issues` is the GitHub App, whose Issues: Read-only permission is the only way to read a private repository's issues without granting write access to all the user's code. Neither can do the other's job, so both registrations exist. 503 `github_app_unconfigured` if no App is registered."}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["authorize_url", "state"], "properties": {"authorize_url": {"type": "string"}, "state": {"type": "string"}, "scope": {"type": ["string", "null"], "description": "null for the GitHub App: its permissions live on the app"}, "purpose": {"type": "string"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/github/oauth/callback": {"get": {"operationId": "github_callback", "summary": "GitHub's redirect target", "tags": ["github"], "description": "Unauthenticated by necessity \u2014 a browser redirect carries no bearer header, and the single-use `state` is what binds it to a user. Returns HTML, not JSON. A grant that came back without project access is refused rather than stored, since it would fail on the first board read and look like a Sereo bug.", "parameters": [{"name": "state", "in": "query", "required": false, "description": "The opaque state issued by auth/start.", "schema": {"type": "string"}}, {"name": "code", "in": "query", "required": false, "description": "GitHub's authorization code.", "schema": {"type": "string"}}, {"name": "error", "in": "query", "required": false, "description": "Set if the user declined.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"text/html": {"schema": {"type": "string"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"text/html": {"schema": {"type": "string"}}}}}, "security": []}}, "/v1/github/token": {"post": {"operationId": "github_connect", "summary": "Connect GitHub with a personal access token", "tags": ["github"], "description": "The manual alternative to the OAuth flow, for a deployment with no GitHub app registered. The token needs `read:project` (or `project`) \u2014 Projects v2 is not reachable any other way. It is checked against the API before being stored, so a token that cannot read a board fails here rather than silently at 3am in the scheduler. Never echoed back or logged.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["token"], "properties": {"token": {"type": "string"}, "purpose": {"type": "string", "enum": ["projects", "issues"], "description": "Default `projects`. GitHub has no single read-only credential covering both: user-owned Projects v2 are unreachable by fine-grained tokens, and read-only issues exist only on fine-grained ones. So least privilege is one token per purpose. A single token holding both scopes is used for either."}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "properties": {"connected": {"type": "boolean"}, "boards": {"type": "array"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/github/boards": {"get": {"operationId": "github_boards", "summary": "Boards an account can see", "tags": ["github"], "description": "Open Projects v2 boards for the authenticated GitHub user. Degrades to an empty list with a `source` of `unavailable` rather than failing the page.", "parameters": [{"name": "account", "in": "query", "required": false, "description": "Required when several accounts are connected.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["source"], "properties": {"source": {"type": "string"}, "boards": {"type": "array"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/github/boards/{board}/preview": {"get": {"operationId": "github_preview", "summary": "What a sync would produce", "tags": ["github"], "description": "Translates the board without writing anything. Linking is the moment you discover the dates are wrong, and discovering it by having the goal rewritten is the wrong way round. `skipped` names every item with no target date: those cannot become milestones, because inventing a date would fabricate a deadline the user never set.", "parameters": [{"name": "board", "in": "path", "required": true, "description": "A GitHub Projects v2 project number.", "schema": {"type": "string", "pattern": "^[0-9]{1,6}$"}}, {"name": "account", "in": "query", "required": false, "description": "Required when several accounts are connected.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"source": {"type": "string"}, "title": {"type": "string"}, "milestones": {"type": "array", "items": {"type": "object"}}, "completed": {"type": "array", "items": {"type": "object"}}, "skipped": {"type": "array", "items": {"type": "string"}}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "409": {"description": "Refused because of the account's current state; branch on `code`", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/interests/{interest}/github": {"post": {"operationId": "github_link", "summary": "Point a goal at a board", "tags": ["github"], "description": "Give either `board` or `repo`. Records the link only \u2014 call `POST /v1/github/sync` to pull. A goal may hold several links across several accounts; they are fetched together and applied once. Milestones the user wrote by hand are never replaced, so linking is additive.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9_]{1,64}$"}}], "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"board": {"type": "integer", "description": "a Projects v2 project number"}, "repo": {"type": "string", "description": "'owner/name'. Its milestones become milestones and their issues become tasks \u2014 the hierarchy a flat board cannot express. Needs the `repo` scope."}, "account": {"type": "string", "description": "required when several accounts are connected"}, "title": {"type": "string"}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object"}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "delete": {"operationId": "github_unlink", "summary": "Stop backing a goal with a source", "tags": ["github"], "description": "Drops one source, or every source for the goal when none is named. Milestones already pulled stay where they are; they are simply no longer refreshed.", "parameters": [{"name": "interest", "in": "path", "required": true, "description": "A goal, habit or chore id.", "schema": {"type": "string", "pattern": "^[a-z0-9_]{1,64}$"}}, {"name": "account", "in": "query", "required": false, "description": "Only this account's link.", "schema": {"type": "string"}}, {"name": "kind", "in": "query", "required": false, "description": "board or repo.", "schema": {"type": "string"}}, {"name": "ref", "in": "query", "required": false, "description": "Project number or owner/name.", "schema": {"type": "string"}}], "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/github/sync": {"post": {"operationId": "github_sync", "summary": "Pull the linked boards now", "tags": ["github"], "description": "Read-only against GitHub. Board items become milestones; `Done` moves them to completed. Anything the user typed themselves survives, and the task breakdown under a milestone is carried across by id \u2014 a board item is flat, so a naive refresh would delete it. A board that cannot be reached leaves the profile untouched.", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"interest": {"type": "string", "description": "one goal; omit for all"}, "replace_local": {"type": "boolean", "description": "Destructive. Makes the board the sole source for this goal, discarding milestones written by hand. Needed on the first sync if you were previously copying the board in yourself, since the safe merge leaves two of each."}}}}}}, "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["synced"], "properties": {"synced": {"type": "object"}, "applied": {"type": "integer"}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/github": {"delete": {"operationId": "github_disconnect", "summary": "Disconnect a GitHub account", "tags": ["github"], "description": "Forgets one account and its links, or all of them when none is named. Unlike Todoist there is nothing to orphan: Sereo never wrote to GitHub.", "parameters": [{"name": "account", "in": "query", "required": false, "description": "Only this account. Omit to disconnect all.", "schema": {"type": "string"}}], "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/devices": {"get": {"operationId": "list_devices", "summary": "The phones this account has registered for nudges", "tags": ["push"], "description": "Enabled devices only: one APNs has reported dead (410, or 400 BadDeviceToken) is disabled and drops out of this list until the app registers it again. 404 on a deployment that has not configured APNs \u2014 an unconfigured channel advertises nothing (ADR-0140).", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "required": ["devices"], "properties": {"devices": {"type": "array", "items": {"type": "object", "required": ["token", "platform", "environment", "created_at", "last_seen_at"], "properties": {"token": {"type": "string"}, "platform": {"type": "string", "enum": ["ios"]}, "environment": {"type": "string", "enum": ["sandbox", "production"]}, "created_at": {"type": "string"}, "last_seen_at": {"type": "string", "description": "when the app last registered it"}}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}, "post": {"operationId": "register_device", "summary": "Register this phone for nudges", "tags": ["push"], "description": "The opt-in (ADR-0140). Every nudge is one of four fixed sentences chosen by kind \u2014 never the plan's own words \u2014 so Apple learns that a user was nudged and nothing else. Registering a token again refreshes it, moves it to this account if it was on another, and re-enables one APNs had disabled. Session or `full` API token: the app authenticates with a `sat_` key (ADR-0099). 404 where APNs is not configured.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["token", "platform", "environment"], "properties": {"token": {"type": "string", "minLength": 64, "maxLength": 200, "description": "the APNs device token, hex"}, "platform": {"type": "string", "enum": ["ios"]}, "environment": {"type": "string", "enum": ["sandbox", "production"], "description": "which APNs the token was issued for; only tokens matching the deployment's SEREO_APNS_ENV are sent to"}}}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "required": ["token", "platform", "environment", "created_at", "last_seen_at"], "properties": {"token": {"type": "string"}, "platform": {"type": "string", "enum": ["ios"]}, "environment": {"type": "string", "enum": ["sandbox", "production"]}, "created_at": {"type": "string"}, "last_seen_at": {"type": "string", "description": "when the app last registered it"}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/devices/{device}": {"delete": {"operationId": "remove_device", "summary": "Stop nudging this phone", "tags": ["push"], "description": "Keyed on the account as well as the token, so one account cannot remove another's device; a token that is not this account's is a 404, as is an unconfigured deployment.", "parameters": [{"name": "device", "in": "path", "required": true, "description": "An APNs device token, as the hex the app registered it with.", "schema": {"type": "string", "pattern": "^[a-fA-F0-9]{64,200}$"}}], "responses": {"204": {"description": "No content"}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/v1/support": {"post": {"operationId": "send_support", "summary": "Write to the people who run this Sereo", "tags": ["auth"], "description": "A problem report or a question (ADR-0202). Mailed to the deployment's support mailbox with the account's address as Reply-To; nothing is stored. `context` is a short list of where the person was and what they were using \u2014 never goals, plans or conversations \u2014 and every value is clipped. 503 when the deployment has no support mailbox or the mail could not be sent, so a client can offer the address instead of saying a message arrived.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["message"], "properties": {"kind": {"type": "string", "enum": ["problem", "question"]}, "message": {"type": "string"}, "context": {"type": "object", "properties": {"view": {"type": "string"}, "path": {"type": "string"}, "build": {"type": "string"}, "agent": {"type": "string"}, "window": {"type": "string"}, "last_error": {"type": "string"}}}}}}}}, "responses": {"202": {"description": "Accepted; anything further is sent to the address itself", "content": {"application/json": {"schema": {"type": "object", "required": ["sent"], "properties": {"sent": {"type": "boolean"}, "reply_to": {"type": ["string", "null"]}}}}}}, "400": {"description": "The request was malformed; `code` says how", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "401": {"description": "Missing or invalid bearer token", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "402": {"description": "No active subscription (ADR-0144/0188): 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`)", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "429": {"description": "Too many attempts; wait and retry \u2014 `retry-after` says how long", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}, "503": {"description": "That integration is not configured on this deployment", "content": {"application/json": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": [{"bearerAuth": []}]}}, "/": {"get": {"operationId": "ui_index", "summary": "The web UI's static files", "tags": ["ui"], "description": "Served from an extension allowlist with the path resolved through realpath, so nothing outside the UI directory is reachable.", "responses": {"200": {"description": "OK", "content": {"text/html": {"schema": {"type": "string"}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"text/html": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/{page}": {"get": {"operationId": "ui_page", "summary": "The web UI, at one of its own addresses", "tags": ["ui"], "description": "`/home`, `/today`, `/week`, `/month`, `/goals` and `/reports`, each optionally followed by which one (`/week/2026-11-22`). Every one answers with the same page; the client reads the path (ADR-0200).", "parameters": [{"name": "page", "in": "path", "required": true, "description": "Which screen of the web UI.", "schema": {"type": "string", "pattern": "^home|today|week|month|goals|reports$"}}], "responses": {"200": {"description": "OK", "content": {"text/html": {"schema": {"type": "string"}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"text/html": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/{page}/{which}": {"get": {"operationId": "ui_page_of", "summary": "The web UI, at one of its own addresses", "tags": ["ui"], "description": "`/home`, `/today`, `/week`, `/month`, `/goals` and `/reports`, each optionally followed by which one (`/week/2026-11-22`). Every one answers with the same page; the client reads the path (ADR-0200).", "parameters": [{"name": "page", "in": "path", "required": true, "description": "Which screen of the web UI.", "schema": {"type": "string", "pattern": "^home|today|week|month|goals|reports$"}}, {"name": "which", "in": "path", "required": true, "description": "Which week, day, month or report the screen opens on.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9-]{1,40}$"}}], "responses": {"200": {"description": "OK", "content": {"text/html": {"schema": {"type": "string"}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"text/html": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}, "/ui/{path}": {"get": {"operationId": "ui_asset", "summary": "The web UI's static files", "tags": ["ui"], "description": "Served from an extension allowlist with the path resolved through realpath, so nothing outside the UI directory is reachable.", "parameters": [{"name": "path", "in": "path", "required": true, "description": "A file under the served UI directory.", "schema": {"type": "string", "pattern": "^[A-Za-z0-9._~/-]{0,255}$"}}], "responses": {"200": {"description": "OK", "content": {"text/html": {"schema": {"type": "string"}}}}, "404": {"description": "No such thing, or it belongs to another account", "content": {"text/html": {"schema": {"type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "request_id"], "properties": {"code": {"type": "string", "description": "machine-readable; branch on this, not on prose"}, "message": {"type": "string"}, "request_id": {"type": "string"}}}}}}}}}, "security": []}}}}