{ "components": { "responses": { "Error": { "content": { "application/json": { "examples": { "invalid_input": { "summary": "invalid_input", "value": { "error": { "code": "invalid_input", "message": "invalid op: task.title must be a string" } } }, "not_found": { "summary": "not_found", "value": { "error": { "code": "not_found", "message": "not found" } } }, "unauthorized": { "summary": "unauthorized", "value": { "error": { "code": "unauthorized", "message": "authentication required" } } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "An error, in the JSON error envelope." }, "Unauthorized": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "authentication required" } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No valid session or token (`unauthorized`)." } }, "schemas": { "Due": { "description": "When a task is due: floating (the viewer's day) unless `tz` is set.", "properties": { "date": { "description": "YYYY-MM-DD.", "format": "date", "type": "string" }, "time": { "description": "Optional wall-clock time, HH:MM.", "pattern": "^\\d{2}:\\d{2}$", "type": "string" }, "tz": { "description": "Optional IANA time zone, only with `time`: the due is then the instant `date time` in that zone.", "type": "string" } }, "required": [ "date" ], "type": "object" }, "Error": { "description": "Every error answer: a stable machine-readable code and an English message (docs/api.md, top).", "properties": { "error": { "properties": { "code": { "description": "A stable error code. New codes may be added in 1.x; treat an unknown one by its HTTP status.", "examples": [ "account_active", "account_deactivated", "account_locked", "already_member", "already_undone", "already_uploaded", "assistant_busy", "assistant_disabled", "assistant_quota", "attachment_mismatch", "attachment_too_large", "attachments_disabled", "attachments_unavailable", "automations_off", "bad_origin", "bad_request", "base_url_mismatch", "base_url_required", "body_changed", "busy", "calendar_sync_disabled", "calendar_unreachable", "channels_disabled", "confirmation_mismatch", "conflict", "connection_disabled", "connection_stopped", "consent_required", "default_workspace", "demo_busy", "demo_expired", "demo_limit", "demo_restricted", "demo_token", "destination_error", "email_disabled", "email_failed", "email_taken", "encrypted", "encryption_conflict", "encryption_disabled", "encryption_enabled", "fallback", "feeds_disabled", "forbidden", "google_not_configured", "group_exists", "host_managed", "idempotency_conflict", "identity_taken", "images_unsupported", "insufficient_scope", "insufficient_storage", "integrity", "internal", "invalid_aisle", "invalid_credentials", "invalid_energy", "invalid_file", "invalid_grant", "invalid_input", "invalid_op", "invalid_redirect_uri", "invalid_request", "invalid_rotation", "invalid_scope", "invalid_token", "invitation_email_mismatch", "invitation_invalid", "invitation_spent", "invitation_stale", "issues_disabled", "last_credential", "limit_members", "limit_reached", "link_invalid", "managed_by_env", "managed_by_environment", "maps_disabled", "maps_unavailable", "mcp_disabled", "method_not_allowed", "mfa_already_enrolled", "mfa_challenge_invalid", "mfa_code_invalid", "mfa_enrolment_required", "mfa_not_enrolled", "mfa_required_by_policy", "microsoft_not_configured", "newer_schema", "no_calendars", "no_key", "not_a_member", "not_acceptable", "not_an_occurrence", "not_deleted", "not_encrypted", "not_found", "not_in_workspace", "not_opted_in", "not_recurring", "note_required", "oidc_disabled", "oidc_email_unverified", "oidc_failed", "oidc_link_required", "oidc_state_invalid", "other_workspace", "owner_must_transfer", "page_invalid", "page_not_encrypted", "passkey_challenge_invalid", "passkeys_unavailable", "passphrase_invalid", "passphrase_required", "paused", "plaintext", "private_target", "project_id_conflict", "project_invite_not_allowed", "proposal_closed", "provider_changed", "provider_rate_limited", "quota_exceeded", "rate_limited", "reauth_required", "reset_invalid", "routine_changed", "run_closed", "scope_change", "self_action", "session_only", "session_required", "set_by_environment", "setup_code_invalid", "setup_token_invalid", "signup_closed", "smtp_disabled", "sso_required", "stt_not_configured", "stt_unavailable", "task_required", "token_restricted", "too_large", "too_many_appends", "too_many_objectives", "turn_in_progress", "unauthorized", "unauthorized_remote", "unhealthy", "unknown_skill", "unsupported_format", "unsupported_protocol_version", "upstream_failed", "user_not_found", "verification_invalid", "workspace_gone", "workspace_not_empty", "write_limit" ], "type": "string" }, "message": { "description": "A human-readable English message; do not parse it.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "Field": { "description": "field: a custom field definition of one project (OpenSpec change custom-fields, design D1). Like a section it lives in its project's sharing scope and project_id never changes after creation; type is fixed too (the REST API refuses a change). type is text|number|date|choice|link|checkbox, carried as a string so a later type is additive; options holds a choice field's options, one per line. Values live on the task as `fields.\u003cid\u003e`.", "properties": { "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "id": { "description": "The field's id.", "type": "string" }, "name": { "type": "string" }, "options": { "type": "string" }, "position": { "type": "number" }, "project_id": { "description": "An id: a UUID, or for some entities a name-based id.", "type": "string" }, "type": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "Label": { "description": "task.labels holds label ids (a convention on the string array, not a format change).", "properties": { "color": { "type": "string" }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "group_by": { "description": "Display options of the label's page (OpenSpec change list-display-options, design D1): grouping, order and direction, enumerations carried as strings like a view's; \"\" or an unknown value reads as the default. Labels are personal, so the choice follows the user to their own devices only.", "type": "string" }, "id": { "description": "The label's id.", "type": "string" }, "manual_order": { "description": "The label page's own manual order (OpenSpec change view-manual-order, design D1, D2): the ids of the tasks placed by hand, in order; tasks not listed follow by position. One whole-list register like view.panels, never a task's position. Not content.", "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" }, "position": { "type": "number" }, "row_layout": { "description": "The label page's row layout (row-layouts D1); \"\" follows the account's.", "type": "string" }, "sort_by": { "type": "string" }, "sort_dir": { "type": "string" }, "workspace_id": { "description": "Workspace of the label, null for the default (OpenSpec change workspaces).", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": "object" }, "Location": { "properties": { "address": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "name": { "type": "string" }, "place_id": { "type": "string" } }, "type": "object" }, "Note": { "description": "note: a standalone note (OpenSpec change notes-overview, design D1), not a task: it never shows in task lists, counts, calendars, filters or reminders. It lives in its project's sharing scope like a task, in the author's personal scope without a project (design D2). Its pending appends are the `appends.\u003cid\u003e` family.", "properties": { "created_at": { "type": "number" }, "day": { "description": "A daily note's day, YYYY-MM-DD (daily-notes D1); \"\" for any other note. Set once at creation, only on the note whose id is the name-based id of its author and that day (NameID(\"daily-note\", user + \":\" + day)), so the same day is one note on every device.", "type": "string" }, "deleted_at": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "id": { "description": "The note's id.", "type": "string" }, "labels": { "description": "Label ids, one whole-list register like task.labels.", "items": { "type": "string" }, "type": "array" }, "notes_doc": { "description": "The note itself: Markdown in description, the mergeable document in notes_doc, written as a pair, as on tasks and projects.", "type": "string" }, "position": { "description": "Written at creation (the creation time) and kept for a later manual order; the Notes page sorts by when the note last changed.", "type": "number" }, "project_id": { "description": "The note's project, or null for a personal note; decides its scope.", "type": [ "string", "null" ] }, "template": { "description": "A template (note-templates D1): the note is offered under From template… and New note copies it; otherwise a note like any other.", "type": "boolean" }, "title": { "description": "The note's title; an empty one reads \"Untitled note\".", "type": "string" }, "workspace_id": { "description": "The workspace of a note without a project, or null for the default; a note with a project follows its project, as task.workspace_id.", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": "object" }, "Objective": { "description": "objective: one quarterly or weekly objective (OpenSpec change plan-objectives, design D1). Personal like place: it resolves to the author's personal scope, syncs to that user's devices only and derives no activity event. At most 5 open objectives per period: REST refuses a sixth, sync cannot refuse convergently and devices show all of them.", "properties": { "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "done_at": { "description": "When it was marked done, Unix ms; 0 = open.", "type": "number" }, "id": { "description": "The objective's id.", "type": "string" }, "period": { "description": "The quarter \"YYYY-Qn\" or ISO week \"YYYY-Www\" it is for; never a month.", "type": "string" }, "position": { "description": "Order within its period.", "type": "number" }, "title": { "description": "The objective, one line of 1 to 140 characters (ciphertext for an encrypted account).", "type": "string" } }, "required": [ "id" ], "type": "object" }, "Origin": { "description": "Where a task came from (docs/api.md \"Task fields\").", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "provider": { "type": "string" }, "title": { "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "kind" ], "type": "object" }, "Project": { "properties": { "aisles": { "type": "boolean" }, "archived": { "type": "boolean" }, "color": { "type": "string" }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "description": { "description": "The project's note (OpenSpec change project-notes): Markdown in description, the mergeable document in notes_doc, as on tasks.", "type": "string" }, "flow_mode": { "description": "How the project's tasks flow (OpenSpec change project-flow-modes): \"parallel\", \"sequential\" or \"area\"; empty, missing or unknown reads as parallel. Sync checks the kind only, so a later value stays additive; REST and the agent tools check the set. Not user text.", "type": "string" }, "icon": { "description": "An icon name from the app's set, or null for the colour dot (OpenSpec change ux-overhaul, project-organization \"Project icon\"). Not user text, so it is not an encrypted content field.", "type": [ "string", "null" ] }, "id": { "description": "The project's id.", "type": "string" }, "name": { "type": "string" }, "notes_doc": { "description": "A mergeable notes document (\"ydoc:v1:…\"), see docs/sync.md \"Mergeable documents\". Write `description` (Markdown) instead unless you merge documents yourself.", "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "position": { "type": "number" }, "reusable": { "description": "The reusable-list mode (OpenSpec change reusable-lists, design D1): adding an item already in the project reopens it instead of duplicating it, and ticked items always show. aisles sorts new items into aisle sections and reads as false while reusable is false. Flags, not user text, so not content; additive.", "type": "boolean" }, "status": { "description": "The project's status (OpenSpec change project-review-cadence, design D1): \"active\" or \"maintenance\"; empty, missing or unknown reads as active. Shared with the project's members and written by those who may change its other fields. Maintenance mutes the health words, the stalled marker and \"without a next action\"; a passed deadline still shows. Sync checks the kind only; REST and the agent tools check the set. Not user text.", "type": "string" }, "workspace_id": { "description": "The workspace the project belongs to, or null for the owner's default workspace (OpenSpec change workspaces, design D2). A partition key, not user text, so it is not an encrypted content field; on a shared project only the owner may write it (CanWrite).", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": "object" }, "Reminder": { "description": "reminder: fires relative to its task's due time or at an absolute instant (OpenSpec change reminders, docs/sync.md). fire_at is always the resolved instant, recomputed by the device that changes the task's due; the server scheduler only compares it with the clock. delivered_at is written by the server (device \"server\") when a push went out.", "properties": { "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "delivered_at": { "type": [ "number", "null" ] }, "dismissed_at": { "type": [ "number", "null" ] }, "fire_at": { "description": "A point in time in Unix milliseconds.", "type": [ "integer", "null" ] }, "id": { "description": "The reminder's id.", "type": "string" }, "kind": { "enum": [ "relative", "absolute", "deadline", "arrive", "leave" ], "type": "string" }, "offset_minutes": { "description": "Minutes relative to the due time (negative: before).", "type": [ "integer", "null" ] }, "radius_m": { "description": "A location reminder's radius in metres, 100 to 5,000 (OpenSpec change location-reminders, design D1): set only on the kinds \"arrive\" and \"leave\", which fire on a phone that enters or leaves the circle around the task's location and never have a fire_at or an offset (reminder_check.go refuses the mixes). Not content: the place is in the task's encrypted location.", "type": [ "number", "null" ] }, "task_id": { "description": "An id: a UUID, or for some entities a name-based id.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "Section": { "description": "section: a named, ordered container inside one project (OpenSpec change board-view). It lives in the sharing scope of its project like a task does; project_id never changes after creation (Apply refuses a scope change, the REST API refuses any change).", "properties": { "aisle": { "description": "The aisle an aisle section stands for in a reusable list (OpenSpec change reusable-lists, design D1): produce, bakery, dairy, meat, frozen, pantry, drinks, household or personal, or null. A fixed key, not user text, so it survives a rename and reads the same in every language; clients read an unknown key as null, and the REST API refuses it (invalid_aisle). Sync checks the kind only. Additive.", "type": [ "string", "null" ] }, "color": { "description": "A palette colour (#rrggbb) and a name from the icon catalogue, or null (OpenSpec change icons-and-section-style, design D4–D5). Not user text, so neither is an encrypted content field. Sync checks the kind only: a newer client may write an icon this server does not know yet.", "type": [ "string", "null" ] }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "flow_mode": { "description": "How the section's tasks flow (OpenSpec change project-flow-modes): \"parallel\" or \"sequential\"; empty, missing or unknown follows the project. Sync checks the kind only. Not user text.", "type": "string" }, "icon": { "type": [ "string", "null" ] }, "id": { "description": "The section's id.", "type": "string" }, "name": { "type": "string" }, "position": { "type": "number" }, "project_id": { "description": "An id: a UUID, or for some entities a name-based id.", "type": "string" } }, "required": [ "id" ], "type": "object" }, "SplitFrom": { "properties": { "date": { "format": "date", "type": "string" }, "series": { "type": "string" } }, "required": [ "series", "date" ], "type": "object" }, "Task": { "properties": { "assignee_id": { "description": "Account id of the assignee or null (OpenSpec change task-assignment); additive. Apply checks it against the task scope's membership at receipt.", "type": [ "string", "null" ] }, "blocked_by": { "description": "The tasks this one waits for, in its own sharing scope (OpenSpec change task-dependencies): one whole-list register; the resolver refuses ids of other scopes and lists that close a cycle.", "items": { "type": "string" }, "type": "array" }, "completed_at": { "type": [ "number", "null" ] }, "completed_by": { "description": "Account id of whoever completed the task, or null (OpenSpec change completed-date-filters, design D5); additive. Written beside completed_at; ApplyStrict fills it in for server-side completions.", "type": [ "string", "null" ] }, "created_at": { "type": "number" }, "day_part": { "description": "The part of the day besides Evening (OpenSpec change day-parts, design D1): null, \"morning\" or \"afternoon\". Evening stays the evening flag; clients write both fields in one batch (D2), and a task with the flag set reads as Evening whatever this holds. Not content; additive.", "type": [ "string", "null" ] }, "deadline": { "description": "The day the task must be finished by, separate from the planned due date (OpenSpec change deadlines); additive.", "format": "date", "type": [ "string", "null" ] }, "deleted_at": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "due": { "anyOf": [ { "$ref": "#/components/schemas/Due" }, { "type": "null" } ] }, "energy": { "description": "The energy the task asks for (OpenSpec change task-energy, design D1): \"\" (none), \"deep\", \"medium\" or \"low\". Chosen from a menu, never written text, so not content (D2); additive.", "type": [ "string", "null" ] }, "estimate_minutes": { "description": "Duration estimate in minutes (OpenSpec change nlp-quick-add); additive.", "minimum": 1, "type": [ "integer", "null" ] }, "evening": { "type": "boolean" }, "flow_mode": { "description": "How the task's own subtasks flow (OpenSpec change subtask-flow, GitHub issue 1046): \"sequential\" offers its open subtasks one at a time in list order; empty, \"parallel\", missing or unknown read as parallel, as on a project. Sync checks the kind only, so a later value stays additive; a client that does not know it shows every subtask as available. Not user text, so not content.", "type": "string" }, "habit": { "description": "Habit tracking (habits D1): habit flags a series as a habit; skipped marks a record written by a skip. Additive booleans, not content.", "type": "boolean" }, "habit_amount": { "description": "habit-targets D2: the day's goal (0 none), the check button's step and the unit (content); the day's amount sums its habit_tally rows.", "type": "number" }, "habit_anchor": { "type": "string" }, "habit_color": { "description": "The habit's own colour (OpenSpec change habits-polish, design D5): a palette hex such as \"#22c55e\", or \"\" for automatic (the project's colour, else one picked from the id). Not content, like project colours; additive.", "type": "string" }, "habit_graduated_at": { "description": "When the habit was graduated (habits-home D7), Unix ms, or null: a graduated habit is in no list, projection, reminder or Today limit and keeps its records; Resume continues it as a new piece of its lineage. Not content; additive.", "type": [ "number", "null" ] }, "habit_period": { "type": "string" }, "habit_step": { "type": "number" }, "habit_target": { "description": "habit-targets D1: check-ins a period needs (0 none, at most 31) and the period (\"\", \"week\", \"month\"). Not content.", "type": "number" }, "habit_tiny": { "description": "The habit's tiny version and anchor (OpenSpec change habits-home, design D5): the two-minute version that still counts (\"One page\") and the moment it follows (\"After dinner\"). User-written text, so content; additive. Records copy them with the series' other fields, harmlessly.", "type": "string" }, "habit_unit": { "type": "string" }, "ical_extra": { "description": "Unmapped iCalendar content lines of the task's VTODO (OpenSpec change caldav, design D3): opaque text, stored and synced, never shown.", "type": [ "string", "null" ] }, "id": { "description": "The task's id.", "type": "string" }, "labels": { "items": { "type": "string" }, "type": "array" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/Location" }, { "description": "Ciphertext on an end-to-end encrypted account.", "type": "string" }, { "type": "null" } ], "description": "Where the task happens (OpenSpec change task-locations): one whole-value register like origin, so concurrent locations never mix; additive." }, "note_mentions": { "description": "The members an @mention in the notes names (OpenSpec change editor-everywhere, design D7): written with notes_doc, filtered to current members of the task's shared project at receipt, plaintext.", "items": { "type": "string" }, "type": "array" }, "notes_doc": { "description": "The note as a mergeable rich-text document (OpenSpec change collaborative-rich-text); additive. description stays its Markdown projection, written by clients in the same batch. Opaque here.", "type": "string" }, "occurrence_date": { "description": "The occurrence date an occurrence record stands for (OpenSpec change series-exceptions, design D1; iCalendar RECURRENCE-ID), kept when the record is moved. Written once with series_id; the resolver refuses it on a task without series_id and refuses a change once set. A date, not content; additive (a record without it stands for its due date).", "format": "date", "type": [ "string", "null" ] }, "origin": { "anyOf": [ { "$ref": "#/components/schemas/Origin" }, { "description": "Ciphertext on an end-to-end encrypted account.", "type": "string" }, { "type": "null" } ], "description": "Where the task came from (OpenSpec change task-origin): one whole-value register like due, so concurrent origins never mix; additive." }, "parent_id": { "type": [ "string", "null" ] }, "position": { "type": "number" }, "priority": { "description": "1 is the highest, 4 the default.", "enum": [ 1, 2, 3, 4 ], "type": "integer" }, "project_id": { "type": [ "string", "null" ] }, "recurrence": { "description": "Recurrence rule and the series an occurrence record belongs to (OpenSpec change recurring-tasks); additive. See docs/recurrence.md.", "type": [ "string", "null" ] }, "rotation": { "description": "Who takes turns on a recurring task, in order (OpenSpec change chore-rotation; see rotation.go): plaintext member ids like assignee_id, not content; inert without a rule or a second member.", "items": { "type": "string" }, "type": "array" }, "sample": { "description": "A start guide sample task (moments-and-onboarding D3): excluded from Statistics, the Loop pulse and the digest. Not content; additive.", "type": "boolean" }, "section_id": { "description": "Section of the task's project or null (OpenSpec change board-view); additive. A reference to a deleted, foreign or unknown section is a display rule on clients (\"No section\"), never rejected on the sync path.", "type": [ "string", "null" ] }, "sector": { "description": "The period the task is planned for without a date (OpenSpec change time-sectors, design D1): \"\" (none), an ISO week \"2026-W44\", a month \"2026-11\" or a quarter \"2026-Q4\". A sector with no do-on date schedules the task (it leaves the Inbox and Anytime) and is never overdue; clients name it relative to the viewer's date and derive carry-over, never writing it. A scheduling field like start: plaintext, not content; additive.", "type": [ "string", "null" ] }, "series_id": { "type": [ "string", "null" ] }, "skipped": { "type": "boolean" }, "span": { "description": "Draw the task as a span from its start date to its do-on date (OpenSpec change multi-day-tasks, design D1). Only drawing changes: start keeps deferring and due stays the do-on date, and a flag without a valid range (a date start before due.date) draws as a plain task. Not content; additive.", "type": "boolean" }, "split_from": { "anyOf": [ { "$ref": "#/components/schemas/SplitFrom" }, { "type": "null" } ], "description": "The series a piece of a split lineage continues and the date it starts (OpenSpec change series-split, design D2): {series, date}, one whole value. Set when the piece is created; the resolver refuses it on a task without a rule, with a series in another sharing scope, and as a change once set. Not content; additive (an older client sees an ordinary series)." }, "start": { "description": "When the task becomes relevant: a start date that defers it, or \"someday\" (parked); and the This Evening flag (OpenSpec change someday-and-evening); additive.", "format": "date", "type": [ "string", "null" ] }, "tiny": { "description": "An occurrence record logged as the habit's tiny version (habits-home D5): set in the completion batch, never copied from the series; a full completion writes false. Not content; additive.", "type": "boolean" }, "title": { "type": "string" }, "workspace_id": { "description": "The workspace of a task without a project, or null for the default (OpenSpec change workspaces, design D2); a task with a project follows its project and this value is ignored there.", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": "object" }, "View": { "description": "view: a saved filter query with presentation options (OpenSpec `custom-views`). kind, group_by, sort_by and sort_dir are enumerations carried as plain strings so a future option value stays additive: clients map unknown values to defaults at read time and only the REST API rejects them. panels holds view ids (dashboards).", "properties": { "card_notes": { "description": "The Board layout's notes preview (OpenSpec change board-polish, design D4): each card shows two lines of its notes as plain text. A setting, not user text, so not content; missing reads as off.", "type": "boolean" }, "color": { "type": "string" }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "group_by": { "type": "string" }, "hidden_props": { "items": { "type": "string" }, "type": "array" }, "icon": { "description": "A name from the icon catalogue, or null for the default icon of the view's kind (OpenSpec change sidebar-polish, design D4). Not user text, so not content. Any string is accepted here so a newer catalogue stays additive; REST checks it with iconset.Valid and clients render an unknown name as the default icon.", "type": [ "string", "null" ] }, "id": { "description": "The view's id.", "type": "string" }, "kind": { "type": "string" }, "layout": { "description": "Display options of a list view (OpenSpec change views-and-display): the layout (an enumeration carried as a string), whether completed matches are listed, and the row properties the view hides.", "type": "string" }, "manual_order": { "description": "A list view's own manual order (OpenSpec change view-manual-order, design D1, D2): the ids of the tasks placed by hand, in order; tasks not listed follow by position. One whole-list register. Not content.", "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" }, "on_drop": { "description": "A section's on-drop rule (docs/sync.md)." }, "panels": { "items": { "type": "string" }, "type": "array" }, "pinned": { "type": "boolean" }, "position": { "type": "number" }, "query": { "type": "string" }, "row_layout": { "description": "The view's row layout (row-layouts D1): \"line\" or \"detailed\"; \"\" follows the account's choice (user_prefs.row_layout).", "type": "string" }, "show_completed": { "type": "boolean" }, "sort_by": { "type": "string" }, "sort_dir": { "type": "string" }, "subtasks": { "description": "Nest subtasks in the List layout (GitHub issue 1108): \"nested\" shows a match under its parent when both match, as Today's option does; \"\" or any other value is the flat list.", "type": "string" }, "workspace_id": { "description": "Workspace of the view, null for the default (OpenSpec change workspaces).", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": "object" } }, "securitySchemes": { "bearer": { "bearerFormat": "ot_…", "description": "An API token. Scopes: full, read (refused on writes and sync), agent (writes only through the agent routes), admin, app (docs/api.md \"Token scopes\").", "scheme": "bearer", "type": "http" }, "session": { "description": "The browser session of the web app.", "in": "cookie", "name": "opentodo_session", "type": "apiKey" } } }, "externalDocs": { "description": "HTTP API guide", "url": "https://open-todo.app/docs/api/" }, "info": { "contact": { "name": "OpenTodo", "url": "https://github.com/OpenTodoApp/OpenTodo" }, "description": "Every OpenTodo server serves this API under `/api/v1/` and this description at `/api/v1/openapi.json`. Authenticate with an API token (`Authorization: Bearer ot_…`, created in Settings → Integrations → API tokens) or a session cookie. Within 1.x the API only grows (docs/stability.md): ignore fields you do not know. Dates are floating `YYYY-MM-DD`, timestamps Unix milliseconds, priority 1 is the highest and 4 the default. This file is generated from the server's code; the guide with examples is https://open-todo.app/docs/api/.", "license": { "identifier": "AGPL-3.0-only", "name": "AGPL-3.0" }, "summary": "The HTTP API of an OpenTodo server: tasks, projects, notes, sync and administration.", "title": "OpenTodo REST API", "version": "0.0.0-dev" }, "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "openapi": "3.1.1", "paths": { "/api/v1/activity": { "get": { "description": "the activity feed across every shared project you are a member of; `?cursor=\u0026limit=\u0026project=\u0026actor=\u0026kind=`; see [Activity feed](https://open-todo.app/docs/api/#activity-feed)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getActivity", "responses": { "200": { "content": { "application/json": { "example": { "cursor": "example", "events": [ { "actor": "example", "actorName": "Ada", "changes": [ { "field": "example", "from": "example", "to": "example" } ], "device": "example", "entity": "example", "entityId": "00000000-0000-4000-8000-000000000001", "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "opIds": [ "00000000-0000-4000-8000-000000000001" ], "projectId": "00000000-0000-4000-8000-000000000001", "projectName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence", "ts": 1794906000000 } ], "more": false }, "schema": { "properties": { "cursor": { "type": "string" }, "events": { "items": { "properties": { "actor": { "type": "string" }, "actorName": { "type": "string" }, "changes": { "items": { "properties": { "field": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "device": { "type": "string" }, "entity": { "type": "string" }, "entityId": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "opIds": { "items": { "type": "string" }, "type": "array" }, "projectId": { "type": "string" }, "projectName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" }, "ts": { "type": "number" } }, "type": "object" }, "type": "array" }, "more": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get activity", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/app-passwords": { "get": { "description": "`{appPasswords:[…]}`, see [CalDAV and app passwords](https://open-todo.app/docs/api/#caldav-and-app-passwords)", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "getAppPasswords", "responses": { "200": { "content": { "application/json": { "example": { "appPasswords": [ { "createdAt": 1794906000000, "events": false, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "name": "Ada", "revokedAt": 1794906000000, "scope": { "inboxes": [ "example" ], "mode": "example", "projects": [ "example" ], "workspaces": [ "example" ] } } ] }, "schema": { "properties": { "appPasswords": { "items": { "properties": { "createdAt": { "type": "number" }, "events": { "type": "boolean" }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "revokedAt": { "type": [ "number", "null" ] }, "scope": { "properties": { "inboxes": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "projects": { "items": { "type": "string" }, "type": "array" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List app passwords", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{name, scope?}` → 201 `{appPassword, secret}` (secret shown once)\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "postAppPasswords", "requestBody": { "content": { "application/json": { "example": { "events": false, "name": "Ada", "scope": { "inboxes": [ "example" ], "mode": "example", "projects": [ "example" ], "workspaces": [ "example" ] } }, "schema": { "properties": { "events": { "type": "boolean" }, "name": { "type": "string" }, "scope": { "properties": { "inboxes": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "projects": { "items": { "type": "string" }, "type": "array" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "required": [ "inboxes", "mode", "projects", "workspaces" ], "type": [ "object", "null" ] } }, "required": [ "events", "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "appPassword": { "createdAt": 1794906000000, "events": false, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "name": "Ada", "revokedAt": 1794906000000, "scope": { "inboxes": [ "example" ], "mode": "example", "projects": [ "example" ], "workspaces": [ "example" ] } }, "secret": "example-secret" }, "schema": { "properties": { "appPassword": { "properties": { "createdAt": { "type": "number" }, "events": { "type": "boolean" }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "revokedAt": { "type": [ "number", "null" ] }, "scope": { "properties": { "inboxes": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "projects": { "items": { "type": "string" }, "type": "array" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } }, "type": [ "object", "null" ] }, "secret": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a app password", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in.credential.recent" } }, "/api/v1/app-passwords/{id}": { "delete": { "description": "revoke → 204", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "deleteAppPasswordsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a app password", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`{scope}` → `{appPassword}`\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "patchAppPasswordsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "scope": { "inboxes": [ "example" ], "mode": "example", "projects": [ "example" ], "workspaces": [ "example" ] } }, "schema": { "properties": { "scope": { "properties": { "inboxes": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "projects": { "items": { "type": "string" }, "type": "array" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "required": [ "inboxes", "mode", "projects", "workspaces" ], "type": [ "object", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "appPassword": { "createdAt": 1794906000000, "events": false, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "name": "Ada", "revokedAt": 1794906000000, "scope": { "inboxes": [ "example" ], "mode": "example", "projects": [ "example" ], "workspaces": [ "example" ] } } }, "schema": { "properties": { "appPassword": { "properties": { "createdAt": { "type": "number" }, "events": { "type": "boolean" }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "revokedAt": { "type": [ "number", "null" ] }, "scope": { "properties": { "inboxes": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "projects": { "items": { "type": "string" }, "type": "array" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a app password", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in.credential.recent" } }, "/api/v1/app/sign-out": { "post": { "description": "→ 204: ends the grant of the app token sent (signing out in the app); any other credential → 400 `invalid_request`", "externalDocs": { "url": "https://open-todo.app/docs/api/#app-sign-in" }, "operationId": "postAppSignOut", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "App sign out", "tags": [ "App sign-in" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/app/token": { "post": { "description": "`{grant_type: \"authorization_code\", code, code_verifier, state}` or `{grant_type: \"refresh_token\", refresh_token}` → `{access_token, token_type: \"Bearer\", expires_in: 3600, refresh_token, scope: \"app\"}` with `Cache-Control: no-store`; the errors below\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#app-sign-in" }, "operationId": "postAppToken", "requestBody": { "content": { "application/json": { "example": { "code": "example", "code_verifier": "example", "grant_type": "example", "refresh_token": "ot_example_token", "state": "example" }, "schema": { "properties": { "code": { "type": "string" }, "code_verifier": { "type": "string" }, "grant_type": { "type": "string" }, "refresh_token": { "type": "string" }, "state": { "type": "string" } }, "required": [ "code", "code_verifier", "grant_type", "refresh_token", "state" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "access_token": "ot_example_token", "expires_in": 1, "refresh_token": "ot_example_token", "scope": "full", "token_type": "ot_example_token" }, "schema": { "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "number" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" }, "token_type": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "App token", "tags": [ "App sign-in" ], "x-opentodo-policy": "public" } }, "/api/v1/assistant/routine-draft": { "post": { "description": "`{text}` (at most 500 characters) → `{draft, note, errors, warnings, usage}`: **Describe it** (OpenSpec `routines-describe-it`). One assistant turn drafts a routine with the one tool `draft_routine`; the model gets the steps available to you and the names and ids of your projects (not archived), their sections, labels, saved views and enabled webhooks (by host) as untrusted text. The draft (`{name, trigger, condition, steps}`, or `null` when the model answered in words, then in `note`) is checked like a create plus the draft rules (no task chosen by hand: no `get_task`, no `{\"task\": id}`; only available steps, else `unavailable`); when it does not check, the errors go back to the model once, and `errors` lists what still does not (`[{step?, input?, code, message}]`). Nothing is saved, enabled, tested or run, and a draft never holds `ai_apply`. `usage` is `{input, cached, cache_write, output, month_total, cap, own_key}` as for a turn; the tokens count toward the assistant allowance and `GET /api/v1/me/assistant/usage` lists them as `drafts`. `404 not_found` while the assistant is off, `409 encryption_enabled` for an encrypted account (it drafts on its device), `403 consent_required`, `413 too_large`, `429 assistant_quota` at the cap (with `resets_at`), `409 turn_in_progress` while another answer runs, `429 rate_limited` after 10 drafts in an hour, `422 ai_refused`/`ai_truncated`, provider errors as for a turn (`502`, `504 timeout`)\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "postAssistantRoutineDraft", "requestBody": { "content": { "application/json": { "example": { "text": "example" }, "schema": { "properties": { "text": { "type": "string" } }, "required": [ "text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "draft": { "condition": "example", "name": "Ada", "steps": "example", "trigger": "example" }, "errors": [ { "code": "example", "input": "example", "message": "example", "step": "example" } ], "note": "example", "usage": { "cache_write": 1, "cached": 1, "cap": 1, "input": 1, "month_total": 1, "output": 1, "own_key": false }, "warnings": [ { "kind": "example", "message": "example", "reason": "example", "setting": "example", "step": "example" } ] }, "schema": { "properties": { "draft": { "properties": { "condition": { "type": "string" }, "name": { "type": "string" }, "steps": { "type": "string" }, "trigger": { "type": "string" } }, "type": [ "object", "null" ] }, "errors": { "items": { "properties": { "code": { "type": "string" }, "input": { "type": "string" }, "message": { "type": "string" }, "step": { "type": "string" } }, "type": "object" }, "type": "array" }, "note": { "type": "string" }, "usage": { "properties": { "cache_write": { "type": "number" }, "cached": { "type": "number" }, "cap": { "type": "number" }, "input": { "type": "number" }, "month_total": { "type": "number" }, "output": { "type": "number" }, "own_key": { "type": "boolean" } }, "type": "object" }, "warnings": { "items": { "properties": { "kind": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string" }, "setting": { "type": "string" }, "step": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Assistant routine draft", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/assistant/skills": { "get": { "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "operationId": "getAssistantSkills", "responses": { "200": { "content": { "application/json": { "example": { "skills": [ { "description": "example", "example": "example", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "result": "example", "subject": "example" } ] }, "schema": { "properties": { "skills": { "items": { "properties": { "description": { "type": "string" }, "example": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "result": { "type": "string" }, "subject": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List assistant skills", "tags": [ "In-app assistant" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/assistant/turn": { "post": { "description": "Needs a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "operationId": "postAssistantTurn", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Assistant turn", "tags": [ "In-app assistant" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/attachments/{id}": { "delete": { "description": "Remove (author, project admin or owner); `204`", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "operationId": "deleteAttachmentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a attachment", "tags": [ "Attachments" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`{\"name\": \"…\"}`: rename (author only)", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "operationId": "patchAttachmentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Ada" }, "schema": { "properties": { "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "uploaded": false }, "schema": { "properties": { "uploaded": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a attachment", "tags": [ "Attachments" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/attachments/{id}/content": { "get": { "description": "The file, with ranges and `If-None-Match`. `?download=1` forces a download", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "operationId": "getAttachmentsByIdContent", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get attachment content", "tags": [ "Attachments" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "The raw bytes of an attachment you created (from a device that queued it offline); `204`. The bytes must match the attachment's `size` and `sha256`", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "operationId": "putAttachmentsByIdContent", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update attachment content", "tags": [ "Attachments" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/audit": { "get": { "description": "`{events:[…], cursor}` newest first; filters `name`, `actor`, `target`, `outcome`, `from`, `to`, `cursor`, `limit≤200`, see [Audit log](https://open-todo.app/docs/api/#audit-log)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getAudit", "responses": { "200": { "content": { "application/json": { "example": { "cursor": 1, "events": [ { "actorEmail": "ada@example.com", "actorId": "00000000-0000-4000-8000-000000000001", "details": {}, "hash": "example", "id": 1, "ip": "example", "name": "Ada", "outcome": "example", "targetEmail": "ada@example.com", "targetId": "00000000-0000-4000-8000-000000000001", "ts": 1794906000000, "userAgent": "example" } ] }, "schema": { "properties": { "cursor": { "type": [ "number", "null" ] }, "events": { "items": { "properties": { "actorEmail": { "type": [ "string", "null" ] }, "actorId": { "type": [ "string", "null" ] }, "details": { "type": "object" }, "hash": { "type": [ "string", "null" ] }, "id": { "type": "number" }, "ip": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "outcome": { "type": "string" }, "targetEmail": { "type": [ "string", "null" ] }, "targetId": { "type": [ "string", "null" ] }, "ts": { "type": "number" }, "userAgent": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get audit", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/audit/export": { "get": { "description": "the filtered log as `application/x-ndjson` download, ending with the chain head line; records `audit.exported`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getAuditExport", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get audit export", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/audit/verify": { "get": { "description": "`{ok, checked, uncovered, checkpoint, head, break}`: the hash chain recomputed, see [Audit log](https://open-todo.app/docs/api/#audit-log)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getAuditVerify", "responses": { "200": { "content": { "application/json": { "example": { "break": { "id": 1, "reason": "example" }, "checked": 1, "checkpoint": { "hash": "example", "id": 1 }, "head": { "hash": "example", "id": 1 }, "ok": true, "uncovered": 1 }, "schema": { "properties": { "break": { "properties": { "id": { "type": "number" }, "reason": { "type": "string" } }, "type": [ "object", "null" ] }, "checked": { "type": "number" }, "checkpoint": { "properties": { "hash": { "type": "string" }, "id": { "type": "number" } }, "type": "object" }, "head": { "properties": { "hash": { "type": "string" }, "id": { "type": "number" } }, "type": "object" }, "ok": { "type": "boolean" }, "uncovered": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get audit verify", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/auth/login": { "post": { "description": "`{email, password}` → `{user}` + cookie, or `{mfaRequired:true, challenge, expiresAt}` and no cookie when the account has a second factor. A password over 1,024 bytes is refused with 401 `invalid_credentials` without being checked\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postAuthLogin", "requestBody": { "content": { "application/json": { "example": { "email": "ada@example.com", "invitation": "example", "name": "Ada", "password": "correct horse battery staple", "projectInvite": "example", "setupToken": "ot_example_token", "workspaceInvite": "example" }, "schema": { "properties": { "email": { "type": "string" }, "invitation": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" }, "projectInvite": { "type": "string" }, "setupToken": { "type": "string" }, "workspaceInvite": { "type": "string" } }, "required": [ "email", "invitation", "name", "password", "projectInvite", "setupToken", "workspaceInvite" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "challenge": "example", "expiresAt": 1794906000000, "mfaRequired": false, "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "challenge": { "type": "string" }, "expiresAt": { "type": "number" }, "mfaRequired": { "type": "boolean" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Auth login", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/auth/logout": { "post": { "description": "204, or 200 `{redirect}` (provider sign-out, see [Single sign-on](https://open-todo.app/docs/api/#single-sign-on)); 403 `bad_origin` when `Origin` is another site's or `Sec-Fetch-Site` is not `same-origin` (a request naming neither, such as `ot logout`, is accepted)\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postAuthLogout", "responses": { "200": { "content": { "application/json": { "example": { "redirect": "example" }, "schema": { "properties": { "redirect": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Auth logout", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/auth/mfa": { "post": { "description": "`{challenge, code}` or `{challenge, recoveryCode}`, optional `remember` → `{user}` + cookie (+ `ot_trust` cookie when `remember`)\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postAuthMfa", "requestBody": { "content": { "application/json": { "example": { "challenge": "example", "code": "example", "recoveryCode": "example", "remember": false }, "schema": { "properties": { "challenge": { "type": "string" }, "code": { "type": "string" }, "recoveryCode": { "type": "string" }, "remember": { "type": "boolean" } }, "required": [ "challenge", "code", "recoveryCode", "remember" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Auth mfa", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/auth/oidc/callback": { "get": { "description": "provider return: 303 to `/` + cookie, or to `/?error=…`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "getAuthOidcCallback", "responses": { "200": { "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get auth oidc callback", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/auth/oidc/start": { "get": { "description": "browser navigation: 302 to the provider (links the identity instead when signed in; linking a new identity needs a fresh session)\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "getAuthOidcStart", "responses": { "200": { "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get auth oidc start", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/auth/passkey": { "post": { "description": "`{credential}` → `{user}` + cookie\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postAuthPasskey", "requestBody": { "content": { "application/json": { "example": { "credential": { "id": "00000000-0000-4000-8000-000000000001", "rawId": "00000000-0000-4000-8000-000000000001", "response": { "attestationObject": "example", "authenticatorData": "example", "clientDataJSON": "example", "signature": "example", "transports": [ "example" ] }, "type": "example" } }, "schema": { "properties": { "credential": { "properties": { "id": { "type": "string" }, "rawId": { "type": "string" }, "response": { "properties": { "attestationObject": { "type": "string" }, "authenticatorData": { "type": "string" }, "clientDataJSON": { "type": "string" }, "signature": { "type": "string" }, "transports": { "items": { "type": "string" }, "type": "array" } }, "required": [ "attestationObject", "authenticatorData", "clientDataJSON", "signature", "transports" ], "type": "object" }, "type": { "type": "string" } }, "required": [ "id", "rawId", "response", "type" ], "type": "object" } }, "required": [ "credential" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "challenge": "example", "expiresAt": 1794906000000, "mfaRequired": false, "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "challenge": { "type": "string" }, "expiresAt": { "type": "number" }, "mfaRequired": { "type": "boolean" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Auth passkey", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/auth/passkey/options": { "post": { "description": "→ `{publicKey}` sign-in options, see [Passkeys](https://open-todo.app/docs/api/#passkeys)\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postAuthPasskeyOptions", "responses": { "200": { "content": { "application/json": { "example": { "publicKey": { "allowCredentials": [ { "id": "00000000-0000-4000-8000-000000000001", "type": "example" } ], "challenge": "example", "rpId": "00000000-0000-4000-8000-000000000001", "timeout": 1, "userVerification": "example" } }, "schema": { "properties": { "publicKey": { "properties": { "allowCredentials": { "items": { "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "challenge": { "type": "string" }, "rpId": { "type": "string" }, "timeout": { "type": "number" }, "userVerification": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Create a auth passkey option", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/auth/password-reset": { "post": { "description": "`{email}` → always 202 `{ok: true}`; mails a reset link to an active account's address, see [Outgoing email](https://open-todo.app/docs/api/#outgoing-email); 404 `smtp_disabled` without outgoing email, 409 `base_url_required` without `OPENTODO_BASE_URL`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postAuthPasswordReset", "requestBody": { "content": { "application/json": { "example": { "email": "ada@example.com" }, "schema": { "properties": { "email": { "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "ok": true }, "schema": { "properties": { "ok": { "type": "boolean" } }, "type": "object" } } }, "description": "Accepted" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Auth password reset", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/auth/reauth": { "post": { "description": "`{password}` or `{code}` → `{reauthAt, validForMs}`; unlocks *fresh* routes for 10 minutes", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postAuthReauth", "requestBody": { "content": { "application/json": { "example": { "code": "example", "password": "correct horse battery staple" }, "schema": { "properties": { "code": { "type": "string" }, "password": { "type": "string" } }, "required": [ "code", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "reauthAt": 1794906000000, "validForMs": 1 }, "schema": { "properties": { "reauthAt": { "type": "number" }, "validForMs": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Auth reauth", "tags": [ "Health and authentication" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/auth/register": { "post": { "description": "`{email, name?, password, invitation?, projectInvite?, setupToken?}` → 201 `{user}` + cookie. The first account becomes owner; when `OPENTODO_SETUP_TOKEN` is set (`setupTokenRequired` in the status), it needs `setupToken` with that value, otherwise 403 `setup_token_invalid`; without a token, a client the status asks for the code (`setupCodeRequired`: from another machine with `OPENTODO_SETUP_CODE=required`, or under a domain name while no `OPENTODO_BASE_URL` is set) sends the one-time setup code from the server log as `setupToken` (case and dashes ignored), otherwise 403 `setup_code_invalid`; afterwards an `invitation` secret admits one member while sign-up is closed, and a `projectInvite` secret creates a member who joins that project (201 `{user, projectId, role}`, see [Project invite links](https://open-todo.app/docs/api/#project-invite-links)). With open sign-up and [outgoing email](https://open-todo.app/docs/api/#outgoing-email), a registration without an invitation answers 202 `{verificationRequired: true}` and mails a link instead of creating the account\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postAuthRegister", "requestBody": { "content": { "application/json": { "example": { "email": "ada@example.com", "invitation": "example", "name": "Ada", "password": "correct horse battery staple", "projectInvite": "example", "setupToken": "ot_example_token", "workspaceInvite": "example" }, "schema": { "properties": { "email": { "type": "string" }, "invitation": { "type": "string" }, "name": { "type": "string" }, "password": { "type": "string" }, "projectInvite": { "type": "string" }, "setupToken": { "type": "string" }, "workspaceInvite": { "type": "string" } }, "required": [ "email", "invitation", "name", "password", "projectInvite", "setupToken", "workspaceInvite" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "projectId": "00000000-0000-4000-8000-000000000001", "role": "member", "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" }, "verificationRequired": false, "workspaceId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "projectId": { "type": "string" }, "role": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] }, "verificationRequired": { "type": "boolean" }, "workspaceId": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "202": { "content": { "application/json": { "example": { "projectId": "00000000-0000-4000-8000-000000000001", "role": "member", "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" }, "verificationRequired": false, "workspaceId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "projectId": { "type": "string" }, "role": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] }, "verificationRequired": { "type": "boolean" }, "workspaceId": { "type": "string" } }, "type": "object" } } }, "description": "Accepted" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Auth register", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/auth/status": { "get": { "description": "`{setupRequired, setupTokenRequired, setupCodeRequired, setupCodeForHost, signupAllowed, authenticated, user, version, passkeysAvailable, oidc, outgoingEmail, mfa?, encryption?, minClientVersion?, demo?}`; `outgoingEmail` is `{enabled}`, true when [outgoing email](https://open-todo.app/docs/api/#outgoing-email) is configured (never on a demo instance); `mfa`, `encryption` and `minClientVersion` only when signed in; `setupCodeRequired` is true while no account exists and no setup token is configured, when either `OPENTODO_SETUP_CODE=required` and the request does not come over a direct loopback connection without forwarding headers, or no `OPENTODO_BASE_URL` is set and the request is addressed to a domain name (not an IP address, a name without a dot or a local-only name such as `*.local`, `*.lan` or `*.home.arpa`); `setupCodeForHost` is true when the second reason alone asks for the code; `demo` (`{token, sandboxHours: {idle, max}, resetsAt}`: a fresh single-use sandbox-creation token valid for 10 minutes, the sandbox lifetimes in hours and the next nightly reset; no credentials) only on a [demo instance](https://open-todo.app/docs/self-hosting/demo/); `wipeKey` for a signed-in browser session, and `revoked: {proof}` for the cookie of a session ended by sign out everywhere, deactivation or deletion, where `proof` is base64url(HMAC-SHA256(wipe key, `opentodo device revoked v1`)): the web app removes its local copy when it matches the key it stored (see [Two-factor authentication](https://open-todo.app/docs/api/#two-factor-authentication), [Single sign-on](https://open-todo.app/docs/api/#single-sign-on), [End-to-end encryption](https://open-todo.app/docs/api/#end-to-end-encryption))\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "getAuthStatus", "responses": { "200": { "content": { "application/json": { "example": { "authenticated": false, "branding": { "logoVersion": 1, "name": "Ada" }, "demo": { "resetsAt": 1794906000000, "sandboxHours": { "idle": 1, "max": 1 }, "token": "ot_example_token" }, "encryption": { "enabled": false, "keyVersion": 1 }, "hosted": false, "mfa": { "enrolled": false, "policy": "example", "recoveryCodesRemaining": 1, "required": false, "restricted": false }, "minClientVersion": 1, "oidc": { "displayName": "Ada", "enabled": false, "ssoOnly": false }, "outgoingEmail": { "enabled": false }, "passkeyDomain": "example", "passkeysAvailable": false, "setupCodeForHost": false, "setupCodeRequired": false, "setupRequired": false, "setupTokenRequired": false, "signupAllowed": false, "themes": { "version": 1 }, "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" }, "version": "example" }, "schema": { "properties": { "authenticated": { "type": "boolean" }, "branding": { "properties": { "logoVersion": { "type": "number" }, "name": { "type": "string" } }, "type": "object" }, "demo": { "properties": { "resetsAt": { "type": "number" }, "sandboxHours": { "properties": { "idle": { "type": "number" }, "max": { "type": "number" } }, "type": "object" }, "token": { "type": "string" } }, "type": "object" }, "encryption": { "properties": { "enabled": { "type": "boolean" }, "keyVersion": { "type": "number" } }, "type": "object" }, "hosted": { "type": "boolean" }, "mfa": { "properties": { "enrolled": { "type": "boolean" }, "policy": { "type": "string" }, "recoveryCodesRemaining": { "type": "number" }, "required": { "type": "boolean" }, "restricted": { "type": "boolean" } }, "type": [ "object", "null" ] }, "minClientVersion": { "type": "number" }, "oidc": { "properties": { "displayName": { "type": "string" }, "enabled": { "type": "boolean" }, "ssoOnly": { "type": "boolean" } }, "type": "object" }, "outgoingEmail": { "properties": { "enabled": { "type": "boolean" } }, "type": "object" }, "passkeyDomain": { "type": "string" }, "passkeysAvailable": { "type": "boolean" }, "setupCodeForHost": { "type": "boolean" }, "setupCodeRequired": { "type": "boolean" }, "setupRequired": { "type": "boolean" }, "setupTokenRequired": { "type": "boolean" }, "signupAllowed": { "type": "boolean" }, "themes": { "properties": { "version": { "type": "number" } }, "type": "object" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] }, "version": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "List auth status", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/auth/verify/{token}": { "get": { "description": "pending sign-up `{email, expiresAt}` or 404 `verification_invalid`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "getAuthVerifyByToken", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "email": "ada@example.com", "expiresAt": 1794906000000 }, "schema": { "properties": { "email": { "type": "string" }, "expiresAt": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a auth verify", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" }, "post": { "description": "creates the account of a pending sign-up → 201 `{user}` + cookie; 404 `verification_invalid`, 403 `signup_closed`, 409 `email_taken`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postAuthVerifyByToken", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "example": { "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Created" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Auth verify", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/backups": { "get": { "description": "backup status, see [Backups](https://open-todo.app/docs/api/#backups)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getBackups", "responses": { "200": { "content": { "application/json": { "example": { "destination": "example", "enabled": false, "encrypted": false, "history": [ { "archiveName": "Ada", "bytes": 1, "destination": "example", "durationMs": 1, "error": "example", "finishedAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "startedAt": 1794906000000, "status": "example" } ], "lastRun": { "archiveName": "Ada", "bytes": 1, "destination": "example", "durationMs": 1, "error": "example", "finishedAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "startedAt": 1794906000000, "status": "example" }, "nextRunAt": 1794906000000, "running": { "archiveName": "Ada", "bytes": 1, "destination": "example", "durationMs": 1, "error": "example", "finishedAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "startedAt": 1794906000000, "status": "example" }, "schedule": { "frequency": "example", "time": "example", "weekday": 1 } }, "schema": { "properties": { "destination": { "type": "string" }, "enabled": { "type": "boolean" }, "encrypted": { "type": "boolean" }, "history": { "items": { "properties": { "archiveName": { "type": "string" }, "bytes": { "type": "number" }, "destination": { "type": "string" }, "durationMs": { "type": [ "number", "null" ] }, "error": { "type": "string" }, "finishedAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "startedAt": { "type": "number" }, "status": { "type": "string" } }, "type": "object" }, "type": "array" }, "lastRun": { "properties": { "archiveName": { "type": "string" }, "bytes": { "type": "number" }, "destination": { "type": "string" }, "durationMs": { "type": [ "number", "null" ] }, "error": { "type": "string" }, "finishedAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "startedAt": { "type": "number" }, "status": { "type": "string" } }, "type": [ "object", "null" ] }, "nextRunAt": { "type": [ "number", "null" ] }, "running": { "properties": { "archiveName": { "type": "string" }, "bytes": { "type": "number" }, "destination": { "type": "string" }, "durationMs": { "type": [ "number", "null" ] }, "error": { "type": "string" }, "finishedAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "startedAt": { "type": "number" }, "status": { "type": "string" } }, "type": [ "object", "null" ] }, "schedule": { "properties": { "frequency": { "type": "string" }, "time": { "type": "string" }, "weekday": { "type": "number" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List backups", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/backups/archives": { "get": { "description": "archives in the destination, newest first, see [Restore](https://open-todo.app/docs/api/#restore-from-the-web-app)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getBackupsArchives", "responses": { "200": { "content": { "application/json": { "example": { "archives": [ { "createdAt": 1794906000000, "encrypted": false, "name": "Ada", "size": 1 } ], "destination": "example" }, "schema": { "properties": { "archives": { "items": { "properties": { "createdAt": { "type": "number" }, "encrypted": { "type": "boolean" }, "name": { "type": "string" }, "size": { "type": "number" } }, "type": "object" }, "type": "array" }, "destination": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List backups archives", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/backups/restore": { "get": { "description": "staged restore, last restore outcome, safety copies, free space\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getBackupsRestore", "responses": { "200": { "content": { "application/json": { "example": { "freeBytes": 1, "last": { "actorId": "00000000-0000-4000-8000-000000000001", "archive": "example", "audited": false, "error": "example", "finishedAt": 1794906000000, "formatVersion": 1, "ok": true, "requestedAt": 1794906000000, "retryId": "00000000-0000-4000-8000-000000000001", "safetyCopy": "example", "source": "example" }, "safetyCopies": [ { "createdAt": 1794906000000, "name": "Ada", "size": 1 } ], "staged": { "archive": "example", "counts": { "accounts": 1, "ops": 1, "projects": 1, "tasks": 1 }, "createdAt": 1794906000000, "encrypted": false, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "manifest": { "appVersion": "example", "compression": "example", "createdAt": "example", "encrypted": false, "files": [ { "name": "Ada", "sha256": "example", "size": 1 } ], "format": "example", "formatVersion": 1, "generation": "example", "schemaVersion": 1 }, "size": 1, "source": "example", "verified": false }, "undoAvailable": false, "uploadLimit": 1 }, "schema": { "properties": { "freeBytes": { "type": "number" }, "last": { "properties": { "actorId": { "type": "string" }, "archive": { "type": "string" }, "audited": { "type": "boolean" }, "error": { "type": "string" }, "finishedAt": { "type": "number" }, "formatVersion": { "type": "number" }, "ok": { "type": "boolean" }, "requestedAt": { "type": "number" }, "retryId": { "type": "string" }, "safetyCopy": { "type": "string" }, "source": { "type": "string" } }, "type": [ "object", "null" ] }, "safetyCopies": { "items": { "properties": { "createdAt": { "type": "number" }, "name": { "type": "string" }, "size": { "type": "number" } }, "type": "object" }, "type": "array" }, "staged": { "properties": { "archive": { "type": "string" }, "counts": { "properties": { "accounts": { "type": "number" }, "ops": { "type": "number" }, "projects": { "type": "number" }, "tasks": { "type": "number" } }, "type": [ "object", "null" ] }, "createdAt": { "type": "number" }, "encrypted": { "type": "boolean" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "manifest": { "properties": { "appVersion": { "type": "string" }, "compression": { "type": "string" }, "createdAt": { "type": "string" }, "encrypted": { "type": "boolean" }, "files": { "items": { "properties": { "name": { "type": "string" }, "sha256": { "type": "string" }, "size": { "type": "number" } }, "type": "object" }, "type": "array" }, "format": { "type": "string" }, "formatVersion": { "type": "number" }, "generation": { "type": "string" }, "schemaVersion": { "type": "number" } }, "type": [ "object", "null" ] }, "size": { "type": "number" }, "source": { "type": "string" }, "verified": { "type": "boolean" } }, "type": [ "object", "null" ] }, "undoAvailable": { "type": "boolean" }, "uploadLimit": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get backups restore", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" }, "post": { "description": "`{id, confirm:\"RESTORE\"}` → 202, then the server restarts\n\nOnly the server's owner. Needs a session; tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postBackupsRestore", "requestBody": { "content": { "application/json": { "example": { "confirm": "example", "id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "confirm": { "type": "string" }, "id": { "type": "string" } }, "required": [ "confirm", "id" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "status": "example" }, "schema": { "properties": { "status": { "type": "string" } }, "type": "object" } } }, "description": "Accepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Backups restore", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.session-only.recent" } }, "/api/v1/backups/restore/prepare": { "post": { "description": "`{source, passphrase?}` → verified preview\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postBackupsRestorePrepare", "requestBody": { "content": { "application/json": { "example": { "passphrase": "example", "source": { "archive": "example", "safetyCopy": "example", "upload": "example" } }, "schema": { "properties": { "passphrase": { "type": "string" }, "source": { "properties": { "archive": { "type": "string" }, "safetyCopy": { "type": "string" }, "upload": { "type": "string" } }, "type": "object" } }, "required": [ "passphrase", "source" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "archive": "example", "counts": { "accounts": 1, "ops": 1, "projects": 1, "tasks": 1 }, "createdAt": 1794906000000, "encrypted": false, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "manifest": { "appVersion": "example", "compression": "example", "createdAt": "example", "encrypted": false, "files": [ { "name": "Ada", "sha256": "example", "size": 1 } ], "format": "example", "formatVersion": 1, "generation": "example", "schemaVersion": 1 }, "size": 1, "source": "example", "verified": false }, "schema": { "properties": { "archive": { "type": "string" }, "counts": { "properties": { "accounts": { "type": "number" }, "ops": { "type": "number" }, "projects": { "type": "number" }, "tasks": { "type": "number" } }, "type": [ "object", "null" ] }, "createdAt": { "type": "number" }, "encrypted": { "type": "boolean" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "manifest": { "properties": { "appVersion": { "type": "string" }, "compression": { "type": "string" }, "createdAt": { "type": "string" }, "encrypted": { "type": "boolean" }, "files": { "items": { "properties": { "name": { "type": "string" }, "sha256": { "type": "string" }, "size": { "type": "number" } }, "type": "object" }, "type": "array" }, "format": { "type": "string" }, "formatVersion": { "type": "number" }, "generation": { "type": "string" }, "schemaVersion": { "type": "number" } }, "type": [ "object", "null" ] }, "size": { "type": "number" }, "source": { "type": "string" }, "verified": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Backups restore prepare", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/backups/restore/safety-copies/{name}": { "delete": { "description": "delete a safety copy → 204\n\nOnly the server's owner. Needs a session; tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "deleteBackupsRestoreSafetyCopiesByName", "parameters": [ { "in": "path", "name": "name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Delete a backups restore safety copy", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.session-only.recent" } }, "/api/v1/backups/restore/uploads": { "post": { "description": "raw archive body → 201 staged upload\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postBackupsRestoreUploads", "responses": { "201": { "content": { "application/json": { "example": { "archive": "example", "counts": { "accounts": 1, "ops": 1, "projects": 1, "tasks": 1 }, "createdAt": 1794906000000, "encrypted": false, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "manifest": { "appVersion": "example", "compression": "example", "createdAt": "example", "encrypted": false, "files": [ { "name": "Ada", "sha256": "example", "size": 1 } ], "format": "example", "formatVersion": 1, "generation": "example", "schemaVersion": 1 }, "size": 1, "source": "example", "verified": false }, "schema": { "properties": { "archive": { "type": "string" }, "counts": { "properties": { "accounts": { "type": "number" }, "ops": { "type": "number" }, "projects": { "type": "number" }, "tasks": { "type": "number" } }, "type": [ "object", "null" ] }, "createdAt": { "type": "number" }, "encrypted": { "type": "boolean" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "manifest": { "properties": { "appVersion": { "type": "string" }, "compression": { "type": "string" }, "createdAt": { "type": "string" }, "encrypted": { "type": "boolean" }, "files": { "items": { "properties": { "name": { "type": "string" }, "sha256": { "type": "string" }, "size": { "type": "number" } }, "type": "object" }, "type": "array" }, "format": { "type": "string" }, "formatVersion": { "type": "number" }, "generation": { "type": "string" }, "schemaVersion": { "type": "number" } }, "type": [ "object", "null" ] }, "size": { "type": "number" }, "source": { "type": "string" }, "verified": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a backups restore upload", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/backups/restore/{id}": { "delete": { "description": "cancel a staged restore → 204\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "deleteBackupsRestoreById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a backups restore", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/backups/run": { "post": { "description": "start a backup now → 202, or 409 `conflict` while one runs\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postBackupsRun", "responses": { "202": { "content": { "application/json": { "example": { "status": "example" }, "schema": { "properties": { "status": { "type": "string" } }, "type": "object" } } }, "description": "Accepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Backups run", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/backups/settings": { "get": { "description": "`{settings, secrets}` (secret presence flags only)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getBackupsSettings", "responses": { "200": { "content": { "application/json": { "example": { "secrets": { "hasPassphrase": false, "hasS3SecretKey": false, "hasWebdavPassword": false }, "settings": { "compress": false, "destination": "example", "local": { "dir": "example" }, "retention": { "keepLast": 1, "maxAgeDays": 1 }, "s3": { "accessKey": "example", "bucket": "example", "endpoint": "example", "pathStyle": false, "prefix": "example", "region": "example" }, "schedule": { "frequency": "example", "time": "example", "weekday": 1 }, "scheduleSince": 1, "webdav": { "allowHttp": false, "url": "https://todo.example.com/", "username": "Ada" } } }, "schema": { "properties": { "secrets": { "properties": { "hasPassphrase": { "type": "boolean" }, "hasS3SecretKey": { "type": "boolean" }, "hasWebdavPassword": { "type": "boolean" } }, "type": "object" }, "settings": { "properties": { "compress": { "type": "boolean" }, "destination": { "type": "string" }, "local": { "properties": { "dir": { "type": "string" } }, "type": "object" }, "retention": { "properties": { "keepLast": { "type": "number" }, "maxAgeDays": { "type": "number" } }, "type": "object" }, "s3": { "properties": { "accessKey": { "type": "string" }, "bucket": { "type": "string" }, "endpoint": { "type": "string" }, "pathStyle": { "type": "boolean" }, "prefix": { "type": "string" }, "region": { "type": "string" } }, "type": "object" }, "schedule": { "properties": { "frequency": { "type": "string" }, "time": { "type": "string" }, "weekday": { "type": "number" } }, "type": "object" }, "scheduleSince": { "type": "number" }, "webdav": { "properties": { "allowHttp": { "type": "boolean" }, "url": { "type": "string" }, "username": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List backups settings", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "`{settings, secrets?}` → `{settings, secrets}`\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "putBackupsSettings", "requestBody": { "content": { "application/json": { "example": { "secrets": { "passphrase": "example", "s3SecretKey": "example-secret", "webdavPassword": "correct horse battery staple" }, "settings": { "compress": false, "destination": "example", "local": { "dir": "example" }, "retention": { "keepLast": 1, "maxAgeDays": 1 }, "s3": { "accessKey": "example", "bucket": "example", "endpoint": "example", "pathStyle": false, "prefix": "example", "region": "example" }, "schedule": { "frequency": "example", "time": "example", "weekday": 1 }, "scheduleSince": 1, "webdav": { "allowHttp": false, "url": "https://todo.example.com/", "username": "Ada" } } }, "schema": { "properties": { "secrets": { "properties": { "passphrase": { "type": [ "string", "null" ] }, "s3SecretKey": { "type": [ "string", "null" ] }, "webdavPassword": { "type": [ "string", "null" ] } }, "type": "object" }, "settings": { "properties": { "compress": { "type": "boolean" }, "destination": { "type": "string" }, "local": { "properties": { "dir": { "type": "string" } }, "required": [ "dir" ], "type": "object" }, "retention": { "properties": { "keepLast": { "type": "number" }, "maxAgeDays": { "type": "number" } }, "required": [ "keepLast", "maxAgeDays" ], "type": "object" }, "s3": { "properties": { "accessKey": { "type": "string" }, "bucket": { "type": "string" }, "endpoint": { "type": "string" }, "pathStyle": { "type": "boolean" }, "prefix": { "type": "string" }, "region": { "type": "string" } }, "required": [ "accessKey", "bucket", "endpoint", "pathStyle", "prefix", "region" ], "type": "object" }, "schedule": { "properties": { "frequency": { "type": "string" }, "time": { "type": "string" }, "weekday": { "type": "number" } }, "required": [ "frequency", "time", "weekday" ], "type": "object" }, "scheduleSince": { "type": "number" }, "webdav": { "properties": { "allowHttp": { "type": "boolean" }, "url": { "type": "string" }, "username": { "type": "string" } }, "required": [ "allowHttp", "url", "username" ], "type": "object" } }, "required": [ "compress", "destination", "local", "retention", "s3", "schedule", "scheduleSince", "webdav" ], "type": [ "object", "null" ] } }, "required": [ "secrets" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "secrets": { "hasPassphrase": false, "hasS3SecretKey": false, "hasWebdavPassword": false }, "settings": { "compress": false, "destination": "example", "local": { "dir": "example" }, "retention": { "keepLast": 1, "maxAgeDays": 1 }, "s3": { "accessKey": "example", "bucket": "example", "endpoint": "example", "pathStyle": false, "prefix": "example", "region": "example" }, "schedule": { "frequency": "example", "time": "example", "weekday": 1 }, "scheduleSince": 1, "webdav": { "allowHttp": false, "url": "https://todo.example.com/", "username": "Ada" } } }, "schema": { "properties": { "secrets": { "properties": { "hasPassphrase": { "type": "boolean" }, "hasS3SecretKey": { "type": "boolean" }, "hasWebdavPassword": { "type": "boolean" } }, "type": "object" }, "settings": { "properties": { "compress": { "type": "boolean" }, "destination": { "type": "string" }, "local": { "properties": { "dir": { "type": "string" } }, "type": "object" }, "retention": { "properties": { "keepLast": { "type": "number" }, "maxAgeDays": { "type": "number" } }, "type": "object" }, "s3": { "properties": { "accessKey": { "type": "string" }, "bucket": { "type": "string" }, "endpoint": { "type": "string" }, "pathStyle": { "type": "boolean" }, "prefix": { "type": "string" }, "region": { "type": "string" } }, "type": "object" }, "schedule": { "properties": { "frequency": { "type": "string" }, "time": { "type": "string" }, "weekday": { "type": "number" } }, "type": "object" }, "scheduleSince": { "type": "number" }, "webdav": { "properties": { "allowHttp": { "type": "boolean" }, "url": { "type": "string" }, "username": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update backups settings", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/backups/test": { "post": { "description": "write and delete a probe object at the saved destination → 200 `{ok:true}` or 502 `destination_error`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postBackupsTest", "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "properties": { "ok": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Backups test", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/calendar-feeds/events": { "get": { "description": "at most 92 days; `{events: [{id, subscriptionId, uid, summary, location, start, end, allDay, free}], subscriptions: [{id, name, color, enabled, lastSuccessAt, managed?}]}` (`managed`: a calendar of a [calendar sync](https://open-todo.app/docs/api/#calendar-sync) connection); answers while calendar feeds or calendar sync is on; `start` and `end` are shaped like a task's `due` (`{date, time?, tz?}`; no `tz` means floating)", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "getCalendarFeedsEvents", "responses": { "200": { "content": { "application/json": { "example": { "events": [ { "allDay": false, "end": { "date": "2026-11-20", "time": "example", "tz": "Europe/Rome" }, "free": false, "id": "00000000-0000-4000-8000-000000000001", "location": "example", "start": { "date": "2026-11-20", "time": "example", "tz": "Europe/Rome" }, "subscriptionId": "00000000-0000-4000-8000-000000000001", "summary": "example", "uid": "example" } ], "subscriptions": [ { "color": "#3b82f6", "enabled": false, "id": "00000000-0000-4000-8000-000000000001", "lastSuccessAt": 1794906000000, "managed": false, "name": "Ada" } ] }, "schema": { "properties": { "events": { "items": { "properties": { "allDay": { "type": "boolean" }, "end": { "properties": { "date": { "type": "string" }, "time": { "type": [ "string", "null" ] }, "tz": { "type": [ "string", "null" ] } }, "type": "object" }, "free": { "type": "boolean" }, "id": { "type": "string" }, "location": { "type": "string" }, "start": { "properties": { "date": { "type": "string" }, "time": { "type": [ "string", "null" ] }, "tz": { "type": [ "string", "null" ] } }, "type": "object" }, "subscriptionId": { "type": "string" }, "summary": { "type": "string" }, "uid": { "type": "string" } }, "type": "object" }, "type": "array" }, "subscriptions": { "items": { "properties": { "color": { "type": "string" }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "lastSuccessAt": { "type": [ "number", "null" ] }, "managed": { "type": "boolean" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List calendar feeds events", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/calendar-feeds/feed": { "delete": { "description": "`204`, `404` when there is none; recorded as `calendar_feed.revoked`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "deleteCalendarFeedsFeed", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete calendar feeds feed", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "`{feed: {createdAt, lastUsedAt} | null}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "getCalendarFeedsFeed", "responses": { "200": { "content": { "application/json": { "example": { "feed": { "createdAt": 1794906000000, "lastUsedAt": 1794906000000 } }, "schema": { "properties": { "feed": { "properties": { "createdAt": { "type": "number" }, "lastUsedAt": { "type": [ "number", "null" ] } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get calendar feeds feed", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "create or replace the feed URL: `201 {feed, url}`, the only time the URL is shown; recorded as `calendar_feed.created` or `calendar_feed.rotated`\n\nNeeds a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "postCalendarFeedsFeed", "responses": { "201": { "content": { "application/json": { "example": { "feed": { "createdAt": 1794906000000, "lastUsedAt": 1794906000000 }, "url": "https://todo.example.com/" }, "schema": { "properties": { "feed": { "properties": { "createdAt": { "type": "number" }, "lastUsedAt": { "type": [ "number", "null" ] } }, "type": [ "object", "null" ] }, "url": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Calendar feeds feed", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "signed-in.recent" } }, "/api/v1/calendar-feeds/subscriptions": { "get": { "description": "`{subscriptions: [...]}` with status: `name`, `color`, `enabled`, `eventCount`, `lastSuccessAt`, `lastError` (`timeout`, `http_404`, `too_large`, `invalid_calendar`, `private_target`, …), `stoppedReason`, `warnings`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "getCalendarFeedsSubscriptions", "responses": { "200": { "content": { "application/json": { "example": { "subscriptions": [ { "color": "#3b82f6", "createdAt": 1794906000000, "enabled": false, "eventCount": 1, "id": "00000000-0000-4000-8000-000000000001", "intervalSeconds": 1, "lastError": "example", "lastFetchAt": 1794906000000, "lastSuccessAt": 1794906000000, "name": "Ada", "nextFetchAt": 1794906000000, "refreshSeconds": 1, "stoppedReason": "example", "updatedAt": 1794906000000, "url": "https://todo.example.com/", "warnings": [ "example" ] } ] }, "schema": { "properties": { "subscriptions": { "items": { "properties": { "color": { "type": "string" }, "createdAt": { "type": "number" }, "enabled": { "type": "boolean" }, "eventCount": { "type": "number" }, "id": { "type": "string" }, "intervalSeconds": { "type": "number" }, "lastError": { "type": "string" }, "lastFetchAt": { "type": [ "number", "null" ] }, "lastSuccessAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "nextFetchAt": { "type": "number" }, "refreshSeconds": { "type": [ "number", "null" ] }, "stoppedReason": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List calendar feeds subscriptions", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{url, name?, color?}`; `webcal://` is read as `https://`; the address must not be on a private network unless the owner allows private targets for webhooks (`400 private_target`); at most 10 per account (`400 limit_reached`); fetched once before answering `201 {subscription}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "postCalendarFeedsSubscriptions", "requestBody": { "content": { "application/json": { "example": { "color": "#3b82f6", "enabled": false, "name": "Ada", "url": "https://todo.example.com/" }, "schema": { "properties": { "color": { "type": [ "string", "null" ] }, "enabled": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "subscription": { "color": "#3b82f6", "createdAt": 1794906000000, "enabled": false, "eventCount": 1, "id": "00000000-0000-4000-8000-000000000001", "intervalSeconds": 1, "lastError": "example", "lastFetchAt": 1794906000000, "lastSuccessAt": 1794906000000, "name": "Ada", "nextFetchAt": 1794906000000, "refreshSeconds": 1, "stoppedReason": "example", "updatedAt": 1794906000000, "url": "https://todo.example.com/", "warnings": [ "example" ] } }, "schema": { "properties": { "subscription": { "properties": { "color": { "type": "string" }, "createdAt": { "type": "number" }, "enabled": { "type": "boolean" }, "eventCount": { "type": "number" }, "id": { "type": "string" }, "intervalSeconds": { "type": "number" }, "lastError": { "type": "string" }, "lastFetchAt": { "type": [ "number", "null" ] }, "lastSuccessAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "nextFetchAt": { "type": "number" }, "refreshSeconds": { "type": [ "number", "null" ] }, "stoppedReason": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a calendar feeds subscription", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/calendar-feeds/subscriptions/{id}": { "delete": { "description": "`204`, its events go with it", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "deleteCalendarFeedsSubscriptionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a calendar feeds subscription", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`{url?, name?, color?, enabled?}`; a new URL is checked and fetched; `enabled: true` restarts a subscription stopped for a private target", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "patchCalendarFeedsSubscriptionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "color": "#3b82f6", "enabled": false, "name": "Ada", "url": "https://todo.example.com/" }, "schema": { "properties": { "color": { "type": [ "string", "null" ] }, "enabled": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "subscription": { "color": "#3b82f6", "createdAt": 1794906000000, "enabled": false, "eventCount": 1, "id": "00000000-0000-4000-8000-000000000001", "intervalSeconds": 1, "lastError": "example", "lastFetchAt": 1794906000000, "lastSuccessAt": 1794906000000, "name": "Ada", "nextFetchAt": 1794906000000, "refreshSeconds": 1, "stoppedReason": "example", "updatedAt": 1794906000000, "url": "https://todo.example.com/", "warnings": [ "example" ] } }, "schema": { "properties": { "subscription": { "properties": { "color": { "type": "string" }, "createdAt": { "type": "number" }, "enabled": { "type": "boolean" }, "eventCount": { "type": "number" }, "id": { "type": "string" }, "intervalSeconds": { "type": "number" }, "lastError": { "type": "string" }, "lastFetchAt": { "type": [ "number", "null" ] }, "lastSuccessAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "nextFetchAt": { "type": "number" }, "refreshSeconds": { "type": [ "number", "null" ] }, "stoppedReason": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a calendar feeds subscription", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/calendar-feeds/subscriptions/{id}/refresh": { "post": { "description": "fetch now, `200 {subscription}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "postCalendarFeedsSubscriptionsByIdRefresh", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "subscription": { "color": "#3b82f6", "createdAt": 1794906000000, "enabled": false, "eventCount": 1, "id": "00000000-0000-4000-8000-000000000001", "intervalSeconds": 1, "lastError": "example", "lastFetchAt": 1794906000000, "lastSuccessAt": 1794906000000, "name": "Ada", "nextFetchAt": 1794906000000, "refreshSeconds": 1, "stoppedReason": "example", "updatedAt": 1794906000000, "url": "https://todo.example.com/", "warnings": [ "example" ] } }, "schema": { "properties": { "subscription": { "properties": { "color": { "type": "string" }, "createdAt": { "type": "number" }, "enabled": { "type": "boolean" }, "eventCount": { "type": "number" }, "id": { "type": "string" }, "intervalSeconds": { "type": "number" }, "lastError": { "type": "string" }, "lastFetchAt": { "type": [ "number", "null" ] }, "lastSuccessAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "nextFetchAt": { "type": "number" }, "refreshSeconds": { "type": [ "number", "null" ] }, "stoppedReason": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Calendar feeds subscription refresh", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/calendar-sync/connections": { "get": { "description": "`{connections: [...]}`: `id`, `provider` (`caldav`, `google`, `microsoft`), `name`, `server_url`, `username`, `calendars` (`[{url, name, color, time_zone?, read_only}]`), `target`, `read`, `include_date_only`, `scope` (see [Sync scope](https://open-todo.app/docs/api/#sync-scope)), `enabled`, `state` (`off`, `choose_calendar`, `pending`, `ok`, `failed`, `reconnect`, `stopped`), `next_sync_at`, `last_sync_at`, `last_success_at`, `last_error`, `last_error_at`, `stopped_reason`, `last_run` (`{moved, renamed, unscheduled, written, removed, conflicts, refused, partial}`), `password_set`, `event_count`. Never the password or token.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "getCalendarSyncConnections", "responses": { "200": { "content": { "application/json": { "example": { "connections": [ { "calendars": [ { "color": "#3b82f6", "name": "Ada", "read_only": false, "time_zone": "example", "url": "https://todo.example.com/" } ], "created_at": 1794906000000, "enabled": false, "event_count": 1, "id": "00000000-0000-4000-8000-000000000001", "include_date_only": false, "last_error": "example", "last_error_at": 1794906000000, "last_run": { "conflicts": 1, "moved": 1, "partial": false, "refused": 1, "removed": 1, "renamed": 1, "unscheduled": 1, "written": 1 }, "last_success_at": 1794906000000, "last_sync_at": 1794906000000, "name": "Ada", "next_sync_at": 1794906000000, "password_set": false, "project_calendars": {}, "provider": "example", "read": [ "example" ], "scope": { "inboxes": [ "example" ], "mode": "example", "projects": [ "example" ], "workspaces": [ "example" ] }, "server_url": "https://todo.example.com/", "state": "example", "stopped_reason": "example", "target": "example", "updated_at": 1794906000000, "username": "Ada" } ] }, "schema": { "properties": { "connections": { "items": { "properties": { "calendars": { "items": { "properties": { "color": { "type": "string" }, "name": { "type": "string" }, "read_only": { "type": "boolean" }, "time_zone": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" }, "created_at": { "type": "number" }, "enabled": { "type": "boolean" }, "event_count": { "type": "number" }, "id": { "type": "string" }, "include_date_only": { "type": "boolean" }, "last_error": { "type": "string" }, "last_error_at": { "type": [ "number", "null" ] }, "last_run": { "properties": { "conflicts": { "type": "number" }, "moved": { "type": "number" }, "partial": { "type": "boolean" }, "refused": { "type": "number" }, "removed": { "type": "number" }, "renamed": { "type": "number" }, "unscheduled": { "type": "number" }, "written": { "type": "number" } }, "type": [ "object", "null" ] }, "last_success_at": { "type": [ "number", "null" ] }, "last_sync_at": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "next_sync_at": { "type": "number" }, "password_set": { "type": "boolean" }, "project_calendars": { "type": "object" }, "provider": { "type": "string" }, "read": { "items": { "type": "string" }, "type": "array" }, "scope": { "properties": { "inboxes": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "projects": { "items": { "type": "string" }, "type": "array" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "server_url": { "type": "string" }, "state": { "type": "string" }, "stopped_reason": { "type": "string" }, "target": { "type": "string" }, "updated_at": { "type": "number" }, "username": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List calendar sync connections", "tags": [ "Calendar sync" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{server_url, username, password, name?}`: `server_url` is an address, a host name or an email address (then `/.well-known/caldav` of its domain); discovery runs at once; `201 {connection}` in the state `choose_calendar`\n\nNeeds a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "postCalendarSyncConnections", "requestBody": { "content": { "application/json": { "example": { "name": "Ada", "password": "correct horse battery staple", "server_url": "https://todo.example.com/", "username": "Ada" }, "schema": { "properties": { "name": { "type": "string" }, "password": { "type": "string" }, "server_url": { "type": "string" }, "username": { "type": "string" } }, "required": [ "name", "password", "server_url", "username" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "connection": { "calendars": [ { "color": "#3b82f6", "name": "Ada", "read_only": false, "time_zone": "example", "url": "https://todo.example.com/" } ], "created_at": 1794906000000, "enabled": false, "event_count": 1, "id": "00000000-0000-4000-8000-000000000001", "include_date_only": false, "last_error": "example", "last_error_at": 1794906000000, "last_run": { "conflicts": 1, "moved": 1, "partial": false, "refused": 1, "removed": 1, "renamed": 1, "unscheduled": 1, "written": 1 }, "last_success_at": 1794906000000, "last_sync_at": 1794906000000, "name": "Ada", "next_sync_at": 1794906000000, "password_set": false, "project_calendars": {}, "provider": "example", "read": [ "example" ], "scope": { "inboxes": [ "example" ], "mode": "example", "projects": [ "example" ], "workspaces": [ "example" ] }, "server_url": "https://todo.example.com/", "state": "example", "stopped_reason": "example", "target": "example", "updated_at": 1794906000000, "username": "Ada" } }, "schema": { "properties": { "connection": { "properties": { "calendars": { "items": { "properties": { "color": { "type": "string" }, "name": { "type": "string" }, "read_only": { "type": "boolean" }, "time_zone": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" }, "created_at": { "type": "number" }, "enabled": { "type": "boolean" }, "event_count": { "type": "number" }, "id": { "type": "string" }, "include_date_only": { "type": "boolean" }, "last_error": { "type": "string" }, "last_error_at": { "type": [ "number", "null" ] }, "last_run": { "properties": { "conflicts": { "type": "number" }, "moved": { "type": "number" }, "partial": { "type": "boolean" }, "refused": { "type": "number" }, "removed": { "type": "number" }, "renamed": { "type": "number" }, "unscheduled": { "type": "number" }, "written": { "type": "number" } }, "type": [ "object", "null" ] }, "last_success_at": { "type": [ "number", "null" ] }, "last_sync_at": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "next_sync_at": { "type": "number" }, "password_set": { "type": "boolean" }, "project_calendars": { "type": "object" }, "provider": { "type": "string" }, "read": { "items": { "type": "string" }, "type": "array" }, "scope": { "properties": { "inboxes": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "projects": { "items": { "type": "string" }, "type": "array" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "server_url": { "type": "string" }, "state": { "type": "string" }, "stopped_reason": { "type": "string" }, "target": { "type": "string" }, "updated_at": { "type": "number" }, "username": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a calendar sync connection", "tags": [ "Calendar sync" ], "x-opentodo-policy": "signed-in.recent" } }, "/api/v1/calendar-sync/connections/{id}": { "delete": { "description": "`204`; the secret is removed, tasks and events already written stay", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "deleteCalendarSyncConnectionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a calendar sync connection", "tags": [ "Calendar sync" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "any of `name`, `target` (a writable calendar of the connection), `read` (up to 10 of its calendars), `include_date_only`, `scope` (see [Sync scope](https://open-todo.app/docs/api/#sync-scope); makes the connection due now), `enabled`, `password` (CalDAV only; Google and Microsoft reconnect instead; needs a fresh sign-in, `403 reauth_required`; checked by discovery, then clears a stop)", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "patchCalendarSyncConnectionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "enabled": false, "include_date_only": false, "name": "Ada", "password": "correct horse battery staple", "project_calendars": {}, "read": [ "example" ], "scope": { "inboxes": [ "example" ], "mode": "example", "projects": [ "example" ], "workspaces": [ "example" ] }, "target": "example" }, "schema": { "properties": { "enabled": { "type": [ "boolean", "null" ] }, "include_date_only": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "password": { "type": [ "string", "null" ] }, "project_calendars": { "type": [ "object", "null" ] }, "read": { "items": { "type": "string" }, "type": "array" }, "scope": { "properties": { "inboxes": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "projects": { "items": { "type": "string" }, "type": "array" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "required": [ "inboxes", "mode", "projects", "workspaces" ], "type": [ "object", "null" ] }, "target": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "connection": { "calendars": [ { "color": "#3b82f6", "name": "Ada", "read_only": false, "time_zone": "example", "url": "https://todo.example.com/" } ], "created_at": 1794906000000, "enabled": false, "event_count": 1, "id": "00000000-0000-4000-8000-000000000001", "include_date_only": false, "last_error": "example", "last_error_at": 1794906000000, "last_run": { "conflicts": 1, "moved": 1, "partial": false, "refused": 1, "removed": 1, "renamed": 1, "unscheduled": 1, "written": 1 }, "last_success_at": 1794906000000, "last_sync_at": 1794906000000, "name": "Ada", "next_sync_at": 1794906000000, "password_set": false, "project_calendars": {}, "provider": "example", "read": [ "example" ], "scope": { "inboxes": [ "example" ], "mode": "example", "projects": [ "example" ], "workspaces": [ "example" ] }, "server_url": "https://todo.example.com/", "state": "example", "stopped_reason": "example", "target": "example", "updated_at": 1794906000000, "username": "Ada" } }, "schema": { "properties": { "connection": { "properties": { "calendars": { "items": { "properties": { "color": { "type": "string" }, "name": { "type": "string" }, "read_only": { "type": "boolean" }, "time_zone": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" }, "created_at": { "type": "number" }, "enabled": { "type": "boolean" }, "event_count": { "type": "number" }, "id": { "type": "string" }, "include_date_only": { "type": "boolean" }, "last_error": { "type": "string" }, "last_error_at": { "type": [ "number", "null" ] }, "last_run": { "properties": { "conflicts": { "type": "number" }, "moved": { "type": "number" }, "partial": { "type": "boolean" }, "refused": { "type": "number" }, "removed": { "type": "number" }, "renamed": { "type": "number" }, "unscheduled": { "type": "number" }, "written": { "type": "number" } }, "type": [ "object", "null" ] }, "last_success_at": { "type": [ "number", "null" ] }, "last_sync_at": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "next_sync_at": { "type": "number" }, "password_set": { "type": "boolean" }, "project_calendars": { "type": "object" }, "provider": { "type": "string" }, "read": { "items": { "type": "string" }, "type": "array" }, "scope": { "properties": { "inboxes": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "projects": { "items": { "type": "string" }, "type": "array" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "server_url": { "type": "string" }, "state": { "type": "string" }, "stopped_reason": { "type": "string" }, "target": { "type": "string" }, "updated_at": { "type": "number" }, "username": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a calendar sync connection", "tags": [ "Calendar sync" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/calendar-sync/connections/{id}/sync": { "post": { "description": "discovery and a cycle now: `{ok, run?, reason?, connection}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "postCalendarSyncConnectionsByIdSync", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "connection": { "calendars": [ { "color": "#3b82f6", "name": "Ada", "read_only": false, "time_zone": "example", "url": "https://todo.example.com/" } ], "created_at": 1794906000000, "enabled": false, "event_count": 1, "id": "00000000-0000-4000-8000-000000000001", "include_date_only": false, "last_error": "example", "last_error_at": 1794906000000, "last_run": { "conflicts": 1, "moved": 1, "partial": false, "refused": 1, "removed": 1, "renamed": 1, "unscheduled": 1, "written": 1 }, "last_success_at": 1794906000000, "last_sync_at": 1794906000000, "name": "Ada", "next_sync_at": 1794906000000, "password_set": false, "project_calendars": {}, "provider": "example", "read": [ "example" ], "scope": { "inboxes": [ "example" ], "mode": "example", "projects": [ "example" ], "workspaces": [ "example" ] }, "server_url": "https://todo.example.com/", "state": "example", "stopped_reason": "example", "target": "example", "updated_at": 1794906000000, "username": "Ada" } }, "schema": { "properties": { "connection": { "properties": { "calendars": { "items": { "properties": { "color": { "type": "string" }, "name": { "type": "string" }, "read_only": { "type": "boolean" }, "time_zone": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" }, "created_at": { "type": "number" }, "enabled": { "type": "boolean" }, "event_count": { "type": "number" }, "id": { "type": "string" }, "include_date_only": { "type": "boolean" }, "last_error": { "type": "string" }, "last_error_at": { "type": [ "number", "null" ] }, "last_run": { "properties": { "conflicts": { "type": "number" }, "moved": { "type": "number" }, "partial": { "type": "boolean" }, "refused": { "type": "number" }, "removed": { "type": "number" }, "renamed": { "type": "number" }, "unscheduled": { "type": "number" }, "written": { "type": "number" } }, "type": [ "object", "null" ] }, "last_success_at": { "type": [ "number", "null" ] }, "last_sync_at": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "next_sync_at": { "type": "number" }, "password_set": { "type": "boolean" }, "project_calendars": { "type": "object" }, "provider": { "type": "string" }, "read": { "items": { "type": "string" }, "type": "array" }, "scope": { "properties": { "inboxes": { "items": { "type": "string" }, "type": "array" }, "mode": { "type": "string" }, "projects": { "items": { "type": "string" }, "type": "array" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "server_url": { "type": "string" }, "state": { "type": "string" }, "stopped_reason": { "type": "string" }, "target": { "type": "string" }, "updated_at": { "type": "number" }, "username": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Calendar sync connection sync", "tags": [ "Calendar sync" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/calendar-sync/google/callback": { "get": { "description": "Google's redirect: exchanges the code, stores the refresh token, discovers the calendars and redirects (`303`) to `/settings/integrations/calendar-sync?calendar-sync=connected\u0026connection=\u003cid\u003e`, or `?calendar-sync=\u003creason\u003e`: `denied` (Google's `access_denied`), `redirect_uri_mismatch`, `authorization_failed` (any other error from Google, or no code), `invalid_state`, `google_client_refused` (Google refused the owner's client id or secret), `scope_not_granted` (the calendar permission was unticked), `no_refresh_token`, `caldav_api_disabled` (Google's CalDAV answered `403`: the CalDAV API is not enabled in the owner's project), `limit_reached` or another discovery reason\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "getCalendarSyncGoogleCallback", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Get calendar sync google callback", "tags": [ "Calendar sync" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/calendar-sync/google/start": { "post": { "description": "`{connection_id?}` (to reconnect); `{url}`: Google's consent page with a single-use state (10 minutes) and a PKCE challenge; `409 google_not_configured` without a Google client; `409 base_url_mismatch` when the request's `Origin` is not the origin of the redirect address (set `OPENTODO_BASE_URL`)\n\nNeeds a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "postCalendarSyncGoogleStart", "requestBody": { "content": { "application/json": { "example": { "connection_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "connection_id": { "type": "string" } }, "required": [ "connection_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "url": "https://todo.example.com/" }, "schema": { "properties": { "url": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Calendar sync google start", "tags": [ "Calendar sync" ], "x-opentodo-policy": "signed-in.recent" } }, "/api/v1/calendar-sync/microsoft/callback": { "get": { "description": "Microsoft's redirect: exchanges the code, stores the refresh token, reads the account's address, mailbox time zone and calendars and redirects (`303`) to `/settings/integrations/calendar-sync?calendar-sync=connected\u0026connection=\u003cid\u003e\u0026provider=microsoft`, or `?calendar-sync=\u003creason\u003e\u0026provider=microsoft` (`denied`, `admin_consent_required` when the organisation requires an administrator's approval, `authorization_failed`, `invalid_state` also for a Google state, `no_refresh_token`, `limit_reached`, `unauthorized`, a discovery reason)\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "getCalendarSyncMicrosoftCallback", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Get calendar sync microsoft callback", "tags": [ "Calendar sync" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/calendar-sync/microsoft/start": { "post": { "description": "`{connection_id?}` (to reconnect); `{url}`: Microsoft's sign-in page for the configured tenant (`https://login.microsoftonline.com/\u003ctenant\u003e/oauth2/v2.0/authorize`) with the scopes `offline_access User.Read Calendars.ReadWrite MailboxSettings.Read`, a single-use state bound to the account and to Microsoft (10 minutes) and a PKCE challenge; `409 microsoft_not_configured` without a Microsoft client, `409 limit_reached` at 3 connections; counts toward the limit of 12 per hour\n\nNeeds a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "postCalendarSyncMicrosoftStart", "requestBody": { "content": { "application/json": { "example": { "connection_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "connection_id": { "type": "string" } }, "required": [ "connection_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "url": "https://todo.example.com/" }, "schema": { "properties": { "url": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Calendar sync microsoft start", "tags": [ "Calendar sync" ], "x-opentodo-policy": "signed-in.recent" } }, "/api/v1/comments/{id}": { "delete": { "description": "204; allowed for the author, project admins and the owner", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteCommentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a comment", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`{body?, mentions?}` → 200 comment with `edited_at` set; 403 `forbidden` unless you wrote it", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "patchCommentsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "body": "The shop opens at ten." } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "200": { "content": { "application/json": { "example": { "author_id": "00000000-0000-4000-8000-000000000001", "body": "The shop opens at ten.", "created_at": 1794906000052, "deleted_at": null, "edited_at": 1794906000058, "id": "00000000-0000-4000-8000-000000000007", "mentions": [], "my_reactions": [], "parent_id": null, "reactions": { "check": [], "eyes": [], "heart": [], "party": [], "question": [], "thumbs_up": [] }, "task_id": "00000000-0000-4000-8000-000000000005" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a comment", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/comments/{id}/reactions": { "put": { "description": "`{reactions: [names]}` replaces your own reactions → 200 comment; 400 `invalid_input` naming an unknown name or a duplicate; 404 for an unreadable or deleted comment; `read` and `agent` tokens get 403 `insufficient_scope`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "putCommentsByIdReactions", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "reactions": [ "heart" ] } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "200": { "content": { "application/json": { "example": { "author_id": "00000000-0000-4000-8000-000000000001", "body": "The shop opens at ten.", "created_at": 1794906000052, "deleted_at": null, "edited_at": 1794906000058, "id": "00000000-0000-4000-8000-000000000007", "mentions": [], "my_reactions": [ "heart" ], "parent_id": null, "reactions": { "check": [], "eyes": [], "heart": [ "00000000-0000-4000-8000-000000000001" ], "party": [], "question": [], "thumbs_up": [] }, "task_id": "00000000-0000-4000-8000-000000000005" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update comment reactions", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/demo/sandbox": { "post": { "description": "[demo instance](https://open-todo.app/docs/self-hosting/demo/) only (absent otherwise): `{token}` from `auth/status` → 201 `{user}` + cookie for a new private sandbox. Requires a same-origin `Origin` header; 403 `demo_token` (missing, forged, expired or used token), 403 `bad_origin`, 429 `rate_limited` (5 per address per hour), 503 `demo_busy`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postDemoSandbox", "requestBody": { "content": { "application/json": { "example": { "token": "ot_example_token" }, "schema": { "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Created" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Demo sandbox", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/email-inbox": { "get": { "description": "your email-to-task address and settings, see [Email to task](https://open-todo.app/docs/api/#email-to-task)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "getEmailInbox", "responses": { "200": { "content": { "application/json": { "example": { "address": "example", "allowlist": [ "example" ], "enabled": false, "enabledByOperator": false, "hourlyLimit": 1 }, "schema": { "properties": { "address": { "type": [ "string", "null" ] }, "allowlist": { "items": { "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "enabledByOperator": { "type": "boolean" }, "hourlyLimit": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get email inbox", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in.full-tokens" }, "patch": { "description": "`{enabled?, allowlist?}` → the same shape; creates the inbox when there is none\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "patchEmailInbox", "requestBody": { "content": { "application/json": { "example": { "allowlist": "example", "enabled": false }, "schema": { "properties": { "allowlist": { "type": "string" }, "enabled": { "type": [ "boolean", "null" ] } }, "required": [ "allowlist" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "address": "example", "allowlist": [ "example" ], "enabled": false, "enabledByOperator": false, "hourlyLimit": 1 }, "schema": { "properties": { "address": { "type": [ "string", "null" ] }, "allowlist": { "items": { "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "enabledByOperator": { "type": "boolean" }, "hourlyLimit": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update email inbox", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/email-inbox/rotate": { "post": { "description": "new address; the old one stops working\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "postEmailInboxRotate", "responses": { "200": { "content": { "application/json": { "example": { "address": "example", "allowlist": [ "example" ], "enabled": false, "enabledByOperator": false, "hourlyLimit": 1 }, "schema": { "properties": { "address": { "type": [ "string", "null" ] }, "allowlist": { "items": { "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "enabledByOperator": { "type": "boolean" }, "hourlyLimit": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Email inbox rotate", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/encryption/keys": { "delete": { "description": "204; turns encryption off for the account (404 `encryption_disabled` without a record)\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "deleteEncryptionKeys", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete encryption keys", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential.recent" }, "get": { "description": "`{keys}`: the wrapped key record, or 404 `encryption_disabled`; see [End-to-end encryption](https://open-todo.app/docs/api/#end-to-end-encryption)", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getEncryptionKeys", "responses": { "200": { "content": { "application/json": { "example": { "keys": { "createdAt": 1794906000000, "iterations": 1, "kdf": 1, "salt": "example", "updatedAt": 1794906000000, "version": 1, "wrappedByPassphrase": "example", "wrappedByRecovery": "example" } }, "schema": { "properties": { "keys": { "properties": { "createdAt": { "type": "number" }, "iterations": { "type": "number" }, "kdf": { "type": "number" }, "salt": { "type": "string" }, "updatedAt": { "type": "number" }, "version": { "type": "number" }, "wrappedByPassphrase": { "type": "string" }, "wrappedByRecovery": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List encryption keys", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "create (`version: 1`) or replace (`version` = stored + 1) the key record → 201/200 `{keys}`; 409 `encryption_conflict`\n\nNeeds a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "putEncryptionKeys", "requestBody": { "content": { "application/json": { "example": { "createdAt": 1794906000000, "iterations": 1, "kdf": 1, "salt": "example", "updatedAt": 1794906000000, "version": 1, "wrappedByPassphrase": "example", "wrappedByRecovery": "example" }, "schema": { "properties": { "createdAt": { "type": "number" }, "iterations": { "type": "number" }, "kdf": { "type": "number" }, "salt": { "type": "string" }, "updatedAt": { "type": "number" }, "version": { "type": "number" }, "wrappedByPassphrase": { "type": "string" }, "wrappedByRecovery": { "type": "string" } }, "required": [ "createdAt", "iterations", "kdf", "salt", "updatedAt", "version", "wrappedByPassphrase", "wrappedByRecovery" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "digestDisabled": false, "issueConnectionsStopped": [ "example" ], "keys": { "createdAt": 1794906000000, "iterations": 1, "kdf": 1, "salt": "example", "updatedAt": 1794906000000, "version": 1, "wrappedByPassphrase": "example", "wrappedByRecovery": "example" } }, "schema": { "properties": { "digestDisabled": { "type": "boolean" }, "issueConnectionsStopped": { "items": { "type": "string" }, "type": "array" }, "keys": { "properties": { "createdAt": { "type": "number" }, "iterations": { "type": "number" }, "kdf": { "type": "number" }, "salt": { "type": "string" }, "updatedAt": { "type": "number" }, "version": { "type": "number" }, "wrappedByPassphrase": { "type": "string" }, "wrappedByRecovery": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update encryption keys", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential" } }, "/api/v1/encryption/purge-history": { "post": { "description": "→ `{purged, notice}`; deletes superseded content operations; 409 `encryption_disabled`", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postEncryptionPurgeHistory", "responses": { "200": { "content": { "application/json": { "example": { "notice": "example", "purged": 1 }, "schema": { "properties": { "notice": { "type": "string" }, "purged": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Encryption purge history", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/export": { "get": { "description": "full JSON export (`projects`, `tasks`, `labels`, `views`, `reminders`, `sections`, `comments`, `time_entries`, `places`, `themes` (your custom themes, [Themes](https://open-todo.app/docs/themes/)), `objectives` (your quarterly and weekly [objectives](https://open-todo.app/docs/objectives/), deleted ones included), `memory` (what the [assistant remembers](https://open-todo.app/docs/assistant-memory/), deleted items included; only for a session or a `full` or `admin` token), `user_prefs`, `workspaces` (each with your role; for those you own, the members' ids and roles and the groups), `encryption`, and `userId`, the exporting account), every task with its `origin` (`null` when unset), including deleted items and the projects shared with you (with `role` and `owner_id`); never contains audit events or push subscriptions; reminders are personal, so only your own", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getExport", "responses": { "200": { "content": { "application/json": { "example": { "attachments": [ {} ], "comments": [ {} ], "encryption": { "createdAt": 1794906000000, "iterations": 1, "kdf": 1, "salt": "example", "updatedAt": 1794906000000, "version": 1, "wrappedByPassphrase": "example", "wrappedByRecovery": "example" }, "exportedAt": "example", "format": "example", "habit_tallies": [ {} ], "memory": [ {} ], "places": [ {} ], "project_prefs": [ {} ], "review": [ {} ], "themes": [ {} ], "time_entries": [ {} ], "userId": "00000000-0000-4000-8000-000000000001", "user_prefs": [ {} ], "version": 1, "workspaces": [ {} ] }, "schema": { "properties": { "attachments": { "items": { "type": "object" }, "type": "array" }, "comments": { "items": { "type": "object" }, "type": "array" }, "encryption": { "properties": { "createdAt": { "type": "number" }, "iterations": { "type": "number" }, "kdf": { "type": "number" }, "salt": { "type": "string" }, "updatedAt": { "type": "number" }, "version": { "type": "number" }, "wrappedByPassphrase": { "type": "string" }, "wrappedByRecovery": { "type": "string" } }, "type": [ "object", "null" ] }, "exportedAt": { "type": "string" }, "format": { "type": "string" }, "habit_tallies": { "items": { "type": "object" }, "type": "array" }, "memory": { "items": { "type": "object" }, "type": "array" }, "places": { "items": { "type": "object" }, "type": "array" }, "project_prefs": { "items": { "type": "object" }, "type": "array" }, "review": { "items": { "type": "object" }, "type": "array" }, "themes": { "items": { "type": "object" }, "type": "array" }, "time_entries": { "items": { "type": "object" }, "type": "array" }, "userId": { "type": "string" }, "user_prefs": { "items": { "type": "object" }, "type": "array" }, "version": { "type": "number" }, "workspaces": { "items": { "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get export", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/export/archive": { "get": { "description": "Only the server's owner. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#hosted-servers" }, "operationId": "getExportArchive", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get export archive", "tags": [ "Hosted servers" ], "x-opentodo-policy": "owner-only.credential.recent" } }, "/api/v1/fields": { "get": { "description": "same shape for custom field definitions, see [Custom fields](https://open-todo.app/docs/api/#custom-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getFields", "responses": { "200": { "content": { "application/json": { "example": { "fields": [ { "created_at": 1794906000000, "deleted_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "options": "example", "position": 1, "project_id": "00000000-0000-4000-8000-000000000001", "type": "example" } ] }, "schema": { "properties": { "fields": { "items": { "$ref": "#/components/schemas/Field" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List fields", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "same shape for custom field definitions, see [Custom fields](https://open-todo.app/docs/api/#custom-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postFields", "requestBody": { "content": { "application/json": { "example": { "created_at": 1794906000000, "deleted_at": 1794906000000, "name": "Ada", "options": "example", "position": 1, "project_id": "00000000-0000-4000-8000-000000000001", "type": "example" }, "schema": { "properties": { "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "options": { "type": "string" }, "position": { "type": "number" }, "project_id": { "description": "An id: a UUID, or for some entities a name-based id.", "type": "string" }, "type": { "type": "string" } }, "required": [ "project_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "created_at": 1794906000000, "deleted_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "options": "example", "position": 1, "project_id": "00000000-0000-4000-8000-000000000001", "type": "example" }, "schema": { "$ref": "#/components/schemas/Field" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a field", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/fields/{id}": { "delete": { "description": "same shape for custom field definitions, see [Custom fields](https://open-todo.app/docs/api/#custom-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteFieldsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a field", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "same shape for custom field definitions, see [Custom fields](https://open-todo.app/docs/api/#custom-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getFieldsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "created_at": 1794906000000, "deleted_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "options": "example", "position": 1, "project_id": "00000000-0000-4000-8000-000000000001", "type": "example" }, "schema": { "$ref": "#/components/schemas/Field" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a field", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "same shape for custom field definitions, see [Custom fields](https://open-todo.app/docs/api/#custom-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "patchFieldsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "created_at": 1794906000000, "deleted_at": 1794906000000, "name": "Ada", "options": "example", "position": 1, "project_id": "00000000-0000-4000-8000-000000000001", "type": "example" }, "schema": { "properties": { "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "options": { "type": "string" }, "position": { "type": "number" }, "project_id": { "description": "An id: a UUID, or for some entities a name-based id.", "type": "string" }, "type": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "created_at": 1794906000000, "deleted_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "options": "example", "position": 1, "project_id": "00000000-0000-4000-8000-000000000001", "type": "example" }, "schema": { "$ref": "#/components/schemas/Field" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a field", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/frames": { "get": { "description": "`{frames: [{id, title, weekdays, start, end, color, source, from_date, until_date, position, created_at, encrypted}]}` in their order; `encrypted` is true when the title is ciphertext", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-frames" }, "operationId": "getFrames", "responses": { "200": { "content": { "application/json": { "example": { "frames": [ {} ] }, "schema": { "properties": { "frames": { "items": { "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List frames", "tags": [ "Calendar frames" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{title, weekdays, start?, end?, color?, source?, from_date?, until_date?, position?}` → `201` frame (defaults 09:00 to 10:00, `#64748b`, no source); a 51st live frame answers `422 limit_reached`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-frames" }, "operationId": "postFrames", "requestBody": { "content": { "application/json": { "example": { "color": "#3b82f6", "end": "example", "from_date": "2026-11-20", "position": "example", "source": "example", "start": "example", "title": "Buy paint for the fence", "until_date": "2026-11-20", "weekdays": "example" }, "schema": { "properties": { "color": { "type": "string" }, "end": { "type": "string" }, "from_date": { "type": "string" }, "position": { "type": "string" }, "source": { "type": "string" }, "start": { "type": "string" }, "title": { "type": "string" }, "until_date": { "type": "string" }, "weekdays": { "type": "string" } }, "required": [ "color", "end", "from_date", "position", "source", "start", "title", "until_date", "weekdays" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "encrypted": false, "id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "encrypted": { "type": "boolean" }, "id": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a frame", "tags": [ "Calendar frames" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/frames/{id}": { "delete": { "description": "`PATCH` takes the same fields, checked against the merged frame → `200` frame; `DELETE` → `204` (a tombstone); an unknown or deleted id answers `404 not_found`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-frames" }, "operationId": "deleteFramesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a frame", "tags": [ "Calendar frames" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "`PATCH` takes the same fields, checked against the merged frame → `200` frame; `DELETE` → `204` (a tombstone); an unknown or deleted id answers `404 not_found`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-frames" }, "operationId": "getFramesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "encrypted": false, "id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "encrypted": { "type": "boolean" }, "id": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a frame", "tags": [ "Calendar frames" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`PATCH` takes the same fields, checked against the merged frame → `200` frame; `DELETE` → `204` (a tombstone); an unknown or deleted id answers `404 not_found`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-frames" }, "operationId": "patchFramesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "color": "#3b82f6", "end": "example", "from_date": "2026-11-20", "position": "example", "source": "example", "start": "example", "title": "Buy paint for the fence", "until_date": "2026-11-20", "weekdays": "example" }, "schema": { "properties": { "color": { "type": "string" }, "end": { "type": "string" }, "from_date": { "type": "string" }, "position": { "type": "string" }, "source": { "type": "string" }, "start": { "type": "string" }, "title": { "type": "string" }, "until_date": { "type": "string" }, "weekdays": { "type": "string" } }, "required": [ "color", "end", "from_date", "position", "source", "start", "title", "until_date", "weekdays" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "encrypted": false, "id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "encrypted": { "type": "boolean" }, "id": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a frame", "tags": [ "Calendar frames" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/habits": { "get": { "description": "your open habits with their numbers (`list_habits`' shape); `graduated=true`, `timezone`; see [Habits](https://open-todo.app/docs/api/#habits)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getHabits", "responses": { "200": { "content": { "application/json": { "example": { "habits": [ { "at_risk": false, "back_on_track": false, "best_streak": 0, "current_date": "2026-11-17", "day_part": null, "graduated_at": null, "id": "00000000-0000-4000-8000-000000000012", "kept": 0, "kept_days": 0, "kept_of": 0, "overdue": false, "pending": true, "project_id": null, "rule": "every day", "streak": 0, "strength": 0, "untrusted_text": { "anchor": "", "tiny": "", "title": "Stretch" } } ], "server_time": "2026-11-17T09:00:00Z", "timezone": "", "today": "2026-11-17" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List habits", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/habits/{id}": { "get": { "description": "one habit and its scheduled days with their states and notes (`get_habit`'s shape); `from`, `to` (at most 400 days apart, the last 31 by default), `timezone`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getHabitsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "days": [ { "date": "2026-11-17", "state": "pending" } ], "from": "2026-10-18", "habit": { "at_risk": false, "back_on_track": false, "best_streak": 0, "current_date": "2026-11-17", "day_part": null, "graduated_at": null, "id": "00000000-0000-4000-8000-000000000012", "kept": 0, "kept_days": 0, "kept_of": 0, "overdue": false, "pending": true, "project_id": null, "rule": "every day", "streak": 0, "strength": 0, "untrusted_text": { "anchor": "", "tiny": "", "title": "Stretch" } }, "server_time": "2026-11-17T09:00:00Z", "timezone": "", "to": "2026-11-17", "today": "2026-11-17" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a habit", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/habits/{id}/log": { "post": { "description": "`{state, date?, note?, timezone?}` logs a day as the app does, or `{amount}` / `{set_amount}` for an amount habit → the habit with its days", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postHabitsByIdLog", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Habit log", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/health": { "get": { "description": "The same answer as `/healthz`, under the API path, for reverse proxies and platforms that answer `/healthz` themselves (Pomerium, Google Cloud Run). The mobile apps check a server here first, then at `/healthz`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "getHealth", "responses": { "200": { "content": { "application/json": { "example": { "app_sign_in": false, "status": "example", "version": "example" }, "schema": { "properties": { "app_sign_in": { "type": "boolean" }, "status": { "type": "string" }, "version": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get health", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/import": { "post": { "description": "multipart `file` + options → 202 `{job}`; the import runs in the background", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postImport", "responses": { "202": { "content": { "application/json": { "example": { "job": { "createdAt": 1794906000000, "errors": [ { "reason": "example", "row": 1, "sourceId": "00000000-0000-4000-8000-000000000001" } ], "finishedAt": 1794906000000, "format": "example", "id": "00000000-0000-4000-8000-000000000001", "message": "example", "options": { "columns": {}, "duplicates": "example", "errors": "example", "existing": "example", "format": "example", "sections": "example", "targetProject": "example", "timeZone": "Europe/Rome", "workspace": "example" }, "status": "example", "totals": { "attachments": 1, "create": 1, "deadlines": 1, "entities": 1, "error": 1, "fields": 1, "newLabels": 1, "newProjects": 1, "newSections": 1, "notes": 1, "ops": 1, "places": 1, "possibleDuplicates": 1, "recurring": 1, "refused": 1, "reminders": 1, "rows": 1, "skip": 1, "timeEntries": 1, "update": 1, "warnings": 1, "written": 1 }, "undoneAt": 1794906000000, "viewHints": [ { "projectId": "00000000-0000-4000-8000-000000000001", "view": "example" } ] } }, "schema": { "properties": { "job": { "properties": { "createdAt": { "type": "number" }, "errors": { "items": { "properties": { "reason": { "type": "string" }, "row": { "type": "number" }, "sourceId": { "type": "string" } }, "type": "object" }, "type": "array" }, "finishedAt": { "type": [ "number", "null" ] }, "format": { "type": "string" }, "id": { "type": "string" }, "message": { "type": "string" }, "options": { "properties": { "columns": { "type": "object" }, "duplicates": { "type": "string" }, "errors": { "type": "string" }, "existing": { "type": "string" }, "format": { "type": "string" }, "sections": { "type": "string" }, "targetProject": { "type": "string" }, "timeZone": { "type": "string" }, "workspace": { "type": "string" } }, "type": "object" }, "status": { "type": "string" }, "totals": { "properties": { "attachments": { "type": "number" }, "create": { "type": "number" }, "deadlines": { "type": "number" }, "entities": { "type": "number" }, "error": { "type": "number" }, "fields": { "type": "number" }, "newLabels": { "type": "number" }, "newProjects": { "type": "number" }, "newSections": { "type": "number" }, "notes": { "type": "number" }, "ops": { "type": "number" }, "places": { "type": "number" }, "possibleDuplicates": { "type": "number" }, "recurring": { "type": "number" }, "refused": { "type": "number" }, "reminders": { "type": "number" }, "rows": { "type": "number" }, "skip": { "type": "number" }, "timeEntries": { "type": "number" }, "update": { "type": "number" }, "warnings": { "type": "number" }, "written": { "type": "number" } }, "type": "object" }, "undoneAt": { "type": [ "number", "null" ] }, "viewHints": { "items": { "properties": { "projectId": { "type": "string" }, "view": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Accepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Import", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/import/jobs": { "get": { "description": "`{jobs:[…]}`, newest first (last 50)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getImportJobs", "responses": { "200": { "content": { "application/json": { "example": { "jobs": [ { "createdAt": 1794906000000, "errors": [ { "reason": "example", "row": 1, "sourceId": "00000000-0000-4000-8000-000000000001" } ], "finishedAt": 1794906000000, "format": "example", "id": "00000000-0000-4000-8000-000000000001", "message": "example", "options": { "columns": {}, "duplicates": "example", "errors": "example", "existing": "example", "format": "example", "sections": "example", "targetProject": "example", "timeZone": "Europe/Rome", "workspace": "example" }, "status": "example", "totals": { "attachments": 1, "create": 1, "deadlines": 1, "entities": 1, "error": 1, "fields": 1, "newLabels": 1, "newProjects": 1, "newSections": 1, "notes": 1, "ops": 1, "places": 1, "possibleDuplicates": 1, "recurring": 1, "refused": 1, "reminders": 1, "rows": 1, "skip": 1, "timeEntries": 1, "update": 1, "warnings": 1, "written": 1 }, "undoneAt": 1794906000000, "viewHints": [ { "projectId": "00000000-0000-4000-8000-000000000001", "view": "example" } ] } ] }, "schema": { "properties": { "jobs": { "items": { "properties": { "createdAt": { "type": "number" }, "errors": { "items": { "properties": { "reason": { "type": "string" }, "row": { "type": "number" }, "sourceId": { "type": "string" } }, "type": "object" }, "type": "array" }, "finishedAt": { "type": [ "number", "null" ] }, "format": { "type": "string" }, "id": { "type": "string" }, "message": { "type": "string" }, "options": { "properties": { "columns": { "type": "object" }, "duplicates": { "type": "string" }, "errors": { "type": "string" }, "existing": { "type": "string" }, "format": { "type": "string" }, "sections": { "type": "string" }, "targetProject": { "type": "string" }, "timeZone": { "type": "string" }, "workspace": { "type": "string" } }, "type": "object" }, "status": { "type": "string" }, "totals": { "properties": { "attachments": { "type": "number" }, "create": { "type": "number" }, "deadlines": { "type": "number" }, "entities": { "type": "number" }, "error": { "type": "number" }, "fields": { "type": "number" }, "newLabels": { "type": "number" }, "newProjects": { "type": "number" }, "newSections": { "type": "number" }, "notes": { "type": "number" }, "ops": { "type": "number" }, "places": { "type": "number" }, "possibleDuplicates": { "type": "number" }, "recurring": { "type": "number" }, "refused": { "type": "number" }, "reminders": { "type": "number" }, "rows": { "type": "number" }, "skip": { "type": "number" }, "timeEntries": { "type": "number" }, "update": { "type": "number" }, "warnings": { "type": "number" }, "written": { "type": "number" } }, "type": "object" }, "undoneAt": { "type": [ "number", "null" ] }, "viewHints": { "items": { "properties": { "projectId": { "type": "string" }, "view": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List import jobs", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/import/jobs/{id}": { "get": { "description": "`{job}` with status, counts and row errors", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getImportJobsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "job": { "createdAt": 1794906000000, "errors": [ { "reason": "example", "row": 1, "sourceId": "00000000-0000-4000-8000-000000000001" } ], "finishedAt": 1794906000000, "format": "example", "id": "00000000-0000-4000-8000-000000000001", "message": "example", "options": { "columns": {}, "duplicates": "example", "errors": "example", "existing": "example", "format": "example", "sections": "example", "targetProject": "example", "timeZone": "Europe/Rome", "workspace": "example" }, "status": "example", "totals": { "attachments": 1, "create": 1, "deadlines": 1, "entities": 1, "error": 1, "fields": 1, "newLabels": 1, "newProjects": 1, "newSections": 1, "notes": 1, "ops": 1, "places": 1, "possibleDuplicates": 1, "recurring": 1, "refused": 1, "reminders": 1, "rows": 1, "skip": 1, "timeEntries": 1, "update": 1, "warnings": 1, "written": 1 }, "undoneAt": 1794906000000, "viewHints": [ { "projectId": "00000000-0000-4000-8000-000000000001", "view": "example" } ] } }, "schema": { "properties": { "job": { "properties": { "createdAt": { "type": "number" }, "errors": { "items": { "properties": { "reason": { "type": "string" }, "row": { "type": "number" }, "sourceId": { "type": "string" } }, "type": "object" }, "type": "array" }, "finishedAt": { "type": [ "number", "null" ] }, "format": { "type": "string" }, "id": { "type": "string" }, "message": { "type": "string" }, "options": { "properties": { "columns": { "type": "object" }, "duplicates": { "type": "string" }, "errors": { "type": "string" }, "existing": { "type": "string" }, "format": { "type": "string" }, "sections": { "type": "string" }, "targetProject": { "type": "string" }, "timeZone": { "type": "string" }, "workspace": { "type": "string" } }, "type": "object" }, "status": { "type": "string" }, "totals": { "properties": { "attachments": { "type": "number" }, "create": { "type": "number" }, "deadlines": { "type": "number" }, "entities": { "type": "number" }, "error": { "type": "number" }, "fields": { "type": "number" }, "newLabels": { "type": "number" }, "newProjects": { "type": "number" }, "newSections": { "type": "number" }, "notes": { "type": "number" }, "ops": { "type": "number" }, "places": { "type": "number" }, "possibleDuplicates": { "type": "number" }, "recurring": { "type": "number" }, "refused": { "type": "number" }, "reminders": { "type": "number" }, "rows": { "type": "number" }, "skip": { "type": "number" }, "timeEntries": { "type": "number" }, "update": { "type": "number" }, "warnings": { "type": "number" }, "written": { "type": "number" } }, "type": "object" }, "undoneAt": { "type": [ "number", "null" ] }, "viewHints": { "items": { "properties": { "projectId": { "type": "string" }, "view": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a import job", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/import/jobs/{id}/undo": { "post": { "description": "tombstone everything the job created → `{job}` (status `undone`); idempotent", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postImportJobsByIdUndo", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "job": { "createdAt": 1794906000000, "errors": [ { "reason": "example", "row": 1, "sourceId": "00000000-0000-4000-8000-000000000001" } ], "finishedAt": 1794906000000, "format": "example", "id": "00000000-0000-4000-8000-000000000001", "message": "example", "options": { "columns": {}, "duplicates": "example", "errors": "example", "existing": "example", "format": "example", "sections": "example", "targetProject": "example", "timeZone": "Europe/Rome", "workspace": "example" }, "status": "example", "totals": { "attachments": 1, "create": 1, "deadlines": 1, "entities": 1, "error": 1, "fields": 1, "newLabels": 1, "newProjects": 1, "newSections": 1, "notes": 1, "ops": 1, "places": 1, "possibleDuplicates": 1, "recurring": 1, "refused": 1, "reminders": 1, "rows": 1, "skip": 1, "timeEntries": 1, "update": 1, "warnings": 1, "written": 1 }, "undoneAt": 1794906000000, "viewHints": [ { "projectId": "00000000-0000-4000-8000-000000000001", "view": "example" } ] } }, "schema": { "properties": { "job": { "properties": { "createdAt": { "type": "number" }, "errors": { "items": { "properties": { "reason": { "type": "string" }, "row": { "type": "number" }, "sourceId": { "type": "string" } }, "type": "object" }, "type": "array" }, "finishedAt": { "type": [ "number", "null" ] }, "format": { "type": "string" }, "id": { "type": "string" }, "message": { "type": "string" }, "options": { "properties": { "columns": { "type": "object" }, "duplicates": { "type": "string" }, "errors": { "type": "string" }, "existing": { "type": "string" }, "format": { "type": "string" }, "sections": { "type": "string" }, "targetProject": { "type": "string" }, "timeZone": { "type": "string" }, "workspace": { "type": "string" } }, "type": "object" }, "status": { "type": "string" }, "totals": { "properties": { "attachments": { "type": "number" }, "create": { "type": "number" }, "deadlines": { "type": "number" }, "entities": { "type": "number" }, "error": { "type": "number" }, "fields": { "type": "number" }, "newLabels": { "type": "number" }, "newProjects": { "type": "number" }, "newSections": { "type": "number" }, "notes": { "type": "number" }, "ops": { "type": "number" }, "places": { "type": "number" }, "possibleDuplicates": { "type": "number" }, "recurring": { "type": "number" }, "refused": { "type": "number" }, "reminders": { "type": "number" }, "rows": { "type": "number" }, "skip": { "type": "number" }, "timeEntries": { "type": "number" }, "update": { "type": "number" }, "warnings": { "type": "number" }, "written": { "type": "number" } }, "type": "object" }, "undoneAt": { "type": [ "number", "null" ] }, "viewHints": { "items": { "properties": { "projectId": { "type": "string" }, "view": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Import job undo", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/import/preview": { "post": { "description": "multipart `file` + options → dry run `{format, totals, rows, …}`, see [Import](https://open-todo.app/docs/api/#import)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postImportPreview", "responses": { "200": { "content": { "application/json": { "example": { "columns": { "available": [ "example" ], "ignored": [ "example" ], "recognised": [ "example" ], "roles": {} }, "detected": "example", "format": "example", "notes": [ "example" ], "options": { "columns": {}, "duplicates": "example", "errors": "example", "existing": "example", "format": "example", "sections": "example", "targetProject": "example", "timeZone": "Europe/Rome", "workspace": "example" }, "rows": [ { "file": "example", "kind": "example", "outcome": "example", "project": "example", "reason": "example", "row": 1, "sourceId": "00000000-0000-4000-8000-000000000001", "title": "Buy paint for the fence", "warnings": [ "example" ] } ], "template": { "day": "example" }, "totals": { "attachments": 1, "create": 1, "deadlines": 1, "entities": 1, "error": 1, "fields": 1, "newLabels": 1, "newProjects": 1, "newSections": 1, "notes": 1, "ops": 1, "places": 1, "possibleDuplicates": 1, "recurring": 1, "refused": 1, "reminders": 1, "rows": 1, "skip": 1, "timeEntries": 1, "update": 1, "warnings": 1, "written": 1 }, "truncated": false, "version": 1, "viewHints": [ { "projectId": "00000000-0000-4000-8000-000000000001", "view": "example" } ] }, "schema": { "properties": { "columns": { "properties": { "available": { "items": { "type": "string" }, "type": "array" }, "ignored": { "items": { "type": "string" }, "type": "array" }, "recognised": { "items": { "type": "string" }, "type": "array" }, "roles": { "type": "object" } }, "type": [ "object", "null" ] }, "detected": { "type": "string" }, "format": { "type": "string" }, "notes": { "items": { "type": "string" }, "type": "array" }, "options": { "properties": { "columns": { "type": "object" }, "duplicates": { "type": "string" }, "errors": { "type": "string" }, "existing": { "type": "string" }, "format": { "type": "string" }, "sections": { "type": "string" }, "targetProject": { "type": "string" }, "timeZone": { "type": "string" }, "workspace": { "type": "string" } }, "type": "object" }, "rows": { "items": { "properties": { "file": { "type": "string" }, "kind": { "type": "string" }, "outcome": { "type": "string" }, "project": { "type": "string" }, "reason": { "type": "string" }, "row": { "type": "number" }, "sourceId": { "type": "string" }, "title": { "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" }, "template": { "properties": { "day": { "type": "string" } }, "type": [ "object", "null" ] }, "totals": { "properties": { "attachments": { "type": "number" }, "create": { "type": "number" }, "deadlines": { "type": "number" }, "entities": { "type": "number" }, "error": { "type": "number" }, "fields": { "type": "number" }, "newLabels": { "type": "number" }, "newProjects": { "type": "number" }, "newSections": { "type": "number" }, "notes": { "type": "number" }, "ops": { "type": "number" }, "places": { "type": "number" }, "possibleDuplicates": { "type": "number" }, "recurring": { "type": "number" }, "refused": { "type": "number" }, "reminders": { "type": "number" }, "rows": { "type": "number" }, "skip": { "type": "number" }, "timeEntries": { "type": "number" }, "update": { "type": "number" }, "warnings": { "type": "number" }, "written": { "type": "number" } }, "type": "object" }, "truncated": { "type": "boolean" }, "version": { "type": "number" }, "viewHints": { "items": { "properties": { "projectId": { "type": "string" }, "view": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Import preview", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/import/todoist": { "post": { "description": "`{token}`, a Todoist API token → Todoist's sync answer (projects, sections, labels, tasks, comments) as JSON, which `/api/v1/import/preview` and `/api/v1/import` read like an uploaded file (format `json-items`); one request to Todoist through the outbound policy, the token never stored; 400 `invalid_token` when Todoist refuses it, 413 `too_large` over `OPENTODO_IMPORT_MAX_MB`, 502 `upstream_failed` when Todoist cannot be reached, 429 `rate_limited` (10 an hour); demo instances → 403 `demo_restricted`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postImportTodoist", "requestBody": { "content": { "application/json": { "example": { "token": "ot_example_token" }, "schema": { "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Import todoist", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/invitations": { "get": { "description": "`{invitations:[…]}`, see [Invitations](https://open-todo.app/docs/api/#invitations)\n\nThe owner and admins.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getInvitations", "responses": { "200": { "content": { "application/json": { "example": { "invitations": [ { "acceptedAt": 1794906000000, "acceptedBy": { "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" }, "createdAt": 1794906000000, "createdBy": "example", "createdByName": "Ada", "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "revokedAt": 1794906000000, "role": "member", "status": "example" } ] }, "schema": { "properties": { "invitations": { "items": { "properties": { "acceptedAt": { "type": [ "number", "null" ] }, "acceptedBy": { "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "createdAt": { "type": "number" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "revokedAt": { "type": [ "number", "null" ] }, "role": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List invitations", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "admins-only" }, "post": { "description": "`{email?, expiresInHours?, send?}` → 201 `{invitation, link, sent?}` (link shown once; `send` mails it to `email`)\n\nThe owner and admins. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postInvitations", "requestBody": { "content": { "application/json": { "example": { "email": "ada@example.com", "expiresInHours": 1, "send": false }, "schema": { "properties": { "email": { "type": "string" }, "expiresInHours": { "type": [ "number", "null" ] }, "send": { "type": "boolean" } }, "required": [ "email", "send" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "invitation": { "acceptedAt": 1794906000000, "acceptedBy": { "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" }, "createdAt": 1794906000000, "createdBy": "example", "createdByName": "Ada", "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "revokedAt": 1794906000000, "role": "member", "status": "example" }, "link": "example", "sent": false }, "schema": { "properties": { "invitation": { "properties": { "acceptedAt": { "type": [ "number", "null" ] }, "acceptedBy": { "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "createdAt": { "type": "number" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "revokedAt": { "type": [ "number", "null" ] }, "role": { "type": "string" }, "status": { "type": "string" } }, "type": [ "object", "null" ] }, "link": { "type": "string" }, "sent": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a invitation", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "admins-only.credential.recent" } }, "/api/v1/invitations/{id}": { "delete": { "description": "revoke a pending invitation → 204\n\nThe owner and admins. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "deleteInvitationsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a invitation", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "admins-only.credential" }, "get": { "description": "preview `{inviterName, email, expiresAt}` or 404 `invitation_invalid`, see [Invitations](https://open-todo.app/docs/api/#invitations)\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "getInvitationsByToken", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "email": "ada@example.com", "expiresAt": 1794906000000, "inviterName": "Ada" }, "schema": { "properties": { "email": { "type": [ "string", "null" ] }, "expiresAt": { "type": "number" }, "inviterName": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a invitation", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/issues/connections": { "get": { "description": "`{connections: [...]}`: `id`, `provider` (`github`, `gitlab`), `host`, `name`, `project_id` (null for the Inbox), `filter` (`{scope: \"assigned\"|\"repositories\", repositories, labels}`), `map_labels`, `enabled`, `interval_minutes`, `state` (`off`, `pending`, `ok`, `failed`, `stopped`), `next_poll_at`, `last_poll_at`, `last_success_at`, `last_error`, `last_error_at`, `stopped_reason`, `account_login`, `can_read_issues`, `last_run` (`{created, completed, reopened, renamed, unlinked, partial}`), `task_count`, `token_set`. Never the token.", "externalDocs": { "url": "https://open-todo.app/docs/api/#issue-connections" }, "operationId": "getIssuesConnections", "responses": { "200": { "content": { "application/json": { "example": { "connections": [ { "account_login": "example", "can_read_issues": false, "created_at": 1794906000000, "enabled": false, "filter": { "labels": [ "example" ], "repositories": [ "example" ], "scope": "full" }, "host": "example", "id": "00000000-0000-4000-8000-000000000001", "interval_minutes": 1, "last_error": "example", "last_error_at": 1794906000000, "last_poll_at": 1794906000000, "last_run": { "completed": 1, "created": 1, "partial": false, "renamed": 1, "reopened": 1, "unlinked": 1 }, "last_success_at": 1794906000000, "map_labels": false, "name": "Ada", "next_poll_at": 1794906000000, "project_id": "00000000-0000-4000-8000-000000000001", "provider": "example", "state": "example", "stopped_reason": "example", "task_count": 1, "token_set": false, "updated_at": 1794906000000 } ] }, "schema": { "properties": { "connections": { "items": { "properties": { "account_login": { "type": "string" }, "can_read_issues": { "type": [ "boolean", "null" ] }, "created_at": { "type": "number" }, "enabled": { "type": "boolean" }, "filter": { "properties": { "labels": { "items": { "type": "string" }, "type": "array" }, "repositories": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" } }, "type": "object" }, "host": { "type": "string" }, "id": { "type": "string" }, "interval_minutes": { "type": "number" }, "last_error": { "type": "string" }, "last_error_at": { "type": [ "number", "null" ] }, "last_poll_at": { "type": [ "number", "null" ] }, "last_run": { "properties": { "completed": { "type": "number" }, "created": { "type": "number" }, "partial": { "type": "boolean" }, "renamed": { "type": "number" }, "reopened": { "type": "number" }, "unlinked": { "type": "number" } }, "type": [ "object", "null" ] }, "last_success_at": { "type": [ "number", "null" ] }, "map_labels": { "type": "boolean" }, "name": { "type": "string" }, "next_poll_at": { "type": "number" }, "project_id": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "state": { "type": "string" }, "stopped_reason": { "type": "string" }, "task_count": { "type": "number" }, "token_set": { "type": "boolean" }, "updated_at": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List issues connections", "tags": [ "Issue connections" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{provider, host, token, name?, project_id?, filter?, map_labels?, interval_minutes?, enabled?}`; the token is checked at once; `201 {connection}`\n\nNeeds a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#issue-connections" }, "operationId": "postIssuesConnections", "requestBody": { "content": { "application/json": { "example": { "enabled": false, "filter": { "labels": [ "example" ], "repositories": [ "example" ], "scope": "full" }, "host": "example", "interval_minutes": 1, "map_labels": false, "name": "Ada", "project_id": "00000000-0000-4000-8000-000000000001", "provider": "example", "token": "ot_example_token" }, "schema": { "properties": { "enabled": { "type": [ "boolean", "null" ] }, "filter": { "properties": { "labels": { "items": { "type": "string" }, "type": "array" }, "repositories": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" } }, "required": [ "labels", "repositories", "scope" ], "type": [ "object", "null" ] }, "host": { "type": [ "string", "null" ] }, "interval_minutes": { "type": [ "number", "null" ] }, "map_labels": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "project_id": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "token": { "type": [ "string", "null" ] } }, "required": [ "project_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "connection": { "account_login": "example", "can_read_issues": false, "created_at": 1794906000000, "enabled": false, "filter": { "labels": [ "example" ], "repositories": [ "example" ], "scope": "full" }, "host": "example", "id": "00000000-0000-4000-8000-000000000001", "interval_minutes": 1, "last_error": "example", "last_error_at": 1794906000000, "last_poll_at": 1794906000000, "last_run": { "completed": 1, "created": 1, "partial": false, "renamed": 1, "reopened": 1, "unlinked": 1 }, "last_success_at": 1794906000000, "map_labels": false, "name": "Ada", "next_poll_at": 1794906000000, "project_id": "00000000-0000-4000-8000-000000000001", "provider": "example", "state": "example", "stopped_reason": "example", "task_count": 1, "token_set": false, "updated_at": 1794906000000 } }, "schema": { "properties": { "connection": { "properties": { "account_login": { "type": "string" }, "can_read_issues": { "type": [ "boolean", "null" ] }, "created_at": { "type": "number" }, "enabled": { "type": "boolean" }, "filter": { "properties": { "labels": { "items": { "type": "string" }, "type": "array" }, "repositories": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" } }, "type": "object" }, "host": { "type": "string" }, "id": { "type": "string" }, "interval_minutes": { "type": "number" }, "last_error": { "type": "string" }, "last_error_at": { "type": [ "number", "null" ] }, "last_poll_at": { "type": [ "number", "null" ] }, "last_run": { "properties": { "completed": { "type": "number" }, "created": { "type": "number" }, "partial": { "type": "boolean" }, "renamed": { "type": "number" }, "reopened": { "type": "number" }, "unlinked": { "type": "number" } }, "type": [ "object", "null" ] }, "last_success_at": { "type": [ "number", "null" ] }, "map_labels": { "type": "boolean" }, "name": { "type": "string" }, "next_poll_at": { "type": "number" }, "project_id": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "state": { "type": "string" }, "stopped_reason": { "type": "string" }, "task_count": { "type": "number" }, "token_set": { "type": "boolean" }, "updated_at": { "type": "number" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a issues connection", "tags": [ "Issue connections" ], "x-opentodo-policy": "signed-in.recent" } }, "/api/v1/issues/connections/{id}": { "delete": { "description": "`204`; the token is removed, the tasks stay", "externalDocs": { "url": "https://open-todo.app/docs/api/#issue-connections" }, "operationId": "deleteIssuesConnectionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a issues connection", "tags": [ "Issue connections" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "any of the fields above except `provider`; a `token` needs a fresh sign-in (`403 reauth_required`) and clears a stop for a token reason; `enabled: true` clears any stop", "externalDocs": { "url": "https://open-todo.app/docs/api/#issue-connections" }, "operationId": "patchIssuesConnectionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "enabled": false, "filter": { "labels": [ "example" ], "repositories": [ "example" ], "scope": "full" }, "host": "example", "interval_minutes": 1, "map_labels": false, "name": "Ada", "project_id": "00000000-0000-4000-8000-000000000001", "provider": "example", "token": "ot_example_token" }, "schema": { "properties": { "enabled": { "type": [ "boolean", "null" ] }, "filter": { "properties": { "labels": { "items": { "type": "string" }, "type": "array" }, "repositories": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" } }, "required": [ "labels", "repositories", "scope" ], "type": [ "object", "null" ] }, "host": { "type": [ "string", "null" ] }, "interval_minutes": { "type": [ "number", "null" ] }, "map_labels": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "project_id": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "token": { "type": [ "string", "null" ] } }, "required": [ "project_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "connection": { "account_login": "example", "can_read_issues": false, "created_at": 1794906000000, "enabled": false, "filter": { "labels": [ "example" ], "repositories": [ "example" ], "scope": "full" }, "host": "example", "id": "00000000-0000-4000-8000-000000000001", "interval_minutes": 1, "last_error": "example", "last_error_at": 1794906000000, "last_poll_at": 1794906000000, "last_run": { "completed": 1, "created": 1, "partial": false, "renamed": 1, "reopened": 1, "unlinked": 1 }, "last_success_at": 1794906000000, "map_labels": false, "name": "Ada", "next_poll_at": 1794906000000, "project_id": "00000000-0000-4000-8000-000000000001", "provider": "example", "state": "example", "stopped_reason": "example", "task_count": 1, "token_set": false, "updated_at": 1794906000000 } }, "schema": { "properties": { "connection": { "properties": { "account_login": { "type": "string" }, "can_read_issues": { "type": [ "boolean", "null" ] }, "created_at": { "type": "number" }, "enabled": { "type": "boolean" }, "filter": { "properties": { "labels": { "items": { "type": "string" }, "type": "array" }, "repositories": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" } }, "type": "object" }, "host": { "type": "string" }, "id": { "type": "string" }, "interval_minutes": { "type": "number" }, "last_error": { "type": "string" }, "last_error_at": { "type": [ "number", "null" ] }, "last_poll_at": { "type": [ "number", "null" ] }, "last_run": { "properties": { "completed": { "type": "number" }, "created": { "type": "number" }, "partial": { "type": "boolean" }, "renamed": { "type": "number" }, "reopened": { "type": "number" }, "unlinked": { "type": "number" } }, "type": [ "object", "null" ] }, "last_success_at": { "type": [ "number", "null" ] }, "map_labels": { "type": "boolean" }, "name": { "type": "string" }, "next_poll_at": { "type": "number" }, "project_id": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "state": { "type": "string" }, "stopped_reason": { "type": "string" }, "task_count": { "type": "number" }, "token_set": { "type": "boolean" }, "updated_at": { "type": "number" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a issues connection", "tags": [ "Issue connections" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/issues/connections/{id}/sync": { "post": { "description": "poll now: `{ok, run, reason?, connection}`; `409 connection_stopped`, `409 connection_disabled`, or `409 provider_rate_limited` before the provider's reset, all without a request to the provider", "externalDocs": { "url": "https://open-todo.app/docs/api/#issue-connections" }, "operationId": "postIssuesConnectionsByIdSync", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "connection": { "account_login": "example", "can_read_issues": false, "created_at": 1794906000000, "enabled": false, "filter": { "labels": [ "example" ], "repositories": [ "example" ], "scope": "full" }, "host": "example", "id": "00000000-0000-4000-8000-000000000001", "interval_minutes": 1, "last_error": "example", "last_error_at": 1794906000000, "last_poll_at": 1794906000000, "last_run": { "completed": 1, "created": 1, "partial": false, "renamed": 1, "reopened": 1, "unlinked": 1 }, "last_success_at": 1794906000000, "map_labels": false, "name": "Ada", "next_poll_at": 1794906000000, "project_id": "00000000-0000-4000-8000-000000000001", "provider": "example", "state": "example", "stopped_reason": "example", "task_count": 1, "token_set": false, "updated_at": 1794906000000 }, "ok": true, "reason": "example", "run": { "completed": 1, "created": 1, "partial": false, "renamed": 1, "reopened": 1, "unlinked": 1 } }, "schema": { "properties": { "connection": { "properties": { "account_login": { "type": "string" }, "can_read_issues": { "type": [ "boolean", "null" ] }, "created_at": { "type": "number" }, "enabled": { "type": "boolean" }, "filter": { "properties": { "labels": { "items": { "type": "string" }, "type": "array" }, "repositories": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" } }, "type": "object" }, "host": { "type": "string" }, "id": { "type": "string" }, "interval_minutes": { "type": "number" }, "last_error": { "type": "string" }, "last_error_at": { "type": [ "number", "null" ] }, "last_poll_at": { "type": [ "number", "null" ] }, "last_run": { "properties": { "completed": { "type": "number" }, "created": { "type": "number" }, "partial": { "type": "boolean" }, "renamed": { "type": "number" }, "reopened": { "type": "number" }, "unlinked": { "type": "number" } }, "type": [ "object", "null" ] }, "last_success_at": { "type": [ "number", "null" ] }, "map_labels": { "type": "boolean" }, "name": { "type": "string" }, "next_poll_at": { "type": "number" }, "project_id": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "state": { "type": "string" }, "stopped_reason": { "type": "string" }, "task_count": { "type": "number" }, "token_set": { "type": "boolean" }, "updated_at": { "type": "number" } }, "type": [ "object", "null" ] }, "ok": { "type": "boolean" }, "reason": { "type": "string" }, "run": { "properties": { "completed": { "type": "number" }, "created": { "type": "number" }, "partial": { "type": "boolean" }, "renamed": { "type": "number" }, "reopened": { "type": "number" }, "unlinked": { "type": "number" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Issues connection sync", "tags": [ "Issue connections" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/issues/connections/{id}/test": { "post": { "description": "ask the provider for the token's account: `{ok, login, can_read_issues, reason?, connection}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#issue-connections" }, "operationId": "postIssuesConnectionsByIdTest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "can_read_issues": false, "connection": { "account_login": "example", "can_read_issues": false, "created_at": 1794906000000, "enabled": false, "filter": { "labels": [ "example" ], "repositories": [ "example" ], "scope": "full" }, "host": "example", "id": "00000000-0000-4000-8000-000000000001", "interval_minutes": 1, "last_error": "example", "last_error_at": 1794906000000, "last_poll_at": 1794906000000, "last_run": { "completed": 1, "created": 1, "partial": false, "renamed": 1, "reopened": 1, "unlinked": 1 }, "last_success_at": 1794906000000, "map_labels": false, "name": "Ada", "next_poll_at": 1794906000000, "project_id": "00000000-0000-4000-8000-000000000001", "provider": "example", "state": "example", "stopped_reason": "example", "task_count": 1, "token_set": false, "updated_at": 1794906000000 }, "login": "example", "ok": true, "reason": "example" }, "schema": { "properties": { "can_read_issues": { "type": "boolean" }, "connection": { "properties": { "account_login": { "type": "string" }, "can_read_issues": { "type": [ "boolean", "null" ] }, "created_at": { "type": "number" }, "enabled": { "type": "boolean" }, "filter": { "properties": { "labels": { "items": { "type": "string" }, "type": "array" }, "repositories": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" } }, "type": "object" }, "host": { "type": "string" }, "id": { "type": "string" }, "interval_minutes": { "type": "number" }, "last_error": { "type": "string" }, "last_error_at": { "type": [ "number", "null" ] }, "last_poll_at": { "type": [ "number", "null" ] }, "last_run": { "properties": { "completed": { "type": "number" }, "created": { "type": "number" }, "partial": { "type": "boolean" }, "renamed": { "type": "number" }, "reopened": { "type": "number" }, "unlinked": { "type": "number" } }, "type": [ "object", "null" ] }, "last_success_at": { "type": [ "number", "null" ] }, "map_labels": { "type": "boolean" }, "name": { "type": "string" }, "next_poll_at": { "type": "number" }, "project_id": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "state": { "type": "string" }, "stopped_reason": { "type": "string" }, "task_count": { "type": "number" }, "token_set": { "type": "boolean" }, "updated_at": { "type": "number" } }, "type": [ "object", "null" ] }, "login": { "type": "string" }, "ok": { "type": "boolean" }, "reason": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Issues connection test", "tags": [ "Issue connections" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/labels": { "get": { "description": "same shape for labels, see [Label fields](https://open-todo.app/docs/api/#label-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getLabels", "responses": { "200": { "content": { "application/json": { "example": { "labels": [ { "color": "#f59e0b", "created_at": 1794906000024, "id": "00000000-0000-4000-8000-000000000004", "name": "outside", "position": 1794906000024 } ] }, "schema": { "properties": { "labels": { "items": { "$ref": "#/components/schemas/Label" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List labels", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`name`, `color`, `workspace_id` (a workspace id or exact name; absent or null for the default workspace; an existing label of that name in that workspace is returned with 200)", "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "operationId": "postLabels", "requestBody": { "content": { "application/json": { "example": { "color": "#f59e0b", "name": "errands" }, "schema": { "properties": { "color": { "type": "string" }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "group_by": { "type": "string" }, "manual_order": { "description": "Ids in their display order.", "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" }, "position": { "type": "number" }, "row_layout": { "type": "string" }, "sort_by": { "type": "string" }, "sort_dir": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "color": "#f59e0b", "created_at": 1794906000024, "id": "00000000-0000-4000-8000-000000000004", "name": "errands", "position": 1794906000024 }, "schema": { "$ref": "#/components/schemas/Label" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a label", "tags": [ "Agent tokens" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/labels/{id}": { "delete": { "description": "same shape for labels, see [Label fields](https://open-todo.app/docs/api/#label-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteLabelsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a label", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "same shape for labels, see [Label fields](https://open-todo.app/docs/api/#label-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getLabelsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "color": "#f59e0b", "created_at": 1794906000024, "id": "00000000-0000-4000-8000-000000000004", "name": "errands", "position": 1794906000024 }, "schema": { "$ref": "#/components/schemas/Label" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a label", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`name` (a name another label of the workspace has, ignoring case, is 400 `invalid`), `color`, `position`", "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "operationId": "patchLabelsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "outside" }, "schema": { "properties": { "color": { "type": "string" }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "group_by": { "type": "string" }, "manual_order": { "description": "Ids in their display order.", "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" }, "position": { "type": "number" }, "row_layout": { "type": "string" }, "sort_by": { "type": "string" }, "sort_dir": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "color": "#f59e0b", "created_at": 1794906000024, "id": "00000000-0000-4000-8000-000000000004", "name": "outside", "position": 1794906000024 }, "schema": { "$ref": "#/components/schemas/Label" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a label", "tags": [ "Agent tokens" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/maps/fonts/{fontstack}/{range}": { "get": { "description": "the glyphs of a font range (`.pbf` optional)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#maps" }, "operationId": "getMapsFontsByFontstackByRange", "parameters": [ { "in": "path", "name": "fontstack", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "range", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a maps font", "tags": [ "Maps" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/maps/reverse": { "get": { "description": "`?lat=…\u0026lon=…\u0026lang=en` → `{result: {name, address, lat, lon}}`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#maps" }, "operationId": "getMapsReverse", "responses": { "200": { "content": { "application/json": { "example": { "result": { "address": "example", "lat": 1, "lon": 1, "name": "Ada" } }, "schema": { "properties": { "result": { "properties": { "address": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "name": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get maps reverse", "tags": [ "Maps" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/maps/search": { "get": { "description": "`?q=…\u0026lang=en\u0026limit=5` (1–10) → `{results: [{name, address, lat, lon}]}`; 30 searches a minute per account with `/reverse` (`429 rate_limited`)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#maps" }, "operationId": "getMapsSearch", "responses": { "200": { "content": { "application/json": { "example": { "results": [ { "address": "example", "lat": 1, "lon": 1, "name": "Ada" } ] }, "schema": { "properties": { "results": { "items": { "properties": { "address": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get maps search", "tags": [ "Maps" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/maps/sprites/{file}": { "get": { "description": "the style's sprite sheet (`.png`) or its index (`.json`)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#maps" }, "operationId": "getMapsSpritesByFile", "parameters": [ { "in": "path", "name": "file", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a maps sprite", "tags": [ "Maps" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/maps/style": { "get": { "description": "the provider's style, rewritten to point at the routes below (cached for an hour)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#maps" }, "operationId": "getMapsStyle", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get maps style", "tags": [ "Maps" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/maps/tiles/{z}/{x}/{y}": { "get": { "description": "one vector tile (`.pbf` optional), cached on the server under `\u003cdata\u003e/cache/maps` and in the browser for a day\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#maps" }, "operationId": "getMapsTilesByZByXByY", "parameters": [ { "in": "path", "name": "z", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "x", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "y", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a maps tile", "tags": [ "Maps" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me": { "get": { "description": "`{user, mfa, encryption: {enabled, keyVersion}, minClientVersion, auth, agent_excluded_projects}`; `auth` describes the credential, see [Credential introspection](https://open-todo.app/docs/api/#credential-introspection); `agent_excluded_projects` lists the projects [kept away from assistants](https://open-todo.app/docs/api/#keeping-a-project-away-from-assistants); `day_parts` is the account's [Day parts](https://open-todo.app/docs/day-parts/) preference, `energy_levels` its Energy levels switch and `time_sectors` its [Time sectors](https://open-todo.app/docs/time-sectors/) switch, so a client can read quick-add lines like the app; `closed_list` is `{limit, focus_date, focus, slots_date, slots}`, the account's [Today limit](https://open-todo.app/docs/today-limit/) (0 = off) and the dates and task ids of today's focus and taken slots as stored, so a client can fill Today's slots like the app (ids and dates only). The owner's session also gets `config_warnings: [{variable, message, ignored?}]`, configuration problems the server started despite (an invalid `OPENTODO_TRUSTED_PROXIES` entry, outgoing email without `OPENTODO_BASE_URL`), empty when there are none; admins, members and tokens never get the field", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getMe", "responses": { "200": { "content": { "application/json": { "example": { "agent_excluded_projects": [], "attachments": { "enabled": true, "max_file_bytes": 26214400, "quota_bytes": 1073741824, "used_bytes": 0 }, "auth": { "method": "session", "scope": "full" }, "automations": { "enabled": true, "paused": false }, "closed_list": { "focus": "", "focus_date": "", "limit": 0, "slots": "", "slots_date": "" }, "config_warnings": [], "day_parts": false, "encryption": { "enabled": false, "keyVersion": 0 }, "energy_levels": false, "maps": true, "mfa": { "enrolled": false, "policy": "none", "recoveryCodesRemaining": 0, "required": false, "restricted": false }, "minClientVersion": 1, "speech": { "connected": false }, "time_sectors": false, "user": { "createdAt": 1794906000002, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "owner" } }, "schema": { "properties": { "agent_excluded_projects": { "items": { "type": "string" }, "type": "array" }, "attachments": { "type": "object" }, "auth": { "type": "object" }, "automations": { "properties": { "enabled": { "type": "boolean" }, "paused": { "type": "boolean" } }, "type": "object" }, "closed_list": { "properties": { "focus": { "type": "string" }, "focus_date": { "type": "string" }, "limit": { "type": "number" }, "slots": { "type": "string" }, "slots_date": { "type": "string" } }, "type": "object" }, "config_warnings": { "items": { "properties": { "ignored": { "items": { "type": "string" }, "type": "array" }, "message": { "type": "string" }, "variable": { "type": "string" } }, "type": "object" }, "type": "array" }, "day_parts": { "type": "boolean" }, "encryption": { "properties": { "enabled": { "type": "boolean" }, "keyVersion": { "type": "number" } }, "type": "object" }, "energy_levels": { "type": "boolean" }, "maps": { "type": "boolean" }, "mfa": { "properties": { "enrolled": { "type": "boolean" }, "policy": { "type": "string" }, "recoveryCodesRemaining": { "type": "number" }, "required": { "type": "boolean" }, "restricted": { "type": "boolean" } }, "type": [ "object", "null" ] }, "minClientVersion": { "type": "number" }, "speech": { "type": "object" }, "time_sectors": { "type": "boolean" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get me", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/activity": { "get": { "description": "`{events:[…]}`: your own access events, last 90 days, at most 100", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getMeActivity", "responses": { "200": { "content": { "application/json": { "example": { "events": [ { "actorEmail": "ada@example.com", "actorId": "00000000-0000-4000-8000-000000000001", "details": {}, "hash": "example", "id": 1, "ip": "example", "name": "Ada", "outcome": "example", "targetEmail": "ada@example.com", "targetId": "00000000-0000-4000-8000-000000000001", "ts": 1794906000000, "userAgent": "example" } ] }, "schema": { "properties": { "events": { "items": { "properties": { "actorEmail": { "type": [ "string", "null" ] }, "actorId": { "type": [ "string", "null" ] }, "details": { "type": "object" }, "hash": { "type": [ "string", "null" ] }, "id": { "type": "number" }, "ip": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "outcome": { "type": "string" }, "targetEmail": { "type": [ "string", "null" ] }, "targetId": { "type": [ "string", "null" ] }, "ts": { "type": "number" }, "userAgent": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get me activity", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/agent-access": { "get": { "description": "`{allow_writes, owner_allows_writes, mcp_enabled}`: your \"Allow AI assistants to make changes\" switch; `read` and `agent` tokens → 403 `insufficient_scope`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getMeAgentAccess", "responses": { "200": { "content": { "application/json": { "example": { "allow_writes": false, "mcp_enabled": false, "owner_allows_writes": false }, "schema": { "properties": { "allow_writes": { "type": "boolean" }, "mcp_enabled": { "type": "boolean" }, "owner_allows_writes": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get me agent access", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.full-tokens" }, "put": { "description": "`{allow_writes: boolean}` → same shape; recorded as `settings.changed` (`agent.writes`); anything else → 400 `invalid_input`; demo instances → 403 `demo_restricted`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "putMeAgentAccess", "responses": { "200": { "content": { "application/json": { "example": { "allow_writes": false, "mcp_enabled": false, "owner_allows_writes": false }, "schema": { "properties": { "allow_writes": { "type": "boolean" }, "mcp_enabled": { "type": "boolean" }, "owner_allows_writes": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update me agent access", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/app-sign-in": { "post": { "description": "`{query, allow}` (the confirmation's answer; `query` is the sign-in request) → `{redirect}`: `opentodo://signed-in` with `code` and `state` on allow, with `error=access_denied` and `state` otherwise; recorded as `mcp_oauth.granted` with `oauth_client_id` `opentodo-app`\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#app-sign-in" }, "operationId": "postMeAppSignIn", "requestBody": { "content": { "application/json": { "example": { "allow": false, "query": "example" }, "schema": { "properties": { "allow": { "type": "boolean" }, "query": { "type": "string" } }, "required": [ "allow", "query" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "redirect": "example" }, "schema": { "properties": { "redirect": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Me app sign in", "tags": [ "App sign-in" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/me/apps": { "get": { "description": "`{apps:[{id, device, createdAt, lastUsedAt}]}`: the signed-in apps, most recently used first, shown with the sessions in Settings → Account", "externalDocs": { "url": "https://open-todo.app/docs/api/#app-sign-in" }, "operationId": "getMeApps", "responses": { "200": { "content": { "application/json": { "example": { "apps": [ {} ] }, "schema": { "properties": { "apps": { "items": { "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List me apps", "tags": [ "App sign-in" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/apps/{id}": { "delete": { "description": "204: signs that app out; its next request gets 401; another person's or an unknown id → 404 `not_found`; recorded as `mcp_oauth.revoked`", "externalDocs": { "url": "https://open-todo.app/docs/api/#app-sign-in" }, "operationId": "deleteMeAppsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a me app", "tags": [ "App sign-in" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/assistant": { "get": { "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "operationId": "getMeAssistant", "responses": { "200": { "content": { "application/json": { "example": { "allow_member_keys": false, "anthropic_models": [ "claude-opus-5-5" ], "available": false, "cap_member_keys": false, "consented": false, "disclosure_notice": false, "disclosure_version": 6, "enabled": false, "fields": [ "task titles and descriptions" ], "images": false, "member_providers": [ "anthropic" ], "memory_notice": false, "mode": "", "model": "claude-opus-5-5", "operator_key_set": false, "own_key_in_use": false, "own_key_set": false, "own_provider": null, "provider": "anthropic", "provider_label": "Anthropic (Claude)", "reason": "disabled", "routines_consented": false, "server_model": "claude-opus-5-5", "server_own_key_set": false, "server_provider": "anthropic", "server_provider_label": "Anthropic (Claude)", "source": "server" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get me assistant", "tags": [ "In-app assistant" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "operationId": "putMeAssistant", "requestBody": { "content": { "application/json": { "example": { "consent": false, "own_key": "example", "own_model": "example", "own_provider": "example", "provider": "example", "routines": false }, "schema": { "properties": { "consent": { "type": [ "boolean", "null" ] }, "own_key": { "type": [ "string", "null" ] }, "own_model": { "type": [ "string", "null" ] }, "own_provider": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "routines": { "type": [ "boolean", "null" ] } }, "required": [ "provider" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update me assistant", "tags": [ "In-app assistant" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/assistant/disclosure-seen": { "post": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "operationId": "postMeAssistantDisclosureSeen", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Me assistant disclosure seen", "tags": [ "In-app assistant" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/assistant/test": { "post": { "description": "Needs a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "operationId": "postMeAssistantTest", "requestBody": { "content": { "application/json": { "example": { "key": "example", "model": "example", "provider": "example" }, "schema": { "properties": { "key": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "code": "example", "message": "example", "ok": true, "status": 1 }, "schema": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "ok": { "type": "boolean" }, "status": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Me assistant test", "tags": [ "In-app assistant" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/me/assistant/usage": { "get": { "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "operationId": "getMeAssistantUsage", "responses": { "200": { "content": { "application/json": { "example": { "drafts": { "calls": 1, "input_tokens": 1, "output_tokens": 1, "total_tokens": 1 }, "routines": { "calls": 1, "input_tokens": 1, "output_tokens": 1, "total_tokens": 1 } }, "schema": { "properties": { "drafts": { "properties": { "calls": { "type": "number" }, "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "type": "object" }, "routines": { "properties": { "calls": { "type": "number" }, "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" }, "total_tokens": { "type": "number" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get me assistant usage", "tags": [ "In-app assistant" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/avatar": { "delete": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#profile" }, "operationId": "deleteMeAvatar", "responses": { "200": { "content": { "application/json": { "example": { "avatarVersion": 1, "emailByLink": false, "emailManagedBy": "ada@example.com", "emailVerified": false, "pendingEmail": "ada@example.com", "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "avatarVersion": { "type": "number" }, "emailByLink": { "type": "boolean" }, "emailManagedBy": { "type": "string" }, "emailVerified": { "type": "boolean" }, "pendingEmail": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete me avatar", "tags": [ "Profile" ], "x-opentodo-policy": "signed-in.full-tokens" }, "put": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#profile" }, "operationId": "putMeAvatar", "responses": { "200": { "content": { "application/json": { "example": { "avatarVersion": 1, "emailByLink": false, "emailManagedBy": "ada@example.com", "emailVerified": false, "pendingEmail": "ada@example.com", "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "avatarVersion": { "type": "number" }, "emailByLink": { "type": "boolean" }, "emailManagedBy": { "type": "string" }, "emailVerified": { "type": "boolean" }, "pendingEmail": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update me avatar", "tags": [ "Profile" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/email": { "delete": { "description": "Needs a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#profile" }, "operationId": "deleteMeEmail", "responses": { "200": { "content": { "application/json": { "example": { "avatarVersion": 1, "emailByLink": false, "emailManagedBy": "ada@example.com", "emailVerified": false, "pendingEmail": "ada@example.com", "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "avatarVersion": { "type": "number" }, "emailByLink": { "type": "boolean" }, "emailManagedBy": { "type": "string" }, "emailVerified": { "type": "boolean" }, "pendingEmail": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Delete me email", "tags": [ "Profile" ], "x-opentodo-policy": "signed-in.session-only" }, "post": { "description": "Needs a session; tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#profile" }, "operationId": "postMeEmail", "requestBody": { "content": { "application/json": { "example": { "email": "ada@example.com" }, "schema": { "properties": { "email": { "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "avatarVersion": 1, "emailByLink": false, "emailManagedBy": "ada@example.com", "emailVerified": false, "pendingEmail": "ada@example.com", "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "avatarVersion": { "type": "number" }, "emailByLink": { "type": "boolean" }, "emailManagedBy": { "type": "string" }, "emailVerified": { "type": "boolean" }, "pendingEmail": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Me email", "tags": [ "Profile" ], "x-opentodo-policy": "signed-in.session-only.recent" } }, "/api/v1/me/email-digest": { "get": { "description": "your weekly email digest settings, see [Weekly digest](https://open-todo.app/docs/api/#weekly-digest); `read` and `agent` tokens → 403 `insufficient_scope`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getMeEmailDigest", "responses": { "200": { "content": { "application/json": { "example": { "available": false, "enabled": false, "encryption": false, "hour": 1, "language": "example", "lastAttemptAt": 1794906000000, "lastOutcome": "example", "lastSentFor": "example", "nextSendAt": 1794906000000, "timeZone": "Europe/Rome", "weekday": 1 }, "schema": { "properties": { "available": { "type": "boolean" }, "enabled": { "type": "boolean" }, "encryption": { "type": "boolean" }, "hour": { "type": "number" }, "language": { "type": "string" }, "lastAttemptAt": { "type": [ "number", "null" ] }, "lastOutcome": { "type": "string" }, "lastSentFor": { "type": "string" }, "nextSendAt": { "type": [ "number", "null" ] }, "timeZone": { "type": "string" }, "weekday": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get me email digest", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.full-tokens" }, "put": { "description": "any of `{enabled, weekday, hour, timeZone, language}` → the same shape; demo instances → 403 `demo_restricted`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "putMeEmailDigest", "requestBody": { "content": { "application/json": { "example": { "enabled": false, "hour": 1, "language": "example", "timeZone": "Europe/Rome", "weekday": 1 }, "schema": { "properties": { "enabled": { "type": [ "boolean", "null" ] }, "hour": { "type": [ "number", "null" ] }, "language": { "type": [ "string", "null" ] }, "timeZone": { "type": [ "string", "null" ] }, "weekday": { "type": [ "number", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "available": false, "enabled": false, "encryption": false, "hour": 1, "language": "example", "lastAttemptAt": 1794906000000, "lastOutcome": "example", "lastSentFor": "example", "nextSendAt": 1794906000000, "timeZone": "Europe/Rome", "weekday": 1 }, "schema": { "properties": { "available": { "type": "boolean" }, "enabled": { "type": "boolean" }, "encryption": { "type": "boolean" }, "hour": { "type": "number" }, "language": { "type": "string" }, "lastAttemptAt": { "type": [ "number", "null" ] }, "lastOutcome": { "type": "string" }, "lastSentFor": { "type": "string" }, "nextSendAt": { "type": [ "number", "null" ] }, "timeZone": { "type": "string" }, "weekday": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update me email digest", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/email/confirm": { "post": { "description": "Needs a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#profile" }, "operationId": "postMeEmailConfirm", "requestBody": { "content": { "application/json": { "example": { "token": "ot_example_token" }, "schema": { "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "avatarVersion": 1, "emailByLink": false, "emailManagedBy": "ada@example.com", "emailVerified": false, "pendingEmail": "ada@example.com", "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "avatarVersion": { "type": "number" }, "emailByLink": { "type": "boolean" }, "emailManagedBy": { "type": "string" }, "emailVerified": { "type": "boolean" }, "pendingEmail": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Me email confirm", "tags": [ "Profile" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/me/identities": { "get": { "description": "`{identities:[…], provider}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getMeIdentities", "responses": { "200": { "content": { "application/json": { "example": { "identities": [ { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "issuer": "example", "lastLoginAt": 1794906000000 } ], "provider": { "displayName": "Ada", "enabled": false, "ssoOnly": false } }, "schema": { "properties": { "identities": { "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "issuer": { "type": "string" }, "lastLoginAt": { "type": [ "number", "null" ] } }, "type": "object" }, "type": "array" }, "provider": { "properties": { "displayName": { "type": "string" }, "enabled": { "type": "boolean" }, "ssoOnly": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List me identities", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/identities/{id}": { "delete": { "description": "204, or 409 `last_credential`\n\nNeeds a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "deleteMeIdentitiesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a me identity", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential" } }, "/api/v1/me/mcp-consent": { "get": { "description": "`?\u003cauthorize query\u003e`: the consent dialog's request → `{client:{id, name, dynamic}, scope, redirectHost}`; 400 with the OAuth error shape when the request is invalid\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "getMeMcpConsent", "responses": { "200": { "content": { "application/json": { "example": { "client": { "dynamic": false, "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" }, "error": "example", "error_description": "example", "redirectHost": "example", "scope": "full" }, "schema": { "properties": { "client": { "properties": { "dynamic": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "error": { "type": "string" }, "error_description": { "type": "string" }, "redirectHost": { "type": "string" }, "scope": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Get me mcp consent", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in.session-only" }, "post": { "description": "`{query, allow}` → `{redirect}`: the registered address with `code` and `state` on allow, with `error=access_denied` otherwise\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "postMeMcpConsent", "requestBody": { "content": { "application/json": { "example": { "allow": false, "query": "example", "workspaces": [ "example" ] }, "schema": { "properties": { "allow": { "type": "boolean" }, "query": { "type": "string" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "required": [ "allow", "query" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "error": "example", "error_description": "example", "redirect": "example" }, "schema": { "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "redirect": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Me mcp consent", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/me/member-invitations": { "get": { "description": "your open invitations `{invitations:[{id,kind,targetId,targetName,role,inviterId,inviterName,createdAt,expiresAt}]}`, see [Membership invitations](https://open-todo.app/docs/api/#membership-invitations)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getMeMemberInvitations", "responses": { "200": { "content": { "application/json": { "example": { "invitations": [ {} ] }, "schema": { "properties": { "invitations": { "items": { "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List me member invitations", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/member-invitations/{id}/accept": { "post": { "description": "join → 200 `{kind, targetId, role}`; 410 `invitation_stale` when the inviter can no longer add you; 404 `not_found`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postMeMemberInvitationsByIdAccept", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "kind": "example", "role": "member", "targetId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "kind": { "type": "string" }, "role": { "type": "string" }, "targetId": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Me member invitation accept", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/member-invitations/{id}/decline": { "post": { "description": "decline → 204; you are not asked again for this project or workspace until it would have expired\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postMeMemberInvitationsByIdDecline", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Me member invitation decline", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/oauth-grants": { "get": { "description": "`{grants:[{id, clientId, clientName, scope, workspaces, createdAt, lastUsedAt}]}`: the AI apps you connected that are neither revoked nor expired, most recently used first; `scope` is `read` or `agent`, `workspaces` is empty for every workspace, `lastUsedAt` is null before first use; shown with the sessions in Settings → Account, also while MCP is off", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "getMeOauthGrants", "responses": { "200": { "content": { "application/json": { "example": { "grants": [ { "clientId": "00000000-0000-4000-8000-000000000019", "clientName": "Gemini", "createdAt": 1794906000154, "id": "00000000-0000-4000-8000-000000000020", "lastUsedAt": 1794906000157, "scope": "agent", "workspaces": [] } ] }, "schema": { "properties": { "grants": { "items": { "properties": { "clientId": { "type": "string" }, "clientName": { "type": "string" }, "createdAt": { "type": "number" }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "scope": { "type": "string" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List me oauth grants", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/oauth-grants/{id}": { "delete": { "description": "204: disconnects that app; its refresh token gets `invalid_grant` and its access token 401; another person's, a revoked or an unknown id → 404 `not_found`; demo instances → 403 `demo_restricted`; recorded as `mcp_oauth.disconnected`", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "deleteMeOauthGrantsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a me oauth grant", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/password": { "post": { "description": "`{currentPassword, newPassword}` → 204; signs out your other sessions\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postMePassword", "requestBody": { "content": { "application/json": { "example": { "currentPassword": "correct horse battery staple", "newPassword": "correct horse battery staple" }, "schema": { "properties": { "currentPassword": { "type": "string" }, "newPassword": { "type": "string" } }, "required": [ "currentPassword", "newPassword" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Me password", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential.recent" } }, "/api/v1/me/profile": { "get": { "externalDocs": { "url": "https://open-todo.app/docs/api/#profile" }, "operationId": "getMeProfile", "responses": { "200": { "content": { "application/json": { "example": { "avatarVersion": 1, "emailByLink": false, "emailManagedBy": "ada@example.com", "emailVerified": false, "pendingEmail": "ada@example.com", "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "avatarVersion": { "type": "number" }, "emailByLink": { "type": "boolean" }, "emailManagedBy": { "type": "string" }, "emailVerified": { "type": "boolean" }, "pendingEmail": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get me profile", "tags": [ "Profile" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#profile" }, "operationId": "patchMeProfile", "requestBody": { "content": { "application/json": { "example": { "name": "Ada" }, "schema": { "properties": { "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "avatarVersion": 1, "emailByLink": false, "emailManagedBy": "ada@example.com", "emailVerified": false, "pendingEmail": "ada@example.com", "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } }, "schema": { "properties": { "avatarVersion": { "type": "number" }, "emailByLink": { "type": "boolean" }, "emailManagedBy": { "type": "string" }, "emailVerified": { "type": "boolean" }, "pendingEmail": { "type": "string" }, "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update me profile", "tags": [ "Profile" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/rules": { "get": { "description": "`{enabled, paused, rules: {id: {last_run, runs_7d, paused_reason}}}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "getMeRules", "responses": { "200": { "content": { "application/json": { "example": { "rules": {} }, "schema": { "properties": { "rules": { "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List me rules", "tags": [ "Automation rules" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/rules/catalogue": { "get": { "description": "`{steps: [{kind, group, inputs, output, content, needs?, available, reason?, setting?}]}`: every step kind and whether you can use it now", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "getMeRulesCatalogue", "responses": { "200": { "content": { "application/json": { "example": { "steps": [ { "available": false, "blocks": [ "example" ], "content": false, "group": "example", "inputs": [ { "accepts": [ "example" ], "content": false, "enum": [ "example" ], "literal": "example", "max": 1, "name": "Ada", "required": false } ], "kind": "example", "needs": "example", "one_of": [ [ "example" ] ], "output": "example", "reason": "example", "same_as": "example", "setting": "example", "tool": "example" } ] }, "schema": { "properties": { "steps": { "items": { "properties": { "available": { "type": "boolean" }, "blocks": { "items": { "type": "string" }, "type": "array" }, "content": { "type": "boolean" }, "group": { "type": "string" }, "inputs": { "items": { "properties": { "accepts": { "items": { "type": "string" }, "type": "array" }, "content": { "type": "boolean" }, "enum": { "items": { "type": "string" }, "type": "array" }, "literal": { "type": "string" }, "max": { "type": "number" }, "name": { "type": "string" }, "required": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "kind": { "type": "string" }, "needs": { "type": "string" }, "one_of": { "items": { "items": { "type": "string" }, "type": "array" }, "type": "array" }, "output": { "type": "string" }, "reason": { "type": "string" }, "same_as": { "type": "string" }, "setting": { "type": "string" }, "tool": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get me rules catalogue", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/rules/paused": { "put": { "description": "`{paused}` → `{enabled, paused}`: pause or resume all your rules", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "putMeRulesPaused", "requestBody": { "content": { "application/json": { "example": { "paused": false }, "schema": { "properties": { "paused": { "type": [ "boolean", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "enabled": false, "paused": false }, "schema": { "properties": { "enabled": { "type": "boolean" }, "paused": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update me rules paused", "tags": [ "Automation rules" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/rules/proposals": { "get": { "description": "`{proposals: [{id, rule_id, run_id, created_at, expires_at, state, items, applied, skipped, encrypted}]}`: your waiting proposals, newest first\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "getMeRulesProposals", "responses": { "200": { "content": { "application/json": { "example": { "proposals": [ { "applied": 1, "created_at": 1794906000000, "encrypted": false, "envelope": "example", "expires_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "items": 1, "list": [ { "ai": false, "before": {}, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001", "key": "example", "kind": "example", "side": { "day": "example", "delivery": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "StepID": "example", "TaskIDs": [ "example" ], "Text": "example" }, "fired": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence" }, "hook": "example", "kind": "example", "mail": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "Subject": "example", "Text": "example" }, "members": [ "example" ], "notice": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "runId": "00000000-0000-4000-8000-000000000001", "stepId": "00000000-0000-4000-8000-000000000001", "taskId": "00000000-0000-4000-8000-000000000001", "text": "example" }, "project": "example" } } ], "rule_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "skipped": 1, "state": "example" } ] }, "schema": { "properties": { "proposals": { "items": { "properties": { "applied": { "type": "number" }, "created_at": { "type": "number" }, "encrypted": { "type": "boolean" }, "envelope": { "type": "string" }, "expires_at": { "type": "number" }, "id": { "type": "string" }, "items": { "type": "number" }, "list": { "items": { "properties": { "ai": { "type": "boolean" }, "before": { "type": "object" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "side": { "properties": { "day": { "type": "string" }, "delivery": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "StepID": { "type": "string" }, "TaskIDs": { "items": { "type": "string" }, "type": "array" }, "Text": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "fired": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" } }, "type": [ "object", "null" ] }, "hook": { "type": "string" }, "kind": { "type": "string" }, "mail": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "Subject": { "type": "string" }, "Text": { "type": "string" } }, "type": [ "object", "null" ] }, "members": { "items": { "type": "string" }, "type": "array" }, "notice": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "runId": { "type": "string" }, "stepId": { "type": "string" }, "taskId": { "type": "string" }, "text": { "type": "string" } }, "type": [ "object", "null" ] }, "project": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "rule_id": { "type": "string" }, "run_id": { "type": "string" }, "skipped": { "type": "number" }, "state": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List me rules proposals", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/rules/proposals/{id}": { "delete": { "description": "→ `204`: dismisses a waiting proposal and deletes its body; `409 proposal_closed` otherwise\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "deleteMeRulesProposalsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a me rules proposal", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in.full-tokens" }, "get": { "description": "one proposal; while waiting it carries `list`: `[{key, kind, entity?, id?, fields?, before?, ai, side?}]` (`kind` is `create`, `change`, `notify`, `webhook` or `email`; `before` the values the change was planned on; `ai` marks text the AI wrote), or for an encrypted account `envelope`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "getMeRulesProposalsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "applied": 1, "created_at": 1794906000000, "encrypted": false, "envelope": "example", "expires_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "items": 1, "list": [ { "ai": false, "before": {}, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001", "key": "example", "kind": "example", "side": { "day": "example", "delivery": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "StepID": "example", "TaskIDs": [ "example" ], "Text": "example" }, "fired": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence" }, "hook": "example", "kind": "example", "mail": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "Subject": "example", "Text": "example" }, "members": [ "example" ], "notice": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "runId": "00000000-0000-4000-8000-000000000001", "stepId": "00000000-0000-4000-8000-000000000001", "taskId": "00000000-0000-4000-8000-000000000001", "text": "example" }, "project": "example" } } ], "rule_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "skipped": 1, "state": "example" }, "schema": { "properties": { "applied": { "type": "number" }, "created_at": { "type": "number" }, "encrypted": { "type": "boolean" }, "envelope": { "type": "string" }, "expires_at": { "type": "number" }, "id": { "type": "string" }, "items": { "type": "number" }, "list": { "items": { "properties": { "ai": { "type": "boolean" }, "before": { "type": "object" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "side": { "properties": { "day": { "type": "string" }, "delivery": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "StepID": { "type": "string" }, "TaskIDs": { "items": { "type": "string" }, "type": "array" }, "Text": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "fired": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" } }, "type": [ "object", "null" ] }, "hook": { "type": "string" }, "kind": { "type": "string" }, "mail": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "Subject": { "type": "string" }, "Text": { "type": "string" } }, "type": [ "object", "null" ] }, "members": { "items": { "type": "string" }, "type": "array" }, "notice": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "runId": { "type": "string" }, "stepId": { "type": "string" }, "taskId": { "type": "string" }, "text": { "type": "string" } }, "type": [ "object", "null" ] }, "project": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "rule_id": { "type": "string" }, "run_id": { "type": "string" }, "skipped": { "type": "number" }, "state": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a me rules proposal", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/rules/proposals/{id}/apply": { "post": { "description": "`{items?: [key, …]}` (all when left out) → `{state, applied, skipped, changed, refused, run_id, rule_id}`: writes the items with device `rule:\u003crule-id\u003e`, recorded on the run (Undo run takes them back); an item whose target was deleted or whose field changed since is skipped and counted (`changed`); `409 proposal_closed` once applied, dismissed or expired; `409 encrypted` for an encrypted account's proposal sent with `items`: a device decrypts its `envelope`, re-checks the items and sends the ticked ones as `{changes, completing?, sides?, skipped?, changed?}` in the commit route's form (ciphertext only, `400 plaintext` otherwise)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "postMeRulesProposalsByIdApply", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "changed": 1, "changes": [ { "create": false, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001" } ], "completing": [ "example" ], "items": [ "example" ], "sides": [ { "kind": "example", "step": "example", "task": "example", "tasks": [ "example" ], "text": "example", "webhook": "example" } ], "skipped": 1 }, "schema": { "properties": { "changed": { "type": "number" }, "changes": { "items": { "properties": { "create": { "type": "boolean" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" } }, "required": [ "entity", "fields", "id" ], "type": "object" }, "type": "array" }, "completing": { "items": { "type": "string" }, "type": "array" }, "items": { "items": { "type": "string" }, "type": "array" }, "sides": { "items": { "properties": { "kind": { "type": "string" }, "step": { "type": "string" }, "task": { "type": "string" }, "tasks": { "items": { "type": "string" }, "type": "array" }, "text": { "type": "string" }, "webhook": { "type": "string" } }, "required": [ "kind", "step" ], "type": "object" }, "type": "array" }, "skipped": { "type": "number" } }, "required": [ "changed", "changes", "completing", "sides", "skipped" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "applied": 1, "changed": 1, "refused": 1, "rule_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "skipped": 1, "state": "example" }, "schema": { "properties": { "applied": { "type": "number" }, "changed": { "type": "number" }, "refused": { "type": "number" }, "rule_id": { "type": "string" }, "run_id": { "type": "string" }, "skipped": { "type": "number" }, "state": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Me rules proposal apply", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/me/rules/runs": { "get": { "description": "`?outcome=\u0026source=\u0026rule=\u0026limit=\u0026before=` → `{runs, before?}`: every routine's runs, newest first (`limit` 1 to 100, default 50; `before` is the last run's `id` to page back)", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "getMeRulesRuns", "responses": { "200": { "content": { "application/json": { "example": { "before": 1, "hide_successes": false, "runs": [ { "ai_auto": false, "at": 1, "blocks": [ { "date": "2026-11-20", "from": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "kind": "example", "span": "example", "to": "example" } ], "changes": "example", "depth": 1, "device_id": "00000000-0000-4000-8000-000000000001", "duration_ms": 1, "failed_step": 1, "id": 1, "kind": "example", "note_id": "00000000-0000-4000-8000-000000000001", "occurrence": "example", "outcome": "example", "project_id": "00000000-0000-4000-8000-000000000001", "proposal": { "applied": 1, "created_at": 1794906000000, "encrypted": false, "envelope": "example", "expires_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "items": 1, "list": [ { "ai": false, "before": {}, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001", "key": "example", "kind": "example", "side": { "day": "example", "delivery": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "StepID": "example", "TaskIDs": [ "example" ], "Text": "example" }, "fired": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence" }, "hook": "example", "kind": "example", "mail": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "Subject": "example", "Text": "example" }, "members": [ "example" ], "notice": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "runId": "00000000-0000-4000-8000-000000000001", "stepId": "00000000-0000-4000-8000-000000000001", "taskId": "00000000-0000-4000-8000-000000000001", "text": "example" }, "project": "example" } } ], "rule_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "skipped": 1, "state": "example" }, "reason": "example", "rule_id": "00000000-0000-4000-8000-000000000001", "run_as": "example", "run_id": "00000000-0000-4000-8000-000000000001", "source": "example", "steps": [ { "duration_ms": 1, "error": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1 } ], "steps_count": 1, "task_id": "00000000-0000-4000-8000-000000000001", "test": false, "tokens": 1, "undone_at": 1794906000000, "writes": 1 } ], "seen_at": 1794906000000 }, "schema": { "properties": { "before": { "type": "number" }, "hide_successes": { "type": "boolean" }, "runs": { "items": { "properties": { "ai_auto": { "type": "boolean" }, "at": { "type": "number" }, "blocks": { "items": { "properties": { "date": { "type": "string" }, "from": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "span": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "changes": { "type": "string" }, "depth": { "type": "number" }, "device_id": { "type": "string" }, "duration_ms": { "type": "number" }, "failed_step": { "type": "number" }, "id": { "type": "number" }, "kind": { "type": "string" }, "note_id": { "type": "string" }, "occurrence": { "type": "string" }, "outcome": { "type": "string" }, "project_id": { "type": "string" }, "proposal": { "properties": { "applied": { "type": "number" }, "created_at": { "type": "number" }, "encrypted": { "type": "boolean" }, "envelope": { "type": "string" }, "expires_at": { "type": "number" }, "id": { "type": "string" }, "items": { "type": "number" }, "list": { "items": { "properties": { "ai": { "type": "boolean" }, "before": { "type": "object" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "side": { "properties": { "day": { "type": "string" }, "delivery": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "StepID": { "type": "string" }, "TaskIDs": { "items": { "type": "string" }, "type": "array" }, "Text": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "fired": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" } }, "type": [ "object", "null" ] }, "hook": { "type": "string" }, "kind": { "type": "string" }, "mail": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "Subject": { "type": "string" }, "Text": { "type": "string" } }, "type": [ "object", "null" ] }, "members": { "items": { "type": "string" }, "type": "array" }, "notice": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "runId": { "type": "string" }, "stepId": { "type": "string" }, "taskId": { "type": "string" }, "text": { "type": "string" } }, "type": [ "object", "null" ] }, "project": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "rule_id": { "type": "string" }, "run_id": { "type": "string" }, "skipped": { "type": "number" }, "state": { "type": "string" } }, "type": [ "object", "null" ] }, "reason": { "type": "string" }, "rule_id": { "type": "string" }, "run_as": { "type": "string" }, "run_id": { "type": "string" }, "source": { "type": "string" }, "steps": { "items": { "properties": { "duration_ms": { "type": "number" }, "error": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" } }, "type": "object" }, "type": "array" }, "steps_count": { "type": "number" }, "task_id": { "type": "string" }, "test": { "type": "boolean" }, "tokens": { "type": "number" }, "undone_at": { "type": [ "number", "null" ] }, "writes": { "type": "number" } }, "type": "object" }, "type": "array" }, "seen_at": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List me rules runs", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/me/rules/runs/{run}/commit": { "post": { "description": "a device run's result: `{steps, outcome?, duration_ms?, tokens?, changes?: [{entity, id, create?, fields}], completing?: [task id], sides?: [{kind: \"notify\", step, text?, task?} | {kind: \"fired\", task} | {kind: \"webhook\", step, webhook, tasks?}], proposal?: {envelope, items}, blocks?: [block]}` → `{run, steps, writes, test}`. `blocks` are the run's blocks (below), at most 4 (`400 invalid_input` otherwise). Content fields and a notice's text must be ciphertext (`400 plaintext`). `403 forbidden` from another session than the one the run was sent to, `409 run_closed` once it was committed, failed or missed, `409 routine_changed` when the routine changed since it was sent (the run is recorded failed), `409 fallback` when a routine with an AI step is not in auto mode or the result breaks auto mode's limits (commit a `proposal` instead), `400 write_limit` past 500 items; nothing is written in each case\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "postMeRulesRunsByRunCommit", "parameters": [ { "in": "path", "name": "run", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "blocks": [ { "date": "2026-11-20", "from": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "kind": "example", "span": "example", "to": "example" } ], "changes": [ { "create": false, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001" } ], "completing": [ "example" ], "duration_ms": 1, "outcome": "example", "proposal": { "envelope": "example", "items": 1 }, "sides": [ { "kind": "example", "step": "example", "task": "example", "tasks": [ "example" ], "text": "example", "webhook": "example" } ], "steps": [ { "duration_ms": 1, "error": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1 } ], "tokens": 1 }, "schema": { "properties": { "blocks": { "items": { "properties": { "date": { "type": "string" }, "from": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "span": { "type": "string" }, "to": { "type": "string" } }, "required": [ "kind" ], "type": "object" }, "type": "array" }, "changes": { "items": { "properties": { "create": { "type": "boolean" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" } }, "required": [ "entity", "fields", "id" ], "type": "object" }, "type": "array" }, "completing": { "items": { "type": "string" }, "type": "array" }, "duration_ms": { "type": "number" }, "outcome": { "type": "string" }, "proposal": { "properties": { "envelope": { "type": "string" }, "items": { "type": "number" } }, "required": [ "envelope", "items" ], "type": [ "object", "null" ] }, "sides": { "items": { "properties": { "kind": { "type": "string" }, "step": { "type": "string" }, "task": { "type": "string" }, "tasks": { "items": { "type": "string" }, "type": "array" }, "text": { "type": "string" }, "webhook": { "type": "string" } }, "required": [ "kind", "step" ], "type": "object" }, "type": "array" }, "steps": { "items": { "properties": { "duration_ms": { "type": "number" }, "error": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" } }, "required": [ "duration_ms", "ids", "index", "items", "kind", "output", "status", "step_id" ], "type": "object" }, "type": "array" }, "tokens": { "type": "number" } }, "required": [ "blocks", "changes", "completing", "duration_ms", "outcome", "sides", "steps", "tokens" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "device_run": { "at": 1, "auto": false, "budget": 1, "note": "example", "occurrence": "example", "op": "example", "rev": "example", "rule": "example", "run": "example", "task": "example", "tokens": 1 }, "run": { "ai_auto": false, "at": 1, "blocks": [ { "date": "2026-11-20", "from": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "kind": "example", "span": "example", "to": "example" } ], "changes": "example", "depth": 1, "device_id": "00000000-0000-4000-8000-000000000001", "duration_ms": 1, "failed_step": 1, "id": 1, "note_id": "00000000-0000-4000-8000-000000000001", "occurrence": "example", "outcome": "example", "project_id": "00000000-0000-4000-8000-000000000001", "proposal": { "applied": 1, "created_at": 1794906000000, "encrypted": false, "envelope": "example", "expires_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "items": 1, "list": [ { "ai": false, "before": {}, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001", "key": "example", "kind": "example", "side": { "day": "example", "delivery": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "StepID": "example", "TaskIDs": [ "example" ], "Text": "example" }, "fired": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence" }, "hook": "example", "kind": "example", "mail": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "Subject": "example", "Text": "example" }, "members": [ "example" ], "notice": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "runId": "00000000-0000-4000-8000-000000000001", "stepId": "00000000-0000-4000-8000-000000000001", "taskId": "00000000-0000-4000-8000-000000000001", "text": "example" }, "project": "example" } } ], "rule_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "skipped": 1, "state": "example" }, "reason": "example", "rule_id": "00000000-0000-4000-8000-000000000001", "run_as": "example", "run_id": "00000000-0000-4000-8000-000000000001", "source": "example", "steps": [ { "duration_ms": 1, "error": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1 } ], "steps_count": 1, "task_id": "00000000-0000-4000-8000-000000000001", "test": false, "tokens": 1, "undone_at": 1794906000000, "writes": 1 }, "steps": [ { "changes": [ { "base": {}, "create": false, "entity": "example", "entityId": "00000000-0000-4000-8000-000000000001", "patch": {} } ], "duration_ms": 1, "error": "example", "estimate": 1, "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "preview": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1, "warning": { "kind": "example", "message": "example", "reason": "example", "setting": "example", "step": "example" } } ], "test": false, "writes": 1 }, "schema": { "properties": { "device_run": { "properties": { "at": { "type": "number" }, "auto": { "type": "boolean" }, "budget": { "type": "number" }, "note": { "type": "string" }, "occurrence": { "type": "string" }, "op": { "type": "string" }, "rev": { "type": "string" }, "rule": { "type": "string" }, "run": { "type": "string" }, "task": { "type": "string" }, "tokens": { "type": "number" } }, "type": [ "object", "null" ] }, "run": { "properties": { "ai_auto": { "type": "boolean" }, "at": { "type": "number" }, "blocks": { "items": { "properties": { "date": { "type": "string" }, "from": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "span": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "changes": { "type": "string" }, "depth": { "type": "number" }, "device_id": { "type": "string" }, "duration_ms": { "type": "number" }, "failed_step": { "type": "number" }, "id": { "type": "number" }, "note_id": { "type": "string" }, "occurrence": { "type": "string" }, "outcome": { "type": "string" }, "project_id": { "type": "string" }, "proposal": { "properties": { "applied": { "type": "number" }, "created_at": { "type": "number" }, "encrypted": { "type": "boolean" }, "envelope": { "type": "string" }, "expires_at": { "type": "number" }, "id": { "type": "string" }, "items": { "type": "number" }, "list": { "items": { "properties": { "ai": { "type": "boolean" }, "before": { "type": "object" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "side": { "properties": { "day": { "type": "string" }, "delivery": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "StepID": { "type": "string" }, "TaskIDs": { "items": { "type": "string" }, "type": "array" }, "Text": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "fired": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" } }, "type": [ "object", "null" ] }, "hook": { "type": "string" }, "kind": { "type": "string" }, "mail": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "Subject": { "type": "string" }, "Text": { "type": "string" } }, "type": [ "object", "null" ] }, "members": { "items": { "type": "string" }, "type": "array" }, "notice": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "runId": { "type": "string" }, "stepId": { "type": "string" }, "taskId": { "type": "string" }, "text": { "type": "string" } }, "type": [ "object", "null" ] }, "project": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "rule_id": { "type": "string" }, "run_id": { "type": "string" }, "skipped": { "type": "number" }, "state": { "type": "string" } }, "type": [ "object", "null" ] }, "reason": { "type": "string" }, "rule_id": { "type": "string" }, "run_as": { "type": "string" }, "run_id": { "type": "string" }, "source": { "type": "string" }, "steps": { "items": { "properties": { "duration_ms": { "type": "number" }, "error": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" } }, "type": "object" }, "type": "array" }, "steps_count": { "type": "number" }, "task_id": { "type": "string" }, "test": { "type": "boolean" }, "tokens": { "type": "number" }, "undone_at": { "type": [ "number", "null" ] }, "writes": { "type": "number" } }, "type": "object" }, "steps": { "items": { "properties": { "changes": { "items": { "properties": { "base": { "type": "object" }, "create": { "type": "boolean" }, "entity": { "type": "string" }, "entityId": { "type": "string" }, "patch": { "type": "object" } }, "type": "object" }, "type": "array" }, "duration_ms": { "type": "number" }, "error": { "type": "string" }, "estimate": { "type": "number" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "preview": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": { "type": "string" }, "type": "object" }, { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array" } ], "description": "A preview of the step's output, by its type: text and a date are a string, lines a list of strings, a number a number, a task or a note {id, title}, a project {id, name}, tasks or notes a list of {id, title}." }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" }, "warning": { "properties": { "kind": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string" }, "setting": { "type": "string" }, "step": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "test": { "type": "boolean" }, "writes": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Me rules run commit", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/me/rules/runs/{run}/fail": { "post": { "description": "`{step, code, steps?, duration_ms?, tokens?}` → `{run}`: the device could not finish; the run is recorded failed with `code`\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "postMeRulesRunsByRunFail", "parameters": [ { "in": "path", "name": "run", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "code": "example", "duration_ms": 1, "step": 1, "steps": [ { "duration_ms": 1, "error": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1 } ], "tokens": 1 }, "schema": { "properties": { "code": { "type": "string" }, "duration_ms": { "type": "number" }, "step": { "type": "number" }, "steps": { "items": { "properties": { "duration_ms": { "type": "number" }, "error": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" } }, "required": [ "duration_ms", "ids", "index", "items", "kind", "output", "status", "step_id" ], "type": "object" }, "type": "array" }, "tokens": { "type": "number" } }, "required": [ "code", "duration_ms", "step", "steps", "tokens" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "run": { "ai_auto": false, "at": 1, "blocks": [ { "date": "2026-11-20", "from": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "kind": "example", "span": "example", "to": "example" } ], "changes": "example", "depth": 1, "device_id": "00000000-0000-4000-8000-000000000001", "duration_ms": 1, "failed_step": 1, "id": 1, "note_id": "00000000-0000-4000-8000-000000000001", "occurrence": "example", "outcome": "example", "project_id": "00000000-0000-4000-8000-000000000001", "proposal": { "applied": 1, "created_at": 1794906000000, "encrypted": false, "envelope": "example", "expires_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "items": 1, "list": [ { "ai": false, "before": {}, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001", "key": "example", "kind": "example", "side": { "day": "example", "delivery": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "StepID": "example", "TaskIDs": [ "example" ], "Text": "example" }, "fired": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence" }, "hook": "example", "kind": "example", "mail": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "Subject": "example", "Text": "example" }, "members": [ "example" ], "notice": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "runId": "00000000-0000-4000-8000-000000000001", "stepId": "00000000-0000-4000-8000-000000000001", "taskId": "00000000-0000-4000-8000-000000000001", "text": "example" }, "project": "example" } } ], "rule_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "skipped": 1, "state": "example" }, "reason": "example", "rule_id": "00000000-0000-4000-8000-000000000001", "run_as": "example", "run_id": "00000000-0000-4000-8000-000000000001", "source": "example", "steps": [ { "duration_ms": 1, "error": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1 } ], "steps_count": 1, "task_id": "00000000-0000-4000-8000-000000000001", "test": false, "tokens": 1, "undone_at": 1794906000000, "writes": 1 } }, "schema": { "properties": { "run": { "properties": { "ai_auto": { "type": "boolean" }, "at": { "type": "number" }, "blocks": { "items": { "properties": { "date": { "type": "string" }, "from": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "span": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "changes": { "type": "string" }, "depth": { "type": "number" }, "device_id": { "type": "string" }, "duration_ms": { "type": "number" }, "failed_step": { "type": "number" }, "id": { "type": "number" }, "note_id": { "type": "string" }, "occurrence": { "type": "string" }, "outcome": { "type": "string" }, "project_id": { "type": "string" }, "proposal": { "properties": { "applied": { "type": "number" }, "created_at": { "type": "number" }, "encrypted": { "type": "boolean" }, "envelope": { "type": "string" }, "expires_at": { "type": "number" }, "id": { "type": "string" }, "items": { "type": "number" }, "list": { "items": { "properties": { "ai": { "type": "boolean" }, "before": { "type": "object" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "side": { "properties": { "day": { "type": "string" }, "delivery": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "StepID": { "type": "string" }, "TaskIDs": { "items": { "type": "string" }, "type": "array" }, "Text": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "fired": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" } }, "type": [ "object", "null" ] }, "hook": { "type": "string" }, "kind": { "type": "string" }, "mail": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "Subject": { "type": "string" }, "Text": { "type": "string" } }, "type": [ "object", "null" ] }, "members": { "items": { "type": "string" }, "type": "array" }, "notice": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "runId": { "type": "string" }, "stepId": { "type": "string" }, "taskId": { "type": "string" }, "text": { "type": "string" } }, "type": [ "object", "null" ] }, "project": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "rule_id": { "type": "string" }, "run_id": { "type": "string" }, "skipped": { "type": "number" }, "state": { "type": "string" } }, "type": [ "object", "null" ] }, "reason": { "type": "string" }, "rule_id": { "type": "string" }, "run_as": { "type": "string" }, "run_id": { "type": "string" }, "source": { "type": "string" }, "steps": { "items": { "properties": { "duration_ms": { "type": "number" }, "error": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" } }, "type": "object" }, "type": "array" }, "steps_count": { "type": "number" }, "task_id": { "type": "string" }, "test": { "type": "boolean" }, "tokens": { "type": "number" }, "undone_at": { "type": [ "number", "null" ] }, "writes": { "type": "number" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Me rules run fail", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/me/sign-out-everywhere": { "post": { "description": "→ 204 and the session cookie cleared: ends every session of the account (this one too), forgets its remembered browsers and revokes its API tokens and app passwords; recorded as `sessions.revoked`; the other devices remove their local copy on their next `auth/status` (`revoked`); a token gets 403 `session_required`\n\nNeeds a session; tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postMeSignOutEverywhere", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Me sign out everywhere", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.session-only.recent" } }, "/api/v1/members/{id}/mfa/reset": { "post": { "description": "remove a member's second factor, recovery codes and remembered browsers → 204\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postMembersByIdMfaReset", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Member mfa reset", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.credential.recent" } }, "/api/v1/mfa": { "get": { "description": "`{mfa}`, see [Two-factor authentication](https://open-todo.app/docs/api/#two-factor-authentication)", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getMfa", "responses": { "200": { "content": { "application/json": { "example": { "mfa": { "enrolled": false, "policy": "example", "recoveryCodesRemaining": 1, "required": false, "restricted": false } }, "schema": { "properties": { "mfa": { "properties": { "enrolled": { "type": "boolean" }, "policy": { "type": "string" }, "recoveryCodesRemaining": { "type": "number" }, "required": { "type": "boolean" }, "restricted": { "type": "boolean" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get mfa", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/mfa/recovery-codes/regenerate": { "post": { "description": "→ `{recoveryCodes:[10]}`; every earlier code stops working\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postMfaRecoveryCodesRegenerate", "responses": { "200": { "content": { "application/json": { "example": { "recoveryCodes": [ "example" ] }, "schema": { "properties": { "recoveryCodes": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Mfa recovery codes regenerate", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential.recent" } }, "/api/v1/mfa/totp": { "delete": { "description": "turn the second factor off → 204\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "deleteMfaTotp", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete mfa totp", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential.recent" } }, "/api/v1/mfa/totp/confirm": { "post": { "description": "`{code}` → `{recoveryCodes:[10], mfa}` (codes shown once)\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postMfaTotpConfirm", "requestBody": { "content": { "application/json": { "example": { "code": "example" }, "schema": { "properties": { "code": { "type": "string" } }, "required": [ "code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "mfa": { "enrolled": false, "policy": "example", "recoveryCodesRemaining": 1, "required": false, "restricted": false }, "recoveryCodes": [ "example" ] }, "schema": { "properties": { "mfa": { "properties": { "enrolled": { "type": "boolean" }, "policy": { "type": "string" }, "recoveryCodesRemaining": { "type": "number" }, "required": { "type": "boolean" }, "restricted": { "type": "boolean" } }, "type": [ "object", "null" ] }, "recoveryCodes": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Mfa totp confirm", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential.recent" } }, "/api/v1/mfa/totp/enroll": { "post": { "description": "→ `{secret, uri, expiresAt}` (pending for 10 minutes; the only time the secret is returned)\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postMfaTotpEnroll", "responses": { "200": { "content": { "application/json": { "example": { "expiresAt": 1794906000000, "secret": "example-secret", "uri": "example" }, "schema": { "properties": { "expiresAt": { "type": "number" }, "secret": { "type": "string" }, "uri": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Mfa totp enroll", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential.recent" } }, "/api/v1/mfa/trusted-devices": { "delete": { "description": "forget every remembered browser → 204", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "deleteMfaTrustedDevices", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete mfa trusted devices", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "`{devices:[{id,userAgent,createdAt,expiresAt,lastUsedAt}]}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getMfaTrustedDevices", "responses": { "200": { "content": { "application/json": { "example": { "devices": [ { "createdAt": 1794906000000, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "userAgent": "example" } ] }, "schema": { "properties": { "devices": { "items": { "properties": { "createdAt": { "type": "number" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "userAgent": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List mfa trusted devices", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/mfa/trusted-devices/{id}": { "delete": { "description": "forget one → 204", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "deleteMfaTrustedDevicesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a mfa trusted device", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notes": { "get": { "description": "same shape for [standalone notes](https://open-todo.app/docs/api/#standalone-notes): `{title, description, project_id, labels}`; a read carries `body_version` and `appends`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getNotes", "responses": { "200": { "content": { "application/json": { "example": { "notes": [ { "appends": [ { "id": "00000000-0000-4000-8000-000000000009", "text": "- decided: green" } ], "body_version": "1794906000074:server:0a1b2c3d", "created_at": 1794906000066, "description": "- fence\n- beds", "id": "00000000-0000-4000-8000-000000000008", "position": 1794906000066, "title": "Garden plan 2027" } ] }, "schema": { "properties": { "notes": { "items": { "allOf": [ { "$ref": "#/components/schemas/Note" }, { "properties": { "appends": { "description": "Appends not yet merged into the body, oldest first.", "items": { "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "body_version": { "type": "string" } }, "type": "object" } ] }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List notes", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "same shape for [standalone notes](https://open-todo.app/docs/api/#standalone-notes): `{title, description, project_id, labels}`; a read carries `body_version` and `appends`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postNotes", "requestBody": { "content": { "application/json": { "example": { "description": "- fence\n- beds", "title": "Garden plan" }, "schema": { "properties": { "created_at": { "type": "number" }, "day": { "type": "string" }, "deleted_at": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "labels": { "items": { "type": "string" }, "type": "array" }, "notes_doc": { "description": "A mergeable notes document (\"ydoc:v1:…\"), see docs/sync.md \"Mergeable documents\". Write `description` (Markdown) instead unless you merge documents yourself.", "type": "string" }, "position": { "type": "number" }, "project_id": { "type": [ "string", "null" ] }, "template": { "type": "boolean" }, "title": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "appends": [], "body_version": "1794906000067:server:0a1b2c3d", "created_at": 1794906000066, "description": "- fence\n- beds", "id": "00000000-0000-4000-8000-000000000008", "position": 1794906000066, "title": "Garden plan" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Note" }, { "properties": { "appends": { "description": "Appends not yet merged into the body, oldest first.", "items": { "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "body_version": { "type": "string" } }, "type": "object" } ] } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a note", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notes/{id}": { "delete": { "description": "same shape for [standalone notes](https://open-todo.app/docs/api/#standalone-notes): `{title, description, project_id, labels}`; a read carries `body_version` and `appends`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteNotesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a note", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "same shape for [standalone notes](https://open-todo.app/docs/api/#standalone-notes): `{title, description, project_id, labels}`; a read carries `body_version` and `appends`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getNotesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "appends": [], "body_version": "1794906000067:server:0a1b2c3d", "created_at": 1794906000066, "description": "- fence\n- beds", "id": "00000000-0000-4000-8000-000000000008", "position": 1794906000066, "title": "Garden plan" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Note" }, { "properties": { "appends": { "description": "Appends not yet merged into the body, oldest first.", "items": { "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "body_version": { "type": "string" } }, "type": "object" } ] } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a note", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "same shape for [standalone notes](https://open-todo.app/docs/api/#standalone-notes): `{title, description, project_id, labels}`; a read carries `body_version` and `appends`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "patchNotesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "title": "Garden plan 2027" }, "schema": { "properties": { "created_at": { "type": "number" }, "day": { "type": "string" }, "deleted_at": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "labels": { "items": { "type": "string" }, "type": "array" }, "notes_doc": { "description": "A mergeable notes document (\"ydoc:v1:…\"), see docs/sync.md \"Mergeable documents\". Write `description` (Markdown) instead unless you merge documents yourself.", "type": "string" }, "position": { "type": "number" }, "project_id": { "type": [ "string", "null" ] }, "template": { "type": "boolean" }, "title": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "appends": [], "body_version": "1794906000067:server:0a1b2c3d", "created_at": 1794906000066, "description": "- fence\n- beds", "id": "00000000-0000-4000-8000-000000000008", "position": 1794906000066, "title": "Garden plan 2027" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Note" }, { "properties": { "appends": { "description": "Appends not yet merged into the body, oldest first.", "items": { "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "body_version": { "type": "string" } }, "type": "object" } ] } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a note", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notes/{id}/append": { "post": { "description": "`{id?, text}` adds Markdown at the end of the note without replacing it → 201 `{entity, entity_id, append_id, body_version}`; see [Appending to a note](https://open-todo.app/docs/api/#appending-to-a-note); 409 `too_many_appends` past 100 waiting; `read` and `agent` tokens get 403 `insufficient_scope`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postNotesByIdAppend", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "text": "- decided: green" }, "schema": { "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "required": [ "text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "append_id": "00000000-0000-4000-8000-000000000001", "body_version": "example", "entity": "example", "entity_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "append_id": { "type": "string" }, "body_version": { "type": "string" }, "entity": { "type": "string" }, "entity_id": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "201": { "content": { "application/json": { "example": { "append_id": "00000000-0000-4000-8000-000000000009", "body_version": "1794906000074:server:0a1b2c3d", "entity": "note", "entity_id": "00000000-0000-4000-8000-000000000008" }, "schema": { "properties": { "append_id": { "type": "string" }, "body_version": { "type": "string" }, "entity": { "type": "string" }, "entity_id": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Note append", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notes/{id}/attachments": { "get": { "description": "The same for a standalone note: its attachments carry `note_id` instead of `task_id` (no `comment_id`). A note's copy (moved to another project, or turned into a task) names the original's stored file in `file_id` and serves its bytes", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "operationId": "getNotesByIdAttachments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "attachments": [ {} ] }, "schema": { "properties": { "attachments": { "items": { "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List note attachments", "tags": [ "Attachments" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "The same for a standalone note: its attachments carry `note_id` instead of `task_id` (no `comment_id`). A note's copy (moved to another project, or turned into a task) names the original's stored file in `file_id` and serves its bytes", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "operationId": "postNotesByIdAttachments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Ada", "url": "https://todo.example.com/" }, "schema": { "properties": { "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "uploaded": false }, "schema": { "properties": { "uploaded": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "201": { "content": { "application/json": { "example": { "uploaded": false }, "schema": { "properties": { "uploaded": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a note attachment", "tags": [ "Attachments" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notes/{id}/history": { "get": { "description": "change sets from the operation log, oldest first; `?before=\u003cts\u003e\u0026limit=\u003c1-200\u003e` pages backwards; see [Trash and history](https://open-todo.app/docs/api/#trash-and-history)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getNotesByIdHistory", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "before": 1, "changeSets": [ { "changes": [ { "field": "example", "from": "example", "lost": false, "opId": "00000000-0000-4000-8000-000000000001", "to": "example" } ], "device": "example", "device_label": "example", "ts": 1794906000000, "userId": "00000000-0000-4000-8000-000000000001" } ], "entity": "example", "id": "00000000-0000-4000-8000-000000000001", "more": false }, "schema": { "properties": { "before": { "type": "number" }, "changeSets": { "items": { "properties": { "changes": { "items": { "properties": { "field": { "type": "string" }, "from": { "type": "string" }, "lost": { "type": "boolean" }, "opId": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "device": { "type": "string" }, "device_label": { "type": "string" }, "ts": { "type": "number" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "entity": { "type": "string" }, "id": { "type": "string" }, "more": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get note history", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notes/{id}/page": { "delete": { "description": "revoke → 204\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteNotesByIdPage", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete note page", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" }, "get": { "description": "the active page's status (never the secret or a key)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getNotesByIdPage", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdBy": "example", "encrypted": false, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "label": "example", "lastOpenedAt": 1794906000000, "noteId": "00000000-0000-4000-8000-000000000001", "publishedAt": 1794906000000, "snapshotAt": 1794906000000 }, "schema": { "properties": { "createdBy": { "type": "string" }, "encrypted": { "type": "boolean" }, "expiresAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "lastOpenedAt": { "type": [ "number", "null" ] }, "noteId": { "type": "string" }, "publishedAt": { "type": "number" }, "snapshotAt": { "type": [ "number", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get note page", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" }, "post": { "description": "`{label?, expiresInDays?, snapshot?, wrappedKey?}` → 201 the page with `link` (shown once), see [Note pages](https://open-todo.app/docs/api/#note-pages)\n\nRefuses read and agent tokens. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postNotesByIdPage", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "expiresInDays": 1, "label": "example", "snapshot": "example", "wrappedKey": "example" }, "schema": { "properties": { "expiresInDays": { "type": [ "number", "null" ] }, "label": { "type": [ "string", "null" ] }, "snapshot": { "type": "string" }, "wrappedKey": { "type": "string" } }, "required": [ "snapshot", "wrappedKey" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "encrypted": false, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "label": "example", "link": "example", "noteId": "00000000-0000-4000-8000-000000000001", "publishedAt": 1794906000000 }, "schema": { "properties": { "encrypted": { "type": "boolean" }, "expiresAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "link": { "type": "string" }, "noteId": { "type": "string" }, "publishedAt": { "type": "number" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Note page", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens.recent" } }, "/api/v1/notes/{id}/page/snapshot": { "put": { "description": "`{ciphertext, version, wrappedKey?}` → 200; an older `version` changes nothing\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "putNotesByIdPageSnapshot", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "ciphertext": "example", "version": 1, "wrappedKey": "example" }, "schema": { "properties": { "ciphertext": { "type": "string" }, "version": { "type": "number" }, "wrappedKey": { "type": "string" } }, "required": [ "ciphertext", "version", "wrappedKey" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "properties": { "ok": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update note page snapshot", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/notes/{id}/purge": { "delete": { "description": "permanently delete an item that is in the Trash → `{purged:{tasks,projects,notes,reminders,sections,comments}}`; 409 `not_deleted` otherwise", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteNotesByIdPurge", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "purged": { "attachments": 1, "comments": 1, "fields": 1, "notes": 1, "orphans": 1, "projects": 1, "reminders": 1, "sections": 1, "tasks": 1, "timeEntries": 1 } }, "schema": { "properties": { "purged": { "properties": { "attachments": { "type": "number" }, "comments": { "type": "number" }, "fields": { "type": "number" }, "notes": { "type": "number" }, "orphans": { "type": "number" }, "projects": { "type": "number" }, "reminders": { "type": "number" }, "sections": { "type": "number" }, "tasks": { "type": "number" }, "timeEntries": { "type": "number" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete note purge", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notes/{id}/to-task": { "post": { "description": "turn the note into a task in one batch (the note goes to the Trash) → 201 task; on an encrypted account the body carries `{task_id, title, description, notes_doc?}` sealed for that id, else 409 `encryption_enabled`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postNotesByIdToTask", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "example": { "appends": [ { "id": "00000000-0000-4000-8000-000000000009", "text": "- decided: green" } ], "body_version": "1794906000101:server:0a1b2c3d", "created_at": 1794906000100, "description": "- fence\n- beds", "energy": null, "fields": {}, "id": "00000000-0000-4000-8000-000000000011", "origin": null, "position": 1794906000100, "priority": 4, "rotation": [], "sector": null, "title": "Garden plan 2027" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Note to task", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notification-channels": { "get": { "description": "`{channels: [...], kinds, events}`: `id`, `kind`, `name`, `url`, `topic`, `events`, `includeTitles`, `enabled`, `disabledReason` (`too_many_failures`), `lang`, `tokenSet`, `userKeySet` (Pushover), `secretSet` (webhook), `lastOkAt`, `lastError`, `failures`, `createdAt`, `updatedAt`. Never a secret", "externalDocs": { "url": "https://open-todo.app/docs/api/#notification-channels" }, "operationId": "getNotificationChannels", "responses": { "200": { "content": { "application/json": { "example": { "channels": [ { "createdAt": 1794906000000, "disabledReason": "example", "enabled": false, "events": [ "example" ], "failures": 1, "id": "00000000-0000-4000-8000-000000000001", "includeTitles": false, "kind": "example", "lang": "example", "lastError": "example", "lastOkAt": 1794906000000, "name": "Ada", "secretSet": false, "tokenSet": false, "topic": "example", "updatedAt": 1794906000000, "url": "https://todo.example.com/", "userKeySet": false } ], "events": [ "example" ], "kinds": [ "example" ] }, "schema": { "properties": { "channels": { "items": { "properties": { "createdAt": { "type": "number" }, "disabledReason": { "type": "string" }, "enabled": { "type": "boolean" }, "events": { "items": { "type": "string" }, "type": "array" }, "failures": { "type": "number" }, "id": { "type": "string" }, "includeTitles": { "type": "boolean" }, "kind": { "type": "string" }, "lang": { "type": "string" }, "lastError": { "type": "string" }, "lastOkAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "secretSet": { "type": "boolean" }, "tokenSet": { "type": "boolean" }, "topic": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" }, "userKeySet": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "events": { "items": { "type": "string" }, "type": "array" }, "kinds": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List notification channels", "tags": [ "Notification channels" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{kind, name?, url?, topic?, token?, userKey?, events?, includeTitles?, enabled?, lang?, origin?}` → `201 {channel, secret?}`; `secret` is a webhook channel's signing secret, shown only here", "externalDocs": { "url": "https://open-todo.app/docs/api/#notification-channels" }, "operationId": "postNotificationChannels", "requestBody": { "content": { "application/json": { "example": { "enabled": false, "events": [ "example" ], "includeTitles": false, "kind": "example", "lang": "example", "name": "Ada", "origin": "example", "rotateSecret": false, "token": "ot_example_token", "topic": "example", "url": "https://todo.example.com/", "userKey": "example" }, "schema": { "properties": { "enabled": { "type": [ "boolean", "null" ] }, "events": { "items": { "type": "string" }, "type": "array" }, "includeTitles": { "type": [ "boolean", "null" ] }, "kind": { "type": [ "string", "null" ] }, "lang": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "origin": { "type": [ "string", "null" ] }, "rotateSecret": { "type": "boolean" }, "token": { "type": [ "string", "null" ] }, "topic": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "userKey": { "type": [ "string", "null" ] } }, "required": [ "rotateSecret" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "channel": { "createdAt": 1794906000000, "disabledReason": "example", "enabled": false, "events": [ "example" ], "failures": 1, "id": "00000000-0000-4000-8000-000000000001", "includeTitles": false, "kind": "example", "lang": "example", "lastError": "example", "lastOkAt": 1794906000000, "name": "Ada", "secretSet": false, "tokenSet": false, "topic": "example", "updatedAt": 1794906000000, "url": "https://todo.example.com/", "userKeySet": false }, "secret": "example-secret" }, "schema": { "properties": { "channel": { "properties": { "createdAt": { "type": "number" }, "disabledReason": { "type": "string" }, "enabled": { "type": "boolean" }, "events": { "items": { "type": "string" }, "type": "array" }, "failures": { "type": "number" }, "id": { "type": "string" }, "includeTitles": { "type": "boolean" }, "kind": { "type": "string" }, "lang": { "type": "string" }, "lastError": { "type": "string" }, "lastOkAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "secretSet": { "type": "boolean" }, "tokenSet": { "type": "boolean" }, "topic": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" }, "userKeySet": { "type": "boolean" } }, "type": [ "object", "null" ] }, "secret": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a notification channel", "tags": [ "Notification channels" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notification-channels/{id}": { "delete": { "description": "`204`; its secrets and queued messages are removed", "externalDocs": { "url": "https://open-todo.app/docs/api/#notification-channels" }, "operationId": "deleteNotificationChannelsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a notification channel", "tags": [ "Notification channels" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "any field above except `kind`; `token` and `userKey` replace the stored ones; `rotateSecret: true` gives a webhook channel a new signing secret, returned once as `secret`; `enabled: true` clears a stop and the failure count", "externalDocs": { "url": "https://open-todo.app/docs/api/#notification-channels" }, "operationId": "patchNotificationChannelsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "enabled": false, "events": [ "example" ], "includeTitles": false, "kind": "example", "lang": "example", "name": "Ada", "origin": "example", "rotateSecret": false, "token": "ot_example_token", "topic": "example", "url": "https://todo.example.com/", "userKey": "example" }, "schema": { "properties": { "enabled": { "type": [ "boolean", "null" ] }, "events": { "items": { "type": "string" }, "type": "array" }, "includeTitles": { "type": [ "boolean", "null" ] }, "kind": { "type": [ "string", "null" ] }, "lang": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "origin": { "type": [ "string", "null" ] }, "rotateSecret": { "type": "boolean" }, "token": { "type": [ "string", "null" ] }, "topic": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "userKey": { "type": [ "string", "null" ] } }, "required": [ "rotateSecret" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "channel": { "createdAt": 1794906000000, "disabledReason": "example", "enabled": false, "events": [ "example" ], "failures": 1, "id": "00000000-0000-4000-8000-000000000001", "includeTitles": false, "kind": "example", "lang": "example", "lastError": "example", "lastOkAt": 1794906000000, "name": "Ada", "secretSet": false, "tokenSet": false, "topic": "example", "updatedAt": 1794906000000, "url": "https://todo.example.com/", "userKeySet": false }, "secret": "example-secret" }, "schema": { "properties": { "channel": { "properties": { "createdAt": { "type": "number" }, "disabledReason": { "type": "string" }, "enabled": { "type": "boolean" }, "events": { "items": { "type": "string" }, "type": "array" }, "failures": { "type": "number" }, "id": { "type": "string" }, "includeTitles": { "type": "boolean" }, "kind": { "type": "string" }, "lang": { "type": "string" }, "lastError": { "type": "string" }, "lastOkAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "secretSet": { "type": "boolean" }, "tokenSet": { "type": "boolean" }, "topic": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" }, "userKeySet": { "type": "boolean" } }, "type": [ "object", "null" ] }, "secret": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a notification channel", "tags": [ "Notification channels" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notification-channels/{id}/deliveries": { "get": { "description": "`{deliveries: [{id, event, status, attempts, nextAttemptAt, lastStatusCode, lastError, createdAt, deliveredAt}]}`, newest first, at most 50; `status` is `pending`, `retry`, `delivered`, `failed` or `skipped` (`rate_limited`)", "externalDocs": { "url": "https://open-todo.app/docs/api/#notification-channels" }, "operationId": "getNotificationChannelsByIdDeliveries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "deliveries": [ { "attempts": 1, "createdAt": 1794906000000, "deliveredAt": 1794906000000, "event": "example", "id": "00000000-0000-4000-8000-000000000001", "lastError": "example", "lastStatusCode": 1, "nextAttemptAt": 1794906000000, "status": "example" } ] }, "schema": { "properties": { "deliveries": { "items": { "properties": { "attempts": { "type": "number" }, "createdAt": { "type": "number" }, "deliveredAt": { "type": [ "number", "null" ] }, "event": { "type": "string" }, "id": { "type": "string" }, "lastError": { "type": "string" }, "lastStatusCode": { "type": [ "number", "null" ] }, "nextAttemptAt": { "type": [ "number", "null" ] }, "status": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List notification channel deliveries", "tags": [ "Notification channels" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notification-channels/{id}/test": { "post": { "description": "send \"Test from OpenTodo\" now: `{delivered, statusCode?, error?}`; at most 12 per account per hour (`429 rate_limited`)", "externalDocs": { "url": "https://open-todo.app/docs/api/#notification-channels" }, "operationId": "postNotificationChannelsByIdTest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "delivered": false, "error": "example", "statusCode": 1 }, "schema": { "properties": { "delivered": { "type": "boolean" }, "error": { "type": "string" }, "statusCode": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Notification channel test", "tags": [ "Notification channels" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notifications": { "get": { "description": "your in-app notifications and the unread count, see [Assignment and notifications](https://open-todo.app/docs/api/#assignment-and-notifications)", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getNotifications", "responses": { "200": { "content": { "application/json": { "example": { "notifications": [ { "createdAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "payload": "example", "readAt": 1794906000000 } ], "unread": 1 }, "schema": { "properties": { "notifications": { "items": { "properties": { "createdAt": { "type": "number" }, "id": { "type": "string" }, "kind": { "type": "string" }, "payload": { "type": "string" }, "readAt": { "type": [ "number", "null" ] } }, "type": "object" }, "type": "array" }, "unread": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List notifications", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/notifications/{id}/read": { "post": { "description": "mark one read → 204", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postNotificationsByIdRead", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Notification read", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/objectives": { "get": { "description": "same shape for your quarterly and weekly [objectives](https://open-todo.app/docs/api/#objectives): `{title, period, position, done_at}`; the list takes `?period=\u003cYYYY-Qn or YYYY-Www\u003e` and `?open=true`; 409 `too_many_objectives` past 5 open in a period", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getObjectives", "responses": { "200": { "content": { "application/json": { "example": { "objectives": [ { "created_at": 1794906000000, "deleted_at": 1794906000000, "done_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "period": "example", "position": 1, "title": "Buy paint for the fence" } ] }, "schema": { "properties": { "objectives": { "items": { "$ref": "#/components/schemas/Objective" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List objectives", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "same shape for your quarterly and weekly [objectives](https://open-todo.app/docs/api/#objectives): `{title, period, position, done_at}`; the list takes `?period=\u003cYYYY-Qn or YYYY-Www\u003e` and `?open=true`; 409 `too_many_objectives` past 5 open in a period", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postObjectives", "requestBody": { "content": { "application/json": { "example": { "created_at": 1794906000000, "deleted_at": 1794906000000, "done_at": 1794906000000, "period": "example", "position": 1, "title": "Buy paint for the fence" }, "schema": { "properties": { "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "done_at": { "type": "number" }, "period": { "description": "An objective's period: a quarter (2026-Q4), a month or a year.", "type": "string" }, "position": { "type": "number" }, "title": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "created_at": 1794906000000, "deleted_at": 1794906000000, "done_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "period": "example", "position": 1, "title": "Buy paint for the fence" }, "schema": { "$ref": "#/components/schemas/Objective" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a objective", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/objectives/{id}": { "delete": { "description": "same shape for your quarterly and weekly [objectives](https://open-todo.app/docs/api/#objectives): `{title, period, position, done_at}`; the list takes `?period=\u003cYYYY-Qn or YYYY-Www\u003e` and `?open=true`; 409 `too_many_objectives` past 5 open in a period", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteObjectivesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a objective", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "same shape for your quarterly and weekly [objectives](https://open-todo.app/docs/api/#objectives): `{title, period, position, done_at}`; the list takes `?period=\u003cYYYY-Qn or YYYY-Www\u003e` and `?open=true`; 409 `too_many_objectives` past 5 open in a period", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getObjectivesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "created_at": 1794906000000, "deleted_at": 1794906000000, "done_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "period": "example", "position": 1, "title": "Buy paint for the fence" }, "schema": { "$ref": "#/components/schemas/Objective" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a objective", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "same shape for your quarterly and weekly [objectives](https://open-todo.app/docs/api/#objectives): `{title, period, position, done_at}`; the list takes `?period=\u003cYYYY-Qn or YYYY-Www\u003e` and `?open=true`; 409 `too_many_objectives` past 5 open in a period", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "patchObjectivesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "created_at": 1794906000000, "deleted_at": 1794906000000, "done_at": 1794906000000, "period": "example", "position": 1, "title": "Buy paint for the fence" }, "schema": { "properties": { "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "done_at": { "type": "number" }, "period": { "description": "An objective's period: a quarter (2026-Q4), a month or a year.", "type": "string" }, "position": { "type": "number" }, "title": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "created_at": 1794906000000, "deleted_at": 1794906000000, "done_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "period": "example", "position": 1, "title": "Buy paint for the fence" }, "schema": { "$ref": "#/components/schemas/Objective" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a objective", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/openapi.json": { "get": { "description": "The [OpenAPI 3.1 description](https://open-todo.app/docs/api/#openapi-description) of this server's API: `application/json`, gzip when accepted, `ETag` and `Cache-Control: public, max-age=3600`, readable from any site\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "getOpenapiJson", "responses": { "200": { "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get openapi.json", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/pages/{secret}": { "get": { "description": "the page: `kind` `task` or `note`, `mode` `live` (the shown fields) or `encrypted` (`snapshot`)\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getPagesBySecret", "parameters": [ { "in": "path", "name": "secret", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "changedAt": 1794906000000, "comments": [ {} ], "files": [ {} ], "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "label": "example", "links": [ {} ], "location": "example", "mode": "example", "rights": "example", "serverTime": 1794906000000, "snapshot": "example", "snapshotAt": 1794906000000, "subtasks": [ {} ], "text": "example", "title": "Buy paint for the fence" }, "schema": { "properties": { "changedAt": { "type": "number" }, "comments": { "items": { "type": "object" }, "type": "array" }, "files": { "items": { "type": "object" }, "type": "array" }, "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "links": { "items": { "type": "object" }, "type": "array" }, "location": { "type": "string" }, "mode": { "type": "string" }, "rights": { "type": "string" }, "serverTime": { "type": "number" }, "snapshot": { "type": "string" }, "snapshotAt": { "type": [ "number", "null" ] }, "subtasks": { "items": { "type": "object" }, "type": "array" }, "text": { "type": "string" }, "title": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a page", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "public" } }, "/api/v1/pages/{secret}/files/{fileId}": { "get": { "description": "a file of the task, as a download; of a note page, a raster image inline\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getPagesBySecretFilesByFileId", "parameters": [ { "in": "path", "name": "secret", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "fileId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a page file", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "public" } }, "/api/v1/pages/{secret}/maps/fonts/{fontstack}/{range}": { "get": { "description": "the page's map style, tiles, fonts and sprites, see [Maps](https://open-todo.app/docs/api/#maps)\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getPagesBySecretMapsFontsByFontstackByRange", "parameters": [ { "in": "path", "name": "secret", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "fontstack", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "range", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a page maps font", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "public" } }, "/api/v1/pages/{secret}/maps/sprites/{file}": { "get": { "description": "the page's map style, tiles, fonts and sprites, see [Maps](https://open-todo.app/docs/api/#maps)\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getPagesBySecretMapsSpritesByFile", "parameters": [ { "in": "path", "name": "secret", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "file", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a page maps sprite", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "public" } }, "/api/v1/pages/{secret}/maps/style": { "get": { "description": "No authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#maps" }, "operationId": "getPagesBySecretMapsStyle", "parameters": [ { "in": "path", "name": "secret", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get page maps style", "tags": [ "Maps" ], "x-opentodo-policy": "public" } }, "/api/v1/pages/{secret}/maps/tiles/{z}/{x}/{y}": { "get": { "description": "the page's map style, tiles, fonts and sprites, see [Maps](https://open-todo.app/docs/api/#maps)\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getPagesBySecretMapsTilesByZByXByY", "parameters": [ { "in": "path", "name": "secret", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "z", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "x", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "y", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a page maps tile", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "public" } }, "/api/v1/pages/{secret}/replies": { "post": { "description": "`{name, body}`, or `{ciphertext}` on an encrypted page → 201\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postPagesBySecretReplies", "parameters": [ { "in": "path", "name": "secret", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "body": "example", "ciphertext": "example", "name": "Ada" }, "schema": { "properties": { "body": { "type": "string" }, "ciphertext": { "type": "string" }, "name": { "type": "string" } }, "required": [ "body", "ciphertext", "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "body": "example", "createdAt": 1794906000000, "guest": false, "id": "00000000-0000-4000-8000-000000000001", "name": "Ada", "pending": false }, "schema": { "properties": { "body": { "type": "string" }, "createdAt": { "type": "number" }, "guest": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "pending": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Create a page reply", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "public" } }, "/api/v1/pages/{secret}/tick": { "post": { "description": "`{taskId, completed, name}` → `{taskId, completed_at}`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postPagesBySecretTick", "parameters": [ { "in": "path", "name": "secret", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "completed": false, "name": "Ada", "taskId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "completed": { "type": [ "boolean", "null" ] }, "name": { "type": "string" }, "taskId": { "type": "string" } }, "required": [ "name", "taskId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "completed_at": "example", "taskId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "completed_at": { "type": "string" }, "taskId": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Page tick", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "public" } }, "/api/v1/passkeys": { "get": { "description": "`{passkeys:[{id,name,createdAt,lastUsedAt,suspiciousAt,backedUp}]}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getPasskeys", "responses": { "200": { "content": { "application/json": { "example": { "passkeys": [ { "backedUp": false, "createdAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "name": "Ada", "suspiciousAt": 1794906000000 } ] }, "schema": { "properties": { "passkeys": { "items": { "properties": { "backedUp": { "type": "boolean" }, "createdAt": { "type": "number" }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "suspiciousAt": { "type": [ "number", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List passkeys", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/passkeys/register": { "post": { "description": "`{name, credential}` → 201 `{passkey}`\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postPasskeysRegister", "requestBody": { "content": { "application/json": { "example": { "credential": { "id": "00000000-0000-4000-8000-000000000001", "rawId": "00000000-0000-4000-8000-000000000001", "response": { "attestationObject": "example", "authenticatorData": "example", "clientDataJSON": "example", "signature": "example", "transports": [ "example" ] }, "type": "example" }, "name": "Ada" }, "schema": { "properties": { "credential": { "properties": { "id": { "type": "string" }, "rawId": { "type": "string" }, "response": { "properties": { "attestationObject": { "type": "string" }, "authenticatorData": { "type": "string" }, "clientDataJSON": { "type": "string" }, "signature": { "type": "string" }, "transports": { "items": { "type": "string" }, "type": "array" } }, "required": [ "attestationObject", "authenticatorData", "clientDataJSON", "signature", "transports" ], "type": "object" }, "type": { "type": "string" } }, "required": [ "id", "rawId", "response", "type" ], "type": "object" }, "name": { "type": "string" } }, "required": [ "credential", "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "passkey": { "backedUp": false, "createdAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "name": "Ada", "suspiciousAt": 1794906000000 } }, "schema": { "properties": { "passkey": { "properties": { "backedUp": { "type": "boolean" }, "createdAt": { "type": "number" }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "suspiciousAt": { "type": [ "number", "null" ] } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Passkeys register", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential.recent" } }, "/api/v1/passkeys/register/options": { "post": { "description": "→ `{publicKey}` creation options\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postPasskeysRegisterOptions", "responses": { "200": { "content": { "application/json": { "example": { "publicKey": { "attestation": "example", "authenticatorSelection": {}, "challenge": "example", "excludeCredentials": [ { "id": "00000000-0000-4000-8000-000000000001", "type": "example" } ], "pubKeyCredParams": [ {} ], "rp": {}, "timeout": 1, "user": {} } }, "schema": { "properties": { "publicKey": { "properties": { "attestation": { "type": "string" }, "authenticatorSelection": { "type": "object" }, "challenge": { "type": "string" }, "excludeCredentials": { "items": { "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "pubKeyCredParams": { "items": { "type": "object" }, "type": "array" }, "rp": { "type": "object" }, "timeout": { "type": "number" }, "user": { "type": "object" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a passkeys register option", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential.recent" } }, "/api/v1/passkeys/{id}": { "delete": { "description": "204\n\nNeeds a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "deletePasskeysById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a passkey", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential" }, "patch": { "description": "`{name}` → `{passkey}`\n\nNeeds a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "patchPasskeysById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Ada" }, "schema": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "passkey": { "backedUp": false, "createdAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "name": "Ada", "suspiciousAt": 1794906000000 } }, "schema": { "properties": { "passkey": { "properties": { "backedUp": { "type": "boolean" }, "createdAt": { "type": "number" }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "suspiciousAt": { "type": [ "number", "null" ] } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a passkey", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential" } }, "/api/v1/password-resets/{token}": { "get": { "description": "preview `{email, expiresAt}` or 404 `reset_invalid`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "getPasswordResetsByToken", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "email": "ada@example.com", "expiresAt": 1794906000000 }, "schema": { "properties": { "email": { "type": "string" }, "expiresAt": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a password reset", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" }, "post": { "description": "`{password}` → 204 or 404 `reset_invalid`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "postPasswordResetsByToken", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "password": "correct horse battery staple" }, "schema": { "properties": { "password": { "type": "string" } }, "required": [ "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Password reset", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/places": { "get": { "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "operationId": "getPlaces", "responses": { "200": { "content": { "application/json": { "example": { "places": [ {} ] }, "schema": { "properties": { "places": { "items": { "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List places", "tags": [ "Agent tokens" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/project-invites/{token}": { "get": { "description": "preview `{inviterName, projectName, role, email, expiresAt, canCreateAccount, alreadyMember?}` or 404 `invitation_invalid`, see [Project invite links](https://open-todo.app/docs/api/#project-invite-links)\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "operationId": "getProjectInvitesByToken", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "alreadyMember": false, "canCreateAccount": false, "email": "ada@example.com", "expiresAt": 1794906000000, "inviterName": "Ada", "projectName": "Ada", "role": "member" }, "schema": { "properties": { "alreadyMember": { "type": "boolean" }, "canCreateAccount": { "type": "boolean" }, "email": { "type": [ "string", "null" ] }, "expiresAt": { "type": "number" }, "inviterName": { "type": "string" }, "projectName": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a project invite", "tags": [ "Health and authentication" ], "x-opentodo-policy": "public" } }, "/api/v1/project-invites/{token}/accept": { "post": { "description": "join the project as the signed-in account → `{projectId, role}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postProjectInvitesByTokenAccept", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Project invite accept", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects": { "get": { "description": "same shape for projects, see [Project fields](https://open-todo.app/docs/api/#project-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getProjects", "responses": { "200": { "content": { "application/json": { "example": { "projects": [ { "aisles": false, "body_version": "0", "color": "#3b82f6", "created_at": 1794906000006, "flow_mode": "", "id": "00000000-0000-4000-8000-000000000002", "name": "Home and garden", "position": 1794906000006, "reusable": false, "status": "active" } ] }, "schema": { "properties": { "projects": { "items": { "allOf": [ { "$ref": "#/components/schemas/Project" }, { "properties": { "body_version": { "type": "string" } }, "type": "object" } ] }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List projects", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`name`, `color`, `parent_id`, `icon`, `flow_mode` (`archived: false` is accepted)", "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "operationId": "postProjects", "requestBody": { "content": { "application/json": { "example": { "color": "#3b82f6", "name": "Home" }, "schema": { "properties": { "aisles": { "type": "boolean" }, "archived": { "type": "boolean" }, "color": { "type": "string" }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "flow_mode": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "notes_doc": { "description": "A mergeable notes document (\"ydoc:v1:…\"), see docs/sync.md \"Mergeable documents\". Write `description` (Markdown) instead unless you merge documents yourself.", "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "position": { "type": "number" }, "reusable": { "type": "boolean" }, "status": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "aisles": false, "body_version": "0", "color": "#3b82f6", "created_at": 1794906000006, "flow_mode": "", "id": "00000000-0000-4000-8000-000000000002", "name": "Home", "position": 1794906000006, "reusable": false, "status": "active" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Project" }, { "properties": { "body_version": { "type": "string" } }, "type": "object" } ] } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a project", "tags": [ "Agent tokens" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects/{id}": { "delete": { "description": "same shape for projects, see [Project fields](https://open-todo.app/docs/api/#project-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteProjectsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a project", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "same shape for projects, see [Project fields](https://open-todo.app/docs/api/#project-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getProjectsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "aisles": false, "body_version": "0", "color": "#3b82f6", "created_at": 1794906000006, "flow_mode": "", "id": "00000000-0000-4000-8000-000000000002", "name": "Home", "position": 1794906000006, "reusable": false, "status": "active" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Project" }, { "properties": { "body_version": { "type": "string" } }, "type": "object" } ] } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a project", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`name`, `color`, `icon` and `parent_id` (`null` clears them), `description` (the project's note, Markdown; editors may write it); or `archived` on its own (`true` archives the project with its sub-projects, `false` unarchives that project; owner or admin only; with any other field 400 `invalid_input`)", "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "operationId": "patchProjectsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Home and garden" }, "schema": { "properties": { "aisles": { "type": "boolean" }, "archived": { "type": "boolean" }, "color": { "type": "string" }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "flow_mode": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "notes_doc": { "description": "A mergeable notes document (\"ydoc:v1:…\"), see docs/sync.md \"Mergeable documents\". Write `description` (Markdown) instead unless you merge documents yourself.", "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "position": { "type": "number" }, "reusable": { "type": "boolean" }, "status": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "aisles": false, "body_version": "0", "color": "#3b82f6", "created_at": 1794906000006, "flow_mode": "", "id": "00000000-0000-4000-8000-000000000002", "name": "Home and garden", "position": 1794906000006, "reusable": false, "status": "active" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Project" }, { "properties": { "body_version": { "type": "string" } }, "type": "object" } ] } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a project", "tags": [ "Agent tokens" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects/{id}/activity": { "get": { "description": "`{events, more, cursor?}` newest first, derived from the operation log; `?before=\u003ccursor\u003e\u0026limit=\u003c1-200\u003e` (default 50)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getProjectsByIdActivity", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "cursor": "example", "events": [ { "actor": "example", "actorName": "Ada", "changes": [ { "field": "example", "from": "example", "to": "example" } ], "device": "example", "entity": "example", "entityId": "00000000-0000-4000-8000-000000000001", "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "opIds": [ "00000000-0000-4000-8000-000000000001" ], "projectId": "00000000-0000-4000-8000-000000000001", "projectName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence", "ts": 1794906000000 } ], "more": false }, "schema": { "properties": { "cursor": { "type": "string" }, "events": { "items": { "properties": { "actor": { "type": "string" }, "actorName": { "type": "string" }, "changes": { "items": { "properties": { "field": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "device": { "type": "string" }, "entity": { "type": "string" }, "entityId": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "opIds": { "items": { "type": "string" }, "type": "array" }, "projectId": { "type": "string" }, "projectName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" }, "ts": { "type": "number" } }, "type": "object" }, "type": "array" }, "more": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get project activity", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects/{id}/agent-access": { "get": { "description": "`{kept_away, inherited_from}`; `inherited_from` is the nearest ancestor that is kept away, or `null`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#keeping-a-project-away-from-assistants" }, "operationId": "getProjectsByIdAgentAccess", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "inherited_from": "example", "kept_away": false }, "schema": { "properties": { "inherited_from": { "type": [ "string", "null" ] }, "kept_away": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get project agent access", "tags": [ "Keeping a project away from assistants" ], "x-opentodo-policy": "signed-in.full-tokens" }, "put": { "description": "`{kept_away: boolean}` → the same shape; recorded as `project.agent_access`; demo instances → 403 `demo_restricted`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#keeping-a-project-away-from-assistants" }, "operationId": "putProjectsByIdAgentAccess", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "inherited_from": "example", "kept_away": false }, "schema": { "properties": { "inherited_from": { "type": [ "string", "null" ] }, "kept_away": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update project agent access", "tags": [ "Keeping a project away from assistants" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/projects/{id}/grants": { "post": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "postProjectsByIdGrants", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "groupId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "groupId": { "type": "string" }, "role": { "type": "string" } }, "required": [ "groupId", "role" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "grants": [ { "groupId": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } ], "members": [ { "avatarVersion": 1, "email": "ada@example.com", "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001", "via": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" } ] } ], "ownerId": "00000000-0000-4000-8000-000000000001", "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "grants": { "items": { "properties": { "groupId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "members": { "items": { "properties": { "avatarVersion": { "type": "number" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" }, "via": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "ownerId": { "type": "string" }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a project grant", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/projects/{id}/grants/{groupId}": { "delete": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "deleteProjectsByIdGrantsByGroupId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "groupId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "grants": [ { "groupId": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } ], "members": [ { "avatarVersion": 1, "email": "ada@example.com", "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001", "via": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" } ] } ], "ownerId": "00000000-0000-4000-8000-000000000001", "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "grants": { "items": { "properties": { "groupId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "members": { "items": { "properties": { "avatarVersion": { "type": "number" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" }, "via": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "ownerId": { "type": "string" }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a project grant", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" }, "patch": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "patchProjectsByIdGrantsByGroupId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "groupId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "role": "member" }, "schema": { "properties": { "role": { "type": "string" } }, "required": [ "role" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "grants": [ { "groupId": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } ], "members": [ { "avatarVersion": 1, "email": "ada@example.com", "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001", "via": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" } ] } ], "ownerId": "00000000-0000-4000-8000-000000000001", "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "grants": { "items": { "properties": { "groupId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "members": { "items": { "properties": { "avatarVersion": { "type": "number" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" }, "via": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "ownerId": { "type": "string" }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a project grant", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/projects/{id}/history": { "get": { "description": "change sets from the operation log, oldest first; `?before=\u003cts\u003e\u0026limit=\u003c1-200\u003e` pages backwards; see [Trash and history](https://open-todo.app/docs/api/#trash-and-history)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getProjectsByIdHistory", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "before": 1, "changeSets": [ { "changes": [ { "field": "example", "from": "example", "lost": false, "opId": "00000000-0000-4000-8000-000000000001", "to": "example" } ], "device": "example", "device_label": "example", "ts": 1794906000000, "userId": "00000000-0000-4000-8000-000000000001" } ], "entity": "example", "id": "00000000-0000-4000-8000-000000000001", "more": false }, "schema": { "properties": { "before": { "type": "number" }, "changeSets": { "items": { "properties": { "changes": { "items": { "properties": { "field": { "type": "string" }, "from": { "type": "string" }, "lost": { "type": "boolean" }, "opId": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "device": { "type": "string" }, "device_label": { "type": "string" }, "ts": { "type": "number" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "entity": { "type": "string" }, "id": { "type": "string" }, "more": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get project history", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects/{id}/invites": { "get": { "description": "pending invite links `{invites:[…]}`, see [Project invite links](https://open-todo.app/docs/api/#project-invite-links)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getProjectsByIdInvites", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "invites": [ { "createdAt": 1794906000000, "createdBy": "example", "createdByName": "Ada", "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" } ] }, "schema": { "properties": { "invites": { "items": { "properties": { "createdAt": { "type": "number" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List project invites", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{role, email?, expiresInHours?, send?}` → 201 `{invite, link, newAccounts, sent?}` (link shown once; `send` mails it to `email`)\n\nNeeds a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postProjectsByIdInvites", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "email": "ada@example.com", "expiresInHours": 1, "role": "member", "send": false }, "schema": { "properties": { "email": { "type": "string" }, "expiresInHours": { "type": [ "number", "null" ] }, "role": { "type": "string" }, "send": { "type": "boolean" } }, "required": [ "email", "role", "send" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "invite": { "createdAt": 1794906000000, "createdBy": "example", "createdByName": "Ada", "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "link": "example", "newAccounts": false, "sent": false }, "schema": { "properties": { "invite": { "properties": { "createdAt": { "type": "number" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": [ "object", "null" ] }, "link": { "type": "string" }, "newAccounts": { "type": "boolean" }, "sent": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a project invite", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.recent" } }, "/api/v1/projects/{id}/invites/{inviteId}": { "delete": { "description": "revoke a pending link → 204", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteProjectsByIdInvitesByInviteId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "inviteId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a project invite", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects/{id}/member-invitations/{invitationId}": { "delete": { "description": "cancel an open invitation → 204; 404 `not_found`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteProjectsByIdMemberInvitationsByInvitationId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "invitationId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a project member invitation", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects/{id}/members": { "get": { "description": "`{projectId, role, ownerId, members:[{userId,name,email,role}], pending?}`; `pending` (owners and admins only) lists the open [invitations](https://open-todo.app/docs/api/#membership-invitations) `[{id,email,role,invitedBy,createdAt,expiresAt}]`, see [Sharing](https://open-todo.app/docs/api/#sharing)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getProjectsByIdMembers", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "grants": [ { "groupId": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } ], "members": [ { "avatarVersion": 1, "email": "ada@example.com", "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001", "via": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" } ] } ], "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "grants": { "items": { "properties": { "groupId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "members": { "items": { "properties": { "avatarVersion": { "type": "number" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" }, "via": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List project members", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{email, role}` → 201 membership (shares the project on first use) when the account already shares a project or workspace with you, otherwise **202 `{pending: true}`**, also for an address without an account: the person is invited and becomes a member when they accept (see [Membership invitations](https://open-todo.app/docs/api/#membership-invitations)); 400 `invalid_input` for anything but one address; recorded as `project.member_added` or `member_invitation.created`; adding by email is limited to 30 attempts per account per hour, together with workspace members (429 `rate_limited`)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postProjectsByIdMembers", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "email": "ada@example.com", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "email": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "email", "role", "userId" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "grants": [ { "groupId": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } ], "members": [ { "avatarVersion": 1, "email": "ada@example.com", "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001", "via": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" } ] } ], "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "grants": { "items": { "properties": { "groupId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "members": { "items": { "properties": { "avatarVersion": { "type": "number" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" }, "via": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "ownerId": { "type": "string" }, "pending": { "anyOf": [ { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, { "type": "boolean" } ] }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "202": { "content": { "application/json": { "example": { "grants": [ { "groupId": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } ], "members": [ { "avatarVersion": 1, "email": "ada@example.com", "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001", "via": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" } ] } ], "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "grants": { "items": { "properties": { "groupId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "members": { "items": { "properties": { "avatarVersion": { "type": "number" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" }, "via": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "ownerId": { "type": "string" }, "pending": { "anyOf": [ { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, { "type": "boolean" } ] }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "Accepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a project member", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects/{id}/members/{userId}": { "delete": { "description": "remove a member, or leave with your own id or `me` → 204", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteProjectsByIdMembersByUserId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a project member", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`{role}` → membership", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "patchProjectsByIdMembersByUserId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "role": "member" }, "schema": { "properties": { "role": { "type": "string" } }, "required": [ "role" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "grants": [ { "groupId": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } ], "members": [ { "avatarVersion": 1, "email": "ada@example.com", "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001", "via": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" } ] } ], "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "grants": { "items": { "properties": { "groupId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "members": { "items": { "properties": { "avatarVersion": { "type": "number" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" }, "via": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a project member", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects/{id}/public-links": { "get": { "description": "active public links `{links:[…]}`, see [Public links](https://open-todo.app/docs/api/#public-links)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getProjectsByIdPublicLinks", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "links": [ { "createdAt": 1794906000000, "createdBy": "example", "createdByName": "Ada", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "layout": "example", "name": "Ada", "projectId": "00000000-0000-4000-8000-000000000001", "rights": "example" } ] }, "schema": { "properties": { "links": { "items": { "properties": { "createdAt": { "type": "number" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "expiresAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "layout": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "projectId": { "type": "string" }, "rights": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List project public links", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{rights, name?, layout?, expiresInDays?}` → 201 the link with `link` (shown once)\n\nNeeds a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postProjectsByIdPublicLinks", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "expiresInDays": 1, "layout": "example", "name": "Ada", "rights": "example" }, "schema": { "properties": { "expiresInDays": { "type": [ "number", "null" ] }, "layout": { "type": "string" }, "name": { "type": "string" }, "rights": { "type": "string" } }, "required": [ "layout", "name", "rights" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "createdAt": 1794906000000, "createdBy": "example", "createdByName": "Ada", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "layout": "example", "link": "example", "name": "Ada", "projectId": "00000000-0000-4000-8000-000000000001", "rights": "example" }, "schema": { "properties": { "createdAt": { "type": "number" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "expiresAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "layout": { "type": "string" }, "link": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "projectId": { "type": "string" }, "rights": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a project public link", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.recent" } }, "/api/v1/projects/{id}/public-links/{linkId}": { "delete": { "description": "revoke → 204", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteProjectsByIdPublicLinksByLinkId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "linkId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a project public link", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects/{id}/purge": { "delete": { "description": "permanently delete an item that is in the Trash → `{purged:{tasks,projects,notes,reminders,sections,comments}}`; 409 `not_deleted` otherwise", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteProjectsByIdPurge", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "purged": { "attachments": 1, "comments": 1, "fields": 1, "notes": 1, "orphans": 1, "projects": 1, "reminders": 1, "sections": 1, "tasks": 1, "timeEntries": 1 } }, "schema": { "properties": { "purged": { "properties": { "attachments": { "type": "number" }, "comments": { "type": "number" }, "fields": { "type": "number" }, "notes": { "type": "number" }, "orphans": { "type": "number" }, "projects": { "type": "number" }, "reminders": { "type": "number" }, "sections": { "type": "number" }, "tasks": { "type": "number" }, "timeEntries": { "type": "number" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete project purge", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/projects/{id}/transfer": { "post": { "description": "`{userId}` → membership; the previous owner becomes an admin", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postProjectsByIdTransfer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "userId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "userId": { "type": "string" } }, "required": [ "userId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "grants": [ { "groupId": "00000000-0000-4000-8000-000000000001", "name": "Ada", "role": "member" } ], "members": [ { "avatarVersion": 1, "email": "ada@example.com", "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001", "via": [ { "id": "00000000-0000-4000-8000-000000000001", "name": "Ada" } ] } ], "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "projectId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "grants": { "items": { "properties": { "groupId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "members": { "items": { "properties": { "avatarVersion": { "type": "number" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" }, "via": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Project transfer", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/public/{token}": { "get": { "description": "a public list `{projectName, projectColor, rights, sections, tasks, serverTime}`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getPublicByToken", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "layout": "example", "projectColor": "#3b82f6", "projectName": "Ada", "rights": "example", "sections": [ {} ], "serverTime": 1794906000000, "tasks": [ {} ] }, "schema": { "properties": { "layout": { "type": "string" }, "projectColor": { "type": "string" }, "projectName": { "type": "string" }, "rights": { "type": "string" }, "sections": { "items": { "type": "object" }, "type": "array" }, "serverTime": { "type": "number" }, "tasks": { "items": { "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a public", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "public" } }, "/api/v1/public/{token}/tick": { "post": { "description": "`{taskId, completed}` → `{taskId, completed_at}`\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postPublicByTokenTick", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "completed": false, "taskId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "completed": { "type": [ "boolean", "null" ] }, "taskId": { "type": "string" } }, "required": [ "taskId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "completed_at": "example", "taskId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "completed_at": { "type": "string" }, "taskId": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Public tick", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "public" } }, "/api/v1/push/subscriptions": { "post": { "description": "`{deviceId, endpoint, keys:{p256dh, auth}, includeContent?}` → 201 `{subscription}` (200 when the device's subscription was replaced)", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postPushSubscriptions", "requestBody": { "content": { "application/json": { "example": { "deviceId": "00000000-0000-4000-8000-000000000001", "endpoint": "example", "includeContent": false, "keys": { "auth": "example", "p256dh": "example" } }, "schema": { "properties": { "deviceId": { "type": "string" }, "endpoint": { "type": "string" }, "includeContent": { "type": "boolean" }, "keys": { "properties": { "auth": { "type": "string" }, "p256dh": { "type": "string" } }, "required": [ "auth", "p256dh" ], "type": "object" } }, "required": [ "deviceId", "endpoint", "includeContent", "keys" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "subscription": { "createdAt": 1794906000000, "deviceId": "00000000-0000-4000-8000-000000000001", "failures": 1, "id": "00000000-0000-4000-8000-000000000001", "includeContent": false, "lastError": "example", "lastOkAt": 1794906000000, "needsRenewal": false } }, "schema": { "properties": { "subscription": { "properties": { "createdAt": { "type": "number" }, "deviceId": { "type": "string" }, "failures": { "type": "number" }, "id": { "type": "string" }, "includeContent": { "type": "boolean" }, "lastError": { "type": "string" }, "lastOkAt": { "type": [ "number", "null" ] }, "needsRenewal": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a push subscription", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/push/subscriptions/{id}": { "delete": { "description": "204, or 404 `not_found`", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "deletePushSubscriptionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a push subscription", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/push/test": { "post": { "description": "`{deviceId}` → 200 `{outcome, testId?, subscription, status?, error?}`: sends one real test push to that device; 5 per account per 10 minutes, see [Reminders and push](https://open-todo.app/docs/api/#reminders-and-push)", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postPushTest", "requestBody": { "content": { "application/json": { "example": { "deviceId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "deviceId": { "type": "string" } }, "required": [ "deviceId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "error": "example", "outcome": "example", "status": 1, "subscription": { "createdAt": 1794906000000, "deviceId": "00000000-0000-4000-8000-000000000001", "failures": 1, "id": "00000000-0000-4000-8000-000000000001", "includeContent": false, "lastError": "example", "lastOkAt": 1794906000000, "needsRenewal": false }, "testId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "error": { "type": "string" }, "outcome": { "type": "string" }, "status": { "type": "number" }, "subscription": { "properties": { "createdAt": { "type": "number" }, "deviceId": { "type": "string" }, "failures": { "type": "number" }, "id": { "type": "string" }, "includeContent": { "type": "boolean" }, "lastError": { "type": "string" }, "lastOkAt": { "type": [ "number", "null" ] }, "needsRenewal": { "type": "boolean" } }, "type": "object" }, "testId": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Push test", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/push/vapid-key": { "get": { "description": "`{publicKey}`; with `?device={id}` also `subscription` (that device's status or `null`), see [Reminders and push](https://open-todo.app/docs/api/#reminders-and-push)", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getPushVapidKey", "responses": { "200": { "content": { "application/json": { "example": { "publicKey": "example", "subscription": { "createdAt": 1794906000000, "deviceId": "00000000-0000-4000-8000-000000000001", "failures": 1, "id": "00000000-0000-4000-8000-000000000001", "includeContent": false, "lastError": "example", "lastOkAt": 1794906000000, "needsRenewal": false } }, "schema": { "properties": { "publicKey": { "type": "string" }, "subscription": { "properties": { "createdAt": { "type": "number" }, "deviceId": { "type": "string" }, "failures": { "type": "number" }, "id": { "type": "string" }, "includeContent": { "type": "boolean" }, "lastError": { "type": "string" }, "lastOkAt": { "type": [ "number", "null" ] }, "needsRenewal": { "type": "boolean" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get push vapid key", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/quick-add/parse": { "post": { "description": "read a quick-add line with the account's languages, projects and labels; writes nothing, so a `read` token may call it; see [Quick-add parse](https://open-todo.app/docs/api/#quick-add-parse)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postQuickAddParse", "requestBody": { "content": { "application/json": { "example": { "day_parts": false, "line": "example", "now": "example", "today": "example", "url": "https://todo.example.com/" }, "schema": { "properties": { "day_parts": { "type": [ "boolean", "null" ] }, "line": { "type": [ "string", "null" ] }, "now": { "type": "string" }, "today": { "type": "string" }, "url": { "type": "string" } }, "required": [ "now", "today", "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "chips": [ { "end": 1, "kind": "example", "start": 1, "text": "example" } ], "fields": {}, "origin": { "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "provider": "example", "title": "Buy paint for the fence", "url": "https://todo.example.com/" }, "title": "Buy paint for the fence", "unmatched": [ "example" ] }, "schema": { "properties": { "chips": { "items": { "properties": { "end": { "type": "number" }, "kind": { "type": "string" }, "start": { "type": "number" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "fields": { "type": "object" }, "origin": { "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "provider": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } }, "type": [ "object", "null" ] }, "title": { "type": "string" }, "unmatched": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Quick add parse", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/relay/answers/{id}": { "post": { "description": "`{box}` sealed the same way, holding `{results: [{value} or {error}]}` or `{error: \"device_limit\"|\"declined_on_device\"|\"locked\"}` → 204; any other session, a second answer or a box that does not open → 404 `not_found`\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#device-relay" }, "operationId": "postRelayAnswersById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "box": "example" }, "schema": { "properties": { "box": { "type": "string" } }, "required": [ "box" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Relay answer", "tags": [ "Device relay" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/relay/devices": { "get": { "description": "`{devices: [{deviceId, label, enabledAt, online, thisSession, mcp, routines, connected, capabilities}]}`: `mcp` answers AI connectors, `routines` runs your routines ([below](https://open-todo.app/docs/api/#routines-on-your-devices)), `connected` its own stream is open, `capabilities` what it announced (`routines`, `ai`)\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#device-relay" }, "operationId": "getRelayDevices", "responses": { "200": { "content": { "application/json": { "example": { "devices": [ { "capabilities": [ "example" ], "connected": false, "deviceId": "00000000-0000-4000-8000-000000000001", "enabledAt": 1794906000000, "label": "example", "mcp": false, "online": false, "routines": false, "thisSession": false } ] }, "schema": { "properties": { "devices": { "items": { "properties": { "capabilities": { "items": { "type": "string" }, "type": "array" }, "connected": { "type": "boolean" }, "deviceId": { "type": "string" }, "enabledAt": { "type": "number" }, "label": { "type": "string" }, "mcp": { "type": "boolean" }, "online": { "type": "boolean" }, "routines": { "type": "boolean" }, "thisSession": { "type": "boolean" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "List relay devices", "tags": [ "Device relay" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/relay/devices/{device}": { "delete": { "description": "→ 204; ends the device's AI connector opt-in and its stream (a routines opt-in stays). Recorded as `relay.disabled`. Signing out the session that opted in and turning encryption off also end it\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#device-relay" }, "operationId": "deleteRelayDevicesByDevice", "parameters": [ { "in": "path", "name": "device", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Delete a relay device", "tags": [ "Device relay" ], "x-opentodo-policy": "signed-in.session-only" }, "put": { "description": "`{label}` → 204. Needs a recently confirmed session; binds the opt-in to this session. 409 `not_encrypted` without encryption, 409 `mcp_disabled` while the owner has MCP off. Recorded as `relay.enabled`\n\nNeeds a session; tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#device-relay" }, "operationId": "putRelayDevicesByDevice", "parameters": [ { "in": "path", "name": "device", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "label": "example" }, "schema": { "properties": { "label": { "type": "string" } }, "required": [ "label" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Replace a relay device", "tags": [ "Device relay" ], "x-opentodo-policy": "signed-in.session-only.recent" } }, "/api/v1/relay/devices/{device}/routines": { "delete": { "description": "→ 204 from any of your devices: ends the routines opt-in\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#device-relay" }, "operationId": "deleteRelayDevicesByDeviceRoutines", "parameters": [ { "in": "path", "name": "device", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Delete relay device routines", "tags": [ "Device relay" ], "x-opentodo-policy": "signed-in.session-only" }, "put": { "description": "`{label}` → 204: \"Run my routines on this device\". Needs a recently confirmed session; binds the opt-in to this session; does not need the owner's MCP switch. Survives locking (the device answers only while unlocked); ends at sign-out of that session or when encryption is turned off. 409 `not_encrypted` without encryption\n\nNeeds a session; tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#device-relay" }, "operationId": "putRelayDevicesByDeviceRoutines", "parameters": [ { "in": "path", "name": "device", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "label": "example" }, "schema": { "properties": { "label": { "type": "string" } }, "required": [ "label" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "Update relay device routines", "tags": [ "Device relay" ], "x-opentodo-policy": "signed-in.session-only.recent" } }, "/api/v1/relay/events": { "get": { "description": "Server-sent events for the opted-in device of this session only (403 `not_opted_in` otherwise). `caps` (comma-separated, for a routines opt-in): `routines`, and `ai` when the on-device assistant is set up and consented on it. `key` is the device's ephemeral ECDH P-256 public key (uncompressed, base64url). The first event, `hello`, carries `{stream, key}`: the stream id and the server's key. Both sides derive an AES-256-GCM key with HKDF-SHA-256 (salt = stream id, info `opentodo relay v1`). Each `request` event is `{id, box}`: `box` is base64url(nonce ‖ AES-GCM of `{op, items, call, deadline}`) with `id` as associated data. A `routine` event (routines opt-in) is `{id, box}` sealed the same way with the run id as `id`, holding `{op: \"routine.run\", rule, run, occurrence, at, task?, rev, auto, tokens, budget}`: ids and numbers only\n\nNeeds a session; tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#device-relay" }, "operationId": "getRelayEvents", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ], "summary": "List relay events", "tags": [ "Device relay" ], "x-opentodo-policy": "signed-in.session-only" } }, "/api/v1/reminders": { "get": { "description": "same shape for reminders, see [Reminders and push](https://open-todo.app/docs/api/#reminders-and-push)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getReminders", "responses": { "200": { "content": { "application/json": { "example": { "reminders": [ { "created_at": 1794906000043, "deleted_at": null, "delivered_at": null, "dismissed_at": null, "fire_at": 1795167000000, "id": "00000000-0000-4000-8000-000000000006", "kind": "relative", "offset_minutes": -30, "task_id": "00000000-0000-4000-8000-000000000005" } ] }, "schema": { "properties": { "reminders": { "items": { "$ref": "#/components/schemas/Reminder" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List reminders", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`task_id`, `kind` (`relative`, `deadline` or `absolute`, the default), `offset_minutes` (0 or less: minutes before the due time, or before 09:00 on the deadline day) or, for `absolute`, `fire_at` (Unix milliseconds on a whole minute); `fire_at` of the others is computed in your time zone. Your own reminders only, at most 10 on a task", "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "operationId": "postReminders", "requestBody": { "content": { "application/json": { "example": { "kind": "relative", "offset_minutes": -60, "task_id": "00000000-0000-4000-8000-000000000005" }, "schema": { "properties": { "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "delivered_at": { "type": [ "number", "null" ] }, "dismissed_at": { "type": [ "number", "null" ] }, "fire_at": { "description": "A point in time in Unix milliseconds.", "type": [ "integer", "null" ] }, "kind": { "enum": [ "relative", "absolute", "deadline", "arrive", "leave" ], "type": "string" }, "offset_minutes": { "description": "Minutes relative to the due time (negative: before).", "type": [ "integer", "null" ] }, "radius_m": { "description": "A radius in metres.", "type": [ "number", "null" ] }, "task_id": { "description": "An id: a UUID, or for some entities a name-based id.", "type": "string" } }, "required": [ "task_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "created_at": 1794906000043, "deleted_at": null, "delivered_at": null, "dismissed_at": null, "fire_at": 1795165200000, "id": "00000000-0000-4000-8000-000000000006", "kind": "relative", "offset_minutes": -60, "task_id": "00000000-0000-4000-8000-000000000005" }, "schema": { "$ref": "#/components/schemas/Reminder" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a reminder", "tags": [ "Agent tokens" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/reminders/{id}": { "delete": { "description": "any of your own reminders", "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "operationId": "deleteRemindersById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a reminder", "tags": [ "Agent tokens" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "same shape for reminders, see [Reminders and push](https://open-todo.app/docs/api/#reminders-and-push)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getRemindersById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "created_at": 1794906000043, "deleted_at": null, "delivered_at": null, "dismissed_at": null, "fire_at": 1795165200000, "id": "00000000-0000-4000-8000-000000000006", "kind": "relative", "offset_minutes": -60, "task_id": "00000000-0000-4000-8000-000000000005" }, "schema": { "$ref": "#/components/schemas/Reminder" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a reminder", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`offset_minutes`, or `fire_at` of an absolute reminder (the kind never changes)", "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "operationId": "patchRemindersById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "offset_minutes": -30 }, "schema": { "properties": { "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "delivered_at": { "type": [ "number", "null" ] }, "dismissed_at": { "type": [ "number", "null" ] }, "fire_at": { "description": "A point in time in Unix milliseconds.", "type": [ "integer", "null" ] }, "kind": { "enum": [ "relative", "absolute", "deadline", "arrive", "leave" ], "type": "string" }, "offset_minutes": { "description": "Minutes relative to the due time (negative: before).", "type": [ "integer", "null" ] }, "radius_m": { "description": "A radius in metres.", "type": [ "number", "null" ] }, "task_id": { "description": "An id: a UUID, or for some entities a name-based id.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "created_at": 1794906000043, "deleted_at": null, "delivered_at": null, "dismissed_at": null, "fire_at": 1795167000000, "id": "00000000-0000-4000-8000-000000000006", "kind": "relative", "offset_minutes": -30, "task_id": "00000000-0000-4000-8000-000000000005" }, "schema": { "$ref": "#/components/schemas/Reminder" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a reminder", "tags": [ "Agent tokens" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/routine-emails/{token}": { "get": { "description": "`{routine, stopped}`: the routine's name and whether the member already stopped its emails; nothing else about the routine\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines-of-a-shared-project" }, "operationId": "getRoutineEmailsByToken", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "routine": "example", "stopped": false }, "schema": { "properties": { "routine": { "type": "string" }, "stopped": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a routine email", "tags": [ "Routines of a shared project" ], "x-opentodo-policy": "public" } }, "/api/v1/routine-emails/{token}/stop": { "post": { "description": "→ `{routine, stopped: true}`: the member gets no more emails from the routine; repeating it changes nothing. Audited as `settings.changed` (`routine_email`, `on` → `off`) of the member\n\nNo authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines-of-a-shared-project" }, "operationId": "postRoutineEmailsByTokenStop", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "routine": "example", "stopped": false }, "schema": { "properties": { "routine": { "type": "string" }, "stopped": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Routine email stop", "tags": [ "Routines of a shared project" ], "x-opentodo-policy": "public" } }, "/api/v1/rules": { "get": { "description": "`{rules: [...]}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "getRules", "responses": { "200": { "content": { "application/json": { "example": { "rules": [] } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List rules", "tags": [ "Automation rules" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{name, trigger, condition?, actions?, steps?, enabled?, workspace_id?}` → `201` (a rule needs `actions` or `steps`); ids are resolved (live labels, projects, sections of that project, your webhooks), a project action into a shared project is refused (`400 invalid_input`), a `comment` action on an encrypted account answers `409 encryption_enabled`, a 51st rule `409 limit_reached`", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "postRules", "responses": { "200": { "content": { "application/json": { "example": { "reused": "example" }, "schema": { "properties": { "reused": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "201": { "content": { "application/json": { "example": { "reused": "example" }, "schema": { "properties": { "reused": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a rule", "tags": [ "Automation rules" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/rules/test": { "post": { "description": "an unsaved draft `{trigger, condition?, actions?, steps?, task_id?, call_ai?, workspace_id?}` → `{run, steps, writes, test}`; validated like a create; nothing is written or logged; each step carries `preview` (its output, titles included, never stored) and the last one the planned `changes`; an AI step carries `estimate` and calls the model only with `call_ai: true`", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "postRulesTest", "requestBody": { "content": { "application/json": { "example": { "actions": "example", "call_ai": false, "condition": "example", "note_id": "00000000-0000-4000-8000-000000000001", "project_id": "00000000-0000-4000-8000-000000000001", "steps": "example", "task_id": "00000000-0000-4000-8000-000000000001", "trigger": "example", "workspace_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "actions": { "type": "string" }, "call_ai": { "type": "boolean" }, "condition": { "type": "string" }, "note_id": { "type": "string" }, "project_id": { "type": "string" }, "steps": { "type": "string" }, "task_id": { "type": "string" }, "trigger": { "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "actions", "call_ai", "condition", "note_id", "project_id", "steps", "task_id", "trigger", "workspace_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "device_run": { "at": 1, "auto": false, "budget": 1, "note": "example", "occurrence": "example", "op": "example", "rev": "example", "rule": "example", "run": "example", "task": "example", "tokens": 1 }, "run": { "ai_auto": false, "at": 1, "blocks": [ { "date": "2026-11-20", "from": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "kind": "example", "span": "example", "to": "example" } ], "changes": "example", "depth": 1, "device_id": "00000000-0000-4000-8000-000000000001", "duration_ms": 1, "failed_step": 1, "id": 1, "note_id": "00000000-0000-4000-8000-000000000001", "occurrence": "example", "outcome": "example", "project_id": "00000000-0000-4000-8000-000000000001", "proposal": { "applied": 1, "created_at": 1794906000000, "encrypted": false, "envelope": "example", "expires_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "items": 1, "list": [ { "ai": false, "before": {}, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001", "key": "example", "kind": "example", "side": { "day": "example", "delivery": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "StepID": "example", "TaskIDs": [ "example" ], "Text": "example" }, "fired": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence" }, "hook": "example", "kind": "example", "mail": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "Subject": "example", "Text": "example" }, "members": [ "example" ], "notice": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "runId": "00000000-0000-4000-8000-000000000001", "stepId": "00000000-0000-4000-8000-000000000001", "taskId": "00000000-0000-4000-8000-000000000001", "text": "example" }, "project": "example" } } ], "rule_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "skipped": 1, "state": "example" }, "reason": "example", "rule_id": "00000000-0000-4000-8000-000000000001", "run_as": "example", "run_id": "00000000-0000-4000-8000-000000000001", "source": "example", "steps": [ { "duration_ms": 1, "error": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1 } ], "steps_count": 1, "task_id": "00000000-0000-4000-8000-000000000001", "test": false, "tokens": 1, "undone_at": 1794906000000, "writes": 1 }, "steps": [ { "changes": [ { "base": {}, "create": false, "entity": "example", "entityId": "00000000-0000-4000-8000-000000000001", "patch": {} } ], "duration_ms": 1, "error": "example", "estimate": 1, "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "preview": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1, "warning": { "kind": "example", "message": "example", "reason": "example", "setting": "example", "step": "example" } } ], "test": false, "writes": 1 }, "schema": { "properties": { "device_run": { "properties": { "at": { "type": "number" }, "auto": { "type": "boolean" }, "budget": { "type": "number" }, "note": { "type": "string" }, "occurrence": { "type": "string" }, "op": { "type": "string" }, "rev": { "type": "string" }, "rule": { "type": "string" }, "run": { "type": "string" }, "task": { "type": "string" }, "tokens": { "type": "number" } }, "type": [ "object", "null" ] }, "run": { "properties": { "ai_auto": { "type": "boolean" }, "at": { "type": "number" }, "blocks": { "items": { "properties": { "date": { "type": "string" }, "from": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "span": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "changes": { "type": "string" }, "depth": { "type": "number" }, "device_id": { "type": "string" }, "duration_ms": { "type": "number" }, "failed_step": { "type": "number" }, "id": { "type": "number" }, "note_id": { "type": "string" }, "occurrence": { "type": "string" }, "outcome": { "type": "string" }, "project_id": { "type": "string" }, "proposal": { "properties": { "applied": { "type": "number" }, "created_at": { "type": "number" }, "encrypted": { "type": "boolean" }, "envelope": { "type": "string" }, "expires_at": { "type": "number" }, "id": { "type": "string" }, "items": { "type": "number" }, "list": { "items": { "properties": { "ai": { "type": "boolean" }, "before": { "type": "object" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "side": { "properties": { "day": { "type": "string" }, "delivery": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "StepID": { "type": "string" }, "TaskIDs": { "items": { "type": "string" }, "type": "array" }, "Text": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "fired": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" } }, "type": [ "object", "null" ] }, "hook": { "type": "string" }, "kind": { "type": "string" }, "mail": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "Subject": { "type": "string" }, "Text": { "type": "string" } }, "type": [ "object", "null" ] }, "members": { "items": { "type": "string" }, "type": "array" }, "notice": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "runId": { "type": "string" }, "stepId": { "type": "string" }, "taskId": { "type": "string" }, "text": { "type": "string" } }, "type": [ "object", "null" ] }, "project": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "rule_id": { "type": "string" }, "run_id": { "type": "string" }, "skipped": { "type": "number" }, "state": { "type": "string" } }, "type": [ "object", "null" ] }, "reason": { "type": "string" }, "rule_id": { "type": "string" }, "run_as": { "type": "string" }, "run_id": { "type": "string" }, "source": { "type": "string" }, "steps": { "items": { "properties": { "duration_ms": { "type": "number" }, "error": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" } }, "type": "object" }, "type": "array" }, "steps_count": { "type": "number" }, "task_id": { "type": "string" }, "test": { "type": "boolean" }, "tokens": { "type": "number" }, "undone_at": { "type": [ "number", "null" ] }, "writes": { "type": "number" } }, "type": "object" }, "steps": { "items": { "properties": { "changes": { "items": { "properties": { "base": { "type": "object" }, "create": { "type": "boolean" }, "entity": { "type": "string" }, "entityId": { "type": "string" }, "patch": { "type": "object" } }, "type": "object" }, "type": "array" }, "duration_ms": { "type": "number" }, "error": { "type": "string" }, "estimate": { "type": "number" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "preview": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": { "type": "string" }, "type": "object" }, { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array" } ], "description": "A preview of the step's output, by its type: text and a date are a string, lines a list of strings, a number a number, a task or a note {id, title}, a project {id, name}, tasks or notes a list of {id, title}." }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" }, "warning": { "properties": { "kind": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string" }, "setting": { "type": "string" }, "step": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "test": { "type": "boolean" }, "writes": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Rules test", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/rules/{id}": { "delete": { "description": "like every collection", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "deleteRulesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a rule", "tags": [ "Automation rules" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "like every collection", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "getRulesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a rule", "tags": [ "Automation rules" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "like every collection", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "patchRulesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a rule", "tags": [ "Automation rules" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/rules/{id}/ai-usage": { "get": { "description": "`{days: [{day, tokens}], budget, mode}`: the routine's AI tokens of the last 7 UTC days, its daily budget and its `ai_mode` (null without AI steps)", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "getRulesByIdAiUsage", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "budget": 1, "days": [ { "day": "example", "tokens": 1 } ], "mode": { "asked": false, "at": 1, "auto": false, "blocked": { "step": "example", "what": "example" }, "reason": "example" } }, "schema": { "properties": { "budget": { "type": "number" }, "days": { "items": { "properties": { "day": { "type": "string" }, "tokens": { "type": "number" } }, "type": "object" }, "type": "array" }, "mode": { "properties": { "asked": { "type": "boolean" }, "at": { "type": "number" }, "auto": { "type": "boolean" }, "blocked": { "properties": { "step": { "type": "string" }, "what": { "type": "string" } }, "type": "object" }, "reason": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get rule ai usage", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/rules/{id}/run": { "post": { "description": "`{run_id, task_id?, note_id?, test?, call_ai?, device?}` → `{run, steps, writes, test, device_run?}`. `note_id` is the standalone note a routine triggered by a note, or run on a note (`trigger: {kind: \"manual\", on: \"note\"}`), runs on: `400 note_required` without it or with a `task_id` instead, `400 invalid_input` with both; the run then carries `note_id` instead of `task_id`. `run_id` is your UUID: the same value answers the first run again. `test: true` plans, logs a test run and writes nothing; its AI steps call the model only with `call_ai: true` (otherwise they answer nothing and carry their `estimate` of tokens). A disabled routine can be run; `409 paused` while the server paused it, `409 automations_off` when the owner turned automations off, `400 task_required` when its steps read the trigger's task and `task_id` is missing, `429 rate_limited` past 60 runs a minute (nothing is queued). On an encrypted account a routine with text or AI steps runs on a device ([below](https://open-todo.app/docs/api/#routines-on-your-devices)): `device` (session cookies only) runs it on the calling device, which gets `device_run` (the `routine.run` request) and commits it; without `device` it is sent to an opted-in device", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "postRulesByIdRun", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "call_ai": false, "device": "example", "note_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "task_id": "00000000-0000-4000-8000-000000000001", "test": false }, "schema": { "properties": { "call_ai": { "type": "boolean" }, "device": { "type": "string" }, "note_id": { "type": "string" }, "run_id": { "type": "string" }, "task_id": { "type": "string" }, "test": { "type": "boolean" } }, "required": [ "call_ai", "device", "note_id", "run_id", "task_id", "test" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "device_run": { "at": 1, "auto": false, "budget": 1, "note": "example", "occurrence": "example", "op": "example", "rev": "example", "rule": "example", "run": "example", "task": "example", "tokens": 1 }, "run": { "ai_auto": false, "at": 1, "blocks": [ { "date": "2026-11-20", "from": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "kind": "example", "span": "example", "to": "example" } ], "changes": "example", "depth": 1, "device_id": "00000000-0000-4000-8000-000000000001", "duration_ms": 1, "failed_step": 1, "id": 1, "note_id": "00000000-0000-4000-8000-000000000001", "occurrence": "example", "outcome": "example", "project_id": "00000000-0000-4000-8000-000000000001", "proposal": { "applied": 1, "created_at": 1794906000000, "encrypted": false, "envelope": "example", "expires_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "items": 1, "list": [ { "ai": false, "before": {}, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001", "key": "example", "kind": "example", "side": { "day": "example", "delivery": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "StepID": "example", "TaskIDs": [ "example" ], "Text": "example" }, "fired": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence" }, "hook": "example", "kind": "example", "mail": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "Subject": "example", "Text": "example" }, "members": [ "example" ], "notice": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "runId": "00000000-0000-4000-8000-000000000001", "stepId": "00000000-0000-4000-8000-000000000001", "taskId": "00000000-0000-4000-8000-000000000001", "text": "example" }, "project": "example" } } ], "rule_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "skipped": 1, "state": "example" }, "reason": "example", "rule_id": "00000000-0000-4000-8000-000000000001", "run_as": "example", "run_id": "00000000-0000-4000-8000-000000000001", "source": "example", "steps": [ { "duration_ms": 1, "error": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1 } ], "steps_count": 1, "task_id": "00000000-0000-4000-8000-000000000001", "test": false, "tokens": 1, "undone_at": 1794906000000, "writes": 1 }, "steps": [ { "changes": [ { "base": {}, "create": false, "entity": "example", "entityId": "00000000-0000-4000-8000-000000000001", "patch": {} } ], "duration_ms": 1, "error": "example", "estimate": 1, "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "preview": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1, "warning": { "kind": "example", "message": "example", "reason": "example", "setting": "example", "step": "example" } } ], "test": false, "writes": 1 }, "schema": { "properties": { "device_run": { "properties": { "at": { "type": "number" }, "auto": { "type": "boolean" }, "budget": { "type": "number" }, "note": { "type": "string" }, "occurrence": { "type": "string" }, "op": { "type": "string" }, "rev": { "type": "string" }, "rule": { "type": "string" }, "run": { "type": "string" }, "task": { "type": "string" }, "tokens": { "type": "number" } }, "type": [ "object", "null" ] }, "run": { "properties": { "ai_auto": { "type": "boolean" }, "at": { "type": "number" }, "blocks": { "items": { "properties": { "date": { "type": "string" }, "from": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "span": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "changes": { "type": "string" }, "depth": { "type": "number" }, "device_id": { "type": "string" }, "duration_ms": { "type": "number" }, "failed_step": { "type": "number" }, "id": { "type": "number" }, "note_id": { "type": "string" }, "occurrence": { "type": "string" }, "outcome": { "type": "string" }, "project_id": { "type": "string" }, "proposal": { "properties": { "applied": { "type": "number" }, "created_at": { "type": "number" }, "encrypted": { "type": "boolean" }, "envelope": { "type": "string" }, "expires_at": { "type": "number" }, "id": { "type": "string" }, "items": { "type": "number" }, "list": { "items": { "properties": { "ai": { "type": "boolean" }, "before": { "type": "object" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "side": { "properties": { "day": { "type": "string" }, "delivery": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "StepID": { "type": "string" }, "TaskIDs": { "items": { "type": "string" }, "type": "array" }, "Text": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "fired": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" } }, "type": [ "object", "null" ] }, "hook": { "type": "string" }, "kind": { "type": "string" }, "mail": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "Subject": { "type": "string" }, "Text": { "type": "string" } }, "type": [ "object", "null" ] }, "members": { "items": { "type": "string" }, "type": "array" }, "notice": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "runId": { "type": "string" }, "stepId": { "type": "string" }, "taskId": { "type": "string" }, "text": { "type": "string" } }, "type": [ "object", "null" ] }, "project": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "rule_id": { "type": "string" }, "run_id": { "type": "string" }, "skipped": { "type": "number" }, "state": { "type": "string" } }, "type": [ "object", "null" ] }, "reason": { "type": "string" }, "rule_id": { "type": "string" }, "run_as": { "type": "string" }, "run_id": { "type": "string" }, "source": { "type": "string" }, "steps": { "items": { "properties": { "duration_ms": { "type": "number" }, "error": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" } }, "type": "object" }, "type": "array" }, "steps_count": { "type": "number" }, "task_id": { "type": "string" }, "test": { "type": "boolean" }, "tokens": { "type": "number" }, "undone_at": { "type": [ "number", "null" ] }, "writes": { "type": "number" } }, "type": "object" }, "steps": { "items": { "properties": { "changes": { "items": { "properties": { "base": { "type": "object" }, "create": { "type": "boolean" }, "entity": { "type": "string" }, "entityId": { "type": "string" }, "patch": { "type": "object" } }, "type": "object" }, "type": "array" }, "duration_ms": { "type": "number" }, "error": { "type": "string" }, "estimate": { "type": "number" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "preview": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": { "type": "string" }, "type": "object" }, { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array" } ], "description": "A preview of the step's output, by its type: text and a date are a string, lines a list of strings, a number a number, a task or a note {id, title}, a project {id, name}, tasks or notes a list of {id, title}." }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" }, "warning": { "properties": { "kind": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string" }, "setting": { "type": "string" }, "step": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "test": { "type": "boolean" }, "writes": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Rule run", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/rules/{id}/runs": { "get": { "description": "`{runs: [...]}`, newest first, at most 100: `id`, `rule_id`, `occurrence` (the run key), `task_id`, `at`, `outcome` (`pending`, `applied`, `already_matched`, `skipped`, `stopped`, `failed`, `partial`), `reason`, `changes` (`[{task_id, fields}]`), `depth`; another account's rule answers `404 not_found`", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "getRulesByIdRuns", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "runs": [ { "ai_auto": false, "at": 1, "blocks": [ { "date": "2026-11-20", "from": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "kind": "example", "span": "example", "to": "example" } ], "changes": "example", "depth": 1, "device_id": "00000000-0000-4000-8000-000000000001", "duration_ms": 1, "failed_step": 1, "id": 1, "note_id": "00000000-0000-4000-8000-000000000001", "occurrence": "example", "outcome": "example", "project_id": "00000000-0000-4000-8000-000000000001", "proposal": { "applied": 1, "created_at": 1794906000000, "encrypted": false, "envelope": "example", "expires_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "items": 1, "list": [ { "ai": false, "before": {}, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001", "key": "example", "kind": "example", "side": { "day": "example", "delivery": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "StepID": "example", "TaskIDs": [ "example" ], "Text": "example" }, "fired": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence" }, "hook": "example", "kind": "example", "mail": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "Subject": "example", "Text": "example" }, "members": [ "example" ], "notice": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "runId": "00000000-0000-4000-8000-000000000001", "stepId": "00000000-0000-4000-8000-000000000001", "taskId": "00000000-0000-4000-8000-000000000001", "text": "example" }, "project": "example" } } ], "rule_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "skipped": 1, "state": "example" }, "reason": "example", "rule_id": "00000000-0000-4000-8000-000000000001", "run_as": "example", "run_id": "00000000-0000-4000-8000-000000000001", "source": "example", "steps": [ { "duration_ms": 1, "error": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1 } ], "steps_count": 1, "task_id": "00000000-0000-4000-8000-000000000001", "test": false, "tokens": 1, "undone_at": 1794906000000, "writes": 1 } ] }, "schema": { "properties": { "runs": { "items": { "properties": { "ai_auto": { "type": "boolean" }, "at": { "type": "number" }, "blocks": { "items": { "properties": { "date": { "type": "string" }, "from": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "span": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "changes": { "type": "string" }, "depth": { "type": "number" }, "device_id": { "type": "string" }, "duration_ms": { "type": "number" }, "failed_step": { "type": "number" }, "id": { "type": "number" }, "note_id": { "type": "string" }, "occurrence": { "type": "string" }, "outcome": { "type": "string" }, "project_id": { "type": "string" }, "proposal": { "properties": { "applied": { "type": "number" }, "created_at": { "type": "number" }, "encrypted": { "type": "boolean" }, "envelope": { "type": "string" }, "expires_at": { "type": "number" }, "id": { "type": "string" }, "items": { "type": "number" }, "list": { "items": { "properties": { "ai": { "type": "boolean" }, "before": { "type": "object" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "side": { "properties": { "day": { "type": "string" }, "delivery": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "StepID": { "type": "string" }, "TaskIDs": { "items": { "type": "string" }, "type": "array" }, "Text": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "fired": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" } }, "type": [ "object", "null" ] }, "hook": { "type": "string" }, "kind": { "type": "string" }, "mail": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "Subject": { "type": "string" }, "Text": { "type": "string" } }, "type": [ "object", "null" ] }, "members": { "items": { "type": "string" }, "type": "array" }, "notice": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "runId": { "type": "string" }, "stepId": { "type": "string" }, "taskId": { "type": "string" }, "text": { "type": "string" } }, "type": [ "object", "null" ] }, "project": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "rule_id": { "type": "string" }, "run_id": { "type": "string" }, "skipped": { "type": "number" }, "state": { "type": "string" } }, "type": [ "object", "null" ] }, "reason": { "type": "string" }, "rule_id": { "type": "string" }, "run_as": { "type": "string" }, "run_id": { "type": "string" }, "source": { "type": "string" }, "steps": { "items": { "properties": { "duration_ms": { "type": "number" }, "error": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" } }, "type": "object" }, "type": "array" }, "steps_count": { "type": "number" }, "task_id": { "type": "string" }, "test": { "type": "boolean" }, "tokens": { "type": "number" }, "undone_at": { "type": [ "number", "null" ] }, "writes": { "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List rule runs", "tags": [ "Automation rules" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/rules/{id}/runs/{run}": { "get": { "description": "one run with `steps` (`index`, `step_id`, `kind`, `status`: `ok`, `skipped`, `ended`, `failed`, `unavailable` or `truncated`, `duration_ms`, `items`, `output`, `ids` (at most 50), `error`)", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "getRulesByIdRunsByRun", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "ai_auto": false, "at": 1, "blocks": [ { "date": "2026-11-20", "from": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "kind": "example", "span": "example", "to": "example" } ], "changes": "example", "depth": 1, "device_id": "00000000-0000-4000-8000-000000000001", "duration_ms": 1, "failed_step": 1, "id": 1, "note_id": "00000000-0000-4000-8000-000000000001", "occurrence": "example", "outcome": "example", "project_id": "00000000-0000-4000-8000-000000000001", "proposal": { "applied": 1, "created_at": 1794906000000, "encrypted": false, "envelope": "example", "expires_at": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "items": 1, "list": [ { "ai": false, "before": {}, "entity": "example", "fields": {}, "id": "00000000-0000-4000-8000-000000000001", "key": "example", "kind": "example", "side": { "day": "example", "delivery": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "StepID": "example", "TaskIDs": [ "example" ], "Text": "example" }, "fired": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence" }, "hook": "example", "kind": "example", "mail": { "RuleID": "example", "RuleName": "Ada", "RunID": "example", "Subject": "example", "Text": "example" }, "members": [ "example" ], "notice": { "at": 1, "ruleId": "00000000-0000-4000-8000-000000000001", "ruleName": "Ada", "runId": "00000000-0000-4000-8000-000000000001", "stepId": "00000000-0000-4000-8000-000000000001", "taskId": "00000000-0000-4000-8000-000000000001", "text": "example" }, "project": "example" } } ], "rule_id": "00000000-0000-4000-8000-000000000001", "run_id": "00000000-0000-4000-8000-000000000001", "skipped": 1, "state": "example" }, "reason": "example", "rule_id": "00000000-0000-4000-8000-000000000001", "run_as": "example", "run_id": "00000000-0000-4000-8000-000000000001", "source": "example", "steps": [ { "duration_ms": 1, "error": "example", "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1 } ], "steps_count": 1, "task_id": "00000000-0000-4000-8000-000000000001", "test": false, "tokens": 1, "undone_at": 1794906000000, "writes": 1 }, "schema": { "properties": { "ai_auto": { "type": "boolean" }, "at": { "type": "number" }, "blocks": { "items": { "properties": { "date": { "type": "string" }, "from": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "kind": { "type": "string" }, "span": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "changes": { "type": "string" }, "depth": { "type": "number" }, "device_id": { "type": "string" }, "duration_ms": { "type": "number" }, "failed_step": { "type": "number" }, "id": { "type": "number" }, "note_id": { "type": "string" }, "occurrence": { "type": "string" }, "outcome": { "type": "string" }, "project_id": { "type": "string" }, "proposal": { "properties": { "applied": { "type": "number" }, "created_at": { "type": "number" }, "encrypted": { "type": "boolean" }, "envelope": { "type": "string" }, "expires_at": { "type": "number" }, "id": { "type": "string" }, "items": { "type": "number" }, "list": { "items": { "properties": { "ai": { "type": "boolean" }, "before": { "type": "object" }, "entity": { "type": "string" }, "fields": { "type": "object" }, "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" }, "side": { "properties": { "day": { "type": "string" }, "delivery": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "StepID": { "type": "string" }, "TaskIDs": { "items": { "type": "string" }, "type": "array" }, "Text": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "fired": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" } }, "type": [ "object", "null" ] }, "hook": { "type": "string" }, "kind": { "type": "string" }, "mail": { "properties": { "RuleID": { "type": "string" }, "RuleName": { "type": "string" }, "RunID": { "type": "string" }, "Subject": { "type": "string" }, "Text": { "type": "string" } }, "type": [ "object", "null" ] }, "members": { "items": { "type": "string" }, "type": "array" }, "notice": { "properties": { "at": { "type": "number" }, "ruleId": { "type": "string" }, "ruleName": { "type": "string" }, "runId": { "type": "string" }, "stepId": { "type": "string" }, "taskId": { "type": "string" }, "text": { "type": "string" } }, "type": [ "object", "null" ] }, "project": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "rule_id": { "type": "string" }, "run_id": { "type": "string" }, "skipped": { "type": "number" }, "state": { "type": "string" } }, "type": [ "object", "null" ] }, "reason": { "type": "string" }, "rule_id": { "type": "string" }, "run_as": { "type": "string" }, "run_id": { "type": "string" }, "source": { "type": "string" }, "steps": { "items": { "properties": { "duration_ms": { "type": "number" }, "error": { "type": "string" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" } }, "type": "object" }, "type": "array" }, "steps_count": { "type": "number" }, "task_id": { "type": "string" }, "test": { "type": "boolean" }, "tokens": { "type": "number" }, "undone_at": { "type": [ "number", "null" ] }, "writes": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a rule run", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/rules/{id}/runs/{run}/dismiss": { "post": { "description": "→ `204`: hides the run from the Inbox card on every device; another account's run answers `404 not_found`", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "postRulesByIdRunsByRunDismiss", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Rule run dismiss", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/rules/{id}/runs/{run}/undo": { "post": { "description": "→ `{restored, kept, not_undoable}`: puts back what the run wrote that has not changed since, moves what it created to the Trash, stops a timer it started; notifications, deliveries and emails are listed in `not_undoable`; `409 already_undone` the second time", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "operationId": "postRulesByIdRunsByRunUndo", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "run", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "kept": 1, "not_undoable": [ "example" ], "restored": 1 }, "schema": { "properties": { "kept": { "type": "number" }, "not_undoable": { "items": { "type": "string" }, "type": "array" }, "restored": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Rule run undo", "tags": [ "Routines" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/rules/{id}/test": { "post": { "description": "`{task_id}` → `{matches, changes, skipped, steps, writes}`: the condition and the planned changes on one task now, and each step's plan; nothing is written. `task_id` may be left out for a routine that does not read the trigger's task", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "postRulesByIdTest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "task_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "task_id": { "type": "string" } }, "required": [ "task_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "changes": {}, "matches": false, "skipped": [ "example" ], "steps": [ { "changes": [ { "base": {}, "create": false, "entity": "example", "entityId": "00000000-0000-4000-8000-000000000001", "patch": {} } ], "duration_ms": 1, "error": "example", "estimate": 1, "ids": [ "00000000-0000-4000-8000-000000000001" ], "index": 1, "items": 1, "kind": "example", "output": "example", "preview": "example", "status": "example", "step_id": "00000000-0000-4000-8000-000000000001", "tokens": 1, "warning": { "kind": "example", "message": "example", "reason": "example", "setting": "example", "step": "example" } } ], "writes": 1 }, "schema": { "properties": { "changes": { "type": "object" }, "matches": { "type": "boolean" }, "skipped": { "items": { "type": "string" }, "type": "array" }, "steps": { "items": { "properties": { "changes": { "items": { "properties": { "base": { "type": "object" }, "create": { "type": "boolean" }, "entity": { "type": "string" }, "entityId": { "type": "string" }, "patch": { "type": "object" } }, "type": "object" }, "type": "array" }, "duration_ms": { "type": "number" }, "error": { "type": "string" }, "estimate": { "type": "number" }, "ids": { "items": { "type": "string" }, "type": "array" }, "index": { "type": "number" }, "items": { "type": "number" }, "kind": { "type": "string" }, "output": { "type": "string" }, "preview": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "items": { "type": "string" }, "type": "array" }, { "additionalProperties": { "type": "string" }, "type": "object" }, { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array" } ], "description": "A preview of the step's output, by its type: text and a date are a string, lines a list of strings, a number a number, a task or a note {id, title}, a project {id, name}, tasks or notes a list of {id, title}." }, "status": { "type": "string" }, "step_id": { "type": "string" }, "tokens": { "type": "number" }, "warning": { "properties": { "kind": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string" }, "setting": { "type": "string" }, "step": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" }, "type": "array" }, "writes": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Rule test", "tags": [ "Automation rules" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/sections": { "get": { "description": "same shape for sections, see [Sections](https://open-todo.app/docs/api/#sections)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getSections", "responses": { "200": { "content": { "application/json": { "example": { "sections": [ { "aisle": null, "color": null, "created_at": 1794906000015, "flow_mode": "", "icon": null, "id": "00000000-0000-4000-8000-000000000003", "name": "Next week", "position": 1794906000015, "project_id": "00000000-0000-4000-8000-000000000002" } ] }, "schema": { "properties": { "sections": { "items": { "$ref": "#/components/schemas/Section" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List sections", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`name`, `project_id`, `color`, `icon`, `position`", "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "operationId": "postSections", "requestBody": { "content": { "application/json": { "example": { "name": "This week", "project_id": "00000000-0000-4000-8000-000000000002" }, "schema": { "properties": { "aisle": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "flow_mode": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "position": { "type": "number" }, "project_id": { "description": "An id: a UUID, or for some entities a name-based id.", "type": "string" } }, "required": [ "project_id" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "aisle": null, "color": null, "created_at": 1794906000015, "flow_mode": "", "icon": null, "id": "00000000-0000-4000-8000-000000000003", "name": "This week", "position": 1794906000015, "project_id": "00000000-0000-4000-8000-000000000002" }, "schema": { "$ref": "#/components/schemas/Section" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a section", "tags": [ "Agent tokens" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/sections/{id}": { "delete": { "externalDocs": { "url": "https://open-todo.app/docs/api/#sections" }, "operationId": "deleteSectionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a section", "tags": [ "Sections" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "same shape for sections, see [Sections](https://open-todo.app/docs/api/#sections)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getSectionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "aisle": null, "color": null, "created_at": 1794906000015, "flow_mode": "", "icon": null, "id": "00000000-0000-4000-8000-000000000003", "name": "This week", "position": 1794906000015, "project_id": "00000000-0000-4000-8000-000000000002" }, "schema": { "$ref": "#/components/schemas/Section" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a section", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`name`, `color`, `icon`, `position`", "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "operationId": "patchSectionsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Next week" }, "schema": { "properties": { "aisle": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "flow_mode": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "position": { "type": "number" }, "project_id": { "description": "An id: a UUID, or for some entities a name-based id.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "aisle": null, "color": null, "created_at": 1794906000015, "flow_mode": "", "icon": null, "id": "00000000-0000-4000-8000-000000000003", "name": "Next week", "position": 1794906000015, "project_id": "00000000-0000-4000-8000-000000000002" }, "schema": { "$ref": "#/components/schemas/Section" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a section", "tags": [ "Agent tokens" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/settings/assistant": { "get": { "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "operationId": "getSettingsAssistant", "responses": { "200": { "content": { "application/json": { "example": { "allow_member_keys": false, "cap_member_keys": false, "enabled": false, "model": "example", "monthly_token_cap_per_user": 1, "provider": "example", "provider_label": "example" }, "schema": { "properties": { "allow_member_keys": { "type": "boolean" }, "cap_member_keys": { "type": "boolean" }, "enabled": { "type": "boolean" }, "model": { "type": "string" }, "monthly_token_cap_per_user": { "type": "number" }, "provider": { "type": "string" }, "provider_label": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings assistant", "tags": [ "In-app assistant" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "Only the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "operationId": "putSettingsAssistant", "requestBody": { "content": { "application/json": { "example": { "allow_member_keys": false, "allow_private_endpoint": false, "cap_member_keys": false, "default_provider": "example", "device": { "enabled": false, "origins": [ "example" ], "providers": [ "example" ] }, "enabled": false, "keys": {}, "monthly_token_cap_per_user": 1, "providers": {} }, "schema": { "properties": { "allow_member_keys": { "type": "boolean" }, "allow_private_endpoint": { "type": "boolean" }, "cap_member_keys": { "type": "boolean" }, "default_provider": { "type": "string" }, "device": { "properties": { "enabled": { "type": "boolean" }, "origins": { "items": { "type": "string" }, "type": "array" }, "providers": { "items": { "type": "string" }, "type": "array" } }, "required": [ "enabled", "origins", "providers" ], "type": "object" }, "enabled": { "type": "boolean" }, "keys": { "type": "object" }, "monthly_token_cap_per_user": { "type": "number" }, "providers": { "type": "object" } }, "required": [ "allow_member_keys", "allow_private_endpoint", "cap_member_keys", "default_provider", "device", "enabled", "keys", "monthly_token_cap_per_user", "providers" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings assistant", "tags": [ "In-app assistant" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/settings/assistant/test": { "post": { "description": "Only the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "operationId": "postSettingsAssistantTest", "requestBody": { "content": { "application/json": { "example": { "allow_private_endpoint": false, "base_url": "https://todo.example.com/", "images": false, "key": "example", "model": "example", "provider": "example" }, "schema": { "properties": { "allow_private_endpoint": { "type": [ "boolean", "null" ] }, "base_url": { "type": [ "string", "null" ] }, "images": { "type": [ "boolean", "null" ] }, "key": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "provider": { "type": "string" } }, "required": [ "provider" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "code": "example", "message": "example", "ok": true, "status": 1 }, "schema": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "ok": { "type": "boolean" }, "status": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Settings assistant test", "tags": [ "In-app assistant" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/attachments": { "get": { "description": "`{enabled, max_file_mb, quota_mb}`; changing them is for the owner (`max_file_mb` 1–2048, `quota_mb` 0 = unlimited). Changes are audited as `settings.changed`", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "operationId": "getSettingsAttachments", "responses": { "200": { "content": { "application/json": { "example": { "enabled": false, "max_file_mb": 1, "quota_mb": 1 }, "schema": { "properties": { "enabled": { "type": "boolean" }, "max_file_mb": { "type": "number" }, "quota_mb": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List settings attachments", "tags": [ "Attachments" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "`{enabled, max_file_mb, quota_mb}`; changing them is for the owner (`max_file_mb` 1–2048, `quota_mb` 0 = unlimited). Changes are audited as `settings.changed`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "operationId": "putSettingsAttachments", "requestBody": { "content": { "application/json": { "example": { "enabled": false, "max_file_mb": 1, "quota_mb": 1 }, "schema": { "properties": { "enabled": { "type": "boolean" }, "max_file_mb": { "type": "number" }, "quota_mb": { "type": "number" } }, "required": [ "enabled", "max_file_mb", "quota_mb" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "enabled": false, "max_file_mb": 1, "quota_mb": 1 }, "schema": { "properties": { "enabled": { "type": "boolean" }, "max_file_mb": { "type": "number" }, "quota_mb": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings attachments", "tags": [ "Attachments" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/audit": { "get": { "description": "`{retentionDays, logIp}`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getSettingsAudit", "responses": { "200": { "content": { "application/json": { "example": { "logIp": false, "retentionDays": 1 }, "schema": { "properties": { "logIp": { "type": "boolean" }, "retentionDays": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings audit", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "`{retentionDays?: 7–3650, logIp?}` → settings; disabling `logIp` erases stored addresses\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "putSettingsAudit", "requestBody": { "content": { "application/json": { "example": { "logIp": false, "retentionDays": 1 }, "schema": { "properties": { "logIp": { "type": [ "boolean", "null" ] }, "retentionDays": { "type": [ "number", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "logIp": false, "retentionDays": 1 }, "schema": { "properties": { "logIp": { "type": "boolean" }, "retentionDays": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings audit", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/settings/automations": { "get": { "description": "`{enabled}` → `{enabled, locked, locked_by}`; `409 set_by_environment` while `OPENTODO_AUTOMATIONS` is set; a change is recorded as `settings.changed` (`automations.enabled`)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "getSettingsAutomations", "responses": { "200": { "content": { "application/json": { "example": { "enabled": true, "locked": false, "locked_by": "" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List settings automations", "tags": [ "Automation rules" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "`{enabled}` → `{enabled, locked, locked_by}`; `409 set_by_environment` while `OPENTODO_AUTOMATIONS` is set; a change is recorded as `settings.changed` (`automations.enabled`)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "operationId": "putSettingsAutomations", "requestBody": { "content": { "application/json": { "example": { "enabled": true } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "200": { "content": { "application/json": { "example": { "enabled": true, "locked": false, "locked_by": "" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings automations", "tags": [ "Automation rules" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/branding": { "get": { "description": "Owner. `PUT {\"name\": \"…\"}`: up to 40 characters after trimming, no control characters, empty for OpenTodo's own name (400 `invalid_input` otherwise). Answers `{name, logoVersion}`; recorded as `settings.changed` (`branding.name`)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#instance-branding" }, "operationId": "getSettingsBranding", "responses": { "200": { "content": { "application/json": { "example": { "logoVersion": 1, "name": "Ada" }, "schema": { "properties": { "logoVersion": { "type": "number" }, "name": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings branding", "tags": [ "Instance branding" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "Owner. `PUT {\"name\": \"…\"}`: up to 40 characters after trimming, no control characters, empty for OpenTodo's own name (400 `invalid_input` otherwise). Answers `{name, logoVersion}`; recorded as `settings.changed` (`branding.name`)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#instance-branding" }, "operationId": "putSettingsBranding", "requestBody": { "content": { "application/json": { "example": { "name": "Ada" }, "schema": { "properties": { "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "logoVersion": 1, "name": "Ada" }, "schema": { "properties": { "logoVersion": { "type": "number" }, "name": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings branding", "tags": [ "Instance branding" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/branding/logo": { "delete": { "description": "Owner. Removes the rendered files; `logoVersion` becomes 0 and the app's own icons return\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#instance-branding" }, "operationId": "deleteSettingsBrandingLogo", "responses": { "200": { "content": { "application/json": { "example": { "logoVersion": 1, "name": "Ada" }, "schema": { "properties": { "logoVersion": { "type": "number" }, "name": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete settings branding logo", "tags": [ "Instance branding" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "Owner. The raw bytes of a PNG or JPEG, at most 2 MB (413 `too_large`), at least 192 and at most 4096 pixels a side (400 `invalid_input`). The server crops the centre square and renders 32, 180, 192 and 512 px PNGs plus a maskable 512 px icon under `\u003cdata\u003e/branding/`, bumps `logoVersion` and answers `{name, logoVersion}`; recorded as `settings.changed` (`branding.logo`)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#instance-branding" }, "operationId": "putSettingsBrandingLogo", "responses": { "200": { "content": { "application/json": { "example": { "logoVersion": 1, "name": "Ada" }, "schema": { "properties": { "logoVersion": { "type": "number" }, "name": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings branding logo", "tags": [ "Instance branding" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/caldav": { "get": { "description": "`{enabled, url, secure, encryption}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getSettingsCaldav", "responses": { "200": { "content": { "application/json": { "example": { "enabled": false, "encryption": false, "secure": false, "url": "https://todo.example.com/dav/" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings caldav", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "`{enabled}` → the same shape\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "putSettingsCaldav", "requestBody": { "content": { "application/json": { "example": { "enabled": false } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "200": { "content": { "application/json": { "example": { "enabled": false, "secure": false, "url": "https://todo.example.com/dav/" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings caldav", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/calendar-feeds": { "get": { "description": "`{enabled}`; off by default, `OPENTODO_CALENDAR_FEEDS=true` presets it on first start; a change is recorded as `settings.changed`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "getSettingsCalendarFeeds", "responses": { "200": { "content": { "application/json": { "example": { "enabled": false } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List settings calendar feeds", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "`{enabled}`; off by default, `OPENTODO_CALENDAR_FEEDS=true` presets it on first start; a change is recorded as `settings.changed`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "operationId": "putSettingsCalendarFeeds", "requestBody": { "content": { "application/json": { "example": { "enabled": false } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "200": { "content": { "application/json": { "example": { "enabled": false } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings calendar feeds", "tags": [ "Calendar feeds" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/calendar-sync": { "get": { "description": "`{enabled, google, microsoft, max_connections}` (`google`, `microsoft`: that client is set up); the setting `calendar_sync.enabled`; off by default; a change is recorded as `settings.changed`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "getSettingsCalendarSync", "responses": { "200": { "content": { "application/json": { "example": { "enabled": false, "google": false, "max_connections": 3, "microsoft": false } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings calendar sync", "tags": [ "Calendar sync" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "`{enabled, google, microsoft, max_connections}` (`google`, `microsoft`: that client is set up); the setting `calendar_sync.enabled`; off by default; a change is recorded as `settings.changed`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "putSettingsCalendarSync", "requestBody": { "content": { "application/json": { "example": { "enabled": false } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "200": { "content": { "application/json": { "example": { "enabled": false } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings calendar sync", "tags": [ "Calendar sync" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/calendar-sync/google": { "get": { "description": "`{client_id, secret_set, from_env, redirect_uri}`; never the secret\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "getSettingsCalendarSyncGoogle", "responses": { "200": { "content": { "application/json": { "example": { "client_id": "00000000-0000-4000-8000-000000000001", "from_env": false, "redirect_uri": "example", "secret_set": false }, "schema": { "properties": { "client_id": { "type": "string" }, "from_env": { "type": "boolean" }, "redirect_uri": { "type": "string" }, "secret_set": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings calendar sync google", "tags": [ "Calendar sync" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "`{client_id, client_secret?}` (an empty secret removes it); `409 managed_by_environment` while `OPENTODO_GOOGLE_CLIENT_ID` and a secret are set; recorded as `settings.changed` for `calendar_sync.google_client` without values\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "putSettingsCalendarSyncGoogle", "requestBody": { "content": { "application/json": { "example": { "client_id": "00000000-0000-4000-8000-000000000001", "client_secret": "example-secret" }, "schema": { "properties": { "client_id": { "type": [ "string", "null" ] }, "client_secret": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "client_id": "00000000-0000-4000-8000-000000000001", "from_env": false, "redirect_uri": "example", "secret_set": false }, "schema": { "properties": { "client_id": { "type": "string" }, "from_env": { "type": "boolean" }, "redirect_uri": { "type": "string" }, "secret_set": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings calendar sync google", "tags": [ "Calendar sync" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/settings/calendar-sync/microsoft": { "get": { "description": "`{client_id, tenant, secret_set, from_env, redirect_uri, refused_at}` (`tenant` is `common` unless set; `refused_at`: when Microsoft last refused the secret, Unix ms, else `null`); never the secret\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "getSettingsCalendarSyncMicrosoft", "responses": { "200": { "content": { "application/json": { "example": { "client_id": "00000000-0000-4000-8000-000000000001", "from_env": false, "redirect_uri": "example", "refused_at": 1794906000000, "secret_set": false, "tenant": "example" }, "schema": { "properties": { "client_id": { "type": "string" }, "from_env": { "type": "boolean" }, "redirect_uri": { "type": "string" }, "refused_at": { "type": [ "number", "null" ] }, "secret_set": { "type": "boolean" }, "tenant": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings calendar sync microsoft", "tags": [ "Calendar sync" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "`{client_id, tenant?, client_secret?}` (an empty secret removes it; `tenant` is `common`, `organizations`, `consumers`, a tenant id or a domain, else `400 invalid_input` with `field: tenant`); a new secret clears `refused_at` and resumes the connections stopped with `microsoft_client_refused`; `409 managed_by_environment` while `OPENTODO_MICROSOFT_CLIENT_ID` and a secret are set; recorded as `settings.changed` for `calendar_sync.microsoft_client` without values\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "operationId": "putSettingsCalendarSyncMicrosoft", "requestBody": { "content": { "application/json": { "example": { "client_id": "00000000-0000-4000-8000-000000000001", "client_secret": "example-secret", "tenant": "example" }, "schema": { "properties": { "client_id": { "type": [ "string", "null" ] }, "client_secret": { "type": [ "string", "null" ] }, "tenant": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "client_id": "00000000-0000-4000-8000-000000000001", "from_env": false, "redirect_uri": "example", "refused_at": 1794906000000, "secret_set": false, "tenant": "example" }, "schema": { "properties": { "client_id": { "type": "string" }, "from_env": { "type": "boolean" }, "redirect_uri": { "type": "string" }, "refused_at": { "type": [ "number", "null" ] }, "secret_set": { "type": "boolean" }, "tenant": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings calendar sync microsoft", "tags": [ "Calendar sync" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/settings/issues": { "get": { "description": "`{enabled}`, the setting `integrations.issues`; off by default; a change is recorded as `settings.changed`", "externalDocs": { "url": "https://open-todo.app/docs/api/#issue-connections" }, "operationId": "getSettingsIssues", "responses": { "200": { "content": { "application/json": { "example": { "enabled": false } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List settings issues", "tags": [ "Issue connections" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "`{enabled}`, the setting `integrations.issues`; off by default; a change is recorded as `settings.changed`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#issue-connections" }, "operationId": "putSettingsIssues", "requestBody": { "content": { "application/json": { "example": { "enabled": false } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "200": { "content": { "application/json": { "example": { "enabled": false } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings issues", "tags": [ "Issue connections" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/maps": { "get": { "description": "`{enabled, tiles_url, geocoder_url, locked, defaults: {tiles_url, geocoder_url}}`; `PUT {enabled, tiles_url?, geocoder_url?}` (empty URLs use the defaults). A value set by `OPENTODO_MAPS*` is listed in `locked` and cannot be changed. Changes are audited as `settings.changed` (`maps.enabled`, `maps.tiles_url`, `maps.geocoder_url`); refused on a demo\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#maps" }, "operationId": "getSettingsMaps", "responses": { "200": { "content": { "application/json": { "example": { "defaults": { "geocoder_url": "https://todo.example.com/", "tiles_url": "https://todo.example.com/" }, "enabled": false, "geocoder_url": "https://todo.example.com/", "locked": [ "example" ], "tiles_url": "https://todo.example.com/" }, "schema": { "properties": { "defaults": { "properties": { "geocoder_url": { "type": "string" }, "tiles_url": { "type": "string" } }, "type": "object" }, "enabled": { "type": "boolean" }, "geocoder_url": { "type": "string" }, "locked": { "items": { "type": "string" }, "type": "array" }, "tiles_url": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List settings maps", "tags": [ "Maps" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "`{enabled, tiles_url, geocoder_url, locked, defaults: {tiles_url, geocoder_url}}`; `PUT {enabled, tiles_url?, geocoder_url?}` (empty URLs use the defaults). A value set by `OPENTODO_MAPS*` is listed in `locked` and cannot be changed. Changes are audited as `settings.changed` (`maps.enabled`, `maps.tiles_url`, `maps.geocoder_url`); refused on a demo\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#maps" }, "operationId": "putSettingsMaps", "requestBody": { "content": { "application/json": { "example": { "enabled": false, "geocoder_url": "https://todo.example.com/", "tiles_url": "https://todo.example.com/" }, "schema": { "properties": { "enabled": { "type": [ "boolean", "null" ] }, "geocoder_url": { "type": [ "string", "null" ] }, "tiles_url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "defaults": { "geocoder_url": "https://todo.example.com/", "tiles_url": "https://todo.example.com/" }, "enabled": false, "geocoder_url": "https://todo.example.com/", "locked": [ "example" ], "tiles_url": "https://todo.example.com/" }, "schema": { "properties": { "defaults": { "properties": { "geocoder_url": { "type": "string" }, "tiles_url": { "type": "string" } }, "type": "object" }, "enabled": { "type": "boolean" }, "geocoder_url": { "type": "string" }, "locked": { "items": { "type": "string" }, "type": "array" }, "tiles_url": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings maps", "tags": [ "Maps" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/settings/mcp": { "get": { "description": "`{enabled, writes_enabled, endpoint}`: whether the [MCP endpoint](https://open-todo.app/docs/mcp/) is on, whether assistants may make changes, and its URL", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getSettingsMcp", "responses": { "200": { "content": { "application/json": { "example": { "enabled": false, "endpoint": "example", "writes_enabled": false }, "schema": { "properties": { "enabled": { "type": "boolean" }, "endpoint": { "type": "string" }, "writes_enabled": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings mcp", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "`{enabled?, writes_enabled?}` (at least one) → `{enabled, writes_enabled, endpoint}`; each change is recorded as `settings.changed` (`mcp.enabled`, `mcp.writes`)\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "putSettingsMcp", "responses": { "200": { "content": { "application/json": { "example": { "enabled": false, "endpoint": "example", "writes_enabled": false }, "schema": { "properties": { "enabled": { "type": "boolean" }, "endpoint": { "type": "string" }, "writes_enabled": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings mcp", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/settings/mcp/clients": { "get": { "description": "`{clients:[{id, name, scope, redirect_uris, dynamic, created_at, last_used_at, secret_set}], platforms:[{id, name, redirect_uris}], resource, discovery_url, metadata_url, authorize_url, token_url}`; never a secret\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getSettingsMcpClients", "responses": { "200": { "content": { "application/json": { "example": { "authorize_url": "https://todo.example.com/", "clients": [ { "created_at": 1794906000000, "created_by": "example", "dynamic": false, "id": "00000000-0000-4000-8000-000000000001", "last_used_at": 1794906000000, "name": "Ada", "redirect_uris": [ "example" ], "scope": "full", "secret_set": false } ], "discovery_url": "https://todo.example.com/", "metadata_url": "https://todo.example.com/", "platforms": [ {} ], "redirect_uris": [ "example" ], "resource": "example", "token_url": "ot_example_token" }, "schema": { "properties": { "authorize_url": { "type": "string" }, "clients": { "items": { "properties": { "created_at": { "type": "number" }, "created_by": { "type": "string" }, "dynamic": { "type": "boolean" }, "id": { "type": "string" }, "last_used_at": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "redirect_uris": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" }, "secret_set": { "type": "boolean" } }, "type": "object" }, "type": "array" }, "discovery_url": { "type": "string" }, "metadata_url": { "type": "string" }, "platforms": { "items": { "type": "object" }, "type": "array" }, "redirect_uris": { "items": { "type": "string" }, "type": "array" }, "resource": { "type": "string" }, "token_url": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List settings mcp clients", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" }, "post": { "description": "`{name?, scope? (read or agent), platform? (google, openai or anthropic), redirect_uris?}`: a platform's addresses, or up to ten custom addresses, each an absolute `https` address without user information, fragment or `*`, matched exactly; neither: Google's six connector addresses → 201 `{client, secret}`, the secret only here; 400 `bad_request` for both or an unknown platform, 400 `invalid_redirect_uri` for an address that breaks a rule. A stored address is a prefix only when it is a platform's own prefix (`…/r/`, `https://chatgpt.com/connector/oauth/`), followed by exactly one segment\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postSettingsMcpClients", "requestBody": { "content": { "application/json": { "example": { "name": "Ada", "platform": "example", "redirect_uris": [ "example" ], "scope": "full" }, "schema": { "properties": { "name": { "type": "string" }, "platform": { "type": "string" }, "redirect_uris": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" } }, "required": [ "name", "platform", "redirect_uris", "scope" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "client": { "created_at": 1794906000000, "created_by": "example", "dynamic": false, "id": "00000000-0000-4000-8000-000000000001", "last_used_at": 1794906000000, "name": "Ada", "redirect_uris": [ "example" ], "scope": "full", "secret_set": false }, "secret": "example-secret" }, "schema": { "properties": { "client": { "properties": { "created_at": { "type": "number" }, "created_by": { "type": "string" }, "dynamic": { "type": "boolean" }, "id": { "type": "string" }, "last_used_at": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "redirect_uris": { "items": { "type": "string" }, "type": "array" }, "scope": { "type": "string" }, "secret_set": { "type": "boolean" } }, "type": "object" }, "secret": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a settings mcp client", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/settings/mcp/clients/{id}": { "delete": { "description": "delete the client, its grants and their access tokens → 204\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "deleteSettingsMcpClientsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a settings mcp client", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/mfa": { "get": { "description": "`{required: \"none\"|\"owner\"|\"all\"}`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getSettingsMfa", "responses": { "200": { "content": { "application/json": { "example": { "required": "example" }, "schema": { "properties": { "required": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings mfa", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "`{required}` → `{required}`\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "putSettingsMfa", "requestBody": { "content": { "application/json": { "example": { "required": "example" }, "schema": { "properties": { "required": { "type": "string" } }, "required": [ "required" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "required": "example" }, "schema": { "properties": { "required": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings mfa", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.credential.recent" } }, "/api/v1/settings/notification-channels": { "get": { "description": "`{enabled}`, the setting `notifications.channels`; on by default; a change is recorded as `settings.changed`", "externalDocs": { "url": "https://open-todo.app/docs/api/#notification-channels" }, "operationId": "getSettingsNotificationChannels", "responses": { "200": { "content": { "application/json": { "example": { "enabled": true } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List settings notification channels", "tags": [ "Notification channels" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "`{enabled}`, the setting `notifications.channels`; on by default; a change is recorded as `settings.changed`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#notification-channels" }, "operationId": "putSettingsNotificationChannels", "requestBody": { "content": { "application/json": { "example": { "enabled": true } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "200": { "content": { "application/json": { "example": { "enabled": true } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings notification channels", "tags": [ "Notification channels" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/oidc": { "get": { "description": "provider configuration, secret masked, see [Single sign-on](https://open-todo.app/docs/api/#single-sign-on)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getSettingsOidc", "responses": { "200": { "content": { "application/json": { "example": { "allowProvision": false, "baseUrlConfigured": false, "clientId": "00000000-0000-4000-8000-000000000001", "clientSecret": "example-secret", "clientSecretSet": false, "displayName": "Ada", "enabled": false, "issuer": "example", "managedBy": {}, "providerLogout": false, "redirectUri": "example", "scopes": "example", "ssoOnly": false, "syncPictures": false }, "schema": { "properties": { "allowProvision": { "type": "boolean" }, "baseUrlConfigured": { "type": "boolean" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "clientSecretSet": { "type": "boolean" }, "displayName": { "type": "string" }, "enabled": { "type": "boolean" }, "issuer": { "type": "string" }, "managedBy": { "type": "object" }, "providerLogout": { "type": "boolean" }, "redirectUri": { "type": "string" }, "scopes": { "type": "string" }, "ssoOnly": { "type": "boolean" }, "syncPictures": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings oidc", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "change the provider configuration\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "putSettingsOidc", "requestBody": { "content": { "application/json": { "example": { "allowProvision": false, "clientId": "00000000-0000-4000-8000-000000000001", "clientSecret": "example-secret", "displayName": "Ada", "issuer": "example", "providerLogout": false, "scopes": "example", "ssoOnly": false, "syncPictures": false }, "schema": { "properties": { "allowProvision": { "type": [ "boolean", "null" ] }, "clientId": { "type": [ "string", "null" ] }, "clientSecret": { "type": [ "string", "null" ] }, "displayName": { "type": [ "string", "null" ] }, "issuer": { "type": [ "string", "null" ] }, "providerLogout": { "type": [ "boolean", "null" ] }, "scopes": { "type": [ "string", "null" ] }, "ssoOnly": { "type": [ "boolean", "null" ] }, "syncPictures": { "type": [ "boolean", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "allowProvision": false, "baseUrlConfigured": false, "clientId": "00000000-0000-4000-8000-000000000001", "clientSecret": "example-secret", "clientSecretSet": false, "displayName": "Ada", "enabled": false, "issuer": "example", "managedBy": {}, "providerLogout": false, "redirectUri": "example", "scopes": "example", "ssoOnly": false, "syncPictures": false }, "schema": { "properties": { "allowProvision": { "type": "boolean" }, "baseUrlConfigured": { "type": "boolean" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "clientSecretSet": { "type": "boolean" }, "displayName": { "type": "string" }, "enabled": { "type": "boolean" }, "issuer": { "type": "string" }, "managedBy": { "type": "object" }, "providerLogout": { "type": "boolean" }, "redirectUri": { "type": "string" }, "scopes": { "type": "string" }, "ssoOnly": { "type": "boolean" }, "syncPictures": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings oidc", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.credential.recent" } }, "/api/v1/settings/oidc/test": { "post": { "description": "`{issuer?}` → `{ok, issuer, authorizationHost, tokenHost, endSessionSupported}`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postSettingsOidcTest", "requestBody": { "content": { "application/json": { "example": { "issuer": "example" }, "schema": { "properties": { "issuer": { "type": "string" } }, "required": [ "issuer" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "authorizationHost": "example", "endSessionSupported": false, "issuer": "example", "ok": true, "redirectUri": "example", "redirectUriConfigured": false, "tokenHost": "ot_example_token" }, "schema": { "properties": { "authorizationHost": { "type": "string" }, "endSessionSupported": { "type": "boolean" }, "issuer": { "type": "string" }, "ok": { "type": "boolean" }, "redirectUri": { "type": "string" }, "redirectUriConfigured": { "type": "boolean" }, "tokenHost": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Settings oidc test", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/project-invites": { "get": { "description": "`{membersCanInviteNewPeople}` (the owner switch)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getSettingsProjectInvites", "responses": { "200": { "content": { "application/json": { "example": { "membersCanInviteNewPeople": false } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List settings project invites", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "put": { "description": "`{membersCanInviteNewPeople: true|false}` → the same shape\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "putSettingsProjectInvites", "requestBody": { "content": { "application/json": { "example": { "membersCanInviteNewPeople": false } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "200": { "content": { "application/json": { "example": { "membersCanInviteNewPeople": false } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings project invites", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/smtp": { "get": { "description": "the [outgoing email](https://open-todo.app/docs/api/#outgoing-email) configuration without the password\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getSettingsSmtp", "responses": { "200": { "content": { "application/json": { "example": { "configured": false, "from": "example", "host": "example", "lastTest": { "at": 1, "outcome": "example", "reply": "example", "stage": "example" }, "managedBy": {}, "passwordSet": false, "port": 1, "security": "example", "username": "Ada" }, "schema": { "properties": { "configured": { "type": "boolean" }, "from": { "type": "string" }, "host": { "type": "string" }, "lastTest": { "properties": { "at": { "type": "number" }, "outcome": { "type": "string" }, "reply": { "type": "string" }, "stage": { "type": "string" } }, "type": "object" }, "managedBy": { "type": "object" }, "passwordSet": { "type": "boolean" }, "port": { "type": "number" }, "security": { "type": "string" }, "username": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings smtp", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.credential" }, "put": { "description": "`{host?, port?, security?, username?, password?, from?}` → the same shape\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "putSettingsSmtp", "requestBody": { "content": { "application/json": { "example": { "from": "example", "host": "example", "password": "correct horse battery staple", "port": 1, "security": "example", "username": "Ada" }, "schema": { "properties": { "from": { "type": [ "string", "null" ] }, "host": { "type": [ "string", "null" ] }, "password": { "type": [ "string", "null" ] }, "port": { "type": [ "number", "null" ] }, "security": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "configured": false, "from": "example", "host": "example", "lastTest": { "at": 1, "outcome": "example", "reply": "example", "stage": "example" }, "managedBy": {}, "passwordSet": false, "port": 1, "security": "example", "username": "Ada" }, "schema": { "properties": { "configured": { "type": "boolean" }, "from": { "type": "string" }, "host": { "type": "string" }, "lastTest": { "properties": { "at": { "type": "number" }, "outcome": { "type": "string" }, "reply": { "type": "string" }, "stage": { "type": "string" } }, "type": "object" }, "managedBy": { "type": "object" }, "passwordSet": { "type": "boolean" }, "port": { "type": "number" }, "security": { "type": "string" }, "username": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings smtp", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.credential.recent" } }, "/api/v1/settings/smtp/test": { "post": { "description": "sends a test message to the owner → `{outcome: \"sent\"|\"failed\", stage?, reply?}`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postSettingsSmtpTest", "responses": { "200": { "content": { "application/json": { "example": { "outcome": "example", "reply": "example", "stage": "example", "to": "example" }, "schema": { "properties": { "outcome": { "type": "string" }, "reply": { "type": "string" }, "stage": { "type": "string" }, "to": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Settings smtp test", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/storage": { "get": { "description": "database file size, free space inside it, write-ahead log size, last notes compaction, conversion state; see [Database storage](https://open-todo.app/docs/api/#database-storage)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getSettingsStorage", "responses": { "200": { "content": { "application/json": { "example": { "conversion": "example", "conversion_needed_bytes": 1, "database_bytes": 1, "free_bytes": 1, "last_compaction": { "at": 1, "converted": false, "file_bytes_reclaimed": 1, "more": false, "ops_removed": 1, "value_bytes_removed": 1 }, "wal_bytes": 1 }, "schema": { "properties": { "conversion": { "type": "string" }, "conversion_needed_bytes": { "type": "number" }, "database_bytes": { "type": "number" }, "free_bytes": { "type": "number" }, "last_compaction": { "properties": { "at": { "type": "number" }, "converted": { "type": "boolean" }, "file_bytes_reclaimed": { "type": "number" }, "more": { "type": "boolean" }, "ops_removed": { "type": "number" }, "value_bytes_removed": { "type": "number" } }, "type": [ "object", "null" ] }, "wal_bytes": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings storage", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/stt": { "get": { "description": "`{url, model, keySet, locked, connected}`; the key is write-only. A value set by `OPENTODO_STT_URL`, `OPENTODO_STT_MODEL` or `OPENTODO_STT_KEY_FILE` is listed in `locked`\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#speech-to-text" }, "operationId": "getSettingsStt", "responses": { "200": { "content": { "application/json": { "example": { "connected": false, "host": "example", "keySet": false, "locked": [ "example" ], "model": "example", "url": "https://todo.example.com/" }, "schema": { "properties": { "connected": { "type": "boolean" }, "host": { "type": "string" }, "keySet": { "type": "boolean" }, "locked": { "items": { "type": "string" }, "type": "array" }, "model": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get settings stt", "tags": [ "Speech to text" ], "x-opentodo-policy": "owner-only.credential" }, "put": { "description": "any of `{url, model, key}` (`\"\"` clears; a model is needed while a URL is set) → the same shape; `400 invalid_input` names a bad field; connecting or disconnecting is audited as `settings.changed` (`stt.connected`)\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#speech-to-text" }, "operationId": "putSettingsStt", "requestBody": { "content": { "application/json": { "example": { "key": "example", "model": "example", "url": "https://todo.example.com/" }, "schema": { "properties": { "key": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "connected": false, "host": "example", "keySet": false, "locked": [ "example" ], "model": "example", "url": "https://todo.example.com/" }, "schema": { "properties": { "connected": { "type": "boolean" }, "host": { "type": "string" }, "keySet": { "type": "boolean" }, "locked": { "items": { "type": "string" }, "type": "array" }, "model": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings stt", "tags": [ "Speech to text" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/settings/stt/test": { "post": { "description": "optional draft `{url, model, key}`: sends a built-in sample with the draft or the stored values → `{ok: true, text}` or `{ok: false, error}`; `409 stt_not_configured` without a service\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#speech-to-text" }, "operationId": "postSettingsSttTest", "requestBody": { "content": { "application/json": { "example": { "key": "example", "model": "example", "url": "https://todo.example.com/" }, "schema": { "properties": { "key": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "example": { "error": "example", "ok": true, "text": "example" }, "schema": { "properties": { "error": { "type": "string" }, "ok": { "type": "boolean" }, "text": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Settings stt test", "tags": [ "Speech to text" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/settings/themes/default": { "put": { "description": "Owner. `{light, dark}`, each `\"\"`, `builtin:\u003cid\u003e` or `instance:\u003cid\u003e` of that side's kind (400 `invalid_input` for an unknown id or a theme of the other kind; OpenTodo's own theme is stored as `\"\"`). Answers like the read; recorded as `settings.changed` (`themes.default.light`, `themes.default.dark`, the ids only)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#server-themes" }, "operationId": "putSettingsThemesDefault", "requestBody": { "content": { "application/json": { "example": { "dark": "example", "light": "example" }, "schema": { "properties": { "dark": { "type": "string" }, "light": { "type": "string" } }, "required": [ "dark", "light" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "default": { "dark": "example", "light": "example" }, "themes": [ { "doc": "example", "id": "00000000-0000-4000-8000-000000000001", "kind": "example" } ], "version": 1 }, "schema": { "properties": { "default": { "properties": { "dark": { "type": "string" }, "light": { "type": "string" } }, "type": "object" }, "themes": { "items": { "properties": { "doc": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" } }, "type": "object" }, "type": "array" }, "version": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings themes default", "tags": [ "Server themes" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/themes/instance/{id}": { "delete": { "description": "Owner. Removes the theme and clears a default that names it in the same change (404 `not_found` for an unknown id). Members who chose it fall back to their side's default and keep their stored choice. Recorded as `settings.changed` (`themes.instance`, `removed` and the id)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#server-themes" }, "operationId": "deleteSettingsThemesInstanceById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "default": { "dark": "example", "light": "example" }, "themes": [ { "doc": "example", "id": "00000000-0000-4000-8000-000000000001", "kind": "example" } ], "version": 1 }, "schema": { "properties": { "default": { "properties": { "dark": { "type": "string" }, "light": { "type": "string" } }, "type": "object" }, "themes": { "items": { "properties": { "doc": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" } }, "type": "object" }, "type": "array" }, "version": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a settings themes instance", "tags": [ "Server themes" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "Owner. A theme document as the body, at most 16 KB (413 `too_large`), valid (400 `invalid_input`); `{id}` is `new` to add one (409 `limit_reached` past 20) or the id of one to replace (404 `not_found`). The server sets the document's `id`. A theme that is a default keeps its kind (400 `invalid_input`). Answers the read plus the theme's `id`; recorded as `settings.changed` (`themes.instance`, `added` or `changed` and the id)\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#server-themes" }, "operationId": "putSettingsThemesInstanceById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "default": { "dark": "example", "light": "example" }, "id": "00000000-0000-4000-8000-000000000001", "themes": [ { "doc": "example", "id": "00000000-0000-4000-8000-000000000001", "kind": "example" } ], "version": 1 }, "schema": { "properties": { "default": { "properties": { "dark": { "type": "string" }, "light": { "type": "string" } }, "type": "object" }, "id": { "type": "string" }, "themes": { "items": { "properties": { "doc": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" } }, "type": "object" }, "type": "array" }, "version": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Replace a settings themes instance", "tags": [ "Server themes" ], "x-opentodo-policy": "owner-only" } }, "/api/v1/settings/webhooks": { "get": { "description": "`{allowPrivate}`\n\nOnly the server's owner.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getSettingsWebhooks", "responses": { "200": { "content": { "application/json": { "example": { "allowPrivate": false }, "schema": { "properties": { "allowPrivate": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List settings webhooks", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only" }, "put": { "description": "`{allowPrivate}` → `{allowPrivate}`\n\nOnly the server's owner. Needs a session or an admin token; full tokens are refused.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "putSettingsWebhooks", "requestBody": { "content": { "application/json": { "example": { "allowPrivate": false }, "schema": { "properties": { "allowPrivate": { "type": [ "boolean", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "allowPrivate": false }, "schema": { "properties": { "allowPrivate": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update settings webhooks", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "owner-only.credential" } }, "/api/v1/slots": { "get": { "description": "`?from=\u0026to=` (optional dates, inclusive) → `{slots: [{id, title, date, start, minutes, task_ids, color, created_at, encrypted}]}` by date and start", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-slots" }, "operationId": "getSlots", "responses": { "200": { "content": { "application/json": { "example": { "slots": [ {} ] }, "schema": { "properties": { "slots": { "items": { "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List slots", "tags": [ "Calendar slots" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{date, title?, start?, minutes?, task_ids?, color?, move_tasks?}` → `201` slot (defaults 09:00, 30 minutes, `#64748b`)", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-slots" }, "operationId": "postSlots", "requestBody": { "content": { "application/json": { "example": { "color": "#3b82f6", "date": "2026-11-20", "minutes": "example", "move_tasks": false, "start": "example", "task_ids": "example", "title": "Buy paint for the fence" }, "schema": { "properties": { "color": { "type": "string" }, "date": { "type": "string" }, "minutes": { "type": "string" }, "move_tasks": { "type": "boolean" }, "start": { "type": "string" }, "task_ids": { "type": "string" }, "title": { "type": "string" } }, "required": [ "color", "date", "minutes", "move_tasks", "start", "task_ids", "title" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "encrypted": false, "id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "encrypted": { "type": "boolean" }, "id": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a slot", "tags": [ "Calendar slots" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/slots/{id}": { "delete": { "description": "`PATCH` takes the same fields → `200` slot; `DELETE` → `204` (a tombstone; the tasks keep their date without a time); an unknown or deleted id answers `404 not_found`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-slots" }, "operationId": "deleteSlotsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a slot", "tags": [ "Calendar slots" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "`PATCH` takes the same fields → `200` slot; `DELETE` → `204` (a tombstone; the tasks keep their date without a time); an unknown or deleted id answers `404 not_found`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-slots" }, "operationId": "getSlotsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "encrypted": false, "id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "encrypted": { "type": "boolean" }, "id": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a slot", "tags": [ "Calendar slots" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`PATCH` takes the same fields → `200` slot; `DELETE` → `204` (a tombstone; the tasks keep their date without a time); an unknown or deleted id answers `404 not_found`", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-slots" }, "operationId": "patchSlotsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "color": "#3b82f6", "date": "2026-11-20", "minutes": "example", "move_tasks": false, "start": "example", "task_ids": "example", "title": "Buy paint for the fence" }, "schema": { "properties": { "color": { "type": "string" }, "date": { "type": "string" }, "minutes": { "type": "string" }, "move_tasks": { "type": "boolean" }, "start": { "type": "string" }, "task_ids": { "type": "string" }, "title": { "type": "string" } }, "required": [ "color", "date", "minutes", "move_tasks", "start", "task_ids", "title" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "encrypted": false, "id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "encrypted": { "type": "boolean" }, "id": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a slot", "tags": [ "Calendar slots" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/sync": { "post": { "description": "device sync, see [sync.md](https://open-todo.app/docs/sync/#exchange); the response carries the log `generation`; with `\"features\": [\"push_only\"]` the ops are applied and nothing is pulled (for devices that only write)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postSync", "requestBody": { "content": { "application/json": { "example": { "cursor": 53, "device": "laptop", "ops": [ { "device": "laptop", "entity": "task", "entityId": "00000000-0000-4000-8000-000000000005", "field": "title", "id": "laptop-1", "ts": 1794906000000, "value": "Buy green paint" } ] }, "schema": { "properties": { "backfillAck": { "type": "number" }, "cursor": { "type": "number" }, "device": { "type": "string" }, "features": { "items": { "type": "string" }, "type": "array" }, "ops": { "items": { "properties": { "actor": { "type": "string" }, "device": { "type": "string" }, "entity": { "type": "string" }, "entityId": { "type": "string" }, "field": { "type": "string" }, "id": { "type": "string" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "value": { "description": "The field's value: any JSON value of the field's kind (docs/sync.md \"Schema (v1)\")." } }, "required": [ "device", "entity", "entityId", "field", "id", "ts", "value" ], "type": "object" }, "type": "array" }, "tzOffset": { "type": [ "number", "null" ] } }, "required": [ "cursor", "device", "ops" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "applied": 1, "cursor": 54, "duplicates": 0, "generation": "0a1b2c3d4e5f60718293a4b5c6d7e8f9", "hasMore": false, "memberships": [], "ops": [], "purged": [], "rejected": [], "serverTime": 1794906000082, "trashRetentionDays": 0, "workspaces": [ { "color": "", "default": true, "groups": [], "icon": "", "id": "00000000-0000-4000-8000-000000000010", "members": [ { "name": "Ada", "role": "owner", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Personal", "ownerId": "00000000-0000-4000-8000-000000000001", "role": "owner" } ] }, "schema": { "properties": { "applied": { "type": "number" }, "backfillSeq": { "type": "number" }, "cursor": { "type": "number" }, "duplicates": { "type": "number" }, "generation": { "type": "string" }, "hasMore": { "type": "boolean" }, "memberships": { "items": { "properties": { "grants": { "items": { "properties": { "groupId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "members": { "items": { "properties": { "avatarVersion": { "type": "number" }, "email": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" }, "via": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" }, "ownerId": { "type": "string" }, "projectId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "ops": { "items": { "properties": { "actor": { "type": "string" }, "device": { "type": "string" }, "entity": { "type": "string" }, "entityId": { "type": "string" }, "field": { "type": "string" }, "id": { "type": "string" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "value": { "description": "The field's value: any JSON value of the field's kind (docs/sync.md \"Schema (v1)\")." } }, "type": "object" }, "type": "array" }, "purged": { "items": { "properties": { "entity": { "type": "string" }, "entityId": { "type": "string" } }, "type": "object" }, "type": "array" }, "rejected": { "items": { "properties": { "id": { "type": "string" }, "reason": { "type": "string" }, "serverTime": { "type": "number" } }, "type": "object" }, "type": "array" }, "serverTime": { "type": "number" }, "trashRetentionDays": { "type": "number" }, "workspaces": { "items": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Sync", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/sync/events": { "get": { "description": "server-sent event stream; wakes the device when other devices or the API record operations, see [sync.md](https://open-todo.app/docs/sync/#live-updates)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getSyncEvents", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List sync events", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/task-pages": { "get": { "description": "the caller's own active pages, with the wrapped share key of encrypted ones\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTaskPages", "responses": { "200": { "content": { "application/json": { "example": { "pages": [ { "createdBy": "example", "encrypted": false, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "includeMap": false, "kind": "example", "label": "example", "lastOpenedAt": 1794906000000, "noteId": "00000000-0000-4000-8000-000000000001", "pendingReplies": 1, "publishedAt": 1794906000000, "replies": 1, "rights": "example", "snapshotAt": 1794906000000, "snapshotVersion": 1, "taskId": "00000000-0000-4000-8000-000000000001", "ticks": 1, "wrappedKey": "example" } ] }, "schema": { "properties": { "pages": { "items": { "properties": { "createdBy": { "type": "string" }, "encrypted": { "type": "boolean" }, "expiresAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "includeMap": { "type": "boolean" }, "kind": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "lastOpenedAt": { "type": [ "number", "null" ] }, "noteId": { "type": "string" }, "pendingReplies": { "type": "number" }, "publishedAt": { "type": "number" }, "replies": { "type": "number" }, "rights": { "type": "string" }, "snapshotAt": { "type": [ "number", "null" ] }, "snapshotVersion": { "type": "number" }, "taskId": { "type": "string" }, "ticks": { "type": "number" }, "wrappedKey": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List task pages", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/tasks": { "get": { "description": "`{tasks:[…]}` (yours and those of projects shared with you); `?include_deleted=true` to include tombstones; `?completed_after=…\u0026completed_before=…` for [tasks completed in a range](https://open-todo.app/docs/api/#tasks-completed-in-a-range)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTasks", "responses": { "200": { "content": { "application/json": { "example": { "tasks": [ { "appends": [], "body_version": "1794906000034:server:0a1b2c3d", "created_at": 1794906000033, "description": "Two litres, dark green.", "due": { "date": "2026-11-20", "time": "10:00" }, "energy": null, "estimate_minutes": 30, "fields": {}, "id": "00000000-0000-4000-8000-000000000005", "labels": [ "00000000-0000-4000-8000-000000000004" ], "origin": null, "position": 1794906000033, "priority": 1, "project_id": "00000000-0000-4000-8000-000000000002", "rotation": [], "section_id": "00000000-0000-4000-8000-000000000003", "sector": null, "title": "Buy paint for the fence" } ] }, "schema": { "properties": { "tasks": { "items": { "allOf": [ { "$ref": "#/components/schemas/Task" }, { "properties": { "appends": { "description": "Appends not yet merged into the body, oldest first.", "items": { "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "body_version": { "type": "string" }, "fields": { "type": "object" } }, "type": "object" } ] }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List tasks", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "create → 201 task, see [Task fields](https://open-todo.app/docs/api/#task-fields); optional `Idempotency-Key` header, see [Idempotency keys](https://open-todo.app/docs/api/#idempotency-keys) (every collection below accepts it on create); `?default_reminder=true` adds your [default reminder](https://open-todo.app/docs/api/#default-reminders); `\"reuse\": true` in a reusable list reopens a matching item instead, see [Reusable lists](https://open-todo.app/docs/api/#reusable-lists)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postTasks", "requestBody": { "content": { "application/json": { "example": { "description": "Two litres, dark green.", "due": { "date": "2026-11-20", "time": "10:00" }, "labels": [ "00000000-0000-4000-8000-000000000004" ], "priority": 2, "project_id": "00000000-0000-4000-8000-000000000002", "section_id": "00000000-0000-4000-8000-000000000003", "title": "Buy paint for the fence" }, "schema": { "properties": { "assignee_id": { "type": [ "string", "null" ] }, "blocked_by": { "description": "A list of ids.", "items": { "type": "string" }, "type": "array" }, "completed_at": { "type": [ "number", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "created_at": { "type": "number" }, "day_part": { "description": "The part of the day: morning, afternoon, or null (the evening is the `evening` flag).", "type": [ "string", "null" ] }, "deadline": { "description": "A calendar date, YYYY-MM-DD.", "format": "date", "type": [ "string", "null" ] }, "deleted_at": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "due": { "anyOf": [ { "$ref": "#/components/schemas/Due" }, { "type": "null" } ] }, "energy": { "description": "The energy a task needs: deep, medium or low; null for none (a write also takes \"\").", "type": [ "string", "null" ] }, "estimate_minutes": { "minimum": 1, "type": [ "integer", "null" ] }, "evening": { "type": "boolean" }, "flow_mode": { "type": "string" }, "habit": { "type": "boolean" }, "habit_amount": { "type": "number" }, "habit_anchor": { "type": "string" }, "habit_color": { "type": "string" }, "habit_graduated_at": { "type": [ "number", "null" ] }, "habit_period": { "type": "string" }, "habit_step": { "type": "number" }, "habit_target": { "type": "number" }, "habit_tiny": { "type": "string" }, "habit_unit": { "type": "string" }, "ical_extra": { "type": [ "string", "null" ] }, "labels": { "items": { "type": "string" }, "type": "array" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/Location" }, { "description": "Ciphertext on an end-to-end encrypted account.", "type": "string" }, { "type": "null" } ] }, "note_mentions": { "description": "A list of ids.", "items": { "type": "string" }, "type": "array" }, "notes_doc": { "description": "A mergeable notes document (\"ydoc:v1:…\"), see docs/sync.md \"Mergeable documents\". Write `description` (Markdown) instead unless you merge documents yourself.", "type": "string" }, "occurrence_date": { "description": "A calendar date, YYYY-MM-DD.", "format": "date", "type": [ "string", "null" ] }, "origin": { "anyOf": [ { "$ref": "#/components/schemas/Origin" }, { "description": "Ciphertext on an end-to-end encrypted account.", "type": "string" }, { "type": "null" } ] }, "parent_id": { "type": [ "string", "null" ] }, "position": { "type": "number" }, "priority": { "description": "1 is the highest, 4 the default.", "enum": [ 1, 2, 3, 4 ], "type": "integer" }, "project_id": { "type": [ "string", "null" ] }, "recurrence": { "description": "A repeat rule in English, such as \"every weekday\" (docs/recurrence.md).", "type": [ "string", "null" ] }, "rotation": { "description": "A list of ids.", "items": { "type": "string" }, "type": "array" }, "sample": { "type": "boolean" }, "section_id": { "type": [ "string", "null" ] }, "sector": { "description": "A time sector: a week (2026-W45), a month (2026-11) or a quarter (2026-Q4); null for none (a write also takes \"\").", "type": [ "string", "null" ] }, "series_id": { "type": [ "string", "null" ] }, "skipped": { "type": "boolean" }, "span": { "type": "boolean" }, "split_from": { "anyOf": [ { "$ref": "#/components/schemas/SplitFrom" }, { "type": "null" } ] }, "start": { "description": "The date a task starts, YYYY-MM-DD.", "format": "date", "type": [ "string", "null" ] }, "tiny": { "type": "boolean" }, "title": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "appends": [], "body_version": "1794906000034:server:0a1b2c3d", "created_at": 1794906000033, "description": "Two litres, dark green.", "due": { "date": "2026-11-20", "time": "10:00" }, "energy": null, "fields": {}, "id": "00000000-0000-4000-8000-000000000005", "labels": [ "00000000-0000-4000-8000-000000000004" ], "origin": null, "position": 1794906000033, "priority": 2, "project_id": "00000000-0000-4000-8000-000000000002", "rotation": [], "section_id": "00000000-0000-4000-8000-000000000003", "sector": null, "title": "Buy paint for the fence" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Task" }, { "properties": { "appends": { "description": "Appends not yet merged into the body, oldest first.", "items": { "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "body_version": { "type": "string" }, "fields": { "type": "object" } }, "type": "object" } ] } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a task", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}": { "delete": { "description": "soft delete (to the Trash) → 204", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteTasksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a task", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "task or 404", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTasksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "appends": [], "body_version": "1794906000034:server:0a1b2c3d", "created_at": 1794906000033, "description": "Two litres, dark green.", "due": { "date": "2026-11-20", "time": "10:00" }, "energy": null, "fields": {}, "id": "00000000-0000-4000-8000-000000000005", "labels": [ "00000000-0000-4000-8000-000000000004" ], "origin": null, "position": 1794906000033, "priority": 2, "project_id": "00000000-0000-4000-8000-000000000002", "rotation": [], "section_id": "00000000-0000-4000-8000-000000000003", "sector": null, "title": "Buy paint for the fence" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Task" }, { "properties": { "appends": { "description": "Appends not yet merged into the body, oldest first.", "items": { "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "body_version": { "type": "string" }, "fields": { "type": "object" } }, "type": "object" } ] } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a task", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "partial update → task; `?default_reminder=true` adds your [default reminder](https://open-todo.app/docs/api/#default-reminders) when the task gets a due date", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "patchTasksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "estimate_minutes": 30, "priority": 1 }, "schema": { "properties": { "assignee_id": { "type": [ "string", "null" ] }, "blocked_by": { "description": "A list of ids.", "items": { "type": "string" }, "type": "array" }, "completed_at": { "type": [ "number", "null" ] }, "completed_by": { "type": [ "string", "null" ] }, "created_at": { "type": "number" }, "day_part": { "description": "The part of the day: morning, afternoon, or null (the evening is the `evening` flag).", "type": [ "string", "null" ] }, "deadline": { "description": "A calendar date, YYYY-MM-DD.", "format": "date", "type": [ "string", "null" ] }, "deleted_at": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "due": { "anyOf": [ { "$ref": "#/components/schemas/Due" }, { "type": "null" } ] }, "energy": { "description": "The energy a task needs: deep, medium or low; null for none (a write also takes \"\").", "type": [ "string", "null" ] }, "estimate_minutes": { "minimum": 1, "type": [ "integer", "null" ] }, "evening": { "type": "boolean" }, "flow_mode": { "type": "string" }, "habit": { "type": "boolean" }, "habit_amount": { "type": "number" }, "habit_anchor": { "type": "string" }, "habit_color": { "type": "string" }, "habit_graduated_at": { "type": [ "number", "null" ] }, "habit_period": { "type": "string" }, "habit_step": { "type": "number" }, "habit_target": { "type": "number" }, "habit_tiny": { "type": "string" }, "habit_unit": { "type": "string" }, "ical_extra": { "type": [ "string", "null" ] }, "labels": { "items": { "type": "string" }, "type": "array" }, "location": { "anyOf": [ { "$ref": "#/components/schemas/Location" }, { "description": "Ciphertext on an end-to-end encrypted account.", "type": "string" }, { "type": "null" } ] }, "note_mentions": { "description": "A list of ids.", "items": { "type": "string" }, "type": "array" }, "notes_doc": { "description": "A mergeable notes document (\"ydoc:v1:…\"), see docs/sync.md \"Mergeable documents\". Write `description` (Markdown) instead unless you merge documents yourself.", "type": "string" }, "occurrence_date": { "description": "A calendar date, YYYY-MM-DD.", "format": "date", "type": [ "string", "null" ] }, "origin": { "anyOf": [ { "$ref": "#/components/schemas/Origin" }, { "description": "Ciphertext on an end-to-end encrypted account.", "type": "string" }, { "type": "null" } ] }, "parent_id": { "type": [ "string", "null" ] }, "position": { "type": "number" }, "priority": { "description": "1 is the highest, 4 the default.", "enum": [ 1, 2, 3, 4 ], "type": "integer" }, "project_id": { "type": [ "string", "null" ] }, "recurrence": { "description": "A repeat rule in English, such as \"every weekday\" (docs/recurrence.md).", "type": [ "string", "null" ] }, "rotation": { "description": "A list of ids.", "items": { "type": "string" }, "type": "array" }, "sample": { "type": "boolean" }, "section_id": { "type": [ "string", "null" ] }, "sector": { "description": "A time sector: a week (2026-W45), a month (2026-11) or a quarter (2026-Q4); null for none (a write also takes \"\").", "type": [ "string", "null" ] }, "series_id": { "type": [ "string", "null" ] }, "skipped": { "type": "boolean" }, "span": { "type": "boolean" }, "split_from": { "anyOf": [ { "$ref": "#/components/schemas/SplitFrom" }, { "type": "null" } ] }, "start": { "description": "The date a task starts, YYYY-MM-DD.", "format": "date", "type": [ "string", "null" ] }, "tiny": { "type": "boolean" }, "title": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "appends": [], "body_version": "1794906000034:server:0a1b2c3d", "created_at": 1794906000033, "description": "Two litres, dark green.", "due": { "date": "2026-11-20", "time": "10:00" }, "energy": null, "estimate_minutes": 30, "fields": {}, "id": "00000000-0000-4000-8000-000000000005", "labels": [ "00000000-0000-4000-8000-000000000004" ], "origin": null, "position": 1794906000033, "priority": 1, "project_id": "00000000-0000-4000-8000-000000000002", "rotation": [], "section_id": "00000000-0000-4000-8000-000000000003", "sector": null, "title": "Buy paint for the fence" }, "schema": { "allOf": [ { "$ref": "#/components/schemas/Task" }, { "properties": { "appends": { "description": "Appends not yet merged into the body, oldest first.", "items": { "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "type": "array" }, "body_version": { "type": "string" }, "fields": { "type": "object" } }, "type": "object" } ] } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a task", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/activity": { "get": { "description": "`{events, more, cursor?}` newest first, derived from the operation log; `?before=\u003ccursor\u003e\u0026limit=\u003c1-200\u003e` (default 50)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTasksByIdActivity", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "cursor": "example", "events": [ { "actor": "example", "actorName": "Ada", "changes": [ { "field": "example", "from": "example", "to": "example" } ], "device": "example", "entity": "example", "entityId": "00000000-0000-4000-8000-000000000001", "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "opIds": [ "00000000-0000-4000-8000-000000000001" ], "projectId": "00000000-0000-4000-8000-000000000001", "projectName": "Ada", "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence", "ts": 1794906000000 } ], "more": false }, "schema": { "properties": { "cursor": { "type": "string" }, "events": { "items": { "properties": { "actor": { "type": "string" }, "actorName": { "type": "string" }, "changes": { "items": { "properties": { "field": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "device": { "type": "string" }, "entity": { "type": "string" }, "entityId": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" }, "opIds": { "items": { "type": "string" }, "type": "array" }, "projectId": { "type": "string" }, "projectName": { "type": "string" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" }, "ts": { "type": "number" } }, "type": "object" }, "type": "array" }, "more": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get task activity", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/attachments": { "get": { "description": "The task's attachments that are not removed, oldest first, each with `uploaded`", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "operationId": "getTasksByIdAttachments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "attachments": [ {} ] }, "schema": { "properties": { "attachments": { "items": { "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List task attachments", "tags": [ "Attachments" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "Multipart `file` (and optional `comment_id`): stores the file and creates the attachment in one request. JSON `{\"url\": \"https://…\", \"name\"?: \"…\"}`: a link attachment. `201` with the attachment. Honours `Idempotency-Key` (a retry answers `200` with `Idempotent-Replayed: true`)", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "operationId": "postTasksByIdAttachments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Ada", "url": "https://todo.example.com/" }, "schema": { "properties": { "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "uploaded": false }, "schema": { "properties": { "uploaded": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "201": { "content": { "application/json": { "example": { "uploaded": false }, "schema": { "properties": { "uploaded": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a task attachment", "tags": [ "Attachments" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/comments": { "get": { "description": "`{comments}`: the task's live comments in thread order; see [Comments and activity](https://open-todo.app/docs/api/#comments-and-activity)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTasksByIdComments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "comments": [ { "author_id": "00000000-0000-4000-8000-000000000001", "body": "The shop opens at nine.", "created_at": 1794906000052, "deleted_at": null, "edited_at": null, "id": "00000000-0000-4000-8000-000000000007", "mentions": [], "my_reactions": [], "parent_id": null, "reactions": { "check": [], "eyes": [], "heart": [], "party": [], "question": [], "thumbs_up": [] }, "task_id": "00000000-0000-4000-8000-000000000005" } ] }, "schema": { "properties": { "comments": { "items": { "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List task comments", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{body, parent_id?, mentions?}` → 201 comment; 429 `rate_limited` past 60 new comments a minute", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postTasksByIdComments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "body": "The shop opens at nine." } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "201": { "content": { "application/json": { "example": { "author_id": "00000000-0000-4000-8000-000000000001", "body": "The shop opens at nine.", "created_at": 1794906000052, "deleted_at": null, "edited_at": null, "id": "00000000-0000-4000-8000-000000000007", "mentions": [], "my_reactions": [], "parent_id": null, "reactions": { "check": [], "eyes": [], "heart": [], "party": [], "question": [], "thumbs_up": [] }, "task_id": "00000000-0000-4000-8000-000000000005" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a task comment", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/history": { "get": { "description": "change sets from the operation log, oldest first; `?before=\u003cts\u003e\u0026limit=\u003c1-200\u003e` pages backwards; see [Trash and history](https://open-todo.app/docs/api/#trash-and-history)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTasksByIdHistory", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "before": 1, "changeSets": [ { "changes": [ { "field": "example", "from": "example", "lost": false, "opId": "00000000-0000-4000-8000-000000000001", "to": "example" } ], "device": "example", "device_label": "example", "ts": 1794906000000, "userId": "00000000-0000-4000-8000-000000000001" } ], "entity": "example", "id": "00000000-0000-4000-8000-000000000001", "more": false }, "schema": { "properties": { "before": { "type": "number" }, "changeSets": { "items": { "properties": { "changes": { "items": { "properties": { "field": { "type": "string" }, "from": { "type": "string" }, "lost": { "type": "boolean" }, "opId": { "type": "string" }, "to": { "type": "string" } }, "type": "object" }, "type": "array" }, "device": { "type": "string" }, "device_label": { "type": "string" }, "ts": { "type": "number" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "entity": { "type": "string" }, "id": { "type": "string" }, "more": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get task history", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/note/append": { "post": { "description": "`{id?, text}` adds Markdown at the end of the note without replacing it → 201 `{entity, entity_id, append_id, body_version}`; see [Appending to a note](https://open-todo.app/docs/api/#appending-to-a-note); 409 `too_many_appends` past 100 waiting; `read` and `agent` tokens get 403 `insufficient_scope`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postTasksByIdNoteAppend", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "id": "00000000-0000-4000-8000-000000000001", "text": "example" }, "schema": { "properties": { "id": { "type": "string" }, "text": { "type": "string" } }, "required": [ "text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "append_id": "00000000-0000-4000-8000-000000000001", "body_version": "example", "entity": "example", "entity_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "append_id": { "type": "string" }, "body_version": { "type": "string" }, "entity": { "type": "string" }, "entity_id": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "201": { "content": { "application/json": { "example": { "append_id": "00000000-0000-4000-8000-000000000001", "body_version": "example", "entity": "example", "entity_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "append_id": { "type": "string" }, "body_version": { "type": "string" }, "entity": { "type": "string" }, "entity_id": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Task note append", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/occurrences": { "get": { "description": "a recurring task's current, projected and recorded occurrence dates; `from`, `to` (at most 366 days), see [A series' dates ahead](https://open-todo.app/docs/api/#a-series-dates-ahead)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTasksByIdOccurrences", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "capped": false, "occurrences": [ { "date": "2026-11-20", "due": "example", "record_id": "00000000-0000-4000-8000-000000000001", "series_id": "00000000-0000-4000-8000-000000000001", "state": "example", "time": "example", "tz": "Europe/Rome" } ], "rule": "example", "series_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "capped": { "type": "boolean" }, "occurrences": { "items": { "properties": { "date": { "type": "string" }, "due": { "type": "string" }, "record_id": { "type": "string" }, "series_id": { "type": "string" }, "state": { "type": "string" }, "time": { "type": "string" }, "tz": { "type": "string" } }, "type": "object" }, "type": "array" }, "rule": { "type": "string" }, "series_id": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List task occurrences", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/occurrences/{date}": { "patch": { "description": "move or edit one occurrence alone, with task fields (`due`, `title`, `priority`, `labels`, `estimate_minutes`, `description`, …) → its record", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "patchTasksByIdOccurrencesByDate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "date", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "title": "Water the plants and the herbs" } } }, "description": "The body's fields are not described yet; the example shows one." }, "responses": { "200": { "content": { "application/json": { "example": { "appends": [], "body_version": "0", "completed_at": null, "created_at": 1794906000122, "deleted_at": null, "due": { "date": "2026-11-27" }, "energy": null, "fields": {}, "id": "00000000-0000-4000-8000-000000000013", "occurrence_date": "2026-11-27", "origin": null, "position": 1794906000118, "priority": 4, "project_id": null, "recurrence": null, "rotation": [], "sector": null, "series_id": "00000000-0000-4000-8000-000000000014", "skipped": false, "title": "Water the plants and the herbs" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a task occurrence", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/occurrences/{date}/complete": { "post": { "description": "complete one occurrence alone, `{completed_at?}` → its record; see [One occurrence alone](https://open-todo.app/docs/api/#one-occurrence-alone)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postTasksByIdOccurrencesByDateComplete", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "date", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "appends": [], "body_version": "0", "completed_at": 1794906000132, "completed_by": "00000000-0000-4000-8000-000000000001", "created_at": 1794906000132, "deleted_at": null, "due": { "date": "2026-11-20" }, "energy": null, "fields": {}, "id": "00000000-0000-4000-8000-000000000016", "occurrence_date": "2026-11-20", "origin": null, "position": 1794906000118, "priority": 4, "project_id": null, "recurrence": null, "rotation": [], "sector": null, "series_id": "00000000-0000-4000-8000-000000000014", "skipped": false, "title": "Water the plants" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Task occurrence complete", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/occurrences/{date}/skip": { "post": { "description": "skip one occurrence → its record (the series for a plain series' current occurrence)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postTasksByIdOccurrencesByDateSkip", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "date", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "appends": [], "body_version": "0", "completed_at": 1794906000127, "completed_by": "00000000-0000-4000-8000-000000000001", "created_at": 1794906000127, "deleted_at": null, "due": { "date": "2026-12-04" }, "energy": null, "fields": {}, "id": "00000000-0000-4000-8000-000000000015", "occurrence_date": "2026-12-04", "origin": null, "position": 1794906000118, "priority": 4, "project_id": null, "recurrence": null, "rotation": [], "sector": null, "series_id": "00000000-0000-4000-8000-000000000014", "skipped": true, "title": "Water the plants" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Task occurrence skip", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/page": { "delete": { "description": "revoke → 204\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteTasksByIdPage", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete task page", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" }, "get": { "description": "the active page's status (never the secret or a key)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTasksByIdPage", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "createdBy": "example", "encrypted": false, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "includeMap": false, "label": "example", "lastOpenedAt": 1794906000000, "pendingReplies": 1, "publishedAt": 1794906000000, "replies": 1, "rights": "example", "snapshotAt": 1794906000000, "taskId": "00000000-0000-4000-8000-000000000001", "ticks": 1 }, "schema": { "properties": { "createdBy": { "type": "string" }, "encrypted": { "type": "boolean" }, "expiresAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "includeMap": { "type": "boolean" }, "label": { "type": [ "string", "null" ] }, "lastOpenedAt": { "type": [ "number", "null" ] }, "pendingReplies": { "type": "number" }, "publishedAt": { "type": "number" }, "replies": { "type": "number" }, "rights": { "type": "string" }, "snapshotAt": { "type": [ "number", "null" ] }, "taskId": { "type": "string" }, "ticks": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get task page", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" }, "post": { "description": "`{rights, label?, expiresInDays?, includeMap?, snapshot?, wrappedKey?}` → 201 the page with `link` (shown once), see [Task pages](https://open-todo.app/docs/api/#task-pages)\n\nRefuses read and agent tokens. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postTasksByIdPage", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "expiresInDays": 1, "includeMap": false, "label": "example", "rights": "example", "snapshot": "example", "wrappedKey": "example" }, "schema": { "properties": { "expiresInDays": { "type": [ "number", "null" ] }, "includeMap": { "type": [ "boolean", "null" ] }, "label": { "type": [ "string", "null" ] }, "rights": { "type": "string" }, "snapshot": { "type": "string" }, "wrappedKey": { "type": "string" } }, "required": [ "rights", "snapshot", "wrappedKey" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "encrypted": false, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "includeMap": false, "label": "example", "link": "example", "publishedAt": 1794906000000, "rights": "example", "taskId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "encrypted": { "type": "boolean" }, "expiresAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "includeMap": { "type": "boolean" }, "label": { "type": [ "string", "null" ] }, "link": { "type": "string" }, "publishedAt": { "type": "number" }, "rights": { "type": "string" }, "taskId": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Task page", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens.recent" } }, "/api/v1/tasks/{id}/page/replies": { "get": { "description": "pending encrypted replies `{replies:[{id, ciphertext, createdAt}]}`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTasksByIdPageReplies", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "replies": [ { "ciphertext": "example", "createdAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001" } ] }, "schema": { "properties": { "replies": { "items": { "properties": { "ciphertext": { "type": "string" }, "createdAt": { "type": "number" }, "id": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List task page replies", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/tasks/{id}/page/replies/{replyId}": { "delete": { "description": "confirm an imported reply → 204\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteTasksByIdPageRepliesByReplyId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "replyId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a task page reply", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/tasks/{id}/page/snapshot": { "put": { "description": "`{ciphertext, version, wrappedKey?}` → 200; an older `version` changes nothing\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "putTasksByIdPageSnapshot", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "ciphertext": "example", "version": 1, "wrappedKey": "example" }, "schema": { "properties": { "ciphertext": { "type": "string" }, "version": { "type": "number" }, "wrappedKey": { "type": "string" } }, "required": [ "ciphertext", "version", "wrappedKey" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "ok": true }, "schema": { "properties": { "ok": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update task page snapshot", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/tasks/{id}/purge": { "delete": { "description": "permanently delete an item that is in the Trash → `{purged:{tasks,projects,notes,reminders,sections,comments}}`; 409 `not_deleted` otherwise", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteTasksByIdPurge", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "purged": { "attachments": 1, "comments": 1, "fields": 1, "notes": 1, "orphans": 1, "projects": 1, "reminders": 1, "sections": 1, "tasks": 1, "timeEntries": 1 } }, "schema": { "properties": { "purged": { "properties": { "attachments": { "type": "number" }, "comments": { "type": "number" }, "fields": { "type": "number" }, "notes": { "type": "number" }, "orphans": { "type": "number" }, "projects": { "type": "number" }, "reminders": { "type": "number" }, "sections": { "type": "number" }, "tasks": { "type": "number" }, "timeEntries": { "type": "number" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete task purge", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/split": { "post": { "description": "change a recurring task from a later occurrence on, `{from, changes}` → the new series; see [This and following](https://open-todo.app/docs/api/#this-and-following)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postTasksByIdSplit", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "changes": { "title": "Study with Ada" }, "from": "2026-11-25" }, "schema": { "properties": { "changes": { "type": "object" }, "from": { "type": "string" } }, "required": [ "changes", "from" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "appends": [], "body_version": "0", "completed_at": null, "created_at": 1794906000141, "deleted_at": null, "due": { "date": "2026-11-25", "time": "18:00" }, "energy": null, "fields": {}, "id": "00000000-0000-4000-8000-000000000017", "origin": null, "position": 1794906000137, "priority": 4, "project_id": null, "recurrence": "every weekday", "rotation": [], "sector": null, "series_id": null, "skipped": false, "split_from": { "date": "2026-11-25", "series": "00000000-0000-4000-8000-000000000018" }, "title": "Study with Ada" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Task split", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tasks/{id}/time-entries": { "get": { "description": "one task's live time entries, newest first", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTasksByIdTimeEntries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "deviceId": "00000000-0000-4000-8000-000000000001", "endedAt": 1794906000000, "focus": { "mode": "example", "plannedEndAt": 1794906000000, "session": 1 }, "id": "00000000-0000-4000-8000-000000000001", "minutes": 1, "note": "example", "projectId": "00000000-0000-4000-8000-000000000001", "projectName": "Ada", "startedAt": 1794906000000, "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence", "userId": "00000000-0000-4000-8000-000000000001" } ], "nextCursor": "example", "serverTime": 1794906000000 }, "schema": { "properties": { "entries": { "items": { "properties": { "deviceId": { "type": "string" }, "endedAt": { "type": [ "number", "null" ] }, "focus": { "properties": { "mode": { "type": "string" }, "plannedEndAt": { "type": [ "number", "null" ] }, "session": { "type": "number" } }, "type": [ "object", "null" ] }, "id": { "type": "string" }, "minutes": { "type": "number" }, "note": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "projectName": { "type": "string" }, "startedAt": { "type": "number" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "nextCursor": { "type": "string" }, "serverTime": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List task time entries", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/themes/instance": { "get": { "description": "Signed in (read tokens too). Answers `{version, default: {light, dark}, themes: [{id, kind, doc}]}`: each default is `\"\"` (OpenTodo's), `builtin:\u003cid\u003e` or `instance:\u003cid\u003e`; each `doc` is a theme document (`docs/themes.md`) whose `id` is the server id. 401 `unauthorized` without a session or token", "externalDocs": { "url": "https://open-todo.app/docs/api/#server-themes" }, "operationId": "getThemesInstance", "responses": { "200": { "content": { "application/json": { "example": { "default": { "dark": "example", "light": "example" }, "themes": [ { "doc": "example", "id": "00000000-0000-4000-8000-000000000001", "kind": "example" } ], "version": 1 }, "schema": { "properties": { "default": { "properties": { "dark": { "type": "string" }, "light": { "type": "string" } }, "type": "object" }, "themes": { "items": { "properties": { "doc": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string" } }, "type": "object" }, "type": "array" }, "version": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get themes instance", "tags": [ "Server themes" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/time-entries": { "get": { "description": "time entries you can read, newest first; `task`, `from`, `to`, `tz`, `running`, `limit`, `cursor`, `format=csv`, see [Time entries](https://open-todo.app/docs/api/#time-entries)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTimeEntries", "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "deviceId": "00000000-0000-4000-8000-000000000001", "endedAt": 1794906000000, "focus": { "mode": "example", "plannedEndAt": 1794906000000, "session": 1 }, "id": "00000000-0000-4000-8000-000000000001", "minutes": 1, "note": "example", "projectId": "00000000-0000-4000-8000-000000000001", "projectName": "Ada", "startedAt": 1794906000000, "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence", "userId": "00000000-0000-4000-8000-000000000001" } ], "nextCursor": "example", "serverTime": 1794906000000 }, "schema": { "properties": { "entries": { "items": { "properties": { "deviceId": { "type": "string" }, "endedAt": { "type": [ "number", "null" ] }, "focus": { "properties": { "mode": { "type": "string" }, "plannedEndAt": { "type": [ "number", "null" ] }, "session": { "type": "number" } }, "type": [ "object", "null" ] }, "id": { "type": "string" }, "minutes": { "type": "number" }, "note": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "projectName": { "type": "string" }, "startedAt": { "type": "number" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "nextCursor": { "type": "string" }, "serverTime": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List time entries", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{taskId}` starts an entry (the running one ends at its start), or `{taskId, startedAt, endedAt, note?}` logs a closed one → 201", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postTimeEntries", "requestBody": { "content": { "application/json": { "example": { "endedAt": 1794906000000, "note": "example", "startedAt": 1794906000000, "taskId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "endedAt": { "type": [ "number", "null" ] }, "note": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "number", "null" ] }, "taskId": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "deviceId": "00000000-0000-4000-8000-000000000001", "endedAt": 1794906000000, "focus": { "mode": "example", "plannedEndAt": 1794906000000, "session": 1 }, "id": "00000000-0000-4000-8000-000000000001", "minutes": 1, "note": "example", "projectId": "00000000-0000-4000-8000-000000000001", "projectName": "Ada", "startedAt": 1794906000000, "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence", "userId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "deviceId": { "type": "string" }, "endedAt": { "type": [ "number", "null" ] }, "focus": { "properties": { "mode": { "type": "string" }, "plannedEndAt": { "type": [ "number", "null" ] }, "session": { "type": "number" } }, "type": [ "object", "null" ] }, "id": { "type": "string" }, "minutes": { "type": "number" }, "note": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "projectName": { "type": "string" }, "startedAt": { "type": "number" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "201": { "content": { "application/json": { "example": { "deviceId": "00000000-0000-4000-8000-000000000001", "endedAt": 1794906000000, "focus": { "mode": "example", "plannedEndAt": 1794906000000, "session": 1 }, "id": "00000000-0000-4000-8000-000000000001", "minutes": 1, "note": "example", "projectId": "00000000-0000-4000-8000-000000000001", "projectName": "Ada", "startedAt": 1794906000000, "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence", "userId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "deviceId": { "type": "string" }, "endedAt": { "type": [ "number", "null" ] }, "focus": { "properties": { "mode": { "type": "string" }, "plannedEndAt": { "type": [ "number", "null" ] }, "session": { "type": "number" } }, "type": [ "object", "null" ] }, "id": { "type": "string" }, "minutes": { "type": "number" }, "note": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "projectName": { "type": "string" }, "startedAt": { "type": "number" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a time entry", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/time-entries/running": { "get": { "description": "your own running entry with its Focus details, or `null`: `{entry, serverTime}`, see [The running entry](https://open-todo.app/docs/api/#the-running-entry)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getTimeEntriesRunning", "responses": { "200": { "content": { "application/json": { "example": { "entry": { "deviceId": "00000000-0000-4000-8000-000000000001", "endedAt": 1794906000000, "focus": { "mode": "example", "plannedEndAt": 1794906000000, "session": 1 }, "id": "00000000-0000-4000-8000-000000000001", "minutes": 1, "note": "example", "projectId": "00000000-0000-4000-8000-000000000001", "projectName": "Ada", "startedAt": 1794906000000, "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence", "userId": "00000000-0000-4000-8000-000000000001" }, "serverTime": 1794906000000 }, "schema": { "properties": { "entry": { "properties": { "deviceId": { "type": "string" }, "endedAt": { "type": [ "number", "null" ] }, "focus": { "properties": { "mode": { "type": "string" }, "plannedEndAt": { "type": [ "number", "null" ] }, "session": { "type": "number" } }, "type": [ "object", "null" ] }, "id": { "type": "string" }, "minutes": { "type": "number" }, "note": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "projectName": { "type": "string" }, "startedAt": { "type": "number" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" }, "userId": { "type": "string" } }, "type": [ "object", "null" ] }, "serverTime": { "type": "number" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get time entries running", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/time-entries/stop": { "post": { "description": "stop your running entry → the entry; 404 when none runs", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postTimeEntriesStop", "responses": { "200": { "content": { "application/json": { "example": { "deviceId": "00000000-0000-4000-8000-000000000001", "endedAt": 1794906000000, "focus": { "mode": "example", "plannedEndAt": 1794906000000, "session": 1 }, "id": "00000000-0000-4000-8000-000000000001", "minutes": 1, "note": "example", "projectId": "00000000-0000-4000-8000-000000000001", "projectName": "Ada", "startedAt": 1794906000000, "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence", "userId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "deviceId": { "type": "string" }, "endedAt": { "type": [ "number", "null" ] }, "focus": { "properties": { "mode": { "type": "string" }, "plannedEndAt": { "type": [ "number", "null" ] }, "session": { "type": "number" } }, "type": [ "object", "null" ] }, "id": { "type": "string" }, "minutes": { "type": "number" }, "note": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "projectName": { "type": "string" }, "startedAt": { "type": "number" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Time entries stop", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/time-entries/{id}": { "delete": { "description": "tombstone an entry (author, project admin or owner) → 204", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteTimeEntriesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a time entry", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`{startedAt?, endedAt?, note?}` → the entry", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "patchTimeEntriesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "endedAt": 1794906000000, "note": "example", "startedAt": 1794906000000, "taskId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "endedAt": { "type": [ "number", "null" ] }, "note": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "number", "null" ] }, "taskId": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "deviceId": "00000000-0000-4000-8000-000000000001", "endedAt": 1794906000000, "focus": { "mode": "example", "plannedEndAt": 1794906000000, "session": 1 }, "id": "00000000-0000-4000-8000-000000000001", "minutes": 1, "note": "example", "projectId": "00000000-0000-4000-8000-000000000001", "projectName": "Ada", "startedAt": 1794906000000, "taskId": "00000000-0000-4000-8000-000000000001", "taskTitle": "Buy paint for the fence", "userId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "deviceId": { "type": "string" }, "endedAt": { "type": [ "number", "null" ] }, "focus": { "properties": { "mode": { "type": "string" }, "plannedEndAt": { "type": [ "number", "null" ] }, "session": { "type": "number" } }, "type": [ "object", "null" ] }, "id": { "type": "string" }, "minutes": { "type": "number" }, "note": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "projectName": { "type": "string" }, "startedAt": { "type": "number" }, "taskId": { "type": "string" }, "taskTitle": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a time entry", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/tokens": { "get": { "description": "`{tokens:[{id,name,scope,createdAt,lastUsedAt}]}`; `lastUsedAt` is updated at most once a minute", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "getTokens", "responses": { "200": { "content": { "application/json": { "example": { "tokens": [ { "createdAt": 1794906000000, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "name": "Ada", "scope": "full", "workspaces": [ "example" ] } ] }, "schema": { "properties": { "tokens": { "items": { "properties": { "createdAt": { "type": "number" }, "expiresAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "scope": { "type": "string" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List tokens", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{name, scope?}` (`full` default, `read`, `agent` or `admin`) → 201 `{token, secret}` (secret shown once); another scope → 400 `invalid_input`; `admin` only from a session (a token gets 403 `session_required`)\n\nNeeds a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "postTokens", "requestBody": { "content": { "application/json": { "example": { "name": "Ada", "scope": "full", "workspaces": [ "example" ] }, "schema": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "required": [ "name", "scope" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "secret": "example-secret", "token": { "createdAt": 1794906000000, "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "lastUsedAt": 1794906000000, "name": "Ada", "scope": "full", "workspaces": [ "example" ] } }, "schema": { "properties": { "secret": { "type": "string" }, "token": { "properties": { "createdAt": { "type": "number" }, "expiresAt": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "scope": { "type": "string" }, "workspaces": { "items": { "type": "string" }, "type": "array" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a token", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in.credential.recent" } }, "/api/v1/tokens/{id}": { "delete": { "description": "204; deleting a connected AI app's access token also disconnects the app (its refresh token stops working, recorded as `mcp_oauth.disconnected`)", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "operationId": "deleteTokensById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a token", "tags": [ "Your account and credentials" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/trash/purge": { "post": { "description": "empty the Trash (every deleted task, project and note you may delete) → `{purged:{…}}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postTrashPurge", "responses": { "200": { "content": { "application/json": { "example": { "purged": { "attachments": 1, "comments": 1, "fields": 1, "notes": 1, "orphans": 1, "projects": 1, "reminders": 1, "sections": 1, "tasks": 1, "timeEntries": 1 } }, "schema": { "properties": { "purged": { "properties": { "attachments": { "type": "number" }, "comments": { "type": "number" }, "fields": { "type": "number" }, "notes": { "type": "number" }, "orphans": { "type": "number" }, "projects": { "type": "number" }, "reminders": { "type": "number" }, "sections": { "type": "number" }, "tasks": { "type": "number" }, "timeEntries": { "type": "number" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Trash purge", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/users": { "get": { "description": "`{users:[…]}`, see [User administration](https://open-todo.app/docs/api/#user-administration)\n\nThe owner and admins.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "getUsers", "responses": { "200": { "content": { "application/json": { "example": { "users": [ { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "lastLoginAt": 1794906000000, "name": "Ada", "role": "member", "status": "example" } ] }, "schema": { "properties": { "users": { "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "lastLoginAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List users", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "admins-only" } }, "/api/v1/users/{id}": { "delete": { "description": "`{confirmEmail}` → 204; deletes the account and its data\n\nThe owner and admins. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "deleteUsersById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "confirmEmail": "ada@example.com" }, "schema": { "properties": { "confirmEmail": { "type": "string" } }, "required": [ "confirmEmail" ], "type": "object" } } }, "required": false }, "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a user", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "admins-only.credential.recent" } }, "/api/v1/users/{id}/avatar": { "get": { "externalDocs": { "url": "https://open-todo.app/docs/api/#profile" }, "operationId": "getUsersByIdAvatar", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get user avatar", "tags": [ "Profile" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/users/{id}/deactivate": { "post": { "description": "→ `{user}`; revokes sessions, tokens, pending invitations and reset links\n\nThe owner and admins. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postUsersByIdDeactivate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "lastLoginAt": 1794906000000, "name": "Ada", "role": "member", "status": "example" } }, "schema": { "properties": { "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "lastLoginAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "User deactivate", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "admins-only.credential.recent" } }, "/api/v1/users/{id}/password-reset": { "post": { "description": "`{expiresInHours?, send?}` → 201 `{expiresAt, link}` (link shown once), or with `send: true` 201 `{expiresAt, sent: true}` and the link mailed to the account\n\nThe owner and admins. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postUsersByIdPasswordReset", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "expiresInHours": 1, "send": false }, "schema": { "properties": { "expiresInHours": { "type": [ "number", "null" ] }, "send": { "type": "boolean" } }, "required": [ "send" ], "type": "object" } } }, "required": false }, "responses": { "201": { "content": { "application/json": { "example": { "expiresAt": 1794906000000, "link": "example", "sent": false }, "schema": { "properties": { "expiresAt": { "type": "number" }, "link": { "type": "string" }, "sent": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "User password reset", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "admins-only.credential.recent" } }, "/api/v1/users/{id}/reactivate": { "post": { "description": "→ `{user}`\n\nThe owner and admins. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postUsersByIdReactivate", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "lastLoginAt": 1794906000000, "name": "Ada", "role": "member", "status": "example" } }, "schema": { "properties": { "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "lastLoginAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "User reactivate", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "admins-only.credential.recent" } }, "/api/v1/users/{id}/role": { "put": { "description": "`{role: \"admin\"|\"member\"}` → `{user}`\n\nThe owner and admins. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "putUsersByIdRole", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "role": "member" }, "schema": { "properties": { "role": { "type": "string" } }, "required": [ "role" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "lastLoginAt": 1794906000000, "name": "Ada", "role": "member", "status": "example" } }, "schema": { "properties": { "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "lastLoginAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update user role", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "admins-only.credential.recent" } }, "/api/v1/users/{id}/transfer-ownership": { "post": { "description": "`{password}` → `{user}`\n\nThe owner and admins. Needs a session or an admin token; full tokens are refused. Needs a recently confirmed session or second factor.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "operationId": "postUsersByIdTransferOwnership", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "password": "correct horse battery staple" }, "schema": { "properties": { "password": { "type": "string" } }, "required": [ "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "user": { "createdAt": 1794906000000, "email": "ada@example.com", "id": "00000000-0000-4000-8000-000000000001", "lastLoginAt": 1794906000000, "name": "Ada", "role": "member", "status": "example" } }, "schema": { "properties": { "user": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "id": { "type": "string" }, "lastLoginAt": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "User transfer ownership", "tags": [ "Administration (owner and admins)" ], "x-opentodo-policy": "admins-only.credential.recent" } }, "/api/v1/views": { "get": { "description": "same shape for saved views, see [View fields](https://open-todo.app/docs/api/#view-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getViews", "responses": { "200": { "content": { "application/json": { "example": { "views": [ { "card_notes": false, "color": "#3b82f6", "created_at": 1794906000000, "deleted_at": 1794906000000, "group_by": "example", "hidden_props": [ "example" ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "layout": "example", "manual_order": [ "example" ], "name": "Ada", "on_drop": null, "panels": [ "example" ], "pinned": false, "position": 1, "query": "example", "row_layout": "example", "show_completed": false, "sort_by": "example", "sort_dir": "example", "subtasks": "example", "workspace_id": "00000000-0000-4000-8000-000000000001" } ] }, "schema": { "properties": { "views": { "items": { "$ref": "#/components/schemas/View" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List views", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "same shape for saved views, see [View fields](https://open-todo.app/docs/api/#view-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "postViews", "requestBody": { "content": { "application/json": { "example": { "card_notes": false, "color": "#3b82f6", "created_at": 1794906000000, "deleted_at": 1794906000000, "group_by": "example", "hidden_props": [ "example" ], "icon": "example", "kind": "example", "layout": "example", "manual_order": [ "example" ], "name": "Ada", "on_drop": null, "panels": [ "example" ], "pinned": false, "position": 1, "query": "example", "row_layout": "example", "show_completed": false, "sort_by": "example", "sort_dir": "example", "subtasks": "example", "workspace_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "card_notes": { "type": "boolean" }, "color": { "type": "string" }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "group_by": { "type": "string" }, "hidden_props": { "items": { "type": "string" }, "type": "array" }, "icon": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "layout": { "type": "string" }, "manual_order": { "description": "Ids in their display order.", "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" }, "on_drop": { "description": "A section's on-drop rule (docs/sync.md)." }, "panels": { "items": { "type": "string" }, "type": "array" }, "pinned": { "type": "boolean" }, "position": { "type": "number" }, "query": { "type": "string" }, "row_layout": { "type": "string" }, "show_completed": { "type": "boolean" }, "sort_by": { "type": "string" }, "sort_dir": { "type": "string" }, "subtasks": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "card_notes": false, "color": "#3b82f6", "created_at": 1794906000000, "deleted_at": 1794906000000, "group_by": "example", "hidden_props": [ "example" ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "layout": "example", "manual_order": [ "example" ], "name": "Ada", "on_drop": null, "panels": [ "example" ], "pinned": false, "position": 1, "query": "example", "row_layout": "example", "show_completed": false, "sort_by": "example", "sort_dir": "example", "subtasks": "example", "workspace_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "$ref": "#/components/schemas/View" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a view", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/views/{id}": { "delete": { "description": "same shape for saved views, see [View fields](https://open-todo.app/docs/api/#view-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "deleteViewsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a view", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "same shape for saved views, see [View fields](https://open-todo.app/docs/api/#view-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "getViewsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "card_notes": false, "color": "#3b82f6", "created_at": 1794906000000, "deleted_at": 1794906000000, "group_by": "example", "hidden_props": [ "example" ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "layout": "example", "manual_order": [ "example" ], "name": "Ada", "on_drop": null, "panels": [ "example" ], "pinned": false, "position": 1, "query": "example", "row_layout": "example", "show_completed": false, "sort_by": "example", "sort_dir": "example", "subtasks": "example", "workspace_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "$ref": "#/components/schemas/View" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a view", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "same shape for saved views, see [View fields](https://open-todo.app/docs/api/#view-fields)", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "operationId": "patchViewsById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "card_notes": false, "color": "#3b82f6", "created_at": 1794906000000, "deleted_at": 1794906000000, "group_by": "example", "hidden_props": [ "example" ], "icon": "example", "kind": "example", "layout": "example", "manual_order": [ "example" ], "name": "Ada", "on_drop": null, "panels": [ "example" ], "pinned": false, "position": 1, "query": "example", "row_layout": "example", "show_completed": false, "sort_by": "example", "sort_dir": "example", "subtasks": "example", "workspace_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "card_notes": { "type": "boolean" }, "color": { "type": "string" }, "created_at": { "type": "number" }, "deleted_at": { "type": [ "number", "null" ] }, "group_by": { "type": "string" }, "hidden_props": { "items": { "type": "string" }, "type": "array" }, "icon": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "layout": { "type": "string" }, "manual_order": { "description": "Ids in their display order.", "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" }, "on_drop": { "description": "A section's on-drop rule (docs/sync.md)." }, "panels": { "items": { "type": "string" }, "type": "array" }, "pinned": { "type": "boolean" }, "position": { "type": "number" }, "query": { "type": "string" }, "row_layout": { "type": "string" }, "show_completed": { "type": "boolean" }, "sort_by": { "type": "string" }, "sort_dir": { "type": "string" }, "subtasks": { "type": "string" }, "workspace_id": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "card_notes": false, "color": "#3b82f6", "created_at": 1794906000000, "deleted_at": 1794906000000, "group_by": "example", "hidden_props": [ "example" ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "kind": "example", "layout": "example", "manual_order": [ "example" ], "name": "Ada", "on_drop": null, "panels": [ "example" ], "pinned": false, "position": 1, "query": "example", "row_layout": "example", "show_completed": false, "sort_by": "example", "sort_dir": "example", "subtasks": "example", "workspace_id": "00000000-0000-4000-8000-000000000001" }, "schema": { "$ref": "#/components/schemas/View" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a view", "tags": [ "Tasks, projects and other synced data" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/voice/transcribe": { "post": { "description": "the raw audio (`Content-Type` `audio/webm`, `audio/ogg`, `audio/mp4` or `audio/wav`; at most 5 MB and 60 seconds, `?seconds=` as recorded), optional `?language=de` → `{text}`; 30 phrases a minute per account (`429 rate_limited`), `409 stt_not_configured`, `502 stt_unavailable`\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#speech-to-text" }, "operationId": "postVoiceTranscribe", "responses": { "200": { "content": { "application/json": { "example": { "text": "example" }, "schema": { "properties": { "text": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Voice transcribe", "tags": [ "Speech to text" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/webhooks": { "get": { "description": "`{webhooks:[…], events:[…]}`, see [Webhooks](https://open-todo.app/docs/api/#webhooks)", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "getWebhooks", "responses": { "200": { "content": { "application/json": { "example": { "events": [ "example" ], "webhooks": [ { "consecutiveFailures": 1, "createdAt": 1794906000000, "disabledReason": "example", "enabled": false, "events": [ "example" ], "id": "00000000-0000-4000-8000-000000000001", "projectId": "00000000-0000-4000-8000-000000000001", "secret": "example-secret", "updatedAt": 1794906000000, "url": "https://todo.example.com/" } ] }, "schema": { "properties": { "events": { "items": { "type": "string" }, "type": "array" }, "webhooks": { "items": { "properties": { "consecutiveFailures": { "type": "number" }, "createdAt": { "type": "number" }, "disabledReason": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "events": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "secret": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List webhooks", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{url, events, projectId?, enabled?}` → 201 `{webhook}` (includes `secret`, shown once)", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "postWebhooks", "responses": { "201": { "content": { "application/json": { "example": { "webhook": { "consecutiveFailures": 1, "createdAt": 1794906000000, "disabledReason": "example", "enabled": false, "events": [ "example" ], "id": "00000000-0000-4000-8000-000000000001", "projectId": "00000000-0000-4000-8000-000000000001", "secret": "example-secret", "updatedAt": 1794906000000, "url": "https://todo.example.com/" } }, "schema": { "properties": { "webhook": { "properties": { "consecutiveFailures": { "type": "number" }, "createdAt": { "type": "number" }, "disabledReason": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "events": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "secret": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a webhook", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/webhooks/{id}": { "delete": { "description": "delete with its delivery log → 204", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "deleteWebhooksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a webhook", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" }, "get": { "description": "`{webhook}` (never the secret)", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "getWebhooksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "webhook": { "consecutiveFailures": 1, "createdAt": 1794906000000, "disabledReason": "example", "enabled": false, "events": [ "example" ], "id": "00000000-0000-4000-8000-000000000001", "projectId": "00000000-0000-4000-8000-000000000001", "secret": "example-secret", "updatedAt": 1794906000000, "url": "https://todo.example.com/" } }, "schema": { "properties": { "webhook": { "properties": { "consecutiveFailures": { "type": "number" }, "createdAt": { "type": "number" }, "disabledReason": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "events": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "secret": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a webhook", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "partial `{url?, events?, projectId?, enabled?}` → `{webhook}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "patchWebhooksById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "webhook": { "consecutiveFailures": 1, "createdAt": 1794906000000, "disabledReason": "example", "enabled": false, "events": [ "example" ], "id": "00000000-0000-4000-8000-000000000001", "projectId": "00000000-0000-4000-8000-000000000001", "secret": "example-secret", "updatedAt": 1794906000000, "url": "https://todo.example.com/" } }, "schema": { "properties": { "webhook": { "properties": { "consecutiveFailures": { "type": "number" }, "createdAt": { "type": "number" }, "disabledReason": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "events": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "secret": { "type": "string" }, "updatedAt": { "type": "number" }, "url": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a webhook", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/webhooks/{id}/deliveries": { "get": { "description": "`{deliveries:[…]}`, newest 100", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "getWebhooksByIdDeliveries", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "deliveries": [ { "attempts": 1, "createdAt": 1794906000000, "deliveredAt": 1794906000000, "durationMs": 1, "error": "example", "event": "example", "id": "00000000-0000-4000-8000-000000000001", "nextAttemptAt": 1794906000000, "responseExcerpt": "example", "status": "example", "statusCode": 1, "webhookId": "00000000-0000-4000-8000-000000000001" } ] }, "schema": { "properties": { "deliveries": { "items": { "properties": { "attempts": { "type": "number" }, "createdAt": { "type": "number" }, "deliveredAt": { "type": [ "number", "null" ] }, "durationMs": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "event": { "type": "string" }, "id": { "type": "string" }, "nextAttemptAt": { "type": [ "number", "null" ] }, "responseExcerpt": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "statusCode": { "type": [ "number", "null" ] }, "webhookId": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List webhook deliveries", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/webhooks/{id}/deliveries/{did}/redeliver": { "post": { "description": "queue the same body with a new id → 202 `{delivery}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "postWebhooksByIdDeliveriesByDidRedeliver", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "did", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "example": { "delivery": { "attempts": 1, "createdAt": 1794906000000, "deliveredAt": 1794906000000, "durationMs": 1, "error": "example", "event": "example", "id": "00000000-0000-4000-8000-000000000001", "nextAttemptAt": 1794906000000, "responseExcerpt": "example", "status": "example", "statusCode": 1, "webhookId": "00000000-0000-4000-8000-000000000001" } }, "schema": { "properties": { "delivery": { "properties": { "attempts": { "type": "number" }, "createdAt": { "type": "number" }, "deliveredAt": { "type": [ "number", "null" ] }, "durationMs": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "event": { "type": "string" }, "id": { "type": "string" }, "nextAttemptAt": { "type": [ "number", "null" ] }, "responseExcerpt": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "statusCode": { "type": [ "number", "null" ] }, "webhookId": { "type": "string" } }, "type": [ "object", "null" ] } }, "type": "object" } } }, "description": "Accepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Webhook delivery redeliver", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/webhooks/{id}/test": { "post": { "description": "send a `ping` now → `{ok, delivery}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "operationId": "postWebhooksByIdTest", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "delivery": { "attempts": 1, "createdAt": 1794906000000, "deliveredAt": 1794906000000, "durationMs": 1, "error": "example", "event": "example", "id": "00000000-0000-4000-8000-000000000001", "nextAttemptAt": 1794906000000, "responseExcerpt": "example", "status": "example", "statusCode": 1, "webhookId": "00000000-0000-4000-8000-000000000001" }, "ok": true }, "schema": { "properties": { "delivery": { "properties": { "attempts": { "type": "number" }, "createdAt": { "type": "number" }, "deliveredAt": { "type": [ "number", "null" ] }, "durationMs": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "event": { "type": "string" }, "id": { "type": "string" }, "nextAttemptAt": { "type": [ "number", "null" ] }, "responseExcerpt": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "statusCode": { "type": [ "number", "null" ] }, "webhookId": { "type": "string" } }, "type": [ "object", "null" ] }, "ok": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Webhook test", "tags": [ "Integrations" ], "x-opentodo-policy": "signed-in" } }, "/api/v1/workspace-invites/{token}": { "get": { "description": "No authentication.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "getWorkspaceInvitesByToken", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "alreadyMember": false, "canCreateAccount": false, "email": "ada@example.com", "expiresAt": 1794906000000, "inviterName": "Ada", "role": "member", "workspaceName": "Ada" }, "schema": { "properties": { "alreadyMember": { "type": "boolean" }, "canCreateAccount": { "type": "boolean" }, "email": { "type": [ "string", "null" ] }, "expiresAt": { "type": "number" }, "inviterName": { "type": "string" }, "role": { "type": "string" }, "workspaceName": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "4XX": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Get a workspace invite", "tags": [ "Workspaces" ], "x-opentodo-policy": "public" } }, "/api/v1/workspace-invites/{token}/accept": { "post": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "postWorkspaceInvitesByTokenAccept", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "role": "member", "workspaceId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "role": { "type": "string" }, "workspaceId": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Workspace invite accept", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces": { "get": { "description": "→ `{workspaces: [workspace]}`", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "getWorkspaces", "responses": { "200": { "content": { "application/json": { "example": { "workspaces": [ { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "role": "member" } ] }, "schema": { "properties": { "workspaces": { "items": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List workspaces", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`{name, icon?, color?}` → 201 workspace; 20 owned per account (409 `limit_reached`)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "postWorkspaces", "requestBody": { "content": { "application/json": { "example": { "color": "#3b82f6", "icon": "example", "name": "Ada" }, "schema": { "properties": { "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a workspace", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}": { "delete": { "description": "`PATCH {name?, icon?, color?}` (owner, admin); `DELETE` (owner) → 204, 409 `workspace_not_empty` while it has projects or other members\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "deleteWorkspacesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a workspace", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" }, "get": { "description": "`PATCH {name?, icon?, color?}` (owner, admin); `DELETE` (owner) → 204, 409 `workspace_not_empty` while it has projects or other members", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "getWorkspacesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Get a workspace", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in" }, "patch": { "description": "`PATCH {name?, icon?, color?}` (owner, admin); `DELETE` (owner) → 204, 409 `workspace_not_empty` while it has projects or other members\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "patchWorkspacesById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "color": "#3b82f6", "icon": "example", "name": "Ada" }, "schema": { "properties": { "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a workspace", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}/groups": { "get": { "description": "`POST {name}` → 201 `{id, name, members}`; names unique ignoring case (409 `group_exists`), 50 groups", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "getWorkspacesByIdGroups", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ] }, "schema": { "properties": { "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List workspace groups", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`POST {name}` → 201 `{id, name, members}`; names unique ignoring case (409 `group_exists`), 50 groups\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "postWorkspacesByIdGroups", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Ada" }, "schema": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" }, "schema": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a workspace group", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}/groups/{groupId}": { "delete": { "description": "rename `{name}`, delete\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "deleteWorkspacesByIdGroupsByGroupId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "groupId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a workspace group", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" }, "patch": { "description": "rename `{name}`, delete\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "patchWorkspacesByIdGroupsByGroupId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "groupId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "name": "Ada" }, "schema": { "properties": { "name": { "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a workspace group", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}/groups/{groupId}/members/{userId}": { "delete": { "description": "100 members per group; only workspace members (409 `not_in_workspace`)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "deleteWorkspacesByIdGroupsByGroupIdMembersByUserId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "groupId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a workspace group member", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" }, "put": { "description": "100 members per group; only workspace members (409 `not_in_workspace`)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "putWorkspacesByIdGroupsByGroupIdMembersByUserId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "groupId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Replace a workspace group member", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}/invites": { "get": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "getWorkspacesByIdInvites", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "invites": [ { "createdAt": 1794906000000, "createdBy": "example", "createdByName": "Ada", "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "role": "member", "workspaceId": "00000000-0000-4000-8000-000000000001" } ] }, "schema": { "properties": { "invites": { "items": { "properties": { "createdAt": { "type": "number" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "role": { "type": "string" }, "workspaceId": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List workspace invites", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" }, "post": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "postWorkspacesByIdInvites", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "email": "ada@example.com", "expiresInHours": 1, "role": "member", "send": false }, "schema": { "properties": { "email": { "type": "string" }, "expiresInHours": { "type": [ "number", "null" ] }, "role": { "type": "string" }, "send": { "type": "boolean" } }, "required": [ "email", "role", "send" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "invite": { "createdAt": 1794906000000, "createdBy": "example", "createdByName": "Ada", "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "role": "member", "workspaceId": "00000000-0000-4000-8000-000000000001" }, "link": "example", "newAccounts": false, "sent": false }, "schema": { "properties": { "invite": { "properties": { "createdAt": { "type": "number" }, "createdBy": { "type": "string" }, "createdByName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "role": { "type": "string" }, "workspaceId": { "type": "string" } }, "type": [ "object", "null" ] }, "link": { "type": "string" }, "newAccounts": { "type": "boolean" }, "sent": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a workspace invite", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}/invites/{inviteId}": { "delete": { "description": "Refuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "deleteWorkspacesByIdInvitesByInviteId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "inviteId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a workspace invite", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}/leave": { "post": { "description": "leave → 204 (the owner: 409 `owner_must_transfer`); transfer `{userId}` (owner, to a member) → 200\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "postWorkspacesByIdLeave", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Workspace leave", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}/member-invitations/{invitationId}": { "delete": { "description": "cancel an open invitation (owner, admin) → 204\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "deleteWorkspacesByIdMemberInvitationsByInvitationId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "invitationId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a workspace member invitation", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}/members": { "get": { "description": "`POST {email, role: member|admin}` (admins add members) → 201 when the account already shares a project or workspace with you, otherwise 202 `{pending: true}` with or without an account ([invitations](https://open-todo.app/docs/api/#membership-invitations)); `GET` → 200 `{members, pending?}` (`pending` for the owner and admins)", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "getWorkspacesByIdMembers", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ] }, "schema": { "properties": { "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "List workspace members", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in" }, "post": { "description": "`POST {email, role: member|admin}` (admins add members) → 201 when the account already shares a project or workspace with you, otherwise 202 `{pending: true}` with or without an account ([invitations](https://open-todo.app/docs/api/#membership-invitations)); `GET` → 200 `{members, pending?}` (`pending` for the owner and admins)\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "postWorkspacesByIdMembers", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "email": "ada@example.com", "role": "member" }, "schema": { "properties": { "email": { "type": "string" }, "role": { "type": "string" } }, "required": [ "email", "role" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "anyOf": [ { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, { "type": "boolean" } ] }, "role": { "type": "string" } }, "type": "object" } } }, "description": "Accepted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Create a workspace member", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}/members/{userId}": { "delete": { "description": "`{role}`; removing a member also removes every grant they hold on the workspace's projects\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "deleteWorkspacesByIdMembersByUserId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Delete a workspace member", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" }, "patch": { "description": "`{role}`; removing a member also removes every grant they hold on the workspace's projects\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "patchWorkspacesByIdMembersByUserId", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "role": "member" }, "schema": { "properties": { "role": { "type": "string" } }, "required": [ "role" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Update a workspace member", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } }, "/api/v1/workspaces/{id}/transfer": { "post": { "description": "leave → 204 (the owner: 409 `owner_must_transfer`); transfer `{userId}` (owner, to a member) → 200\n\nRefuses read and agent tokens.", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "operationId": "postWorkspacesByIdTransfer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "userId": "00000000-0000-4000-8000-000000000001" }, "schema": { "properties": { "userId": { "type": "string" } }, "required": [ "userId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "color": "#3b82f6", "default": false, "groups": [ { "id": "00000000-0000-4000-8000-000000000001", "members": [ "example" ], "name": "Ada" } ], "icon": "example", "id": "00000000-0000-4000-8000-000000000001", "members": [ { "name": "Ada", "role": "member", "userId": "00000000-0000-4000-8000-000000000001" } ], "name": "Ada", "ownerId": "00000000-0000-4000-8000-000000000001", "pending": [ { "createdAt": 1794906000000, "email": "ada@example.com", "expiresAt": 1794906000000, "id": "00000000-0000-4000-8000-000000000001", "invitedBy": "example", "role": "member" } ], "role": "member" }, "schema": { "properties": { "color": { "type": "string" }, "default": { "type": "boolean" }, "groups": { "items": { "properties": { "id": { "type": "string" }, "members": { "items": { "type": "string" }, "type": "array" }, "name": { "type": "string" } }, "type": "object" }, "type": "array" }, "icon": { "type": "string" }, "id": { "type": "string" }, "members": { "items": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "userId": { "type": "string" } }, "type": "object" }, "type": "array" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "pending": { "description": "The open invitations, shown to the owner and admins.", "items": { "properties": { "createdAt": { "type": "number" }, "email": { "type": "string" }, "expiresAt": { "type": "number" }, "id": { "type": "string" }, "invitedBy": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "role": { "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "4XX": { "$ref": "#/components/responses/Error" } }, "summary": "Workspace transfer", "tags": [ "Workspaces" ], "x-opentodo-policy": "signed-in.full-tokens" } } }, "security": [ { "bearer": [] }, { "session": [] } ], "servers": [ { "description": "Your OpenTodo server", "url": "https://{host}", "variables": { "host": { "default": "demo.open-todo.app", "description": "The server's host name, for example todo.example.com" } } } ], "tags": [ { "description": "The Administration (owner and admins) routes.", "externalDocs": { "url": "https://open-todo.app/docs/api/#administration-owner-and-admins" }, "name": "Administration (owner and admins)" }, { "description": "An `agent` token may write through REST on this fixed list of routes only, and only while the owner's **Assistants may make changes** and the user's **Changes to my tasks** are both on:", "externalDocs": { "url": "https://open-todo.app/docs/api/#agent-tokens" }, "name": "Agent tokens" }, { "description": "The OpenTodo app signs in through the system's authentication sheet (`ASWebAuthenticationSession` on iOS, a Custom Tab on Android) with an authorization code and PKCE ([RFC 7636](https://www.rfc-editor.org/rfc/rfc7636), S256 only). The sheet shares the browser's cookies and passkeys, so every sign-in method of the web app works, and a browser that is already signed in only confirms. It does not depend on the owner's AI assistants (MCP) switch. A server that has it says so in `GET /api/v1/health` with `\"app_sign_in\": true`.", "externalDocs": { "url": "https://open-todo.app/docs/api/#app-sign-in" }, "name": "App sign-in" }, { "description": "Attachments (OpenSpec `attachments`) are files or links on a task or one of its comments. Their metadata is an entity in the operation log (`attachment`, fields in [docs/sync.md](https://open-todo.app/docs/sync/#attachments)); the bytes are files moved with these routes. Every route answers `404 not_found` for an attachment or task you cannot read. Uploads need a session or a full token (`read` tokens get `403`) and are limited to 120 per hour per account (`429 rate_limited`).", "externalDocs": { "url": "https://open-todo.app/docs/api/#attachments" }, "name": "Attachments" }, { "description": "Rules (OpenSpec `automation-rules`; guide: [automations.md](https://open-todo.app/docs/automations/)) are the synced entity `rule`, personal like a label: `name` (content, encrypted for an encrypted account), `enabled`, `trigger`, `condition`, `actions`, `steps` (each one whole value), `position`, `created_at`, `deleted_at`. The app calls a rule a **routine**: a rule with `steps: null` is one Change tasks step with its `actions`; a routine of more than one step keeps them in `steps` (OpenSpec `routines-engine`, see [Routines](https://open-todo.app/docs/api/#routines)). Devices write them through `/api/v1/sync`; the REST routes below add id checks. The server runs them; their state (run log, watermarks, pauses) is server data, never operations. Every route answers `403 demo_restricted` on the public demo.", "externalDocs": { "url": "https://open-todo.app/docs/api/#automation-rules" }, "name": "Automation rules" }, { "description": "Other calendars shown in Day and Week, and your tasks as a calendar that calendar apps subscribe to (OpenSpec `calendar-feeds`). Everything here answers `404 feeds_disabled` while the owner's switch is off, and `403 demo_restricted` on the public demo. Read and agent tokens may use the `GET` routes only (`403 insufficient_scope` otherwise).", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-feeds" }, "name": "Calendar feeds" }, { "description": "Frames (OpenSpec `calendar-frames`; guide: [frames.md](https://open-todo.app/docs/frames/)) are the synced entity `frame`, personal like a rule: recurring background windows on the Day and Week grid such as \"Deep work\" on weekdays from 09:00 to 11:00. Fields: `title` (content, encrypted for an encrypted account), `weekdays` (ISO weekdays as a sorted comma list, `\"1,2,3,4,5\"`; 1 is Monday, 7 Sunday), `start` and `end` (floating wall times `HH:MM`, end after start), `color` (hex), `source` (the planning source: `\"\"`, `project:\u003cid\u003e`, `label:\u003cid\u003e` or `view:\u003cid\u003e`), `from_date` and `until_date` (optional first and last day, `YYYY-MM-DD`), `position`, `created_at`, `deleted_at`. Occurrences are derived on the device and never stored. Devices write frames through `/api/v1/sync`; the REST routes below add the checks.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-frames" }, "name": "Calendar frames" }, { "description": "Slots (OpenSpec `calendar-slots`; guide: [slots.md](https://open-todo.app/docs/slots/)) are the synced entity `slot`, personal like a frame: one block on the Day and Week grid that holds a checklist of small tasks, such as \"Admin\" on Wednesday from 16:00 for 45 minutes. Fields: `title` (content, encrypted for an encrypted account; empty reads as \"Slot\"), `date` (`YYYY-MM-DD`), `start` (floating wall time `HH:MM`), `minutes` (15 to 480 in steps of 15; the op log accepts 1 to 1440), `task_ids` (ordered task ids, at most 20, written as one whole list), `color` (hex), `created_at`, `deleted_at`. No field is added to tasks: a task is in a slot when the slot lists it and the task is open and due on the slot's date without a time (or has no due date). Devices write slots through `/api/v1/sync`; the REST routes below add the checks.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-slots" }, "name": "Calendar slots" }, { "description": "The account's own calendar (any CalDAV server with an app password, Google Calendar, or Outlook.com and Microsoft 365 through Microsoft Graph) receives its dated tasks as events, and changes made there come back to the tasks (OpenSpec change `calendar-two-way`; guide: [calendar-sync.md](https://open-todo.app/docs/calendar-sync/)). Every `/api/v1/calendar-sync` route answers `404 calendar_sync_disabled` while the owner's switch is off, and these routes and the settings answer `403 demo_restricted` on the public demo before authentication. Read and agent tokens may use the `GET` routes only. Connections are server data: never operations, never synced or exported; passwords, Google and Microsoft refresh tokens and the Google and Microsoft client secrets live in `\u003cdata\u003e/secrets/calendar-sync.json` only and are never returned.", "externalDocs": { "url": "https://open-todo.app/docs/api/#calendar-sync" }, "name": "Calendar sync" }, { "description": "For an account with end-to-end encryption, a device the user opted in answers the decrypt and encrypt steps of [MCP tool calls](https://open-todo.app/docs/mcp/#encrypted-accounts) (OpenSpec `mcp-device-relay`). The server never holds the key; relayed text exists only in memory during the call and is never stored, logged or audited. Session cookies only (no API tokens); every route is refused on a demo instance.", "externalDocs": { "url": "https://open-todo.app/docs/api/#device-relay" }, "name": "Device relay" }, { "description": "The Health and authentication routes.", "externalDocs": { "url": "https://open-todo.app/docs/api/#health-and-authentication" }, "name": "Health and authentication" }, { "description": "A tenant of a host (see [host mode](https://open-todo.app/docs/self-hosting/host-mode/)) answers like any server, with these differences. `GET /api/v1/auth/status` adds `\"hosted\": true`. Settings that belong to the operator answer `403 host_managed` before authentication: `/api/v1/settings/smtp*`, `/api/v1/settings/oidc*` and `/api/v1/backups*` for every method, and writes to `/api/v1/settings/mcp`, `/api/v1/settings/assistant*`, `/api/v1/settings/webhooks` and `/api/v1/settings/attachments`.", "externalDocs": { "url": "https://open-todo.app/docs/api/#hosted-servers" }, "name": "Hosted servers" }, { "description": "The [in-app assistant](https://open-todo.app/docs/assistant/) (OpenSpec `in-app-assistant`). Every route requires authentication. Settings, consent and usage are server state, never ops; conversations exist only on the device. Keys are write-only: no route ever returns one.", "externalDocs": { "url": "https://open-todo.app/docs/api/#in-app-assistant" }, "name": "In-app assistant" }, { "description": "The owner gives the server a name and a logo (**Settings → Server → Branding**). `GET /api/v1/auth/status` carries `\"branding\": {\"name\": \"Acme Tasks\", \"logoVersion\": 2}` for everyone (`name` empty and `logoVersion` 0 without branding), and the page and the web app manifest are served with the name in the title and the logo as favicon, touch icon and app icons, so an installed app shows them.", "externalDocs": { "url": "https://open-todo.app/docs/api/#instance-branding" }, "name": "Instance branding" }, { "description": "The Integrations routes.", "externalDocs": { "url": "https://open-todo.app/docs/api/#integrations" }, "name": "Integrations" }, { "description": "GitHub and GitLab issues assigned to the account become tasks that follow the issue (OpenSpec `issue-connections`; guide: [issue-import.md](https://open-todo.app/docs/issue-import/)). Every `/api/v1/issues` route answers `404 issues_disabled` while the owner's switch is off, and these routes and the setting answer `403 demo_restricted` on the public demo before authentication. Read and agent tokens may use the `GET` routes only (`403 insufficient_scope` otherwise). Connections are server data: never operations, never synced or exported.", "externalDocs": { "url": "https://open-todo.app/docs/api/#issue-connections" }, "name": "Issue connections" }, { "description": "The owner of a project, or an admin of a shared one, can keep it and its sub-projects away from every AI assistant surface: MCP (whatever the token's scope), the agent content routes above and the in-app assistant then act as if it did not exist. Ordinary REST with a session, a `full` or an `admin` token, sync, CalDAV, feeds and the export are unaffected. It is server access state like membership: never an operation, never exported.", "externalDocs": { "url": "https://open-todo.app/docs/api/#keeping-a-project-away-from-assistants" }, "name": "Keeping a project away from assistants" }, { "description": "The server proxies the map provider for the web app's maps and place search (guide: [locations and places](https://open-todo.app/docs/locations-and-places/)), so a browser never contacts a third party. The routes need a session or a `full` or `admin` token; with maps off they answer `404 maps_disabled`, and when the provider does not answer `502 maps_unavailable`. A demo instance has maps off unless `OPENTODO_MAPS=on`.", "externalDocs": { "url": "https://open-todo.app/docs/api/#maps" }, "name": "Maps" }, { "description": "A person's delivery channels: ntfy, Pushover, Gotify, or a signed webhook (OpenSpec `notification-channels`; guide: [notification-channels.md](https://open-todo.app/docs/notification-channels/)). Every `/api/v1/notification-channels` route answers `404 channels_disabled` while the owner's switch is off; these routes and the setting answer `403 demo_restricted` on the public demo. Channels are server data: never operations, never synced or exported, and their tokens, user keys and signing secrets live in `\u003cdata\u003e/secrets/notification-channels.json` only.", "externalDocs": { "url": "https://open-todo.app/docs/api/#notification-channels" }, "name": "Notification channels" }, { "description": "Every user changes their own name, email and picture. Profile data is server-side account data: never written to the op log, never synced. Members of shared projects see changes on their next sync. Changes are recorded as `account.name_changed`, `account.email_change_requested`, `account.email_changed` and `account.avatar_changed`, never with a name, an address or a picture.", "externalDocs": { "url": "https://open-todo.app/docs/api/#profile" }, "name": "Profile" }, { "description": "A routine's `steps` is an ordered list of at most 20 steps (counted across blocks, at most 3 block levels, 32 KB): `{id, kind, in: {name: {ref} | {literal}}, then?, otherwise?, do?}`. `id` is 1 to 8 characters `a-z0-9`, unique (`trigger` and `item` are reserved); a `ref` names `trigger`, an earlier step visible from the step, or `item` inside a Repeat's `do`. The step kinds, their inputs and output types are listed by the catalogue route and in [routines.md](https://open-todo.app/docs/routines/#steps-and-values). Steps read tasks from the trigger or earlier steps: an input that takes one task (`add_comment.task`, `start_timer.task`, `notify.task`, `note_text.of`, `append_to_note.of`, `clear_note.of`, `create_tasks.parent`) and receives a list runs once per task (OpenSpec `routines-dynamic-data`). A task literal `{\"task\": id}` (on `add_comment`, `start_timer`, `notify` and `get_task`) is for rare fixed targets. `take` is Pick: `from` `start` (default), `end` or `all`, and `n` (default 1, ignored with `all`); `filter` is Pick's \"where\". `of` also takes `{\"project\": id}`. `date` outputs a Date (`date`: `today` by default, `tomorrow`, `{\"in_days\": n}` or `YYYY-MM-DD`); `project_of` outputs a task's project (the Inbox, an empty id, for a task without one); `create_tasks.parent` makes subtasks and refuses a `project` next to it; `split_lines.only: \"open_checkboxes\"` keeps only `- [ ] …` lines; `find_tasks` with a `query` or `view` finds completed tasks when the query names `completed` or `open` (a `condition` finds open tasks); in every form it never finds a task in the Trash or of a project in the Trash, and leaves out tasks of archived projects unless `archived` is `{\"literal\": true}` (OpenSpec `routines-find-scope`; the matching tasks of a `schedule` trigger with a condition follow the same rule). A `schedule` trigger takes `weekdays` or `month_days` (1 to 31 and `\"last\"`; a day a month lacks does not fire that month), exactly one; a condition may hold `unchanged: {days: 1..365}` (no field of the task changed in that many days). A routine is type-checked like the app does (`400 invalid_input` names the step and input, for example `step b: notify: text expects Text, got Tasks`), and every id inside it is resolved.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines" }, "name": "Routines" }, { "description": "OpenSpec `routines-shared`; guide: [routines.md](https://open-todo.app/docs/routines/#routines-of-a-shared-project). The rule field `project_id` (null for a personal routine) makes a routine its project's: once the project is shared it lives in the project's scope like a task and syncs to every member. Owners, admins and editors write it; a viewer's operations are refused (`forbidden`, with the winning value back), and changing `project_id` across scopes is refused (`scope_change`). A shared project holds at most 50 routines; the per-account limit of 50 counts personal routines only (`409 limit_reached`). A create or patch is refused with `400 invalid_input` (*a shared routine acts only in its project: …*) when the trigger, condition or steps name another project, a task of another project or a move out of the project, and when they use labels or a webhook. Steps unavailable in a shared routine carry the reason `not_in_shared` (Favourite, Set today's focus, the timers, Tracked time, Create and Update project, a project from a template, Create labels, Email me, Send a webhook). The representation of a shared routine carries `run_as` (`{id, name}`: the author of the winning `enabled: true`, null before anyone turned it on) and, when someone else's edit paused it, `paused_by`; `GET /api/v1/me/rules` gives both per rule. Its event, schedule, due and overdue runs see only the project, act as `run_as` (role checked before each run and at writing, device `rule:\u003crule-id\u003e`), fire on any member's changes to the project's tasks, and pause with `paused_reason` `edited_by_other` (someone else changed `trigger`, `condition`, `steps`, `actions`, `ai_apply` or `ai_budget`), `run_as_viewer` or `run_as_left` (the owner, admins and editors get a `routine_paused_shared` notification, `{ruleId, ruleName, projectId, projectName, runAsName, reason, at}`). `POST …/run` (also with `test`) runs as the caller and answers a viewer `403 forbidden`; the draft test takes `project_id` to plan inside a project. Every member reads the runs (`project_id` on each run; a non-member gets `404 not_found`); `POST …/undo` needs editor or above (`403 forbidden`). `ai_mode.reason` is `not_run_as` when Apply without asking was turned on by someone other than `run_as`.", "externalDocs": { "url": "https://open-todo.app/docs/api/#routines-of-a-shared-project" }, "name": "Routines of a shared project" }, { "description": "A section is a named, ordered container inside one project (OpenSpec change `board-view`): a heading in the list view and a column on the board. Sections are soft-deleted like everything else, live in the sharing scope of their project (editors and up may write them, viewers read them) and appear in the export, deleted ones included.", "externalDocs": { "url": "https://open-todo.app/docs/api/#sections" }, "name": "Sections" }, { "description": "The owner sets the default light and dark theme of the server and offers up to 20 server themes to everyone (**Settings → Server → Branding**). A member whose choice for a side is empty sees the server default; a member's own choice always wins, and nothing is written to anyone's data. `GET /api/v1/auth/status` carries `\"themes\": {\"version\": 3}` for a signed-in caller; the version grows with every change, so a device reads the themes again when it differs from the one it has.", "externalDocs": { "url": "https://open-todo.app/docs/api/#server-themes" }, "name": "Server themes" }, { "description": "Voice capture sends a recorded phrase through the server to the owner's OpenAI-compatible transcription service (guides: [speech to text](https://open-todo.app/docs/self-hosting/speech-to-text/), [quick add](https://open-todo.app/docs/quick-add/)). The audio and the text stay in memory for the request: never stored, logged or audited. `GET /api/v1/me` carries `speech: {connected, host?}` for every user.", "externalDocs": { "url": "https://open-todo.app/docs/api/#speech-to-text" }, "name": "Speech to text" }, { "description": "The Tasks, projects and other synced data routes.", "externalDocs": { "url": "https://open-todo.app/docs/api/#tasks-projects-and-other-synced-data" }, "name": "Tasks, projects and other synced data" }, { "description": "A workspace is a separate room with its own projects, labels, views and people (OpenSpec `workspaces`, guide: [workspaces](https://open-todo.app/docs/workspaces/)). Every account has one default workspace (`\"default\": true`, named \"Personal\" until renamed), which cannot be deleted, left, transferred or given members (409 `default_workspace`). Projects, labels, views and tasks without a project carry `workspace_id` (null or absent = the default workspace; a task with a project follows its project); on a shared project only the owner may change it. Workspaces, members and groups are server data, never ops; every sync response carries `workspaces` (below).", "externalDocs": { "url": "https://open-todo.app/docs/api/#workspaces" }, "name": "Workspaces" }, { "description": "The Your account and credentials routes.", "externalDocs": { "url": "https://open-todo.app/docs/api/#your-account-and-credentials" }, "name": "Your account and credentials" } ] }