{ "openapi": "3.1.0", "info": { "title": "OpenTask API", "version": "latest" }, "components": { "securitySchemes": { "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "better-auth.session_token" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ot_…" } }, "schemas": {}, "parameters": {} }, "paths": { "/api/v1/tasks/quick": { "post": { "tags": [ "tasks" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Create a task from a raw Quick Add line", "description": "Parses the Quick Add grammar (natural-language due, `{deadline}`, `#project`, `/section`, `@label`, `p1`–`p4`, `// description`, leading `* ` uncompletable, `!` reminders). Missing projects/sections/labels are auto-created. Parsed `!` reminder tokens are persisted; a relative reminder is skipped when the task has no due time.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 } }, "required": [ "text" ] } } } }, "responses": { "201": { "description": "Created task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "string": { "type": "string" }, "is_recurring": { "type": "boolean" }, "recurrence": { "nullable": true } }, "required": [ "date", "time", "string", "is_recurring" ] }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true }, "duration_min": { "type": "integer", "nullable": true }, "day_order": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_collapsed": { "type": "boolean" }, "uncompletable": { "type": "boolean" }, "completed_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "section_id", "parent_id", "child_order", "content", "description", "priority", "due", "deadline_date", "deadline_time", "duration_min", "day_order", "labels", "is_collapsed", "uncompletable", "completed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid Quick Add text", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/tasks/{id}/close": { "post": { "tags": [ "tasks" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Complete a task", "description": "Completes a non-recurring task (and its open subtasks). A recurring task advances to its next occurrence and stays open unless the (optional) JSON body `{ \"complete_series\": true }` forces a final completion, or the recurrence has passed its `until` bound.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": false, "description": "Optional. Omit entirely (or send `{}`) to complete one task/occurrence.", "content": { "application/json": { "schema": { "type": "object", "properties": { "complete_series": { "type": "boolean", "default": false, "description": "Fully complete a recurring task instead of advancing it." } } } } } }, "responses": { "200": { "description": "Completed or advanced task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "string": { "type": "string" }, "is_recurring": { "type": "boolean" }, "recurrence": { "nullable": true } }, "required": [ "date", "time", "string", "is_recurring" ] }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true }, "duration_min": { "type": "integer", "nullable": true }, "day_order": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_collapsed": { "type": "boolean" }, "uncompletable": { "type": "boolean" }, "completed_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "section_id", "parent_id", "child_order", "content", "description", "priority", "due", "deadline_date", "deadline_time", "duration_min", "day_order", "labels", "is_collapsed", "uncompletable", "completed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid request body", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Task not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "409": { "description": "Task is uncompletable or already completed", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/tasks/{id}/reopen": { "post": { "tags": [ "tasks" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Reopen a completed task", "description": "Clears `completed_at`, reopens any completed ancestors, and decrements that day’s completion count.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Reopened task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "string": { "type": "string" }, "is_recurring": { "type": "boolean" }, "recurrence": { "nullable": true } }, "required": [ "date", "time", "string", "is_recurring" ] }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true }, "duration_min": { "type": "integer", "nullable": true }, "day_order": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_collapsed": { "type": "boolean" }, "uncompletable": { "type": "boolean" }, "completed_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "section_id", "parent_id", "child_order", "content", "description", "priority", "due", "deadline_date", "deadline_time", "duration_min", "day_order", "labels", "is_collapsed", "uncompletable", "completed_at", "created_at", "updated_at" ] } } } }, "404": { "description": "Task not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "409": { "description": "Task is not completed", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/tasks": { "get": { "tags": [ "tasks" ], "summary": "List open tasks", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "project_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "section_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "parent_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "label", "in": "query" } ], "responses": { "200": { "description": "Open tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "string": { "type": "string" }, "is_recurring": { "type": "boolean" }, "recurrence": { "nullable": true } }, "required": [ "date", "time", "string", "is_recurring" ] }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true }, "duration_min": { "type": "integer", "nullable": true }, "day_order": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_collapsed": { "type": "boolean" }, "uncompletable": { "type": "boolean" }, "completed_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "section_id", "parent_id", "child_order", "content", "description", "priority", "due", "deadline_date", "deadline_time", "duration_min", "day_order", "labels", "is_collapsed", "uncompletable", "completed_at", "created_at", "updated_at" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "400": { "description": "Invalid cursor", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } }, "post": { "tags": [ "tasks" ], "summary": "Create a task", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1 }, "description": { "type": "string", "default": "" }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4, "default": 4 }, "due": { "type": "object", "nullable": true, "properties": { "string": { "type": "string" }, "date": { "type": "string" }, "time": { "type": "string" } } }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true, "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "duration_min": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 1440 }, "labels": { "type": "array", "items": { "type": "string" }, "default": [] }, "uncompletable": { "type": "boolean" } }, "required": [ "content" ] } } } }, "responses": { "201": { "description": "Created task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "string": { "type": "string" }, "is_recurring": { "type": "boolean" }, "recurrence": { "nullable": true } }, "required": [ "date", "time", "string", "is_recurring" ] }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true }, "duration_min": { "type": "integer", "nullable": true }, "day_order": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_collapsed": { "type": "boolean" }, "uncompletable": { "type": "boolean" }, "completed_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "section_id", "parent_id", "child_order", "content", "description", "priority", "due", "deadline_date", "deadline_time", "duration_min", "day_order", "labels", "is_collapsed", "uncompletable", "completed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/tasks/completed": { "get": { "tags": [ "tasks" ], "summary": "List completed tasks", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "project_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "until", "in": "query" } ], "responses": { "200": { "description": "Completed tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "string": { "type": "string" }, "is_recurring": { "type": "boolean" }, "recurrence": { "nullable": true } }, "required": [ "date", "time", "string", "is_recurring" ] }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true }, "duration_min": { "type": "integer", "nullable": true }, "day_order": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_collapsed": { "type": "boolean" }, "uncompletable": { "type": "boolean" }, "completed_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "section_id", "parent_id", "child_order", "content", "description", "priority", "due", "deadline_date", "deadline_time", "duration_min", "day_order", "labels", "is_collapsed", "uncompletable", "completed_at", "created_at", "updated_at" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "400": { "description": "Invalid cursor", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/tasks/reorder": { "post": { "tags": [ "tasks" ], "summary": "Batch-update task child_order", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "child_order": { "type": "integer" } }, "required": [ "id", "child_order" ] }, "minItems": 1 } }, "required": [ "items" ] } } } }, "responses": { "204": { "description": "Reordered" }, "404": { "description": "A task id does not belong to the user", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/tasks/{id}": { "get": { "tags": [ "tasks" ], "summary": "Get a task", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "string": { "type": "string" }, "is_recurring": { "type": "boolean" }, "recurrence": { "nullable": true } }, "required": [ "date", "time", "string", "is_recurring" ] }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true }, "duration_min": { "type": "integer", "nullable": true }, "day_order": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_collapsed": { "type": "boolean" }, "uncompletable": { "type": "boolean" }, "completed_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "section_id", "parent_id", "child_order", "content", "description", "priority", "due", "deadline_date", "deadline_time", "duration_min", "day_order", "labels", "is_collapsed", "uncompletable", "completed_at", "created_at", "updated_at" ] } } } }, "404": { "description": "Task not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } }, "patch": { "tags": [ "tasks" ], "summary": "Update a task", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1 }, "description": { "type": "string", "default": "" }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4, "default": 4 }, "due": { "type": "object", "nullable": true, "properties": { "string": { "type": "string" }, "date": { "type": "string" }, "time": { "type": "string" } } }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true, "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "duration_min": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 1440 }, "labels": { "type": "array", "items": { "type": "string" }, "default": [] }, "uncompletable": { "type": "boolean" }, "day_order": { "type": "integer" }, "is_collapsed": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "string": { "type": "string" }, "is_recurring": { "type": "boolean" }, "recurrence": { "nullable": true } }, "required": [ "date", "time", "string", "is_recurring" ] }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true }, "duration_min": { "type": "integer", "nullable": true }, "day_order": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_collapsed": { "type": "boolean" }, "uncompletable": { "type": "boolean" }, "completed_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "section_id", "parent_id", "child_order", "content", "description", "priority", "due", "deadline_date", "deadline_time", "duration_min", "day_order", "labels", "is_collapsed", "uncompletable", "completed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid reference (foreign/unknown id, or a parent cycle)", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Task not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } }, "delete": { "tags": [ "tasks" ], "summary": "Soft-delete a task and its subtree", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Task not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/tasks/{id}/move": { "post": { "tags": [ "tasks" ], "summary": "Move a task (project/section/parent)", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Moved task", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "string": { "type": "string" }, "is_recurring": { "type": "boolean" }, "recurrence": { "nullable": true } }, "required": [ "date", "time", "string", "is_recurring" ] }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true }, "duration_min": { "type": "integer", "nullable": true }, "day_order": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_collapsed": { "type": "boolean" }, "uncompletable": { "type": "boolean" }, "completed_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "section_id", "parent_id", "child_order", "content", "description", "priority", "due", "deadline_date", "deadline_time", "duration_min", "day_order", "labels", "is_collapsed", "uncompletable", "completed_at", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid move", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Task not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/tasks/{id}/restore": { "post": { "tags": [ "tasks" ], "summary": "Restore a soft-deleted task and its subtree", "description": "Clears `deleted_at` on the task and every row deleted in the same cascade (delete stamps an identical `deleted_at` across the subtree). Powers the delete-task undo.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "404": { "description": "No soft-deleted task with that id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/projects": { "get": { "tags": [ "projects" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" }, "required": false, "name": "include_archived", "in": "query" } ], "responses": { "200": { "description": "All projects (unpaginated envelope)", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "is_collapsed": { "type": "boolean" }, "is_inbox": { "type": "boolean" }, "view_prefs": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "color", "parent_id", "child_order", "is_favorite", "is_archived", "is_collapsed", "is_inbox", "created_at", "updated_at" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" } } }, "post": { "tags": [ "projects" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "is_favorite": { "type": "boolean" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "is_collapsed": { "type": "boolean" }, "is_inbox": { "type": "boolean" }, "view_prefs": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "color", "parent_id", "child_order", "is_favorite", "is_archived", "is_collapsed", "is_inbox", "created_at", "updated_at" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } } }, "/api/v1/projects/reorder": { "post": { "tags": [ "projects" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "child_order": { "type": "integer" } }, "required": [ "id", "child_order" ] }, "minItems": 1 } }, "required": [ "items" ] } } } }, "responses": { "204": { "description": "Reordered" }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } } }, "/api/v1/projects/{id}": { "get": { "tags": [ "projects" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Project", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "is_collapsed": { "type": "boolean" }, "is_inbox": { "type": "boolean" }, "view_prefs": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "color", "parent_id", "child_order", "is_favorite", "is_archived", "is_collapsed", "is_inbox", "created_at", "updated_at" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } }, "patch": { "tags": [ "projects" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "is_favorite": { "type": "boolean" }, "is_collapsed": { "type": "boolean" }, "view_prefs": { "nullable": true } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "is_collapsed": { "type": "boolean" }, "is_inbox": { "type": "boolean" }, "view_prefs": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "color", "parent_id", "child_order", "is_favorite", "is_archived", "is_collapsed", "is_inbox", "created_at", "updated_at" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } }, "delete": { "tags": [ "projects" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "403": { "description": "Forbidden (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } } }, "/api/v1/projects/{id}/archive": { "post": { "tags": [ "projects" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "is_collapsed": { "type": "boolean" }, "is_inbox": { "type": "boolean" }, "view_prefs": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "color", "parent_id", "child_order", "is_favorite", "is_archived", "is_collapsed", "is_inbox", "created_at", "updated_at" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "403": { "description": "Forbidden (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } } }, "/api/v1/projects/{id}/unarchive": { "post": { "tags": [ "projects" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Unarchived", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "is_collapsed": { "type": "boolean" }, "is_inbox": { "type": "boolean" }, "view_prefs": { "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "color", "parent_id", "child_order", "is_favorite", "is_archived", "is_collapsed", "is_inbox", "created_at", "updated_at" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "403": { "description": "Forbidden (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } } }, "/api/v1/projects/{id}/restore": { "post": { "tags": [ "projects" ], "summary": "Restore a soft-deleted project and its cascade", "description": "Clears `deleted_at` on the project and every section/task deleted in the same cascade (delete stamps an identical `deleted_at`). Powers the delete-project undo.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } } }, "/api/v1/sections": { "get": { "tags": [ "sections" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "project_id", "in": "query" } ], "responses": { "200": { "description": "Sections (unpaginated envelope); all of the user, or one project when filtered", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "section_order": { "type": "integer" }, "is_archived": { "type": "boolean" }, "is_collapsed": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "name", "section_order", "is_archived", "is_collapsed", "created_at", "updated_at" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" } } }, "post": { "tags": [ "sections" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "project_id", "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "section_order": { "type": "integer" }, "is_archived": { "type": "boolean" }, "is_collapsed": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "name", "section_order", "is_archived", "is_collapsed", "created_at", "updated_at" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } } }, "/api/v1/sections/reorder": { "post": { "tags": [ "sections" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "section_order": { "type": "integer" } }, "required": [ "id", "section_order" ] }, "minItems": 1 } }, "required": [ "items" ] } } } }, "responses": { "204": { "description": "Reordered" }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } } }, "/api/v1/sections/{id}": { "patch": { "tags": [ "sections" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "section_order": { "type": "integer" }, "is_archived": { "type": "boolean" }, "is_collapsed": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "section_order": { "type": "integer" }, "is_archived": { "type": "boolean" }, "is_collapsed": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "name", "section_order", "is_archived", "is_collapsed", "created_at", "updated_at" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } }, "delete": { "tags": [ "sections" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } } }, "/api/v1/sections/{id}/restore": { "post": { "tags": [ "sections" ], "summary": "Restore a soft-deleted section and re-attach its tasks", "description": "Clears `deleted_at` on the section and re-attaches the tasks it was deleted with (delete detaches them, stamping `updated_at` with the same instant). Powers the delete-section undo.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Bad request (application/problem+json)" }, "401": { "description": "Unauthorized (application/problem+json)" }, "404": { "description": "Not found (application/problem+json)" } } } }, "/api/v1/labels": { "get": { "tags": [ "labels" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "labels", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "item_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "color", "item_order", "is_favorite", "created_at", "updated_at" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "401": { "description": "unauthorized" } } }, "post": { "tags": [ "labels" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "is_favorite": { "type": "boolean" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "item_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "color", "item_order", "is_favorite", "created_at", "updated_at" ] } } } }, "401": { "description": "unauthorized" }, "409": { "description": "label exists" } } } }, "/api/v1/labels/reorder": { "post": { "tags": [ "labels" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "item_order": { "type": "integer" } }, "required": [ "id", "item_order" ] }, "minItems": 1 } }, "required": [ "items" ] } } } }, "responses": { "204": { "description": "reordered" }, "401": { "description": "unauthorized" }, "404": { "description": "not found" } } } }, "/api/v1/labels/{id}": { "patch": { "tags": [ "labels" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "is_favorite": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "item_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "color", "item_order", "is_favorite", "created_at", "updated_at" ] } } } }, "401": { "description": "unauthorized" }, "404": { "description": "not found" }, "409": { "description": "label exists" } } }, "delete": { "tags": [ "labels" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "deleted" }, "401": { "description": "unauthorized" }, "404": { "description": "not found" } } } }, "/api/v1/filters": { "get": { "tags": [ "filters" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "query": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "item_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "query", "color", "item_order", "is_favorite", "created_at", "updated_at" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "401": { "description": "unauthorized" } } }, "post": { "tags": [ "filters" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "query": { "type": "string", "minLength": 1 }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "is_favorite": { "type": "boolean" } }, "required": [ "name", "query" ] } } } }, "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "query": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "item_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "query", "color", "item_order", "is_favorite", "created_at", "updated_at" ] } } } }, "400": { "description": "invalid filter query" }, "401": { "description": "unauthorized" } } } }, "/api/v1/filters/reorder": { "post": { "tags": [ "filters" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "item_order": { "type": "integer" } }, "required": [ "id", "item_order" ] }, "minItems": 1 } }, "required": [ "items" ] } } } }, "responses": { "204": { "description": "reordered" }, "401": { "description": "unauthorized" }, "404": { "description": "not found" } } } }, "/api/v1/filters/{id}": { "patch": { "tags": [ "filters" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "query": { "type": "string", "minLength": 1 }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "is_favorite": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "query": { "type": "string" }, "color": { "type": "string", "enum": [ "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe" ] }, "item_order": { "type": "integer" }, "is_favorite": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "query", "color", "item_order", "is_favorite", "created_at", "updated_at" ] } } } }, "400": { "description": "invalid filter query" }, "401": { "description": "unauthorized" }, "404": { "description": "not found" } } }, "delete": { "tags": [ "filters" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "deleted" }, "401": { "description": "unauthorized" }, "404": { "description": "not found" } } } }, "/api/v1/comments": { "get": { "tags": [ "comments" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "task_id", "in": "query" } ], "responses": { "200": { "description": "Comments on a task, oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "task_id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "attachment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1 }, "file_name": { "type": "string" }, "file_size": { "type": "integer" }, "file_type": { "type": "string" }, "file_url": { "type": "string" } }, "required": [ "id", "file_name", "file_size", "file_type", "file_url" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "task_id", "content", "attachment", "created_at", "updated_at" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "400": { "description": "Invalid cursor" }, "404": { "description": "Task not found" } } }, "post": { "tags": [ "comments" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "attachment_id": { "type": "string", "minLength": 1 } }, "required": [ "task_id", "content" ] } } } }, "responses": { "201": { "description": "Created comment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "task_id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "attachment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1 }, "file_name": { "type": "string" }, "file_size": { "type": "integer" }, "file_type": { "type": "string" }, "file_url": { "type": "string" } }, "required": [ "id", "file_name", "file_size", "file_type", "file_url" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "task_id", "content", "attachment", "created_at", "updated_at" ] } } } }, "400": { "description": "Unknown attachment" }, "404": { "description": "Task not found" } } } }, "/api/v1/comments/{id}": { "patch": { "tags": [ "comments" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1 } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Updated comment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "task_id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "attachment": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "minLength": 1 }, "file_name": { "type": "string" }, "file_size": { "type": "integer" }, "file_type": { "type": "string" }, "file_url": { "type": "string" } }, "required": [ "id", "file_name", "file_size", "file_type", "file_url" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "task_id", "content", "attachment", "created_at", "updated_at" ] } } } }, "404": { "description": "Comment not found" } } }, "delete": { "tags": [ "comments" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Comment not found" } } } }, "/api/v1/attachments": { "post": { "tags": [ "attachments" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Upload a file", "description": "Multipart upload (`file` field required). The stored name is the sanitized basename of the uploaded filename, and the returned `file_url` is the authenticated download path.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file to store." } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Stored attachment", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "file_name": { "type": "string" }, "file_size": { "type": "integer" }, "file_type": { "type": "string" }, "file_url": { "type": "string" } }, "required": [ "id", "file_name", "file_size", "file_type", "file_url" ] } } } }, "400": { "description": "Missing `file` field or not a multipart form", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "413": { "description": "Upload exceeds the configured size cap", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/attachments/{id}/{filename}": { "get": { "tags": [ "attachments" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Download a stored file", "description": "Streams the stored bytes with the stored content type. `filename` must equal the stored file name. Images are served `inline`, everything else as an `attachment` download.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "filename", "in": "path" } ], "responses": { "200": { "description": "The file bytes (content-type is the stored file type)", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Unknown attachment, foreign owner, or filename mismatch", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/user": { "get": { "tags": [ "User" ], "summary": "Current user", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Current user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "email": { "type": "string" }, "two_factor_enabled": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "email", "two_factor_enabled", "created_at" ] } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "User" ], "summary": "Update the current user", "description": "Updates the display name only. Email, password, 2FA and connected-provider changes go through better-auth endpoints under /api/auth/* and are not reimplemented here.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Updated user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "email": { "type": "string" }, "two_factor_enabled": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "email", "two_factor_enabled", "created_at" ] } } } }, "400": { "description": "Validation failed" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/api/v1/user/settings": { "get": { "tags": [ "User" ], "summary": "Client preferences document", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "User settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "homeView": { "type": "string", "default": "today" }, "timezone": { "type": "string", "default": "UTC" }, "dateFormat": { "type": "string", "enum": [ "MDY", "DMY" ], "default": "MDY" }, "timeFormat": { "type": "string", "enum": [ "12h", "24h" ], "default": "12h" }, "weekStart": { "type": "integer", "minimum": 1, "maximum": 7, "default": 1 }, "nextWeekDay": { "type": "integer", "minimum": 1, "maximum": 7, "default": 1 }, "weekendDay": { "type": "integer", "minimum": 1, "maximum": 7, "default": 6 }, "smartDate": { "type": "boolean", "default": true }, "theme": { "type": "string", "enum": [ "kale", "todoist", "dark", "moonstone", "tangerine", "blueberry", "lavender", "raspberry" ], "default": "kale" }, "autoDark": { "type": "boolean", "default": true }, "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "accent": { "type": "string", "enum": [ "kale", "todoist", "moonstone", "tangerine", "blueberry", "lavender", "raspberry" ] }, "soundCues": { "type": "boolean", "default": true }, "dailyGoal": { "type": "integer", "minimum": 0, "maximum": 100, "default": 5 }, "weeklyGoal": { "type": "integer", "minimum": 0, "maximum": 700, "default": 25 }, "daysOff": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "default": [ 6, 7 ] }, "vacationMode": { "type": "boolean", "default": false }, "karmaEnabled": { "type": "boolean", "default": true }, "autoReminderMinutes": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 10080, "default": 30 }, "notifications": { "type": "object", "properties": { "push": { "type": "boolean", "default": true }, "ntfy": { "type": "boolean", "default": false }, "gotify": { "type": "boolean", "default": false }, "webhook": { "type": "boolean", "default": false } }, "default": { "push": true, "ntfy": false, "gotify": false, "webhook": false } }, "sidebar": { "type": "object", "properties": { "showInbox": { "type": "boolean", "default": true }, "showToday": { "type": "boolean", "default": true }, "showUpcoming": { "type": "boolean", "default": true }, "showFiltersLabels": { "type": "boolean", "default": true }, "showReporting": { "type": "boolean", "default": true }, "showCounts": { "type": "boolean", "default": true } }, "default": { "showInbox": true, "showToday": true, "showUpcoming": true, "showFiltersLabels": true, "showReporting": true, "showCounts": true } }, "quickAdd": { "type": "object", "properties": { "chips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "date", "deadline", "priority", "reminders", "labels", "duration", "description" ] }, "visible": { "type": "boolean" } }, "required": [ "id", "visible" ] }, "default": [ { "id": "date", "visible": true }, { "id": "deadline", "visible": true }, { "id": "priority", "visible": true }, { "id": "reminders", "visible": true }, { "id": "labels", "visible": true }, { "id": "duration", "visible": true }, { "id": "description", "visible": true } ] }, "labeled": { "type": "boolean", "default": true } }, "default": { "chips": [ { "id": "date", "visible": true }, { "id": "deadline", "visible": true }, { "id": "priority", "visible": true }, { "id": "reminders", "visible": true }, { "id": "labels", "visible": true }, { "id": "duration", "visible": true }, { "id": "description", "visible": true } ], "labeled": true } }, "viewPrefs": { "type": "object", "additionalProperties": { "type": "object", "properties": { "layout": { "type": "string", "enum": [ "list", "board" ], "default": "list" }, "groupBy": { "type": "string", "enum": [ "none", "project", "priority", "label", "date" ], "default": "none" }, "sortBy": { "type": "string", "enum": [ "manual", "date", "added", "priority", "alphabetical" ], "default": "manual" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "filterBy": { "type": "object", "properties": { "priority": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] }, { "nullable": true } ], "default": null }, "label": { "type": "string", "nullable": true, "default": null }, "due": { "type": "string", "nullable": true, "enum": [ "has-date", "no-date", "overdue", null ], "default": null } }, "default": { "priority": null, "label": null, "due": null } }, "showCompleted": { "type": "boolean", "default": false } } }, "default": {} } } } } } }, "401": { "description": "Unauthorized" } } }, "patch": { "tags": [ "User" ], "summary": "Update client preferences", "description": "Shallow top-level merge onto the stored document; only the keys present in the request body are changed. `viewPrefs` merges per view key (provided keys replace, others are kept). `autoReminderMinutes` accepts exactly null, 0, 5, 10, 15, 30, 45, 60, or 120 — the extra heads-up before a timed due. Tasks with a due time always get an at-time reminder; null means no extra heads-up and 0 is a back-compat alias for null.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "homeView": { "type": "string", "default": "today" }, "timezone": { "type": "string", "default": "UTC" }, "dateFormat": { "type": "string", "enum": [ "MDY", "DMY" ], "default": "MDY" }, "timeFormat": { "type": "string", "enum": [ "12h", "24h" ], "default": "12h" }, "weekStart": { "type": "integer", "minimum": 1, "maximum": 7, "default": 1 }, "nextWeekDay": { "type": "integer", "minimum": 1, "maximum": 7, "default": 1 }, "weekendDay": { "type": "integer", "minimum": 1, "maximum": 7, "default": 6 }, "smartDate": { "type": "boolean", "default": true }, "theme": { "type": "string", "enum": [ "kale", "todoist", "dark", "moonstone", "tangerine", "blueberry", "lavender", "raspberry" ], "default": "kale" }, "autoDark": { "type": "boolean", "default": true }, "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "accent": { "type": "string", "enum": [ "kale", "todoist", "moonstone", "tangerine", "blueberry", "lavender", "raspberry" ] }, "soundCues": { "type": "boolean", "default": true }, "dailyGoal": { "type": "integer", "minimum": 0, "maximum": 100, "default": 5 }, "weeklyGoal": { "type": "integer", "minimum": 0, "maximum": 700, "default": 25 }, "daysOff": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "default": [ 6, 7 ] }, "vacationMode": { "type": "boolean", "default": false }, "karmaEnabled": { "type": "boolean", "default": true }, "autoReminderMinutes": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 10080, "default": 30 }, "notifications": { "type": "object", "properties": { "push": { "type": "boolean", "default": true }, "ntfy": { "type": "boolean", "default": false }, "gotify": { "type": "boolean", "default": false }, "webhook": { "type": "boolean", "default": false } }, "default": { "push": true, "ntfy": false, "gotify": false, "webhook": false } }, "sidebar": { "type": "object", "properties": { "showInbox": { "type": "boolean", "default": true }, "showToday": { "type": "boolean", "default": true }, "showUpcoming": { "type": "boolean", "default": true }, "showFiltersLabels": { "type": "boolean", "default": true }, "showReporting": { "type": "boolean", "default": true }, "showCounts": { "type": "boolean", "default": true } }, "default": { "showInbox": true, "showToday": true, "showUpcoming": true, "showFiltersLabels": true, "showReporting": true, "showCounts": true } }, "quickAdd": { "type": "object", "properties": { "chips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "date", "deadline", "priority", "reminders", "labels", "duration", "description" ] }, "visible": { "type": "boolean" } }, "required": [ "id", "visible" ] }, "default": [ { "id": "date", "visible": true }, { "id": "deadline", "visible": true }, { "id": "priority", "visible": true }, { "id": "reminders", "visible": true }, { "id": "labels", "visible": true }, { "id": "duration", "visible": true }, { "id": "description", "visible": true } ] }, "labeled": { "type": "boolean", "default": true } }, "default": { "chips": [ { "id": "date", "visible": true }, { "id": "deadline", "visible": true }, { "id": "priority", "visible": true }, { "id": "reminders", "visible": true }, { "id": "labels", "visible": true }, { "id": "duration", "visible": true }, { "id": "description", "visible": true } ], "labeled": true } }, "viewPrefs": { "type": "object", "additionalProperties": { "type": "object", "properties": { "layout": { "type": "string", "enum": [ "list", "board" ], "default": "list" }, "groupBy": { "type": "string", "enum": [ "none", "project", "priority", "label", "date" ], "default": "none" }, "sortBy": { "type": "string", "enum": [ "manual", "date", "added", "priority", "alphabetical" ], "default": "manual" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "filterBy": { "type": "object", "properties": { "priority": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] }, { "nullable": true } ], "default": null }, "label": { "type": "string", "nullable": true, "default": null }, "due": { "type": "string", "nullable": true, "enum": [ "has-date", "no-date", "overdue", null ], "default": null } }, "default": { "priority": null, "label": null, "due": null } }, "showCompleted": { "type": "boolean", "default": false } } }, "default": {} } } } } } }, "responses": { "200": { "description": "Merged settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "homeView": { "type": "string", "default": "today" }, "timezone": { "type": "string", "default": "UTC" }, "dateFormat": { "type": "string", "enum": [ "MDY", "DMY" ], "default": "MDY" }, "timeFormat": { "type": "string", "enum": [ "12h", "24h" ], "default": "12h" }, "weekStart": { "type": "integer", "minimum": 1, "maximum": 7, "default": 1 }, "nextWeekDay": { "type": "integer", "minimum": 1, "maximum": 7, "default": 1 }, "weekendDay": { "type": "integer", "minimum": 1, "maximum": 7, "default": 6 }, "smartDate": { "type": "boolean", "default": true }, "theme": { "type": "string", "enum": [ "kale", "todoist", "dark", "moonstone", "tangerine", "blueberry", "lavender", "raspberry" ], "default": "kale" }, "autoDark": { "type": "boolean", "default": true }, "appearance": { "type": "string", "enum": [ "light", "dark", "system" ] }, "accent": { "type": "string", "enum": [ "kale", "todoist", "moonstone", "tangerine", "blueberry", "lavender", "raspberry" ] }, "soundCues": { "type": "boolean", "default": true }, "dailyGoal": { "type": "integer", "minimum": 0, "maximum": 100, "default": 5 }, "weeklyGoal": { "type": "integer", "minimum": 0, "maximum": 700, "default": 25 }, "daysOff": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "default": [ 6, 7 ] }, "vacationMode": { "type": "boolean", "default": false }, "karmaEnabled": { "type": "boolean", "default": true }, "autoReminderMinutes": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 10080, "default": 30 }, "notifications": { "type": "object", "properties": { "push": { "type": "boolean", "default": true }, "ntfy": { "type": "boolean", "default": false }, "gotify": { "type": "boolean", "default": false }, "webhook": { "type": "boolean", "default": false } }, "default": { "push": true, "ntfy": false, "gotify": false, "webhook": false } }, "sidebar": { "type": "object", "properties": { "showInbox": { "type": "boolean", "default": true }, "showToday": { "type": "boolean", "default": true }, "showUpcoming": { "type": "boolean", "default": true }, "showFiltersLabels": { "type": "boolean", "default": true }, "showReporting": { "type": "boolean", "default": true }, "showCounts": { "type": "boolean", "default": true } }, "default": { "showInbox": true, "showToday": true, "showUpcoming": true, "showFiltersLabels": true, "showReporting": true, "showCounts": true } }, "quickAdd": { "type": "object", "properties": { "chips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "date", "deadline", "priority", "reminders", "labels", "duration", "description" ] }, "visible": { "type": "boolean" } }, "required": [ "id", "visible" ] }, "default": [ { "id": "date", "visible": true }, { "id": "deadline", "visible": true }, { "id": "priority", "visible": true }, { "id": "reminders", "visible": true }, { "id": "labels", "visible": true }, { "id": "duration", "visible": true }, { "id": "description", "visible": true } ] }, "labeled": { "type": "boolean", "default": true } }, "default": { "chips": [ { "id": "date", "visible": true }, { "id": "deadline", "visible": true }, { "id": "priority", "visible": true }, { "id": "reminders", "visible": true }, { "id": "labels", "visible": true }, { "id": "duration", "visible": true }, { "id": "description", "visible": true } ], "labeled": true } }, "viewPrefs": { "type": "object", "additionalProperties": { "type": "object", "properties": { "layout": { "type": "string", "enum": [ "list", "board" ], "default": "list" }, "groupBy": { "type": "string", "enum": [ "none", "project", "priority", "label", "date" ], "default": "none" }, "sortBy": { "type": "string", "enum": [ "manual", "date", "added", "priority", "alphabetical" ], "default": "manual" }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "filterBy": { "type": "object", "properties": { "priority": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] }, { "nullable": true } ], "default": null }, "label": { "type": "string", "nullable": true, "default": null }, "due": { "type": "string", "nullable": true, "enum": [ "has-date", "no-date", "overdue", null ], "default": null } }, "default": { "priority": null, "label": null, "due": null } }, "showCompleted": { "type": "boolean", "default": false } } }, "default": {} } } } } } }, "400": { "description": "Invalid timezone or validation failed" }, "401": { "description": "Unauthorized" } } } }, "/api/v1/tokens": { "get": { "tags": [ "Tokens" ], "summary": "List API tokens (never returns the secret value)", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "API tokens", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "read_write" ] }, "start": { "type": "string", "default": "ot_" }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": "string", "nullable": true, "default": null } }, "required": [ "id", "name", "scope", "createdAt" ] } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "tags": [ "Tokens" ], "summary": "Create an API token", "description": "The full `ot_…` value is returned exactly once and is never retrievable again.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "read", "read_write" ] } }, "required": [ "name", "scope" ] } } } }, "responses": { "201": { "description": "Created token (secret shown once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "read", "read_write" ] }, "start": { "type": "string", "default": "ot_" }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": "string", "nullable": true, "default": null }, "token": { "type": "string", "pattern": "^ot_" } }, "required": [ "id", "name", "scope", "createdAt", "token" ] } } } }, "400": { "description": "Validation failed" }, "401": { "description": "Unauthorized" } } } }, "/api/v1/tokens/{id}": { "delete": { "tags": [ "Tokens" ], "summary": "Revoke an API token", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Not found" } } } }, "/api/v1/activities": { "get": { "tags": [ "Activities" ], "summary": "Activity log (read-only)", "description": "Newest-first, unlimited history. Each item carries a read-time-denormalized `payload` (`content`, `project_name`, and the stored event payload under `meta`). Filter by `types` (csv), `event_type` (single), `entity_type`, `project_id`, and `since`/`until`.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "event_type", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "types", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "entity_type", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "project_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "until", "in": "query" } ], "responses": { "200": { "description": "Activity log", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "event_type": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "nullable": true, "minLength": 1 }, "payload": { "type": "object", "properties": { "content": { "type": "string" }, "project_name": { "type": "string", "nullable": true }, "meta": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "content", "project_name", "meta" ] }, "at": { "type": "string" } }, "required": [ "id", "event_type", "entity_type", "entity_id", "project_id", "payload", "at" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "400": { "description": "Invalid cursor" }, "401": { "description": "Unauthorized" } } } }, "/api/v1/search": { "get": { "tags": [ "search" ], "summary": "Full-text search across tasks and comments", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "q", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" }, "required": false, "name": "include_completed", "in": "query" } ], "responses": { "200": { "description": "Ranked search hits; each hit carries the matching task and where it matched", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "project_id": { "type": "string", "minLength": 1 }, "section_id": { "type": "string", "nullable": true, "minLength": 1 }, "parent_id": { "type": "string", "nullable": true, "minLength": 1 }, "child_order": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "integer", "minimum": 1, "maximum": 4 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string" }, "time": { "type": "string", "nullable": true }, "string": { "type": "string" }, "is_recurring": { "type": "boolean" }, "recurrence": { "nullable": true } }, "required": [ "date", "time", "string", "is_recurring" ] }, "deadline_date": { "type": "string", "nullable": true }, "deadline_time": { "type": "string", "nullable": true }, "duration_min": { "type": "integer", "nullable": true }, "day_order": { "type": "integer" }, "labels": { "type": "array", "items": { "type": "string" } }, "is_collapsed": { "type": "boolean" }, "uncompletable": { "type": "boolean" }, "completed_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "section_id", "parent_id", "child_order", "content", "description", "priority", "due", "deadline_date", "deadline_time", "duration_min", "day_order", "labels", "is_collapsed", "uncompletable", "completed_at", "created_at", "updated_at" ] }, "matched_in": { "type": "string", "enum": [ "task", "comment" ] }, "snippet": { "type": "string" } }, "required": [ "task", "matched_in", "snippet" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "400": { "description": "Malformed cursor (application/problem+json)" }, "401": { "description": "Authentication required (application/problem+json)" } } } }, "/api/v1/events": { "get": { "tags": [ "events" ], "summary": "Server-sent event stream", "description": "Long-lived `text/event-stream` carrying only the authenticated user’s mutations. Emits `sync` frames (one per mutation, JSON body `{type,entity,ids,at}` with the sequence number in the SSE `id:` field) and periodic `ping` heartbeats. Reconnect with the `Last-Event-ID` header (or `?last_event_id=`; the header wins) to replay events buffered in the in-memory ring since that id.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Replay events with a greater id (the Last-Event-ID header wins)." }, "required": false, "description": "Replay events with a greater id (the Last-Event-ID header wins).", "name": "last_event_id", "in": "query" } ], "responses": { "200": { "description": "An open event stream of `sync` and `ping` frames.", "content": { "text/event-stream": { "schema": { "type": "string", "example": "event: sync\nid: 12\ndata: {\"type\":\"task.completed\",\"entity\":\"task\",\"ids\":[\"abc\"],\"at\":\"2026-07-15T09:00:00.000Z\"}\n\n" } } } }, "401": { "description": "Missing or invalid credentials." } } } }, "/api/v1/reminders": { "get": { "tags": [ "reminders" ], "summary": "List reminders", "description": "All of the caller’s reminders, optionally scoped to one task via `task_id`.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "task_id", "in": "query" } ], "responses": { "200": { "description": "Reminders", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string" }, "type": { "type": "string", "enum": [ "relative", "absolute", "recurring" ] }, "minute_offset": { "type": "integer", "nullable": true, "minimum": 0 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "nullable": true, "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "string": { "type": "string" }, "recurrence": { "type": "object", "nullable": true, "properties": { "anchor": { "type": "string", "enum": [ "schedule", "completion" ] }, "freq": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "yearly" ] }, "interval": { "type": "integer", "minimum": 1 }, "weekdays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 7 }, { "type": "string", "enum": [ "workday" ] } ] }, "default": [] }, "monthDays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "default": [] }, "ordinal": { "type": "object", "nullable": true, "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 } }, "default": null, "required": [ "nth", "unit", "weekday" ] }, "ordinals": { "type": "array", "items": { "type": "object", "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 }, "month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12 } }, "required": [ "nth", "unit", "weekday", "month" ] }, "default": [] }, "dates": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "month", "day" ] }, "default": [] }, "times": { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "default": [] }, "starting": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "until": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "required": [ "anchor", "freq", "interval" ] } }, "required": [ "date", "time", "string", "recurrence" ] }, "is_auto": { "type": "boolean" }, "fire_at_utc": { "type": "string", "nullable": true }, "fired_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "task_id", "type", "minute_offset", "due", "is_auto", "fire_at_utc", "fired_at", "created_at" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "400": { "description": "Invalid query parameters", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } }, "post": { "tags": [ "reminders" ], "summary": "Create a reminder", "description": "Attaches a reminder to a task. `relative` fires `minute_offset` minutes before the task’s due time and requires the task to have a due date+time; `absolute` fires at its own due date+time; `recurring` fires on its own recurrence. The next fire instant is (re)computed from the task’s timezone-aware due.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string" }, "type": { "type": "string", "enum": [ "relative", "absolute", "recurring" ] }, "minute_offset": { "type": "integer", "minimum": 0, "maximum": 10080 }, "due": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "nullable": true, "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "string": { "type": "string" }, "recurrence": { "type": "object", "nullable": true, "properties": { "anchor": { "type": "string", "enum": [ "schedule", "completion" ] }, "freq": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "yearly" ] }, "interval": { "type": "integer", "minimum": 1 }, "weekdays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 7 }, { "type": "string", "enum": [ "workday" ] } ] }, "default": [] }, "monthDays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "default": [] }, "ordinal": { "type": "object", "nullable": true, "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 } }, "default": null, "required": [ "nth", "unit", "weekday" ] }, "ordinals": { "type": "array", "items": { "type": "object", "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 }, "month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12 } }, "required": [ "nth", "unit", "weekday", "month" ] }, "default": [] }, "dates": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "month", "day" ] }, "default": [] }, "times": { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "default": [] }, "starting": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "until": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "required": [ "anchor", "freq", "interval" ] } }, "required": [ "date", "time", "string", "recurrence" ] } }, "required": [ "task_id", "type" ] } } } }, "responses": { "201": { "description": "Created reminder", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string" }, "type": { "type": "string", "enum": [ "relative", "absolute", "recurring" ] }, "minute_offset": { "type": "integer", "nullable": true, "minimum": 0 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "nullable": true, "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "string": { "type": "string" }, "recurrence": { "type": "object", "nullable": true, "properties": { "anchor": { "type": "string", "enum": [ "schedule", "completion" ] }, "freq": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "yearly" ] }, "interval": { "type": "integer", "minimum": 1 }, "weekdays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 7 }, { "type": "string", "enum": [ "workday" ] } ] }, "default": [] }, "monthDays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "default": [] }, "ordinal": { "type": "object", "nullable": true, "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 } }, "default": null, "required": [ "nth", "unit", "weekday" ] }, "ordinals": { "type": "array", "items": { "type": "object", "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 }, "month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12 } }, "required": [ "nth", "unit", "weekday", "month" ] }, "default": [] }, "dates": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "month", "day" ] }, "default": [] }, "times": { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "default": [] }, "starting": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "until": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "required": [ "anchor", "freq", "interval" ] } }, "required": [ "date", "time", "string", "recurrence" ] }, "is_auto": { "type": "boolean" }, "fire_at_utc": { "type": "string", "nullable": true }, "fired_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "task_id", "type", "minute_offset", "due", "is_auto", "fire_at_utc", "fired_at", "created_at" ] } } } }, "400": { "description": "Validation failed, or a relative reminder on a task with no due time", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Task not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/reminders/test": { "post": { "tags": [ "reminders" ], "summary": "Send a test notification", "description": "Dispatches a canned \"Reminders are working.\" notification to every push subscription and enabled notification channel, returning a per-sink delivery summary. Bypasses the scheduler and never touches any channel’s failure counters.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Per-sink delivery summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "object", "properties": { "sent": { "type": "integer" }, "gone": { "type": "integer" }, "errors": { "type": "integer" } }, "required": [ "sent", "gone", "errors" ] }, "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "outcome": { "type": "string", "enum": [ "delivered", "gone", "error" ] } }, "required": [ "id", "name", "outcome" ] } } }, "required": [ "push", "channels" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/reminders/{id}": { "patch": { "tags": [ "reminders" ], "summary": "Update a reminder", "description": "Changes a relative reminder’s `minute_offset` or an absolute/recurring reminder’s `due`, then recomputes the fire instant (re-arming the reminder when the instant changes).", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "minute_offset": { "type": "integer", "minimum": 0, "maximum": 10080 }, "due": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "nullable": true, "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "string": { "type": "string" }, "recurrence": { "type": "object", "nullable": true, "properties": { "anchor": { "type": "string", "enum": [ "schedule", "completion" ] }, "freq": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "yearly" ] }, "interval": { "type": "integer", "minimum": 1 }, "weekdays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 7 }, { "type": "string", "enum": [ "workday" ] } ] }, "default": [] }, "monthDays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "default": [] }, "ordinal": { "type": "object", "nullable": true, "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 } }, "default": null, "required": [ "nth", "unit", "weekday" ] }, "ordinals": { "type": "array", "items": { "type": "object", "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 }, "month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12 } }, "required": [ "nth", "unit", "weekday", "month" ] }, "default": [] }, "dates": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "month", "day" ] }, "default": [] }, "times": { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "default": [] }, "starting": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "until": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "required": [ "anchor", "freq", "interval" ] } }, "required": [ "date", "time", "string", "recurrence" ] } } } } } }, "responses": { "200": { "description": "Updated reminder", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string" }, "type": { "type": "string", "enum": [ "relative", "absolute", "recurring" ] }, "minute_offset": { "type": "integer", "nullable": true, "minimum": 0 }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "nullable": true, "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "string": { "type": "string" }, "recurrence": { "type": "object", "nullable": true, "properties": { "anchor": { "type": "string", "enum": [ "schedule", "completion" ] }, "freq": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "yearly" ] }, "interval": { "type": "integer", "minimum": 1 }, "weekdays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 7 }, { "type": "string", "enum": [ "workday" ] } ] }, "default": [] }, "monthDays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "default": [] }, "ordinal": { "type": "object", "nullable": true, "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 } }, "default": null, "required": [ "nth", "unit", "weekday" ] }, "ordinals": { "type": "array", "items": { "type": "object", "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 }, "month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12 } }, "required": [ "nth", "unit", "weekday", "month" ] }, "default": [] }, "dates": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "month", "day" ] }, "default": [] }, "times": { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "default": [] }, "starting": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "until": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "required": [ "anchor", "freq", "interval" ] } }, "required": [ "date", "time", "string", "recurrence" ] }, "is_auto": { "type": "boolean" }, "fire_at_utc": { "type": "string", "nullable": true }, "fired_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "task_id", "type", "minute_offset", "due", "is_auto", "fire_at_utc", "fired_at", "created_at" ] } } } }, "404": { "description": "Reminder not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } }, "delete": { "tags": [ "reminders" ], "summary": "Delete a reminder", "description": "Hard-deletes the reminder. Deleting an automatic reminder does not disable auto-reminders — the next write to the task recreates it while the user’s `autoReminderMinutes` still calls for one.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Reminder not found", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/push-subscriptions": { "get": { "tags": [ "push" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "devices", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint": { "type": "string" }, "user_agent": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "last_used_at": { "type": "string", "nullable": true } }, "required": [ "id", "endpoint", "user_agent", "created_at", "last_used_at" ] } } }, "required": [ "results" ] } } } }, "401": { "description": "unauthorized" } } }, "post": { "tags": [ "push" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "maxLength": 2048, "format": "uri" }, "keys": { "type": "object", "properties": { "p256dh": { "type": "string", "minLength": 1 }, "auth": { "type": "string", "minLength": 1 } }, "required": [ "p256dh", "auth" ] }, "user_agent": { "type": "string", "maxLength": 512 } }, "required": [ "endpoint", "keys" ] } } } }, "responses": { "201": { "description": "subscribed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "endpoint": { "type": "string" }, "user_agent": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "last_used_at": { "type": "string", "nullable": true } }, "required": [ "id", "endpoint", "user_agent", "created_at", "last_used_at" ] } } } }, "400": { "description": "validation failed" }, "401": { "description": "unauthorized" } } } }, "/api/v1/push-subscriptions/{id}": { "delete": { "tags": [ "push" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "revoked" }, "401": { "description": "unauthorized" }, "404": { "description": "not found" } } } }, "/api/v1/push/vapid-public-key": { "get": { "tags": [ "push" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "key", "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key": { "type": "string" } }, "required": [ "public_key" ] } } } }, "401": { "description": "unauthorized" } } } }, "/api/v1/channels": { "get": { "tags": [ "channels" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "channels", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "ntfy", "gotify", "webhook" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "config": { "anyOf": [ { "type": "object", "properties": { "server": { "type": "string", "format": "uri", "default": "https://ntfy.sh" }, "topic": { "type": "string", "minLength": 1, "maxLength": 256 }, "token": { "type": "string", "maxLength": 256 } }, "required": [ "topic" ] }, { "type": "object", "properties": { "server": { "type": "string", "format": "uri" }, "app_token": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "server", "app_token" ] }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "minLength": 8, "maxLength": 256 } }, "required": [ "url", "secret" ] } ] }, "consecutive_failures": { "type": "integer" }, "disabled_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "type", "name", "enabled", "config", "consecutive_failures", "disabled_reason", "created_at" ] } } }, "required": [ "results" ] } } } }, "401": { "description": "unauthorized" } } }, "post": { "tags": [ "channels" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ntfy" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "config": { "type": "object", "properties": { "server": { "type": "string", "format": "uri", "default": "https://ntfy.sh" }, "topic": { "type": "string", "minLength": 1, "maxLength": 256 }, "token": { "type": "string", "maxLength": 256 } }, "required": [ "topic" ] } }, "required": [ "type", "name", "config" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gotify" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "config": { "type": "object", "properties": { "server": { "type": "string", "format": "uri" }, "app_token": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "server", "app_token" ] } }, "required": [ "type", "name", "config" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "webhook" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "config": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "minLength": 8, "maxLength": 256 } }, "required": [ "url", "secret" ] } }, "required": [ "type", "name", "config" ] } ] } } } }, "responses": { "201": { "description": "created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "ntfy", "gotify", "webhook" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "config": { "anyOf": [ { "type": "object", "properties": { "server": { "type": "string", "format": "uri", "default": "https://ntfy.sh" }, "topic": { "type": "string", "minLength": 1, "maxLength": 256 }, "token": { "type": "string", "maxLength": 256 } }, "required": [ "topic" ] }, { "type": "object", "properties": { "server": { "type": "string", "format": "uri" }, "app_token": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "server", "app_token" ] }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "minLength": 8, "maxLength": 256 } }, "required": [ "url", "secret" ] } ] }, "consecutive_failures": { "type": "integer" }, "disabled_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "type", "name", "enabled", "config", "consecutive_failures", "disabled_reason", "created_at" ] } } } }, "400": { "description": "invalid channel" }, "401": { "description": "unauthorized" } } } }, "/api/v1/channels/{id}/test": { "post": { "tags": [ "channels" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "test outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "delivered", "gone", "error" ] } }, "required": [ "outcome" ] } } } }, "401": { "description": "unauthorized" }, "404": { "description": "not found" } } } }, "/api/v1/channels/{id}": { "patch": { "tags": [ "channels" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "enabled": { "type": "boolean" }, "config": { "anyOf": [ { "type": "object", "properties": { "server": { "type": "string", "format": "uri", "default": "https://ntfy.sh" }, "topic": { "type": "string", "minLength": 1, "maxLength": 256 }, "token": { "type": "string", "maxLength": 256 } }, "required": [ "topic" ] }, { "type": "object", "properties": { "server": { "type": "string", "format": "uri" }, "app_token": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "server", "app_token" ] }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "minLength": 8, "maxLength": 256 } }, "required": [ "url", "secret" ] } ] } } } } } }, "responses": { "200": { "description": "updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "ntfy", "gotify", "webhook" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "config": { "anyOf": [ { "type": "object", "properties": { "server": { "type": "string", "format": "uri", "default": "https://ntfy.sh" }, "topic": { "type": "string", "minLength": 1, "maxLength": 256 }, "token": { "type": "string", "maxLength": 256 } }, "required": [ "topic" ] }, { "type": "object", "properties": { "server": { "type": "string", "format": "uri" }, "app_token": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "server", "app_token" ] }, { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string", "minLength": 8, "maxLength": 256 } }, "required": [ "url", "secret" ] } ] }, "consecutive_failures": { "type": "integer" }, "disabled_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string" } }, "required": [ "id", "type", "name", "enabled", "config", "consecutive_failures", "disabled_reason", "created_at" ] } } } }, "400": { "description": "invalid channel config" }, "401": { "description": "unauthorized" }, "404": { "description": "not found" } } }, "delete": { "tags": [ "channels" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "deleted" }, "401": { "description": "unauthorized" }, "404": { "description": "not found" } } } }, "/api/v1/ical-token": { "get": { "tags": [ "Calendar" ], "summary": "Get the calendar-feed token (auto-created on first call)", "description": "Returns the read-only iCal feed token and URLs, creating the token on first call. The token in the feed URL IS the credential — anyone with the URL can read the calendar, so treat it as a secret and rotate it if it leaks.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Calendar-feed token and URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "url": { "type": "string" }, "webcal_url": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "token", "url", "webcal_url", "created_at" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/v1/ical-token/rotate": { "post": { "tags": [ "Calendar" ], "summary": "Rotate the calendar-feed token", "description": "Issues a fresh token; the previous feed URL stops working immediately, so existing calendar subscriptions must be re-added with the new URL.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Rotated token and URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "url": { "type": "string" }, "webcal_url": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "token", "url", "webcal_url", "created_at" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/v1/rambles": { "post": { "tags": [ "rambles" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Upload a voice ramble", "description": "Multipart upload (`audio` file field). Persists the audio and starts the transcribe→extract pipeline. Rejects with 409 when no speech-to-text provider is configured, and 413 when the file exceeds the configured upload cap.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "audio": { "type": "string", "format": "binary", "description": "The recorded audio (webm/opus, mp4/m4a, wav, …)." } }, "required": [ "audio" ] } } } }, "responses": { "201": { "description": "Created ramble", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "uploaded", "transcribed", "extracted", "confirmed", "failed" ] }, "audioMime": { "type": "string" }, "audioBytes": { "type": "integer" }, "durationSec": { "type": "number", "nullable": true }, "transcript": { "type": "string", "nullable": true }, "extractedTasks": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "notes": { "type": "string", "nullable": true }, "due": { "type": "string", "nullable": true }, "priority": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 4 }, "labels": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "title", "notes", "due", "priority" ] } }, "error": { "type": "string", "nullable": true }, "failedStage": { "type": "string", "nullable": true, "enum": [ "transcribe", "extract", null ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "audioMime", "audioBytes", "durationSec", "transcript", "extractedTasks", "error", "failedStage", "createdAt", "updatedAt" ] } } } }, "400": { "description": "Missing `audio` field or not a multipart form", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "409": { "description": "No speech-to-text provider is configured", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "413": { "description": "Upload exceeds the configured size cap", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } }, "get": { "tags": [ "rambles" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "List recent rambles", "description": "Newest first, single page (limit 50). `next_cursor` is always null.", "responses": { "200": { "description": "Rambles", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "uploaded", "transcribed", "extracted", "confirmed", "failed" ] }, "audioMime": { "type": "string" }, "audioBytes": { "type": "integer" }, "durationSec": { "type": "number", "nullable": true }, "transcript": { "type": "string", "nullable": true }, "extractedTasks": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "notes": { "type": "string", "nullable": true }, "due": { "type": "string", "nullable": true }, "priority": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 4 }, "labels": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "title", "notes", "due", "priority" ] } }, "error": { "type": "string", "nullable": true }, "failedStage": { "type": "string", "nullable": true, "enum": [ "transcribe", "extract", null ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "audioMime", "audioBytes", "durationSec", "transcript", "extractedTasks", "error", "failedStage", "createdAt", "updatedAt" ] } }, "next_cursor": { "type": "string", "nullable": true, "default": null } }, "required": [ "results" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/rambles/{id}": { "get": { "tags": [ "rambles" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Get a ramble", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Ramble", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "uploaded", "transcribed", "extracted", "confirmed", "failed" ] }, "audioMime": { "type": "string" }, "audioBytes": { "type": "integer" }, "durationSec": { "type": "number", "nullable": true }, "transcript": { "type": "string", "nullable": true }, "extractedTasks": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "notes": { "type": "string", "nullable": true }, "due": { "type": "string", "nullable": true }, "priority": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 4 }, "labels": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "title", "notes", "due", "priority" ] } }, "error": { "type": "string", "nullable": true }, "failedStage": { "type": "string", "nullable": true, "enum": [ "transcribe", "extract", null ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "audioMime", "audioBytes", "durationSec", "transcript", "extractedTasks", "error", "failedStage", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Unknown ramble or foreign owner", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } }, "delete": { "tags": [ "rambles" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Discard a ramble", "description": "Hard-deletes the row and its audio file. Rambles are transient capture state.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "204": { "description": "Discarded" }, "404": { "description": "Unknown ramble", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/rambles/{id}/transcribe": { "post": { "tags": [ "rambles" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Run (or retry) the transcribe stage", "description": "Valid from status `uploaded` or a `failed`@`transcribe`. On success the ramble becomes `transcribed`; on provider failure it becomes `failed` with `failedStage: transcribe` and an error message (returned with HTTP 200, not an error status).", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Ramble", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "uploaded", "transcribed", "extracted", "confirmed", "failed" ] }, "audioMime": { "type": "string" }, "audioBytes": { "type": "integer" }, "durationSec": { "type": "number", "nullable": true }, "transcript": { "type": "string", "nullable": true }, "extractedTasks": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "notes": { "type": "string", "nullable": true }, "due": { "type": "string", "nullable": true }, "priority": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 4 }, "labels": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "title", "notes", "due", "priority" ] } }, "error": { "type": "string", "nullable": true }, "failedStage": { "type": "string", "nullable": true, "enum": [ "transcribe", "extract", null ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "audioMime", "audioBytes", "durationSec", "transcript", "extractedTasks", "error", "failedStage", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Unknown ramble", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "409": { "description": "Ramble is not in a transcribable state", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/rambles/{id}/extract": { "post": { "tags": [ "rambles" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Run (or retry) the extract stage", "description": "Valid from status `transcribed`, `extracted`, or a `failed`@`extract`. Requires a transcript. The `none` extractor also lands on `extracted` for a uniform client flow.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Ramble", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "uploaded", "transcribed", "extracted", "confirmed", "failed" ] }, "audioMime": { "type": "string" }, "audioBytes": { "type": "integer" }, "durationSec": { "type": "number", "nullable": true }, "transcript": { "type": "string", "nullable": true }, "extractedTasks": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "notes": { "type": "string", "nullable": true }, "due": { "type": "string", "nullable": true }, "priority": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 4 }, "labels": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "title", "notes", "due", "priority" ] } }, "error": { "type": "string", "nullable": true }, "failedStage": { "type": "string", "nullable": true, "enum": [ "transcribe", "extract", null ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "audioMime", "audioBytes", "durationSec", "transcript", "extractedTasks", "error", "failedStage", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Unknown ramble", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "409": { "description": "Ramble is not in an extractable state or has no transcript", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/rambles/{id}/confirm": { "post": { "tags": [ "rambles" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Confirm the extracted tasks", "description": "Creates tasks from the (edited) items through the same path as `POST /tasks/quick`, marks the ramble `confirmed`, and deletes the audio file. Valid only from status `extracted`. If task creation throws midway the ramble stays `extracted` and the client may re-confirm (already-created tasks are not rolled back).", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "notes": { "type": "string", "nullable": true }, "due": { "type": "string", "nullable": true }, "priority": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 4 }, "labels": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "title", "notes", "due", "priority" ] }, "minItems": 1, "maxItems": 50 } }, "required": [ "tasks" ] } } } }, "responses": { "200": { "description": "Created task ids", "content": { "application/json": { "schema": { "type": "object", "properties": { "createdTaskIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "createdTaskIds" ] } } } }, "400": { "description": "Invalid confirm body", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Unknown ramble", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "409": { "description": "Ramble is not in the extracted state", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/settings/integrations": { "get": { "tags": [ "integrations" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Effective STT + LLM provider configuration", "description": "Per-slot effective config (user override > instance env > none). Never returns key material — only `hasApiKey` and the `source` of the effective config.", "responses": { "200": { "description": "Effective integrations configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "stt": { "type": "object", "properties": { "provider": { "type": "string", "nullable": true, "enum": [ "openai-compatible", "deepgram", "elevenlabs", null ] }, "baseUrl": { "type": "string", "nullable": true }, "model": { "type": "string", "nullable": true }, "hasApiKey": { "type": "boolean" }, "source": { "type": "string", "enum": [ "user", "env", "none" ] } }, "required": [ "provider", "baseUrl", "model", "hasApiKey", "source" ] }, "llm": { "type": "object", "properties": { "provider": { "type": "string", "nullable": true, "enum": [ "openai-compatible", null ] }, "baseUrl": { "type": "string", "nullable": true }, "model": { "type": "string", "nullable": true }, "hasApiKey": { "type": "boolean" }, "source": { "type": "string", "enum": [ "user", "env", "none" ] } }, "required": [ "provider", "baseUrl", "model", "hasApiKey", "source" ] } }, "required": [ "stt", "llm" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } }, "put": { "tags": [ "integrations" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Update STT + LLM provider configuration", "description": "Slot-level override: a non-null `provider` replaces the whole instance-default slot for this user. `apiKey`: string = set (stored AES-256-GCM encrypted at rest), null = clear, omitted = keep the stored value. `provider: null` reverts the slot to the instance default.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "stt": { "type": "object", "properties": { "provider": { "type": "string", "nullable": true, "enum": [ "openai-compatible", "deepgram", "elevenlabs", null ] }, "baseUrl": { "type": "string", "nullable": true, "maxLength": 500 }, "model": { "type": "string", "nullable": true, "maxLength": 200 }, "apiKey": { "anyOf": [ { "type": "string", "minLength": 1 }, { "nullable": true } ] } }, "required": [ "provider", "baseUrl", "model" ] }, "llm": { "type": "object", "properties": { "provider": { "type": "string", "nullable": true, "enum": [ "openai-compatible", null ] }, "baseUrl": { "type": "string", "nullable": true, "maxLength": 500 }, "model": { "type": "string", "nullable": true, "maxLength": 200 }, "apiKey": { "anyOf": [ { "type": "string", "minLength": 1 }, { "nullable": true } ] } }, "required": [ "provider", "baseUrl", "model" ] } } } } } }, "responses": { "204": { "description": "Saved" }, "400": { "description": "Invalid provider configuration", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/settings/integrations/stt/test": { "post": { "tags": [ "integrations" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Test the speech-to-text provider", "description": "Transcribes a short silent WAV through the candidate config (or the saved/env config when no candidate is supplied). A missing candidate `apiKey` reuses the stored/env key. Provider or transport failures are returned as `{ok:false, detail}` with HTTP 200.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "candidate": { "type": "object", "properties": { "provider": { "type": "string", "nullable": true }, "baseUrl": { "type": "string", "nullable": true, "maxLength": 500 }, "model": { "type": "string", "nullable": true, "maxLength": 200 }, "apiKey": { "anyOf": [ { "type": "string", "minLength": 1 }, { "nullable": true } ] } }, "required": [ "provider", "baseUrl", "model" ] } } } } } }, "responses": { "200": { "description": "Test outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "detail": { "type": "string", "nullable": true } }, "required": [ "ok", "detail" ] } } } }, "400": { "description": "Invalid request body", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/settings/integrations/llm/test": { "post": { "tags": [ "integrations" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Test the LLM task extractor", "description": "Runs the extractor over a fixed sample transcript. When extraction is disabled (no provider, or `none`), returns `{ok:true}` explaining that rambles become a single task. Provider or transport failures are returned as `{ok:false, detail}` with HTTP 200.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "candidate": { "type": "object", "properties": { "provider": { "type": "string", "nullable": true }, "baseUrl": { "type": "string", "nullable": true, "maxLength": 500 }, "model": { "type": "string", "nullable": true, "maxLength": 200 }, "apiKey": { "anyOf": [ { "type": "string", "minLength": 1 }, { "nullable": true } ] } }, "required": [ "provider", "baseUrl", "model" ] } } } } } }, "responses": { "200": { "description": "Test outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "detail": { "type": "string", "nullable": true } }, "required": [ "ok", "detail" ] } } } }, "400": { "description": "Invalid request body", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "401": { "description": "Not authenticated", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/backups": { "get": { "tags": [ "Backups" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "List backups (newest first)", "responses": { "200": { "description": "Backups", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "kind": { "type": "string", "enum": [ "scheduled", "manual", "pre_restore" ] }, "sizeBytes": { "type": "integer", "minimum": 0 }, "includesAttachments": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "filename", "kind", "sizeBytes", "includesAttachments", "createdAt" ] } }, "next_cursor": { "nullable": true } }, "required": [ "results", "next_cursor" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "403": { "description": "Backups require read_write scope", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } }, "post": { "tags": [ "Backups" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Create a manual backup now", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "kind": { "type": "string", "enum": [ "scheduled", "manual", "pre_restore" ] }, "sizeBytes": { "type": "integer", "minimum": 0 }, "includesAttachments": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "filename", "kind", "sizeBytes", "includesAttachments", "createdAt" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "403": { "description": "Backups require read_write scope", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/backups/settings": { "get": { "tags": [ "Backups" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Get backup retention/attachment settings", "responses": { "200": { "description": "Settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "retentionDays": { "type": "integer", "nullable": true }, "includeAttachments": { "type": "boolean", "nullable": true }, "effective": { "type": "object", "properties": { "retentionDays": { "type": "integer" }, "includeAttachments": { "type": "boolean" } }, "required": [ "retentionDays", "includeAttachments" ] } }, "required": [ "retentionDays", "includeAttachments", "effective" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "403": { "description": "Backups require read_write scope", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } }, "patch": { "tags": [ "Backups" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Update backup settings (null field = fall back to env/default)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "retentionDays": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 365 }, "includeAttachments": { "type": "boolean", "nullable": true } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "retentionDays": { "type": "integer", "nullable": true }, "includeAttachments": { "type": "boolean", "nullable": true }, "effective": { "type": "object", "properties": { "retentionDays": { "type": "integer" }, "includeAttachments": { "type": "boolean" } }, "required": [ "retentionDays", "includeAttachments" ] } }, "required": [ "retentionDays", "includeAttachments", "effective" ] } } } }, "400": { "description": "Invalid patch", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "403": { "description": "Backups require read_write scope", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/backups/{filename}/download": { "get": { "tags": [ "Backups" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Download a backup zip", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "filename", "in": "path" } ], "responses": { "200": { "description": "The backup zip", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "403": { "description": "Backups require read_write scope", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "404": { "description": "Unknown or invalid backup filename", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/backups/restore": { "post": { "tags": [ "Backups" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Restore from an uploaded backup zip (replaces ALL data)", "description": "Multipart upload (`file` field, a backup zip, up to 2 GiB). A pre-restore safety snapshot is taken first and the app pauses (503) while the swap runs.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "A backup zip." } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "restored": { "type": "boolean", "enum": [ true ] }, "preRestoreBackup": { "type": "string" } }, "required": [ "restored", "preRestoreBackup" ] } } } }, "400": { "description": "Missing file or invalid/unverifiable backup zip", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "403": { "description": "Backups require read_write scope", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "409": { "description": "A restore is already in progress", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "413": { "description": "Upload exceeds the 2 GiB restore cap", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/import/todoist-csv": { "post": { "tags": [ "import" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Import from a Todoist backup zip", "description": "Multipart form: `file` (a Todoist backup .zip of per-project CSVs) plus an optional `mode` (`dry-run` | `apply`, default `dry-run`). Starts a background job and returns its id; poll `GET /import/jobs/{id}` for progress and the final report.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Todoist backup .zip" }, "mode": { "type": "string", "enum": [ "dry-run", "apply" ], "description": "Import mode (default `dry-run`)." } }, "required": [ "file" ] } } } }, "responses": { "202": { "description": "Import job started", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" } }, "required": [ "jobId" ] } } } }, "400": { "description": "Missing `file` field or not a multipart form", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "409": { "description": "An import is already running", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "413": { "description": "Upload exceeds the 256 MiB import cap", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/import/todoist-api": { "post": { "tags": [ "import" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Import from the Todoist API", "description": "JSON body `{ token, mode?, baseUrl? }`. The token is used only to fetch your Todoist data and is never persisted or logged. `baseUrl` targets a self-hosted mirror. Starts a background job and returns its id; poll `GET /import/jobs/{id}`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "dry-run", "apply" ], "default": "dry-run" }, "baseUrl": { "type": "string", "format": "uri" } }, "required": [ "token" ] } } } }, "responses": { "202": { "description": "Import job started", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string" } }, "required": [ "jobId" ] } } } }, "400": { "description": "Invalid JSON body", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "409": { "description": "An import is already running", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/import/jobs/{id}": { "get": { "tags": [ "import" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Get an import job", "description": "Returns the job status, current progress, and (when finished) the import report.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Import job", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "todoist-csv", "todoist-api" ] }, "mode": { "type": "string", "enum": [ "dry-run", "apply" ] }, "status": { "type": "string", "enum": [ "running", "done", "error" ] }, "progress": { "type": "object", "properties": { "phase": { "type": "string", "enum": [ "uploading", "fetching", "parsing", "applying", "done", "error" ] }, "detail": { "type": "string", "default": "" }, "fetched": { "type": "object", "properties": { "projects": { "type": "integer" }, "sections": { "type": "integer" }, "labels": { "type": "integer" }, "tasks": { "type": "integer" }, "comments": { "type": "integer" }, "skips": { "type": "integer" } } } }, "required": [ "phase" ] }, "report": { "type": "object", "nullable": true, "properties": { "mode": { "type": "string", "enum": [ "dry-run", "apply" ] }, "counts": { "type": "object", "properties": { "projects": { "type": "integer" }, "sections": { "type": "integer" }, "labels": { "type": "integer" }, "tasks": { "type": "integer" }, "comments": { "type": "integer" }, "skips": { "type": "integer" } }, "required": [ "projects", "sections", "labels", "tasks", "comments", "skips" ] }, "created": { "type": "object", "properties": { "projects": { "type": "integer" }, "sections": { "type": "integer" }, "labels": { "type": "integer" }, "tasks": { "type": "integer" }, "comments": { "type": "integer" }, "skips": { "type": "integer" } }, "required": [ "projects", "sections", "labels", "tasks", "comments", "skips" ] }, "skips": { "type": "array", "items": { "type": "object", "properties": { "entity": { "type": "string" }, "ref": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "entity", "ref", "reason" ] } } }, "required": [ "mode", "counts", "created", "skips" ] }, "error": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "finishedAt": { "type": "string", "nullable": true } }, "required": [ "id", "source", "mode", "status", "progress", "report", "error", "createdAt", "finishedAt" ] } } } }, "404": { "description": "Unknown job id", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/productivity": { "get": { "tags": [ "Productivity" ], "summary": "Karma, goals, streaks, and rollups for the current user", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Productivity snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "karmaEnabled": { "type": "boolean" }, "karma": { "type": "object", "properties": { "total": { "type": "integer" }, "level": { "type": "object", "properties": { "name": { "type": "string" }, "floor": { "type": "number" }, "nextFloor": { "type": "number", "nullable": true }, "progress": { "type": "number" } }, "required": [ "name", "floor", "nextFloor", "progress" ] }, "trend": { "type": "string", "enum": [ "up", "down", "flat" ] } }, "required": [ "total", "level", "trend" ] }, "goals": { "type": "object", "properties": { "dailyGoal": { "type": "integer", "minimum": 1, "maximum": 100 }, "weeklyGoal": { "type": "integer", "minimum": 1, "maximum": 1000 }, "daysOff": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "vacationMode": { "type": "boolean" } }, "required": [ "dailyGoal", "weeklyGoal", "daysOff", "vacationMode" ] }, "today": { "type": "object", "properties": { "date": { "type": "string" }, "completed": { "type": "integer" }, "goalMet": { "type": "boolean" } }, "required": [ "date", "completed", "goalMet" ] }, "week": { "type": "object", "properties": { "start": { "type": "string" }, "completed": { "type": "integer" }, "goalMet": { "type": "boolean" } }, "required": [ "start", "completed", "goalMet" ] }, "streaks": { "type": "object", "properties": { "daily": { "type": "object", "properties": { "current": { "type": "integer" }, "longest": { "type": "integer" } }, "required": [ "current", "longest" ] }, "weekly": { "type": "object", "properties": { "current": { "type": "integer" }, "longest": { "type": "integer" } }, "required": [ "current", "longest" ] } }, "required": [ "daily", "weekly" ] }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "completed": { "type": "integer" }, "goalMet": { "type": "boolean" }, "dayOff": { "type": "boolean" }, "vacation": { "type": "boolean" } }, "required": [ "date", "completed", "goalMet", "dayOff", "vacation" ] } }, "weeks": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "completed": { "type": "integer" }, "goalMet": { "type": "boolean" } }, "required": [ "start", "completed", "goalMet" ] } }, "karmaHistory": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "delta": { "type": "integer" }, "runningTotal": { "type": "integer" } }, "required": [ "date", "delta", "runningTotal" ] } } }, "required": [ "karmaEnabled", "karma", "goals", "today", "week", "streaks", "days", "weeks", "karmaHistory" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/v1/productivity/settings": { "get": { "tags": [ "Productivity" ], "summary": "Goal + karma settings", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Productivity settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "dailyGoal": { "type": "integer", "minimum": 1, "maximum": 100 }, "weeklyGoal": { "type": "integer", "minimum": 1, "maximum": 1000 }, "daysOff": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "vacationMode": { "type": "boolean" }, "karmaEnabled": { "type": "boolean" } }, "required": [ "dailyGoal", "weeklyGoal", "daysOff", "vacationMode", "karmaEnabled" ] } } } }, "401": { "description": "Unauthorized" } } }, "patch": { "tags": [ "Productivity" ], "summary": "Update goal + karma settings", "description": "Partial update of dailyGoal / weeklyGoal / daysOff / vacationMode / karmaEnabled. Values are merged into the shared user-settings document and re-validated.", "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "dailyGoal": { "type": "integer", "minimum": 1, "maximum": 100 }, "weeklyGoal": { "type": "integer", "minimum": 1, "maximum": 1000 }, "daysOff": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "vacationMode": { "type": "boolean" }, "karmaEnabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated productivity settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "dailyGoal": { "type": "integer", "minimum": 1, "maximum": 100 }, "weeklyGoal": { "type": "integer", "minimum": 1, "maximum": 1000 }, "daysOff": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "vacationMode": { "type": "boolean" }, "karmaEnabled": { "type": "boolean" } }, "required": [ "dailyGoal", "weeklyGoal", "daysOff", "vacationMode", "karmaEnabled" ] } } } }, "400": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "401": { "description": "Unauthorized" } } } }, "/api/v1/export/json": { "get": { "tags": [ "export" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Export all data as canonical JSON", "description": "Downloads a single, self-contained JSON document of your whole account (projects, sections, labels, filters, tasks, comments, reminders, settings). Completed tasks are included; soft-deleted rows and attachment file bytes are not. Requires a session or `read_write` token.", "responses": { "200": { "description": "The export document (served as a file download)", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "opentask-export" ] }, "version": { "type": "number", "enum": [ 1 ] }, "exportedAt": { "type": "string" }, "settings": { "type": "object", "additionalProperties": { "nullable": true } }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "color": { "type": "string" }, "parentId": { "type": "string", "nullable": true }, "childOrder": { "type": "integer" }, "isFavorite": { "type": "boolean" }, "isArchived": { "type": "boolean" }, "isCollapsed": { "type": "boolean" }, "isInbox": { "type": "boolean" }, "viewPrefs": { "nullable": true } }, "required": [ "id", "name", "description", "color", "parentId", "childOrder", "isFavorite", "isArchived", "isCollapsed", "isInbox" ] } }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "name": { "type": "string" }, "sectionOrder": { "type": "integer" }, "isArchived": { "type": "boolean" }, "isCollapsed": { "type": "boolean" } }, "required": [ "id", "projectId", "name", "sectionOrder", "isArchived", "isCollapsed" ] } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "itemOrder": { "type": "integer" }, "isFavorite": { "type": "boolean" } }, "required": [ "id", "name", "color", "itemOrder", "isFavorite" ] } }, "filters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "query": { "type": "string" }, "color": { "type": "string" }, "itemOrder": { "type": "integer" }, "isFavorite": { "type": "boolean" } }, "required": [ "id", "name", "query", "color", "itemOrder", "isFavorite" ] } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "sectionId": { "type": "string", "nullable": true }, "parentId": { "type": "string", "nullable": true }, "childOrder": { "type": "integer" }, "content": { "type": "string" }, "description": { "type": "string" }, "priority": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] } ] }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "nullable": true, "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "string": { "type": "string" }, "recurrence": { "type": "object", "nullable": true, "properties": { "anchor": { "type": "string", "enum": [ "schedule", "completion" ] }, "freq": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "yearly" ] }, "interval": { "type": "integer", "minimum": 1 }, "weekdays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 7 }, { "type": "string", "enum": [ "workday" ] } ] }, "default": [] }, "monthDays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "default": [] }, "ordinal": { "type": "object", "nullable": true, "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 } }, "default": null, "required": [ "nth", "unit", "weekday" ] }, "ordinals": { "type": "array", "items": { "type": "object", "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 }, "month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12 } }, "required": [ "nth", "unit", "weekday", "month" ] }, "default": [] }, "dates": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "month", "day" ] }, "default": [] }, "times": { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "default": [] }, "starting": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "until": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "required": [ "anchor", "freq", "interval" ] } }, "required": [ "date", "time", "string", "recurrence" ] }, "deadline": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "durationMin": { "type": "integer", "nullable": true }, "labels": { "type": "array", "items": { "type": "string" } }, "uncompletable": { "type": "boolean" }, "completedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "sectionId", "parentId", "childOrder", "content", "description", "priority", "due", "deadline", "durationMin", "labels", "uncompletable", "completedAt", "createdAt", "updatedAt" ] } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "content": { "type": "string" }, "attachment": { "type": "object", "nullable": true, "properties": { "filename": { "type": "string" }, "size": { "type": "integer" }, "type": { "type": "string" } }, "required": [ "filename", "size", "type" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "taskId", "content", "attachment", "createdAt" ] } }, "reminders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "type": { "type": "string", "enum": [ "relative", "absolute", "recurring" ] }, "minuteOffset": { "type": "integer", "nullable": true }, "due": { "type": "object", "nullable": true, "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time": { "type": "string", "nullable": true, "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "string": { "type": "string" }, "recurrence": { "type": "object", "nullable": true, "properties": { "anchor": { "type": "string", "enum": [ "schedule", "completion" ] }, "freq": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly", "yearly" ] }, "interval": { "type": "integer", "minimum": 1 }, "weekdays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 7 }, { "type": "string", "enum": [ "workday" ] } ] }, "default": [] }, "monthDays": { "type": "array", "items": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "default": [] }, "ordinal": { "type": "object", "nullable": true, "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 } }, "default": null, "required": [ "nth", "unit", "weekday" ] }, "ordinals": { "type": "array", "items": { "type": "object", "properties": { "nth": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 31 }, { "type": "string", "enum": [ "last" ] } ] }, "unit": { "type": "string", "enum": [ "weekday", "workday", "day" ] }, "weekday": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 7 }, "month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12 } }, "required": [ "nth", "unit", "weekday", "month" ] }, "default": [] }, "dates": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer", "minimum": 1, "maximum": 12 }, "day": { "type": "integer", "minimum": 1, "maximum": 31 } }, "required": [ "month", "day" ] }, "default": [] }, "times": { "type": "array", "items": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "default": [] }, "starting": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null }, "until": { "type": "string", "nullable": true, "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "default": null } }, "required": [ "anchor", "freq", "interval" ] } }, "required": [ "date", "time", "string", "recurrence" ] }, "isAuto": { "type": "boolean" }, "fireAtUtc": { "type": "string", "nullable": true }, "firedAt": { "type": "string", "nullable": true } }, "required": [ "id", "taskId", "type", "minuteOffset", "due", "isAuto", "fireAtUtc", "firedAt" ] } } }, "required": [ "format", "version", "exportedAt", "settings", "projects", "sections", "labels", "filters", "tasks", "comments", "reminders" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "403": { "description": "A read-only token cannot export all data", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } }, "/api/v1/export/csv": { "get": { "tags": [ "export" ], "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Export all data as a Todoist-compatible CSV zip", "description": "Downloads a zip with one CSV per non-archived project, in the same per-project column shape Todoist's backup export uses (re-importable here or into Todoist). Active tasks only. Requires a session or `read_write` token.", "responses": { "200": { "description": "A zip of per-project CSV files (served as a file download)", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } }, "403": { "description": "A read-only token cannot export all data", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" } }, "required": [ "type", "title", "status" ] } } } } } } } }, "servers": [ { "url": "https://tryopentask.pranavkarra.me/api/v1", "description": "Public demo instance" }, { "url": "http://localhost:7968/api/v1", "description": "Your own instance" } ] }