{ "openapi": "3.0.3", "info": { "title": "trydeepwork API", "version": "1.0.0", "description": "REST API for trydeepwork tasks, objectives, deep work sessions, and week plans. Designed for AI agents and external integrations.", "contact": { "url": "https://trydeepwork.com" } }, "servers": [ { "url": "https://api.trydeepwork.com" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "Task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "completed", "abandoned", "inbox" ] }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "urgency": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Derived from deadline + is_hard_deadline" }, "estimated_hours": { "type": "number", "nullable": true }, "deadline_ts": { "type": "integer", "nullable": true, "description": "Unix ms" }, "deadline_date": { "type": "string", "nullable": true, "description": "YYYY-MM-DD" }, "is_hard_deadline": { "type": "boolean" }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "objective_id": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "completed": { "type": "boolean" } } } }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } }, "Objective": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "completed", "archived", "paused" ] }, "deadline_ts": { "type": "integer", "nullable": true }, "deadline_date": { "type": "string", "nullable": true }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "milestone_count": { "type": "integer" }, "milestones_completed": { "type": "integer" }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "is_completed": { "type": "boolean" }, "target_date_ts": { "type": "integer", "nullable": true }, "target_date": { "type": "string", "nullable": true } } } }, "order": { "type": "integer", "nullable": true }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } }, "Milestone": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "is_completed": { "type": "boolean" }, "target_date_ts": { "type": "integer", "nullable": true }, "target_date": { "type": "string", "nullable": true } } }, "Session": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string", "nullable": true }, "task_title": { "type": "string", "nullable": true }, "start_ts": { "type": "integer" }, "start_date": { "type": "string" }, "start_time": { "type": "string" }, "end_ts": { "type": "integer", "nullable": true }, "duration_minutes": { "type": "integer" }, "duration_hours": { "type": "number" }, "level": { "type": "string", "nullable": true, "description": "L0|L1|L2|L3" }, "rating": { "type": "integer", "nullable": true }, "intent": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "music_type": { "type": "string", "nullable": true }, "breaks_count": { "type": "integer" } } }, "ScheduledSession": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string", "nullable": true }, "task_title": { "type": "string", "nullable": true }, "scheduled_start_ts": { "type": "integer" }, "scheduled_start_date": { "type": "string" }, "scheduled_start_time": { "type": "string" }, "scheduled_end_ts": { "type": "integer" }, "duration_minutes": { "type": "integer" }, "timezone": { "type": "string", "nullable": true }, "is_completed": { "type": "boolean" }, "actual_session_id": { "type": "string", "nullable": true }, "google_calendar_event_id": { "type": "string", "nullable": true } } } }, "responses": { "Unauthorized": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "BadRequest": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "NotFound": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "Conflict": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } } } }, "paths": { "/getTasks": { "get": { "summary": "List tasks", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "completed", "abandoned", "inbox", "all" ], "default": "active" } }, { "name": "impact", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high" ] } }, { "name": "urgency", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high" ] } }, { "name": "objective_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "completed", "abandoned", "inbox" ] }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "urgency": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Derived from deadline + is_hard_deadline" }, "estimated_hours": { "type": "number", "nullable": true }, "deadline_ts": { "type": "integer", "nullable": true, "description": "Unix ms" }, "deadline_date": { "type": "string", "nullable": true, "description": "YYYY-MM-DD" }, "is_hard_deadline": { "type": "boolean" }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "objective_id": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "completed": { "type": "boolean" } } } }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/getTask": { "get": { "summary": "Get a single task", "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Task", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "completed", "abandoned", "inbox" ] }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "urgency": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Derived from deadline + is_hard_deadline" }, "estimated_hours": { "type": "number", "nullable": true }, "deadline_ts": { "type": "integer", "nullable": true, "description": "Unix ms" }, "deadline_date": { "type": "string", "nullable": true, "description": "YYYY-MM-DD" }, "is_hard_deadline": { "type": "boolean" }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "objective_id": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "completed": { "type": "boolean" } } } }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/createTask": { "post": { "summary": "Create a task", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "estimated_hours" ], "properties": { "title": { "type": "string", "maxLength": 256 }, "estimated_hours": { "type": "number", "minimum": 0.08, "maximum": 99 }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ] }, "deadline": { "type": "integer", "description": "Unix ms" }, "is_hard_deadline": { "type": "boolean" }, "objective_id": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } } } }, "inbox": { "type": "boolean", "default": false, "description": "If true, task lands in inbox (untriaged)" } } } } } }, "responses": { "201": { "description": "Task", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "completed", "abandoned", "inbox" ] }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "urgency": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Derived from deadline + is_hard_deadline" }, "estimated_hours": { "type": "number", "nullable": true }, "deadline_ts": { "type": "integer", "nullable": true, "description": "Unix ms" }, "deadline_date": { "type": "string", "nullable": true, "description": "YYYY-MM-DD" }, "is_hard_deadline": { "type": "boolean" }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "objective_id": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "completed": { "type": "boolean" } } } }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/updateTask": { "post": { "summary": "Update task fields", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id" ], "properties": { "task_id": { "type": "string" }, "title": { "type": "string", "maxLength": 256 }, "estimated_hours": { "type": "number", "minimum": 0.08, "maximum": 99 }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ] }, "deadline": { "type": "integer", "nullable": true }, "is_hard_deadline": { "type": "boolean" }, "objective_id": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Task", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "completed", "abandoned", "inbox" ] }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "urgency": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Derived from deadline + is_hard_deadline" }, "estimated_hours": { "type": "number", "nullable": true }, "deadline_ts": { "type": "integer", "nullable": true, "description": "Unix ms" }, "deadline_date": { "type": "string", "nullable": true, "description": "YYYY-MM-DD" }, "is_hard_deadline": { "type": "boolean" }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "objective_id": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "completed": { "type": "boolean" } } } }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/completeTask": { "post": { "summary": "Mark task complete/incomplete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id" ], "properties": { "task_id": { "type": "string" }, "completed": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Task", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "completed", "abandoned", "inbox" ] }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "urgency": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Derived from deadline + is_hard_deadline" }, "estimated_hours": { "type": "number", "nullable": true }, "deadline_ts": { "type": "integer", "nullable": true, "description": "Unix ms" }, "deadline_date": { "type": "string", "nullable": true, "description": "YYYY-MM-DD" }, "is_hard_deadline": { "type": "boolean" }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "objective_id": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "completed": { "type": "boolean" } } } }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/abandonTask": { "post": { "summary": "Abandon a task", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id" ], "properties": { "task_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Task", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "completed", "abandoned", "inbox" ] }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "urgency": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Derived from deadline + is_hard_deadline" }, "estimated_hours": { "type": "number", "nullable": true }, "deadline_ts": { "type": "integer", "nullable": true, "description": "Unix ms" }, "deadline_date": { "type": "string", "nullable": true, "description": "YYYY-MM-DD" }, "is_hard_deadline": { "type": "boolean" }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "objective_id": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "completed": { "type": "boolean" } } } }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/getObjectives": { "get": { "summary": "List objectives", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "completed", "archived", "paused", "all" ], "default": "active" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Objectives", "content": { "application/json": { "schema": { "type": "object", "properties": { "objectives": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "completed", "archived", "paused" ] }, "deadline_ts": { "type": "integer", "nullable": true }, "deadline_date": { "type": "string", "nullable": true }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "milestone_count": { "type": "integer" }, "milestones_completed": { "type": "integer" }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "is_completed": { "type": "boolean" }, "target_date_ts": { "type": "integer", "nullable": true }, "target_date": { "type": "string", "nullable": true } } } }, "order": { "type": "integer", "nullable": true }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/getObjective": { "get": { "summary": "Get a single objective", "parameters": [ { "name": "objective_id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Objective", "content": { "application/json": { "schema": { "type": "object", "properties": { "objective": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "completed", "archived", "paused" ] }, "deadline_ts": { "type": "integer", "nullable": true }, "deadline_date": { "type": "string", "nullable": true }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "milestone_count": { "type": "integer" }, "milestones_completed": { "type": "integer" }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "is_completed": { "type": "boolean" }, "target_date_ts": { "type": "integer", "nullable": true }, "target_date": { "type": "string", "nullable": true } } } }, "order": { "type": "integer", "nullable": true }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/createObjective": { "post": { "summary": "Create an objective", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "description" ], "properties": { "title": { "type": "string", "maxLength": 50 }, "description": { "type": "string", "maxLength": 500 }, "color": { "type": "string" }, "deadline": { "type": "integer" }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "target_date": { "type": "integer", "nullable": true } } } } } } } } }, "responses": { "201": { "description": "Objective", "content": { "application/json": { "schema": { "type": "object", "properties": { "objective": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "completed", "archived", "paused" ] }, "deadline_ts": { "type": "integer", "nullable": true }, "deadline_date": { "type": "string", "nullable": true }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "milestone_count": { "type": "integer" }, "milestones_completed": { "type": "integer" }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "is_completed": { "type": "boolean" }, "target_date_ts": { "type": "integer", "nullable": true }, "target_date": { "type": "string", "nullable": true } } } }, "order": { "type": "integer", "nullable": true }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/updateObjective": { "post": { "summary": "Update objective fields", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "objective_id" ], "properties": { "objective_id": { "type": "string" }, "title": { "type": "string", "maxLength": 50 }, "description": { "type": "string", "maxLength": 500 }, "color": { "type": "string", "nullable": true }, "deadline": { "type": "integer", "nullable": true }, "milestones": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Objective", "content": { "application/json": { "schema": { "type": "object", "properties": { "objective": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "completed", "archived", "paused" ] }, "deadline_ts": { "type": "integer", "nullable": true }, "deadline_date": { "type": "string", "nullable": true }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "milestone_count": { "type": "integer" }, "milestones_completed": { "type": "integer" }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "is_completed": { "type": "boolean" }, "target_date_ts": { "type": "integer", "nullable": true }, "target_date": { "type": "string", "nullable": true } } } }, "order": { "type": "integer", "nullable": true }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/completeObjective": { "post": { "summary": "Complete objective", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "objective_id" ], "properties": { "objective_id": { "type": "string" }, "completed": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Objective", "content": { "application/json": { "schema": { "type": "object", "properties": { "objective": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "completed", "archived", "paused" ] }, "deadline_ts": { "type": "integer", "nullable": true }, "deadline_date": { "type": "string", "nullable": true }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "milestone_count": { "type": "integer" }, "milestones_completed": { "type": "integer" }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "is_completed": { "type": "boolean" }, "target_date_ts": { "type": "integer", "nullable": true }, "target_date": { "type": "string", "nullable": true } } } }, "order": { "type": "integer", "nullable": true }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/archiveObjective": { "post": { "summary": "Archive objective", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "objective_id" ], "properties": { "objective_id": { "type": "string" }, "archived": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Objective", "content": { "application/json": { "schema": { "type": "object", "properties": { "objective": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "completed", "archived", "paused" ] }, "deadline_ts": { "type": "integer", "nullable": true }, "deadline_date": { "type": "string", "nullable": true }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "milestone_count": { "type": "integer" }, "milestones_completed": { "type": "integer" }, "milestones": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "is_completed": { "type": "boolean" }, "target_date_ts": { "type": "integer", "nullable": true }, "target_date": { "type": "string", "nullable": true } } } }, "order": { "type": "integer", "nullable": true }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/getWeekPlan": { "get": { "summary": "Get a week's plan", "parameters": [ { "name": "week_start", "in": "query", "required": true, "schema": { "type": "integer", "description": "Monday midnight, unix ms" } } ], "responses": { "200": { "description": "Week plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "week_start_ts": { "type": "integer" }, "is_locked": { "type": "boolean" }, "locked_at": { "type": "integer", "nullable": true }, "task_ids": { "type": "array", "items": { "type": "string" } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "completed", "abandoned", "inbox" ] }, "impact": { "type": "string", "enum": [ "low", "medium", "high" ], "nullable": true }, "urgency": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Derived from deadline + is_hard_deadline" }, "estimated_hours": { "type": "number", "nullable": true }, "deadline_ts": { "type": "integer", "nullable": true, "description": "Unix ms" }, "deadline_date": { "type": "string", "nullable": true, "description": "YYYY-MM-DD" }, "is_hard_deadline": { "type": "boolean" }, "is_overdue": { "type": "boolean" }, "days_until_deadline": { "type": "integer", "nullable": true }, "objective_id": { "type": "string", "nullable": true }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "completed": { "type": "boolean" } } } }, "created_at": { "type": "integer", "nullable": true }, "created_date": { "type": "string", "nullable": true }, "completed_at": { "type": "integer", "nullable": true }, "completed_date": { "type": "string", "nullable": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/updateWeekPlan": { "post": { "summary": "Add/remove tasks in the week plan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "week_start" ], "properties": { "week_start": { "type": "integer" }, "add": { "type": "array", "items": { "type": "string" } }, "remove": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Updated plan" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/lockWeekPlan": { "post": { "summary": "Lock the week plan (Mon-Wed only, >=3 tasks, >=1 high-impact)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "week_start" ], "properties": { "week_start": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Locked" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/getSessions": { "get": { "summary": "List completed deep work sessions", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "integer", "description": "Unix ms, default now-7d" } }, { "name": "to", "in": "query", "schema": { "type": "integer", "description": "Unix ms, default now" } }, { "name": "task_id", "in": "query", "schema": { "type": "string" } }, { "name": "objective_id", "in": "query", "schema": { "type": "string" } }, { "name": "level", "in": "query", "schema": { "type": "string", "enum": [ "L0", "L1", "L2", "L3" ] } }, { "name": "min_rating", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string", "nullable": true }, "task_title": { "type": "string", "nullable": true }, "start_ts": { "type": "integer" }, "start_date": { "type": "string" }, "start_time": { "type": "string" }, "end_ts": { "type": "integer", "nullable": true }, "duration_minutes": { "type": "integer" }, "duration_hours": { "type": "number" }, "level": { "type": "string", "nullable": true, "description": "L0|L1|L2|L3" }, "rating": { "type": "integer", "nullable": true }, "intent": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "music_type": { "type": "string", "nullable": true }, "breaks_count": { "type": "integer" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/getScheduledSessions": { "get": { "summary": "List upcoming/scheduled sessions", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "integer", "description": "Unix ms, default now" } }, { "name": "to", "in": "query", "schema": { "type": "integer", "description": "Unix ms, default now+30d" } }, { "name": "task_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Scheduled sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "task_id": { "type": "string", "nullable": true }, "task_title": { "type": "string", "nullable": true }, "scheduled_start_ts": { "type": "integer" }, "scheduled_start_date": { "type": "string" }, "scheduled_start_time": { "type": "string" }, "scheduled_end_ts": { "type": "integer" }, "duration_minutes": { "type": "integer" }, "timezone": { "type": "string", "nullable": true }, "is_completed": { "type": "boolean" }, "actual_session_id": { "type": "string", "nullable": true }, "google_calendar_event_id": { "type": "string", "nullable": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/createScheduledSession": { "post": { "summary": "Schedule a deep work session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "task_id", "scheduled_start_ts", "duration_minutes", "timezone" ], "properties": { "task_id": { "type": "string" }, "scheduled_start_ts": { "type": "integer", "description": "Future unix ms" }, "duration_minutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "timezone": { "type": "string", "description": "IANA timezone, e.g. America/New_York" } } } } } }, "responses": { "201": { "description": "Scheduled" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/deleteScheduledSession": { "post": { "summary": "Delete a scheduled session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } } } }