{ "openapi": "3.1.0", "info": { "title": "ADHDOS cloud data API", "version": "1.1.0", "description": "REST v1 data contract. Bearer key and active Pro subscription required. Scope: cloud-synced data only. After quota migration: 60 requests/minute/account plus daily/monthly request and response budgets; writes require operation IDs. See cloud-api.html for compatibility, authorization and sync semantics." }, "servers": [ { "url": "https://adhdos.app/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/tasks": { "get": { "operationId": "listTasks", "summary": "List tasks", "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "archived", "cancelled" ], "default": "active" }, "description": "Cannot combine with includeArchived/includeCancelled." }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "includeCancelled", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "done", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "partition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "brain-dump-primary", "brain-dump-secondary" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskList" } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createTasks", "summary": "Create a task or atomically import multiline tasks", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Unique new operation ID. Retry with the same ID and body for up to 7 days. Different contents return 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTask" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TaskResult" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } }, "required": [ "tasks" ] } ] } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks/{id}": { "patch": { "operationId": "updateTask", "summary": "Update a task, patch subtasks, cancel an active task, or like an archived task", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded entity ID from the last read." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Unique new operation ID. Retry with the same ID and body for up to 7 days. Different contents return 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTask" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResult" } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks/{id}/complete": { "post": { "operationId": "completeTask", "summary": "Mark done without archiving or awarding desktop XP", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded entity ID from the last read." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Unique new operation ID. Retry with the same ID and body for up to 7 days. Different contents return 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInput" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResult" } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks/{id}/archive": { "post": { "operationId": "archiveTask", "summary": "Archive an already completed task", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded entity ID from the last read." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Unique new operation ID. Retry with the same ID and body for up to 7 days. Different contents return 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInput" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResult" } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/board-items": { "get": { "operationId": "listBoardItems", "summary": "List Board items or partition names", "description": "tabsOnly=true omits items. recent sorts by creation time; since filters by update/creation time.", "parameters": [ { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "widget" ] }, "description": "Compact widget preview: up to 5 displayed items, with total counting the selected page before this display cap. Items contain id, title (120 chars) and preview (80 chars). Cannot combine with tabsOnly=true or includeFullContent=true." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 30 } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Date-parseable lower bound on updatedAt/createdAt." }, { "name": "tabsOnly", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "tab", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 4000 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "recent", "snapshot" ], "default": "recent" } }, { "name": "includeFullContent", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "contentLimit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 80, "maximum": 2000, "default": 500 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "exportedAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." }, "tabs": { "type": "array", "items": { "type": "string" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BoardItem" } } }, "required": [ "exportedAt", "tabs" ] }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "number" } ], "description": "Opaque ID. Preserve original type; encode when used in a URL." }, "title": { "type": "string", "maxLength": 120 }, "preview": { "type": "string", "maxLength": 80 } }, "required": [ "id", "title", "preview" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0 } }, "required": [ "items", "total" ], "additionalProperties": false } ] } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createBoardItem", "summary": "Create Board content with an optional initial thought", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Unique new operation ID. Retry with the same ID and body for up to 7 days. Different contents return 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBoard" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardResult" } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/board-items/{id}/thoughts": { "post": { "operationId": "appendBoardThought", "summary": "Append a thought without replacing existing content", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded entity ID from the last read." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Unique new operation ID. Retry with the same ID and body for up to 7 days. Different contents return 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendThought" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardResult" } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/board-items/{id}/delete": { "post": { "operationId": "deleteBoardItem", "summary": "Move Board content and thoughts to trash", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded entity ID from the last read." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": "Unique new operation ID. Retry with the same ID and body for up to 7 days. Different contents return 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInput" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "const": true }, "id": { "type": "string" } }, "required": [ "deleted", "id" ] } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/board-items/{id}/image": { "get": { "operationId": "getBoardImage", "summary": "Get a 300-second metered image URL (every download consumes the shared account budget)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded entity ID from the last read." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "integer", "description": "Unix milliseconds" } }, "required": [ "url", "expiresAt" ] } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/search": { "get": { "operationId": "search", "summary": "Search tasks and Board", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 4000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "task" }, "item": { "$ref": "#/components/schemas/Task" } }, "required": [ "type", "item" ] }, { "type": "object", "properties": { "type": { "const": "board" }, "item": { "$ref": "#/components/schemas/BoardItem" } }, "required": [ "type", "item" ] } ] } } }, "required": [ "query", "results" ] } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/today-context": { "get": { "operationId": "getTodayContext", "summary": "Read UTC today context", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "exportedAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "overdueTasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "recentBoardItems": { "type": "array", "items": { "$ref": "#/components/schemas/BoardItem" } }, "cycle": {} }, "required": [ "date", "exportedAt", "tasks", "overdueTasks", "recentBoardItems", "cycle" ] } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/snapshot": { "get": { "operationId": "getSnapshot", "summary": "Read the allowlisted full cloud snapshot", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshot": { "$ref": "#/components/schemas/Snapshot" } }, "required": [ "snapshot" ] } } } }, "400": { "description": "Invalid fields/query or missing operation ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "subscription_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or endpoint not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version/operation conflict, limits or missing cloud sync", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body or database response exceeds its size cap; reduce the page or use summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Missing expectedUpdatedAt (task writes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Account rate, daily/monthly request, response budget or snapshot limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the relevant rate/day/month window resets." } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "adhdos_<64 hex characters>" } }, "schemas": { "Task": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "number" } ], "description": "Opaque ID. Preserve original type; encode when used in a URL." }, "text": { "type": "string" }, "done": { "type": [ "boolean", "string" ] }, "dueDate": { "type": [ "string", "null" ], "description": "Valid YYYY-MM-DD or ISO datetime with timezone; null clears the date. Server validates calendar dates." }, "partition": { "type": "string", "enum": [ "brain-dump-primary", "brain-dump-secondary" ] }, "order": { "type": "number" }, "subtasks": { "type": "array", "items": { "$ref": "#/components/schemas/Subtask" } }, "createdAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." }, "updatedAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." }, "source": { "type": "string", "enum": [ "active", "completed", "archived", "cancelled" ] }, "liked": { "type": "boolean" }, "archivedAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." }, "cancelledAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." } }, "required": [ "id", "text" ], "additionalProperties": true, "description": "Raw stored task for ordinary lists and writes; normalized for combined lists/search/today. Legacy fields may be absent." }, "Subtask": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "number" } ], "description": "Opaque ID. Preserve original type; encode when used in a URL." }, "text": { "type": "string" }, "done": { "type": [ "boolean", "string" ] }, "dueDate": { "type": [ "string", "null" ], "description": "Valid YYYY-MM-DD or ISO datetime with timezone; null clears the date. Server validates calendar dates." }, "createdAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." }, "updatedAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." } }, "required": [], "additionalProperties": true }, "Thought": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "number" } ], "description": "Opaque ID. Preserve original type; encode when used in a URL." }, "content": { "type": "string" }, "createdAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." }, "updatedAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." } }, "required": [], "additionalProperties": true }, "BoardItem": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "number" } ], "description": "Opaque ID. Preserve original type; encode when used in a URL." }, "content": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "string" }, "tab": { "type": [ "string", "null" ] }, "partition": { "type": "string" }, "pinned": { "type": "boolean" }, "thoughts": { "type": "array", "items": { "$ref": "#/components/schemas/Thought" } }, "createdAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." }, "updatedAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." }, "contentTruncated": { "type": "boolean" } }, "required": [ "id", "content" ], "additionalProperties": true, "description": "Writes return raw storage fields (partition); list/search return normalized fields (tab)." }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "task": { "$ref": "#/components/schemas/Task" } }, "required": [ "error" ], "additionalProperties": true }, "TaskResult": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Task" } }, "required": [ "task" ] }, "BoardResult": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/BoardItem" } }, "required": [ "item" ] }, "TaskList": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "total": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } }, "required": [ "tasks", "total", "nextOffset" ] }, "Snapshot": { "type": "object", "properties": { "app": { "type": "string" }, "source": { "const": "cloud-sync" }, "readonly": { "const": true }, "exportedAt": { "type": [ "string", "number", "null" ], "description": "Legacy timestamps may be strings, Unix milliseconds or null. Preserve exactly." }, "data": { "type": "object", "properties": { "adhd-tasks": {}, "adhd-archived-tasks": {}, "adhd-cancelled-tasks": {}, "adhd-pasteboard": {}, "adhd-pasteboard-tabs": {}, "adhd-pasteboard-archived-tabs": {}, "adhd-cycle": {}, "adhd-saved-layouts": {}, "adhd-recent-archive-searches": {}, "adhd-reframer-thoughts-v7": {}, "adhd-reframer-active-tags-v2": {}, "adhd-neuro-menu-v5": {}, "adhd-xp": {}, "adhd-xp-multiplier": {}, "adhd-deleted-ids": {}, "adhd-trash-bin": {} }, "additionalProperties": true, "description": "Allowlisted export keys; absent modules omitted. Treat non-task/Board values as opaque read-only exports. Not a writable storage model; see CLOUD_API.md." } }, "required": [ "source", "exportedAt", "data" ] }, "CreateTask": { "oneOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Trimmed task text, 1-5000 characters." }, "done": { "type": "boolean" }, "dueDate": { "type": [ "string", "null" ], "description": "Valid YYYY-MM-DD or ISO datetime with timezone; null clears the date. Server validates calendar dates." }, "partition": { "type": "string", "enum": [ "brain-dump-primary", "brain-dump-secondary" ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Trimmed task text, 1-5000 characters." }, "done": { "type": "boolean" }, "dueDate": { "type": [ "string", "null" ], "description": "Valid YYYY-MM-DD or ISO datetime with timezone; null clears the date. Server validates calendar dates." } }, "required": [ "text" ], "additionalProperties": false }, "maxItems": 30 } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "input": { "type": "string", "description": "Multiline BrainDump input, parsed into 1-50 tasks." }, "subtaskInput": { "type": "string", "description": "Extra subtasks appended to the final parent." } }, "required": [ "input" ], "additionalProperties": false } ] }, "UpdateTask": { "oneOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Trimmed task text, 1-5000 characters." }, "done": { "type": "boolean" }, "dueDate": { "type": [ "string", "null" ], "description": "Valid YYYY-MM-DD or ISO datetime with timezone; null clears the date. Server validates calendar dates." }, "partition": { "type": "string", "enum": [ "brain-dump-primary", "brain-dump-secondary" ] }, "subtasks": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Trimmed task text, 1-5000 characters." }, "done": { "type": "boolean" }, "dueDate": { "type": [ "string", "null" ], "description": "Valid YYYY-MM-DD or ISO datetime with timezone; null clears the date. Server validates calendar dates." } }, "required": [ "text" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "number" } ], "description": "Opaque ID. Preserve original type; encode when used in a URL." }, "text": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Trimmed task text, 1-5000 characters." }, "done": { "type": "boolean" }, "dueDate": { "type": [ "string", "null" ], "description": "Valid YYYY-MM-DD or ISO datetime with timezone; null clears the date. Server validates calendar dates." } }, "required": [ "id" ], "additionalProperties": false, "minProperties": 2 }, { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "number" } ], "description": "Opaque ID. Preserve original type; encode when used in a URL." }, "deleted": { "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 30 }, "expectedUpdatedAt": { "type": [ "string", "number", "null" ], "description": "Last read updatedAt, unchanged. null only if absent on a legacy entity." } }, "required": [ "expectedUpdatedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "deleted": { "const": true }, "expectedUpdatedAt": { "type": [ "string", "number", "null" ], "description": "Last read updatedAt, unchanged. null only if absent on a legacy entity." } }, "required": [ "deleted", "expectedUpdatedAt" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "const": "archived" }, "liked": { "type": "boolean" }, "expectedUpdatedAt": { "type": [ "string", "number", "null" ], "description": "Last read updatedAt, unchanged. null only if absent on a legacy entity." } }, "required": [ "source", "liked", "expectedUpdatedAt" ], "additionalProperties": false } ] }, "VersionInput": { "type": "object", "properties": { "expectedUpdatedAt": { "type": [ "string", "number", "null" ], "description": "Last read updatedAt, unchanged. null only if absent on a legacy entity." } }, "required": [ "expectedUpdatedAt" ], "additionalProperties": false }, "CreateBoard": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 }, "tab": { "type": [ "string", "null" ], "maxLength": 100 }, "thought": { "type": "string", "maxLength": 10000 } }, "required": [ "content" ], "additionalProperties": false }, "AppendThought": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "content" ], "additionalProperties": false } } } }