{ "openapi": "3.1.0", "info": { "title": "Doers API", "version": "2.0.0", "description": "The open API of Doers: tasks, projects, areas, prioritised context and the day's plan.\n\n## Authentication\n\nEvery route requires a bearer token, generated from **Settings > API & MCP** in the app:\n\n```\nAuthorization: Bearer pc_…\n```\n\n## Two date fields, not to be confused\n\n- `when` — the **schedule**: `today`, `anytime` (Later), `someday` (Future) or a date.\n- `deadline` — the **commitment**, independent of the schedule.\n\n## Time zone\n\nThe server reasons in UTC and does not know yours. Send the `X-PC-Today: YYYY-MM-DD` header\n(or the `day` argument where it exists) so dated operations use your local day.\n\n## MCP server\n\nThe same token gives access to the [Model Context Protocol](https://modelcontextprotocol.io)\nserver at `POST https://app.doers.sh/mcp`, which exposes the same operations as tools for Claude,\nCursor and other compatible clients." }, "servers": [ { "url": "https://api.doers.sh", "description": "Production." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Tasks" }, { "name": "Projects" }, { "name": "Areas" }, { "name": "Headings" }, { "name": "Comments" }, { "name": "Realtime" }, { "name": "Devices" }, { "name": "Context" }, { "name": "Plan" }, { "name": "Sessions" }, { "name": "Rounds" }, { "name": "Journal" }, { "name": "Habits" }, { "name": "Stats" }, { "name": "Users" }, { "name": "Profiles" }, { "name": "Workspaces" }, { "name": "Access" }, { "name": "Activity" }, { "name": "Tokens" }, { "name": "Referrals" }, { "name": "Files" }, { "name": "Connections" }, { "name": "Collaborators" }, { "name": "Links" }, { "name": "Packages" }, { "name": "Installs" }, { "name": "Billing" }, { "name": "Calendar" }, { "name": "Coach" }, { "name": "Marketplace" } ], "paths": { "/v2/hierarchy/reorder": { "post": { "operationId": "reorderHierarchy", "summary": "Move tasks and projects atomically", "description": "Commits every supplied order and parent change in one database transaction. A task has exactly one explicit destination: the root, an area, or a project, optionally under a heading in that destination. A project has exactly one destination: the root or an area. If any item, destination, permission, or heading is invalid, nothing moves.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "moves": { "type": "array", "description": "Task and project moves committed together (50 maximum).", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "task" }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "parent": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "root" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "area" }, "areaId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "headingId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] } }, "required": [ "kind", "areaId", "headingId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "headingId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] } }, "required": [ "kind", "projectId", "headingId" ], "additionalProperties": false } ] } }, "required": [ "kind", "taskId", "order", "parent" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "project" }, "projectId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "parent": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "root" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "area" }, "areaId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." } }, "required": [ "kind", "areaId" ], "additionalProperties": false } ] } }, "required": [ "kind", "projectId", "order", "parent" ], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 50 }, "workspaceId": { "type": "string", "description": "Optional workspace assertion. Omit it for legacy clients; the server always derives the authoritative workspace from the moved entities.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "moves" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false } }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "done", "archived" ] }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "type": "string" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this project.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "name", "areaId", "status", "deadline", "notes", "order" ], "additionalProperties": false } } }, "required": [ "tasks", "projects" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/inbox/history": { "get": { "operationId": "listInboxHistory", "summary": "Tasks you have already triaged", "description": "Returns the tasks that arrived in the Inbox and have since been placed, scheduled, completed or archived, most recently triaged first, with the instant each one left. Use it to look back at what an Inbox held, or to find something filed by mistake.\n\nA task created straight into a project or an area never appears here: it was never in the Inbox. A task that returned to the Inbox and was triaged again keeps the instant it first left, and appears once.\n\nUnlike `listTasks`, this does not exclude calendar blocks: a task turned into one left the Inbox like any other, and hiding it would make an item disappear without trace.\n\nThis is the task half of the Inbox history. Agent handbacks live in the local vault and messages come from `listInboxComments`; the Desktop client merges the three into one chronological list.", "tags": [ "Tasks" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "How many triaged tasks to return.", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false }, "processedAt": { "type": "number", "description": "Epoch milliseconds at which the task first left the Inbox." } }, "required": [ "task", "processedAt" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page, or null." } }, "required": [ "items", "nextCursor" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks": { "get": { "operationId": "listTasks", "summary": "List the tasks", "description": "Returns open tasks by default, in manual order. `status=done` returns the most recently completed first. Calendar blocks (`kind: \"event\"`) are always excluded. Filterable by project, by area and by title text.", "tags": [ "Tasks" ], "parameters": [ { "name": "areaId", "in": "query", "required": false, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "assignedToMe", "in": "query", "required": false, "description": "Only what is assigned to you, whoever owns it (`Teams 02`).", "schema": { "type": "boolean", "default": false } }, { "name": "completedSince", "in": "query", "required": false, "description": "For `status=done`, only completions at or after this epoch millisecond.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 200 } }, { "name": "projectId", "in": "query", "required": false, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "query", "in": "query", "required": false, "description": "Search within the title.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "sharedWithMe", "in": "query", "required": false, "description": "Only the tasks of the projects and areas shared with you, none of your own.", "schema": { "type": "boolean", "default": false } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "done", "archived" ], "default": "open" } }, { "name": "workspaceId", "in": "query", "required": false, "description": "The workspace to read within; the personal one by default (T-D11).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of results before `limit` is applied." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page, or null." } }, "required": [ "tasks", "total", "nextCursor" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createTask", "summary": "Create a task", "description": "Creates a task from structured fields. To create from a sentence, use `POST /v2/tasks/quick` instead.\n\nA task belongs to a project **or** to an area, never both: if `projectId` is given, `areaId` is ignored.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "areaId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "conversationPath": { "type": "string", "description": "Local Atelier conversation carrying this delegated task.", "maxLength": 1024 }, "deadline": { "description": "Due date, distinct from `when`.", "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, { "type": "null" } ] }, "durationMin": { "type": "integer", "minimum": 15, "maximum": 1440 }, "headingId": { "description": "Heading of the project or area that groups the task. `null` moves it back to the top. It must belong to the same parent as the task.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "kind": { "type": "string", "description": "`event` is a calendar block, excluded from task lists.", "enum": [ "task", "event" ] }, "notes": { "type": "string", "description": "Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (```) or images**: the app's editor does not support them and truncates the display from that point on.", "maxLength": 10000 }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "priority": { "type": "integer", "description": "0 none · 1 low · 2 medium · 3 high · 4 “goal of the day”. Out of range is a 400.", "minimum": 0, "maximum": 4 }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "repeat": { "description": "Repeat rule. `null` stops it repeating.", "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "requestId": { "type": "string", "description": "Stable creation request identifier. Reusing it returns the first task. If that task has been deleted, the request remains consumed and returns a conflict.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 20 }, "time": { "type": "string", "description": "Time `HH:MM` — only meaningful alongside a date.", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "visibility": { "type": "string", "description": "Who sees this task on shared and social surfaces. Defaults to private on create.", "enum": [ "public", "anonymized", "private" ] }, "when": { "description": "Scheduling: `today`, `anytime` (Later), `someday` (Future), or a `YYYY-MM-DD` date. Not to be confused with `deadline`, which is the due date.", "anyOf": [ { "type": "string", "enum": [ "today", "anytime", "someday" ] }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "updateTasks", "summary": "Update several tasks at once", "description": "Applies the **same** patch to several tasks. Always prefer this as soon as two or more tasks receive the same change.\n\nThe operation is atomic: if a single task is inaccessible, nothing changes.\n\nThis is the reorganisation tool: `projectId` + `headingId` in one call files a whole batch under a milestone. Never fire a burst of `update_task` instead.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "areaId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "deadline": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, { "type": "null" } ] }, "headingId": { "description": "Heading of the project or area that groups the task. `null` moves it back to the top. It must belong to the same parent as the task.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "priority": { "type": "integer", "description": "0 none · 1 low · 2 medium · 3 high · 4 “goal of the day”. Out of range is a 400.", "minimum": 0, "maximum": 4 }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "taskIds": { "type": "array", "description": "Ids of the tasks concerned (50 maximum).", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "minItems": 1, "maxItems": 50 }, "time": { "type": "string", "description": "Time `HH:MM` — only meaningful alongside a date.", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "visibility": { "type": "string", "description": "Who sees this task on shared and social surfaces. Defaults to private on create.", "enum": [ "public", "anonymized", "private" ] }, "when": { "description": "Scheduling: `today`, `anytime` (Later), `someday` (Future), or a `YYYY-MM-DD` date. Not to be confused with `deadline`, which is the due date.", "anyOf": [ { "type": "string", "enum": [ "today", "anytime", "someday" ] }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, "required": [ "taskIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taskIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "count", "taskIds" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/{taskId}": { "get": { "operationId": "getTask", "summary": "Get a task", "description": "Returns a full task (notes, checklist, attachment) and your access role. Returns 404 if the task does not exist **or** is not accessible to you: the API never reveals the existence of another account's task.", "tags": [ "Tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "updateTask", "summary": "Update a task", "description": "Applies a partial patch: only the fields provided change. Passing `null` to `deadline`, `projectId`, `areaId`, `notePath` or `conversationPath` clears the value.", "tags": [ "Tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "areaId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "conversationPath": { "description": "Atelier conversation carrying this delegated task; `null` un-delegates.", "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "deadline": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, { "type": "null" } ] }, "done": { "type": "boolean", "description": "Shortcut for ticking or unticking." }, "durationMin": { "anyOf": [ { "type": "integer", "minimum": 15, "maximum": 1440 }, { "type": "null" } ] }, "headingId": { "description": "Heading of the project or area that groups the task. `null` moves it back to the top. It must belong to the same parent as the task.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "notes": { "type": "string", "description": "Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (```) or images**: the app's editor does not support them and truncates the display from that point on.", "maxLength": 10000 }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "priority": { "type": "integer", "description": "0 none · 1 low · 2 medium · 3 high · 4 “goal of the day”. Out of range is a 400.", "minimum": 0, "maximum": 4 }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "repeat": { "description": "Repeat rule. `null` stops it repeating.", "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 20 }, "time": { "type": "string", "description": "Time `HH:MM` — only meaningful alongside a date.", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "visibility": { "type": "string", "description": "Who sees this task on shared and social surfaces. Defaults to private on create.", "enum": [ "public", "anonymized", "private" ] }, "when": { "description": "Scheduling: `today`, `anytime` (Later), `someday` (Future), or a `YYYY-MM-DD` date. Not to be confused with `deadline`, which is the due date.", "anyOf": [ { "type": "string", "enum": [ "today", "anytime", "someday" ] }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteTask", "summary": "Delete an archived task for good", "description": "Removes a task permanently. **The task must already be archived** — `POST /v2/tasks/archive` first. The irreversible step is deliberately reachable only from the reversible one, which is why `archive` is what an agent should reach for and this is not.\n\nOwner only.", "tags": [ "Tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" } }, "required": [ "taskId" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/{taskId}/assignee": { "patch": { "operationId": "assignTask", "summary": "Assign a task to someone, or to nobody", "description": "`username` names someone who already reaches the task; anyone else is not found. `null` clears the assignment. Takes Can edit. An optional `grant` accepts only an exact existing handle and atomically grants direct task-only access before assigning; only the task owner may use it and existing guest role ceilings still apply.", "tags": [ "Tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant": { "type": "object", "description": "An explicit direct-task grant to create atomically before assignment.", "properties": { "role": { "type": "string", "enum": [ "reader", "commenter", "editor" ] } }, "required": [ "role" ], "additionalProperties": false }, "username": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "username" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/{taskId}/checklist": { "post": { "operationId": "addChecklistItems", "summary": "Add checklist items", "description": "Adds items **without overwriting** the existing ones. Labels already present (case-insensitive comparison) are silently skipped.", "tags": [ "Tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300 }, "minItems": 1, "maxItems": 30 } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "added": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "checklist", "added" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "operationId": "setChecklist", "summary": "Replace a task's checklist", "description": "Replaces the whole list, in the order given. This is what an editor saves — the app lets someone rename, reorder and delete items in one pass, and sending that as a series of adds and ticks could not express a removal at all.\n\nAn item keeping its `id` keeps its identity; one without gets a new id.", "tags": [ "Tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Omit for a new item.", "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 300 }, "done": { "default": false, "type": "boolean" } }, "required": [ "label" ], "additionalProperties": false }, "maxItems": 30 } }, "required": [ "checklist" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } } }, "required": [ "checklist" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "checkChecklistItems", "summary": "Tick checklist items", "description": "Ticks (or unticks with `done: false`) items named by their id **or** by their exact label, case-insensitively.", "tags": [ "Tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "done": { "type": "boolean", "default": true }, "items": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 30 } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "changed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "checklist", "changed" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/{taskId}/members": { "get": { "operationId": "listTaskMembers", "summary": "List the people with access to a task", "description": "Returns the owner and the invited members of a task, with their role (`reader`, `commenter`, `editor`).\n\nA task with no invited members returns just the owner — the common case.", "tags": [ "Tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "label": { "type": "string", "description": "`@username`, else the name, else the email." }, "role": { "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "userId", "label", "role" ], "additionalProperties": false } } }, "required": [ "members" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/archive": { "post": { "operationId": "archiveTasks", "summary": "Archive or restore tasks", "description": "Archiving is **reversible**: it replaces deletion and is undone with `restore: true`. Use `restoreCompletion: true` with `restore: true` to undo archival without changing the original completion time or generating another recurring occurrence. Permanent deletion is a separate operation requiring an archived task.\n\nOwner only.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "restore": { "type": "boolean", "description": "`true` to unarchive and put the task back in progress.", "default": false }, "restoreCompletion": { "type": "boolean", "description": "With `restore: true`, restore the archived completion state and timestamp. Already active tasks are unchanged. Default: reopen tasks.", "default": false }, "taskIds": { "type": "array", "description": "Ids of the tasks concerned (50 maximum).", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "minItems": 1, "maxItems": 50 } }, "required": [ "taskIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "restored": { "type": "boolean" } }, "required": [ "count", "restored" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/batch": { "post": { "operationId": "createTasks", "summary": "Create several tasks atomically", "description": "Creates an ordered task list in one atomic operation. If any parent or heading is invalid, no task is created. Use this for multi-line paste instead of firing several `create_task` calls.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "requestId": { "description": "Stable creation request identifier. Reusing it returns the first task. If that task has been deleted, the request remains consumed and returns a conflict.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "notes": { "type": "string", "maxLength": 10000, "description": "Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (```) or images**: the app's editor does not support them and truncates the display from that point on." }, "when": { "anyOf": [ { "type": "string", "enum": [ "today", "anytime", "someday" ] }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ], "description": "Scheduling: `today`, `anytime` (Later), `someday` (Future), or a `YYYY-MM-DD` date. Not to be confused with `deadline`, which is the due date." }, "time": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Time `HH:MM` — only meaningful alongside a date." }, "deadline": { "description": "Due date, distinct from `when`.", "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, { "type": "null" } ] }, "priority": { "type": "integer", "minimum": 0, "maximum": 4, "description": "0 none · 1 low · 2 medium · 3 high · 4 “goal of the day”. Out of range is a 400." }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "headingId": { "description": "Heading of the project or area that groups the task. `null` moves it back to the top. It must belong to the same parent as the task.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1 } }, "durationMin": { "type": "integer", "minimum": 15, "maximum": 1440 }, "conversationPath": { "description": "Local Atelier conversation carrying this delegated task.", "type": "string", "maxLength": 1024 }, "kind": { "description": "`event` is a calendar block, excluded from task lists.", "type": "string", "enum": [ "task", "event" ] }, "repeat": { "description": "Repeat rule. `null` stops it repeating.", "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "description": "Who sees this task on shared and social surfaces. Defaults to private on create.", "type": "string", "enum": [ "public", "anonymized", "private" ] }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." } }, "required": [ "title" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 } }, "required": [ "tasks" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false } } }, "required": [ "tasks" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/by-id": { "get": { "operationId": "getTasks", "summary": "Get several tasks by id", "description": "Resolves several task identifiers in one request, including shared tasks. Identifiers that are missing or inaccessible are returned together as unavailable, without revealing which case applies.", "tags": [ "Tasks" ], "parameters": [ { "name": "taskIds", "in": "query", "required": true, "description": "Ids of the tasks concerned (50 maximum).", "schema": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "minItems": 1, "maxItems": 50 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee", "accessRole" ], "additionalProperties": false } }, "unavailableTaskIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." } } }, "required": [ "tasks", "unavailableTaskIds" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/complete": { "post": { "operationId": "completeTasks", "summary": "Tick or untick tasks", "description": "Marks tasks as done, or reopens them with `done: false`.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "done": { "type": "boolean", "default": true }, "taskIds": { "type": "array", "description": "Ids of the tasks concerned (50 maximum).", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "minItems": 1, "maxItems": 50 } }, "required": [ "taskIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "done": { "type": "boolean" } }, "required": [ "count", "done" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/quick": { "post": { "operationId": "quickAddTask", "summary": "Create a task from natural language", "description": "Creates a task from a sentence, using the same parser as the app's omnibar. It reads English and French. Three families of token, combinable in any order:\n\n- `!` to `!!!` — priority 1 to 3\n- `#name` — project, else area (prefix match, accent-insensitive)\n- a date in English or French — “tomorrow”, “monday 3pm”, “tmr”\n\nAnything not recognised stays in the title. Example: `!!! edit the video #YouTube tomorrow 3pm`.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deadline": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, { "type": "null" } ] }, "raw": { "type": "string", "minLength": 1, "maxLength": 500, "examples": [ "!!! call the accountant tomorrow 10am #Admin" ] } }, "required": [ "raw" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false }, "parsed": { "type": "object", "properties": { "title": { "type": "string" }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "priority", "projectId", "areaId" ], "additionalProperties": false } }, "required": [ "task", "parsed" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/schedule": { "patch": { "operationId": "scheduleTasks", "summary": "Schedule tasks atomically", "description": "Schedules one or more tasks by day, optional precise time and optional manual order in one transaction. Omitted time preserves an existing precise time; null clears it. If any task is inaccessible, nothing changes. Deadlines are never changed.", "tags": [ "Tasks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "time": { "anyOf": [ { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Time `HH:MM` — only meaningful alongside a date." }, { "type": "null" } ] }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." } }, "required": [ "taskId", "day" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50 } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false } } }, "required": [ "tasks" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/projects": { "get": { "operationId": "listProjects", "summary": "List the projects", "description": "Returns active and completed projects in manual order, with their task counts. Archived projects are excluded unless `includeArchived=true`.", "tags": [ "Projects" ], "parameters": [ { "name": "areaId", "in": "query", "required": false, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "done" ] } }, { "name": "workspaceId", "in": "query", "required": false, "description": "The workspace to read within; the personal one by default (T-D11).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "done", "archived" ] }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "type": "string" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this project.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] }, "openTaskCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "doneTaskCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "areaId", "status", "deadline", "notes", "order", "openTaskCount", "doneTaskCount" ], "additionalProperties": false } } }, "required": [ "projects" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createProject", "summary": "Create a project", "description": "Creates an active project, optionally attached to an area and with a deadline. A project with no area is filed under “No area”.", "tags": [ "Projects" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "areaId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "deadline": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "notes": { "type": "string", "description": "Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (```) or images**: the app's editor does not support them and truncates the display from that point on.", "maxLength": 10000 }, "workspaceId": { "type": "string", "description": "Where to file it: the personal workspace by default, or a team workspace the caller sits in.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "done", "archived" ] }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "type": "string" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this project.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "name", "areaId", "status", "deadline", "notes", "order" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/projects/{projectId}": { "patch": { "operationId": "updateProject", "summary": "Update a project", "description": "Partial patch: name, area, deadline, status or notes. Passing `status: \"done\"` marks the project complete without touching its tasks.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "areaId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "deadline": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "notes": { "type": "string", "description": "Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (```) or images**: the app's editor does not support them and truncates the display from that point on.", "maxLength": 10000 }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "status": { "type": "string", "enum": [ "active", "done" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "done", "archived" ] }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "type": "string" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this project.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "name", "areaId", "status", "deadline", "notes", "order" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteProject", "summary": "Delete an archived project for good", "description": "Removes a project permanently. **The project must already be archived** — the irreversible step is deliberately reachable only from the reversible one.\n\nIts tasks are **detached, never deleted**: they lose their project and stay.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "detachedTasks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "projectId", "detachedTasks" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/projects/{projectId}/archive": { "post": { "operationId": "archiveProject", "summary": "Archive or restore a project", "description": "Archiving is **reversible** and cascades to the project's open tasks. `restore: true` makes the project active again; its tasks are not unarchived automatically, matching the app.", "tags": [ "Projects" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "restore": { "type": "boolean", "default": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "done", "archived" ] }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "type": "string" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this project.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "name", "areaId", "status", "deadline", "notes", "order" ], "additionalProperties": false }, "archivedTasks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "project", "archivedTasks" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/areas": { "get": { "operationId": "listAreas", "summary": "List the areas", "description": "Returns the spheres of life, in manual order. An area contains projects and can carry tasks directly.", "tags": [ "Areas" ], "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "workspaceId", "in": "query", "required": false, "description": "The workspace to read within; the personal one by default (T-D11).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "areas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hue": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 360, "description": "Anodized metal hue angle from 0 to 360 degrees." }, { "type": "null" } ] }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phosphor icon name." }, "notes": { "type": "string" }, "archived": { "type": "boolean" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this area.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "name", "hue", "icon", "notes", "archived", "order" ], "additionalProperties": false } } }, "required": [ "areas" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createArea", "summary": "Create an area", "description": "Creates a sphere of life.", "tags": [ "Areas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hue": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 360, "description": "Anodized metal hue angle from 0 to 360 degrees." }, { "type": "null" } ] }, "icon": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 60 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "notes": { "type": "string", "description": "Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (```) or images**: the app's editor does not support them and truncates the display from that point on.", "maxLength": 10000 }, "workspaceId": { "type": "string", "description": "Where to file it: the personal workspace by default, or a team workspace the caller sits in.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "area": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hue": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 360, "description": "Anodized metal hue angle from 0 to 360 degrees." }, { "type": "null" } ] }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phosphor icon name." }, "notes": { "type": "string" }, "archived": { "type": "boolean" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this area.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "name", "hue", "icon", "notes", "archived", "order" ], "additionalProperties": false } }, "required": [ "area" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/areas/{areaId}": { "patch": { "operationId": "updateArea", "summary": "Update an area", "description": "Partial patch: name, anodized hue, icon (a Phosphor icon name) or notes.", "tags": [ "Areas" ], "parameters": [ { "name": "areaId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "hue": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 360, "description": "Anodized metal hue angle from 0 to 360 degrees." }, { "type": "null" } ] }, "icon": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 60 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "notes": { "type": "string", "description": "Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (```) or images**: the app's editor does not support them and truncates the display from that point on.", "maxLength": 10000 }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "area": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hue": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 360, "description": "Anodized metal hue angle from 0 to 360 degrees." }, { "type": "null" } ] }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phosphor icon name." }, "notes": { "type": "string" }, "archived": { "type": "boolean" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this area.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "name", "hue", "icon", "notes", "archived", "order" ], "additionalProperties": false } }, "required": [ "area" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteArea", "summary": "Delete an archived area for good", "description": "Removes an area permanently. **The area must already be archived** — the irreversible step is deliberately reachable only from the reversible one, so nothing is lost by a single misplaced call.\n\nIts projects and tasks are **detached, never deleted**: they lose their area and stay. An area groups, it does not contain.", "tags": [ "Areas" ], "parameters": [ { "name": "areaId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "areaId": { "type": "string" }, "detachedProjects": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detachedTasks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "areaId", "detachedProjects", "detachedTasks" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/areas/{areaId}/archive": { "post": { "operationId": "archiveArea", "summary": "Archive or restore an area", "description": "Archiving is **reversible** and cascades: the area's active projects, their open tasks, then the open tasks attached directly to the area.", "tags": [ "Areas" ], "parameters": [ { "name": "areaId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "restore": { "type": "boolean", "default": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "area": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hue": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 360, "description": "Anodized metal hue angle from 0 to 360 degrees." }, { "type": "null" } ] }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phosphor icon name." }, "notes": { "type": "string" }, "archived": { "type": "boolean" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this area.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "name", "hue", "icon", "notes", "archived", "order" ], "additionalProperties": false }, "archivedProjects": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "archivedTasks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "area", "archivedProjects", "archivedTasks" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/headings": { "get": { "operationId": "listHeadings", "summary": "List the headings", "description": "Returns the headings of a project or an area, in display order, with the number of open and completed tasks under each.\n\nA heading carrying a `deadline` is a **milestone**: the same object, dated. Call this **before** any reorganisation, to see what already exists.", "tags": [ "Headings" ], "parameters": [ { "name": "areaId", "in": "query", "required": false, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "projectId", "in": "query", "required": false, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "workspaceId", "in": "query", "required": false, "description": "The workspace to read within; the personal one by default (T-D11).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "headings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Milestone due date `YYYY-MM-DD`, or `null` for a plain grouping." }, "notes": { "type": "string" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "openTaskCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "doneTaskCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "projectId", "areaId", "deadline", "notes", "order", "openTaskCount", "doneTaskCount" ], "additionalProperties": false } } }, "required": [ "headings" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createHeading", "summary": "Create a heading (or a milestone)", "description": "Creates a grouping of tasks under a project **or** under an area — never both. Provide `deadline` to make it a dated **milestone**; leave it out for a plain grouping.\n\nThe heading is appended last. File tasks into it afterwards with `update_tasks` and its `headingId` field: one call for a whole batch.", "tags": [ "Headings" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "areaId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "deadline": { "description": "Milestone due date. Absent means a plain grouping.", "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, { "type": "null" } ] }, "name": { "type": "string", "default": "", "maxLength": 200 }, "notes": { "anyOf": [ { "type": "string", "maxLength": 10000, "description": "Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (```) or images**: the app's editor does not support them and truncates the display from that point on." }, { "type": "null" } ] }, "projectId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "heading": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Milestone due date `YYYY-MM-DD`, or `null` for a plain grouping." }, "notes": { "type": "string" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "openTaskCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "doneTaskCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "projectId", "areaId", "deadline", "notes", "order", "openTaskCount", "doneTaskCount" ], "additionalProperties": false } }, "required": [ "heading" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/headings/{headingId}": { "patch": { "operationId": "updateHeading", "summary": "Update a heading", "description": "Partial patch: name, deadline, description, position. `deadline: null` removes the due date and the heading becomes a plain grouping again.\n\nThe **parent does not change** here: a heading moved to another project would leave its tasks attached to a grouping invisible from their own page. To move a batch, create the heading in the right parent then call `update_tasks` with `projectId` and `headingId`.", "tags": [ "Headings" ], "parameters": [ { "name": "headingId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "deadline": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "notes": { "anyOf": [ { "type": "string", "maxLength": 10000, "description": "Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. **Do not use code blocks (```) or images**: the app's editor does not support them and truncates the display from that point on." }, { "type": "null" } ] }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "heading": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Milestone due date `YYYY-MM-DD`, or `null` for a plain grouping." }, "notes": { "type": "string" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "openTaskCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "doneTaskCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "projectId", "areaId", "deadline", "notes", "order", "openTaskCount", "doneTaskCount" ], "additionalProperties": false } }, "required": [ "heading" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteHeading", "summary": "Delete a heading", "description": "Removes the grouping **without touching the tasks**: they move up to the top of their project or area. A heading groups, it does not contain — removing one must never make work disappear.\n\nUnlike tasks, projects and areas, this deletion is **not reversible**: the grouping is lost, only the tasks' attachment is preserved.", "tags": [ "Headings" ], "parameters": [ { "name": "headingId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "headingId": { "type": "string" }, "releasedTasks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "headingId", "releasedTasks" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/changes": { "get": { "operationId": "listChanges", "summary": "List the changes made to an entity", "description": "Returns what happened to a task, project or area — created, When or Deadline set, completed, reopened, handed to an agent — oldest first, with who did it. The most recent `limit` changes are kept.", "tags": [ "Comments" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many changes to return.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "parentId", "in": "query", "required": true, "description": "Id of the parent task, project or area.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "parentKind", "in": "query", "required": true, "description": "Which kind of entity carries the comments.", "schema": { "type": "string", "enum": [ "task", "project", "area" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "created", "when", "deadline", "completed", "reopened", "agent-run" ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "actor": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "username", "image" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "kind", "value", "actor", "createdAt" ], "additionalProperties": false } } }, "required": [ "changes" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/comments": { "get": { "operationId": "listComments", "summary": "List the comments on an entity", "description": "Returns the comments on a task, project or area, oldest first. Attachments are not exposed by the API: only their count is.", "tags": [ "Comments" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many comments to return.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "parentId", "in": "query", "required": true, "description": "Id of the parent task, project or area.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "parentKind", "in": "query", "required": true, "description": "Which kind of entity carries the comments.", "schema": { "type": "string", "enum": [ "task", "project", "area" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "authorId": { "type": "string" }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "username", "image" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "attachmentCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "preview": { "anyOf": [ { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "siteName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "title", "description", "image", "siteName" ], "additionalProperties": false }, { "type": "null" } ] }, "canEdit": { "type": "boolean" }, "canRemove": { "type": "boolean" } }, "required": [ "id", "body", "authorId", "author", "createdAt", "attachmentCount", "preview", "canEdit", "canRemove" ], "additionalProperties": false } } }, "required": [ "comments" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "addComment", "summary": "Add a comment", "description": "Posts a comment on a task, project or area. The first link in the text is unfurled in the background (OpenGraph preview) without blocking the response.\n\nOn a shared task the `commenter` role is enough.", "tags": [ "Comments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The comment text, as markdown.", "minLength": 1, "maxLength": 10000 }, "parentId": { "type": "string", "description": "Id of the parent task, project or area.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "parentKind": { "type": "string", "description": "Which kind of entity carries the comments.", "enum": [ "task", "project", "area" ] } }, "required": [ "body", "parentId", "parentKind" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "authorId": { "type": "string" }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "username", "image" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "attachmentCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "preview": { "anyOf": [ { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "siteName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "title", "description", "image", "siteName" ], "additionalProperties": false }, { "type": "null" } ] }, "canEdit": { "type": "boolean" }, "canRemove": { "type": "boolean" } }, "required": [ "id", "body", "authorId", "author", "createdAt", "attachmentCount", "preview", "canEdit", "canRemove" ], "additionalProperties": false } }, "required": [ "comment" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/comments/{commentId}": { "patch": { "operationId": "updateComment", "summary": "Edit a comment", "description": "Rewrites the text of a comment. **Only its author may edit it** — owning the task, project or area the thread hangs off is not enough, because a thread is a record of who said what.", "tags": [ "Comments" ], "parameters": [ { "name": "commentId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "description": "The replacement text, as markdown.", "minLength": 1, "maxLength": 10000 } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "authorId": { "type": "string" }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "username", "image" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "attachmentCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "preview": { "anyOf": [ { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "siteName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "title", "description", "image", "siteName" ], "additionalProperties": false }, { "type": "null" } ] }, "canEdit": { "type": "boolean" }, "canRemove": { "type": "boolean" } }, "required": [ "id", "body", "authorId", "author", "createdAt", "attachmentCount", "preview", "canEdit", "canRemove" ], "additionalProperties": false } }, "required": [ "comment" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteComment", "summary": "Delete a comment", "description": "Removes a comment and its attachments. The author may always delete their own; anyone else needs to own the entity the thread hangs off.\n\nThis deletion is **not reversible**.", "tags": [ "Comments" ], "parameters": [ { "name": "commentId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "commentId": { "type": "string" } }, "required": [ "commentId" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/inbox/comments": { "get": { "operationId": "listInboxComments", "summary": "Others' comments across your workspace", "description": "Feeds the Inbox: the most recent comments left by someone else on your tasks, projects and areas — newest first, each with the entity it targets. Your own comments never appear here; they live in their threads.", "tags": [ "Comments" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many comments to return.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "comment": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "authorId": { "type": "string" }, "author": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "username", "image" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "attachmentCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "preview": { "anyOf": [ { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "siteName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "title", "description", "image", "siteName" ], "additionalProperties": false }, { "type": "null" } ] }, "canEdit": { "type": "boolean" }, "canRemove": { "type": "boolean" } }, "required": [ "id", "body", "authorId", "author", "createdAt", "attachmentCount", "preview", "canEdit", "canRemove" ], "additionalProperties": false }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "task", "project", "area" ], "description": "Which kind of entity carries the comments." }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "title": { "type": "string" } }, "required": [ "kind", "id", "title" ], "additionalProperties": false } }, "required": [ "comment", "target" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/realtime/events": { "get": { "operationId": "listRealtimeEvents", "summary": "List realtime events since a cursor", "description": "Returns this account's events on the one realtime log, oldest first, after `since`. That id is the resume token: reconnect with it to fill a gap. An omitted `since` starts from the oldest retained event. A `channel` narrows to one stream (inbox, a place, a run, or activity). This read does not mark anything read.", "tags": [ "Realtime" ], "parameters": [ { "name": "channel", "in": "query", "required": false, "description": "One stream. Omit to read every channel for this account.", "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "description": "How many events to return.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "since", "in": "query", "required": false, "description": "Last event id already received. Omit to start from the oldest.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "channel": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "needs-approval", "share-invite", "coach-brief", "run-status", "read" ] }, "title": { "type": "string" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deepLink": { "type": "string" }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "channel", "kind", "title", "body", "deepLink", "createdAt" ], "additionalProperties": false } }, "cursor": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ], "description": "Id of the last event in this page, or null when empty." } }, "required": [ "events", "cursor" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/devices": { "get": { "operationId": "listDevices", "summary": "List paired Macs", "description": "Paired desktops on this account, including revoked ones so Settings can show them.", "tags": [ "Devices" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "const": "desktop" }, "lastSeenAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "name", "kind", "lastSeenAt", "revokedAt" ], "additionalProperties": false } } }, "required": [ "devices" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "registerDevice", "summary": "Register this desktop on the account", "description": "A signed-in desktop registers itself as a device. The phone lists paired Macs. No extra pairing code: both sides use the account session.", "tags": [ "Devices" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "device": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "const": "desktop" }, "lastSeenAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "name", "kind", "lastSeenAt", "revokedAt" ], "additionalProperties": false } }, "required": [ "device" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/devices/{deviceId}/calls": { "get": { "operationId": "listDeviceCalls", "summary": "Pull queued calls for this Mac", "description": "The desktop half of the relay. Marks the device seen so new delegations are not \"will start when your Mac is online\". Revoked devices get an empty list.", "tags": [ "Devices" ], "parameters": [ { "name": "deviceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "operation": { "type": "string", "enum": [ "delegateTask", "approveRun", "rejectRun", "replyToRun", "getRunState" ] }, "state": { "type": "string", "enum": [ "queued", "running", "needs-approval", "done", "failed" ] }, "waitingForMac": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "deviceId", "operation", "state", "waitingForMac", "message", "createdAt" ], "additionalProperties": false } } }, "required": [ "calls" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/devices/{deviceId}/delegate": { "post": { "operationId": "delegateTask", "summary": "Queue a task for an agent on a paired Mac", "description": "Does not run the agent on the server. The Mac pulls this call and runs it in the vault. `agentFolder` is the vault-relative folder (the product's agent id).", "tags": [ "Devices" ], "parameters": [ { "name": "deviceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentFolder": { "type": "string", "minLength": 1, "maxLength": 1024 }, "model": { "type": "string", "minLength": 1, "maxLength": 500 }, "taskId": { "type": "string", "description": "Identifier of a row.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "agentFolder", "taskId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "call": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "operation": { "type": "string", "enum": [ "delegateTask", "approveRun", "rejectRun", "replyToRun", "getRunState" ] }, "state": { "type": "string", "enum": [ "queued", "running", "needs-approval", "done", "failed" ] }, "waitingForMac": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "deviceId", "operation", "state", "waitingForMac", "message", "createdAt" ], "additionalProperties": false } }, "required": [ "call" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/devices/{deviceId}/revoke": { "post": { "operationId": "revokeDevice", "summary": "Revoke a paired device", "description": "Kills the tunnel. Queued calls for that device are no longer returned to it.", "tags": [ "Devices" ], "parameters": [ { "name": "deviceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "device": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "const": "desktop" }, "lastSeenAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "name", "kind", "lastSeenAt", "revokedAt" ], "additionalProperties": false } }, "required": [ "device" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/runs/{runId}": { "get": { "operationId": "getRunState", "summary": "Get a run's state", "description": "When the Mac has never pulled, `message` is \"will start when your Mac is online\".", "tags": [ "Devices" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "call": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "operation": { "type": "string", "enum": [ "delegateTask", "approveRun", "rejectRun", "replyToRun", "getRunState" ] }, "state": { "type": "string", "enum": [ "queued", "running", "needs-approval", "done", "failed" ] }, "waitingForMac": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "deviceId", "operation", "state", "waitingForMac", "message", "createdAt" ], "additionalProperties": false } }, "required": [ "call" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/runs/{runId}/approve": { "post": { "operationId": "approveRun", "summary": "Approve a run waiting on the Mac", "description": "Queues an approval for the Mac. Does not run the agent on the server.", "tags": [ "Devices" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "call": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "operation": { "type": "string", "enum": [ "delegateTask", "approveRun", "rejectRun", "replyToRun", "getRunState" ] }, "state": { "type": "string", "enum": [ "queued", "running", "needs-approval", "done", "failed" ] }, "waitingForMac": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "deviceId", "operation", "state", "waitingForMac", "message", "createdAt" ], "additionalProperties": false } }, "required": [ "call" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/runs/{runId}/reject": { "post": { "operationId": "rejectRun", "summary": "Reject a run waiting on the Mac", "description": "Queues a rejection with a note. Does not run the agent on the server.", "tags": [ "Devices" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "note" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "call": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "operation": { "type": "string", "enum": [ "delegateTask", "approveRun", "rejectRun", "replyToRun", "getRunState" ] }, "state": { "type": "string", "enum": [ "queued", "running", "needs-approval", "done", "failed" ] }, "waitingForMac": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "deviceId", "operation", "state", "waitingForMac", "message", "createdAt" ], "additionalProperties": false } }, "required": [ "call" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/runs/{runId}/reply": { "post": { "operationId": "replyToRun", "summary": "Send a message into a run on the Mac", "description": "Queues a reply. The Mac sends it on the conversation.", "tags": [ "Devices" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "call": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "operation": { "type": "string", "enum": [ "delegateTask", "approveRun", "rejectRun", "replyToRun", "getRunState" ] }, "state": { "type": "string", "enum": [ "queued", "running", "needs-approval", "done", "failed" ] }, "waitingForMac": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "deviceId", "operation", "state", "waitingForMac", "message", "createdAt" ], "additionalProperties": false } }, "required": [ "call" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/runs/{runId}/state": { "post": { "operationId": "reportRunState", "summary": "The Mac publishes a run step", "description": "Desktop only: step events (running, needs-approval, done, failed). Also writes a run-status realtime event for the phone.", "tags": [ "Devices" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "queued", "running", "needs-approval", "done", "failed" ] } }, "required": [ "state" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "call": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "operation": { "type": "string", "enum": [ "delegateTask", "approveRun", "rejectRun", "replyToRun", "getRunState" ] }, "state": { "type": "string", "enum": [ "queued", "running", "needs-approval", "done", "failed" ] }, "waitingForMac": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "deviceId", "operation", "state", "waitingForMac", "message", "createdAt" ], "additionalProperties": false } }, "required": [ "call" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/context": { "get": { "operationId": "getContext", "summary": "Get the prioritised workspace context", "description": "The entry point to call **first**. Returns, in one call: the workspace counters, the tasks scored highest by the prioritisation engine (with the reasons behind each score), the active projects and the areas.\n\nThe score combines the deadline, the scheduled date, the priority and whether the task belongs to a project. Calendar blocks are excluded.", "tags": [ "Context" ], "parameters": [ { "name": "day", "in": "query", "required": false, "description": "Reference day in YOUR timezone. Defaults to the server's UTC day.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 15, "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "day": { "type": "string" }, "counts": { "type": "object", "properties": { "open": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "overdue": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "dueToday": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "doneLast7Days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "open", "overdue", "dueToday", "doneLast7Days" ], "additionalProperties": false }, "topPriorities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "project": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "score", "reasons", "when", "deadline", "project" ], "additionalProperties": false } }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "openTaskCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "name", "openTaskCount" ], "additionalProperties": false } }, "areas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "day", "counts", "topPriorities", "projects", "areas" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/me": { "get": { "operationId": "whoami", "summary": "Identify the account and the server date", "description": "Returns the token holder's profile and the workspace counters.\n\n`nextUsernameChangeAt` is `null` when the username can be changed now, and a moment otherwise: a username is a public URL, so it moves at most once a fortnight.\n\n**Important about dates**: the server does not know your timezone and reasons in UTC. `serverDay` is the current UTC day. If your timezone differs, pass `day` explicitly to the operations that accept it.", "tags": [ "Context" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usernameUpdatedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "nextUsernameChangeAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "serverDay": { "type": "string" }, "serverTime": { "type": "number" }, "counts": { "type": "object", "properties": { "openTasks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "projects": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "areas": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "openTasks", "projects", "areas" ], "additionalProperties": false } }, "required": [ "userId", "name", "email", "username", "image", "usernameUpdatedAt", "nextUsernameChangeAt", "serverDay", "serverTime", "counts" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/search": { "get": { "operationId": "search", "summary": "Search the workspace", "description": "Text search across task titles, project names and area names. Use this **before** asking the user for an identifier.", "tags": [ "Context" ], "parameters": [ { "name": "kinds", "in": "query", "required": false, "description": "Restrict the search. Defaults to all three.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "task", "project", "area" ] } } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 } }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "task", "project", "area" ] }, "id": { "type": "string" }, "label": { "type": "string" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "id", "label", "detail" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/plan": { "get": { "operationId": "getDayPlan", "summary": "Read the day's plan", "description": "Returns the saved plan for the day (3 to 5 tasks, one focus task, a note) and the state of the ADHD-mode rounds.", "tags": [ "Plan" ], "parameters": [ { "name": "day", "in": "query", "required": false, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "day": { "type": "string" }, "plan": { "anyOf": [ { "type": "object", "properties": { "taskIds": { "type": "array", "items": { "type": "string" } }, "focusTaskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "title", "priority" ], "additionalProperties": false } } }, "required": [ "taskIds", "focusTaskId", "note", "tasks" ], "additionalProperties": false }, { "type": "null" } ] }, "rounds": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "type": "string" }, "taskIds": { "type": "array", "items": { "type": "string" } }, "engaged": { "type": "boolean" }, "closedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "index", "label", "taskIds", "engaged", "closedAt" ], "additionalProperties": false } } }, "required": [ "day", "plan", "rounds" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "operationId": "planToday", "summary": "Save the day's plan", "description": "Replaces the day's plan. `focusTaskId` names THE priority — if it is not in `taskIds`, the first task is used instead. The note is a short encouragement shown at the top of Today.", "tags": [ "Plan" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "day": { "type": "string", "description": "Local day key, `YYYY-MM-DD`.", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "focusTaskId": { "type": "string", "description": "Identifier of a row.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "note": { "type": "string", "default": "", "maxLength": 300 }, "taskIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "minItems": 1, "maxItems": 6 } }, "required": [ "taskIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "day": { "type": "string" }, "taskIds": { "type": "array", "items": { "type": "string" } }, "focusTaskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "type": "string" } }, "required": [ "day", "taskIds", "focusTaskId", "note" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/plan/rounds/{index}": { "put": { "operationId": "planRound", "summary": "Fill an ADHD-mode round", "description": "Replaces a round's mini-plan: 3 tasks maximum, the heaviest first. A task lives in one round only — it is removed from the day's other rounds.", "tags": [ "Plan" ], "parameters": [ { "name": "index", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 5 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "day": { "type": "string", "description": "Local day key, `YYYY-MM-DD`.", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "taskIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "minItems": 1, "maxItems": 3 } }, "required": [ "taskIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "day": { "type": "string" }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "taskIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "day", "index", "taskIds" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/plan/suggestion": { "get": { "operationId": "suggestDayPlan", "summary": "Propose a plan for the day", "description": "Computes a proposed plan from the prioritisation engine and splits the day into rounds. **Writes nothing**: it is a draft to put to the user, then commit with `PUT /v2/plan`.\n\nEach round gets at most 3 tasks, the heaviest first.", "tags": [ "Plan" ], "parameters": [ { "name": "day", "in": "query", "required": false, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "maxTasks", "in": "query", "required": false, "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 6 } }, { "name": "roundMin", "in": "query", "required": false, "schema": { "type": "integer", "default": 120, "minimum": 30, "maximum": 240 } }, { "name": "workEnd", "in": "query", "required": false, "description": "Time `HH:MM` — only meaningful alongside a date.", "schema": { "type": "string", "default": "18:00", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, { "name": "workStart", "in": "query", "required": false, "description": "Time `HH:MM` — only meaningful alongside a date.", "schema": { "type": "string", "default": "09:00", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "day": { "type": "string" }, "suggestion": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "score": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "title", "priority" ], "additionalProperties": false } }, "focusTaskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rounds": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "label": { "type": "string" }, "taskIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "index", "label", "taskIds" ], "additionalProperties": false } } }, "required": [ "day", "suggestion", "focusTaskId", "rounds" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/sessions": { "get": { "operationId": "listTodaySessions", "summary": "List the day's sessions", "description": "Sessions started at or after `since`, newest first. `since` is the start of the day in the caller's timezone, which only the caller knows — the server does not guess it. At most 100 are returned.", "tags": [ "Sessions" ], "parameters": [ { "name": "since", "in": "query", "required": true, "description": "Epoch milliseconds.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "startedAt": { "type": "number", "description": "Epoch milliseconds." }, "endedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` while the session is still running." }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "What the activity feed may show of it. Private until shared at the session's end." } }, "required": [ "id", "taskId", "title", "startedAt", "endedAt", "visibility" ], "additionalProperties": false } } }, "required": [ "sessions" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "startSession", "summary": "Start a session", "description": "Starts the timer. Any session still running is stopped first, so this is safe to call without checking the current state.", "tags": [ "Sessions" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, { "type": "null" } ] }, "title": { "type": "string", "maxLength": 500 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "startedAt": { "type": "number", "description": "Epoch milliseconds." }, "endedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` while the session is still running." }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "What the activity feed may show of it. Private until shared at the session's end." } }, "required": [ "id", "taskId", "title", "startedAt", "endedAt", "visibility" ], "additionalProperties": false } }, "required": [ "session" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/sessions/{sessionId}/visibility": { "put": { "operationId": "shareSession", "summary": "Share a finished session to Activity, or take it back", "description": "Public shows the effort and the task's title; anonymized shows the effort and only where the task lived; private, the default, shows nothing. Only a finished session of your own; a running one is refused.", "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private.", "enum": [ "public", "anonymized", "private" ] } }, "required": [ "visibility" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "startedAt": { "type": "number", "description": "Epoch milliseconds." }, "endedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` while the session is still running." }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "What the activity feed may show of it. Private until shared at the session's end." } }, "required": [ "id", "taskId", "title", "startedAt", "endedAt", "visibility" ], "additionalProperties": false } }, "required": [ "session" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/sessions/current": { "get": { "operationId": "getCurrentSession", "summary": "Get the running session", "description": "Returns the session still running, or `null` when the timer is stopped.", "tags": [ "Sessions" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "startedAt": { "type": "number", "description": "Epoch milliseconds." }, "endedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` while the session is still running." }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "What the activity feed may show of it. Private until shared at the session's end." } }, "required": [ "id", "taskId", "title", "startedAt", "endedAt", "visibility" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "session" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/sessions/stop": { "post": { "operationId": "stopSession", "summary": "Stop the running session", "description": "Stops the timer and returns the session it closed. Returns `null` when nothing was running: stopping a stopped timer is not an error.", "tags": [ "Sessions" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "startedAt": { "type": "number", "description": "Epoch milliseconds." }, "endedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` while the session is still running." }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "What the activity feed may show of it. Private until shared at the session's end." } }, "required": [ "id", "taskId", "title", "startedAt", "endedAt", "visibility" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "session" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/rounds": { "get": { "operationId": "listRounds", "summary": "The rounds of a day", "description": "Returns every round already planned, engaged or closed for that day, in order. A day with nothing on it returns an empty list rather than inventing rounds — a round exists once something has been said about it.", "tags": [ "Rounds" ], "parameters": [ { "name": "day", "in": "query", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rounds": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which round of the day, counting from zero." }, "taskIds": { "type": "array", "items": { "type": "string" }, "description": "The mini-plan, in display order." }, "engaged": { "type": "boolean", "description": "A session was started, or a planned task ticked." }, "closedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "When it was closed. The first close wins." } }, "required": [ "day", "index", "taskIds", "engaged", "closedAt" ], "additionalProperties": false } } }, "required": [ "rounds" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/rounds/{day}/{index}/close": { "post": { "operationId": "closeRound", "summary": "Close a round", "description": "Marks the round finished, stamping the moment. **The first close wins**: calling it again leaves the original timestamp alone, because when the work stopped is the fact worth keeping.\n\nA round that was never planned or engaged has nothing to close and answers 404.", "tags": [ "Rounds" ], "parameters": [ { "name": "day", "in": "path", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "index", "in": "path", "required": true, "description": "Which round of the day, counting from zero.", "schema": { "type": "integer", "minimum": 0, "maximum": 5 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "round": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which round of the day, counting from zero." }, "taskIds": { "type": "array", "items": { "type": "string" }, "description": "The mini-plan, in display order." }, "engaged": { "type": "boolean", "description": "A session was started, or a planned task ticked." }, "closedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "When it was closed. The first close wins." } }, "required": [ "day", "index", "taskIds", "engaged", "closedAt" ], "additionalProperties": false } }, "required": [ "round" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/rounds/{day}/{index}/engage": { "post": { "operationId": "markRoundEngaged", "summary": "Record that a round was actually worked", "description": "Engaged means a session was started or a planned task ticked during the round — the difference between a day that was planned and a day that happened.\n\nIdempotent, and it creates the round if nothing was planned for it: working an unplanned block still counts.", "tags": [ "Rounds" ], "parameters": [ { "name": "day", "in": "path", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "index", "in": "path", "required": true, "description": "Which round of the day, counting from zero.", "schema": { "type": "integer", "minimum": 0, "maximum": 5 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "round": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which round of the day, counting from zero." }, "taskIds": { "type": "array", "items": { "type": "string" }, "description": "The mini-plan, in display order." }, "engaged": { "type": "boolean", "description": "A session was started, or a planned task ticked." }, "closedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "When it was closed. The first close wins." } }, "required": [ "day", "index", "taskIds", "engaged", "closedAt" ], "additionalProperties": false } }, "required": [ "round" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/rounds/{day}/{index}/plan": { "put": { "operationId": "setRoundPlan", "summary": "Plan a round", "description": "Replaces the round's mini-plan. At most 3 tasks — one substantial and two small is the shape it was built for; a longer list is not a plan.\n\n**A task belongs to one round of the day.** Planning it here removes it from any other round of the same day, so it cannot appear twice.\n\nAn empty list clears the plan. The round itself is created if it does not exist yet. When movedTaskIds and both interval bounds are supplied, those tasks are also softly scheduled onto the target day without changing deadlines or completion state.", "tags": [ "Rounds" ], "parameters": [ { "name": "day", "in": "path", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "index", "in": "path", "required": true, "description": "Which round of the day, counting from zero.", "schema": { "type": "integer", "minimum": 0, "maximum": 5 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "movedTaskIds": { "type": "array", "description": "The subset moved by this request and softly scheduled into the interval.", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "minItems": 1, "maxItems": 3 }, "roundEndMin": { "type": "integer", "description": "Exclusive target interval end, in minutes after midnight.", "minimum": 1, "maximum": 1440 }, "roundStartMin": { "type": "integer", "description": "Inclusive target interval start, in minutes after midnight.", "minimum": 0, "maximum": 1439 }, "taskIds": { "type": "array", "description": "In display order. Pass an empty array to clear the plan.", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Identifier of a row." }, "maxItems": 3 } }, "required": [ "taskIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "round": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Which round of the day, counting from zero." }, "taskIds": { "type": "array", "items": { "type": "string" }, "description": "The mini-plan, in display order." }, "engaged": { "type": "boolean", "description": "A session was started, or a planned task ticked." }, "closedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "When it was closed. The first close wins." } }, "required": [ "day", "index", "taskIds", "engaged", "closedAt" ], "additionalProperties": false }, "removedFromOtherRounds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "round", "removedFromOtherRounds" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/journal": { "get": { "operationId": "getJournal", "summary": "Read the journal window", "description": "The raw material of the journal: tasks completed, sessions worked, and the entries written. Nothing is bucketed by day — the caller's timezone decides where a day starts, and only the caller knows it. `since` bounds the first two; `sinceDay` bounds the entries, which are already keyed by local day.", "tags": [ "Journal" ], "parameters": [ { "name": "since", "in": "query", "required": true, "description": "Epoch milliseconds.", "schema": { "type": "number" } }, { "name": "sinceDay", "in": "query", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "completions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "completedAt": { "type": "number", "description": "Epoch milliseconds." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "completedAt", "projectId", "areaId" ], "additionalProperties": false } }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "startedAt": { "type": "number", "description": "Epoch milliseconds." }, "endedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` while the session is still running." }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "What the activity feed may show of it. Private until shared at the session's end." } }, "required": [ "id", "taskId", "title", "startedAt", "endedAt", "visibility" ], "additionalProperties": false } }, "entries": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "mood": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "1 worst — 5 best, or `null` for a day left unrated." }, "note": { "type": "string" } }, "required": [ "day", "mood", "note" ], "additionalProperties": false } } }, "required": [ "completions", "sessions", "entries" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/journal/{day}": { "put": { "operationId": "upsertJournalEntry", "summary": "Write the day's mood and note", "description": "Creates the day's entry or patches it. An omitted field is left alone; an explicit `null` mood clears the rating, which is how the app toggles a face off.", "tags": [ "Journal" ], "parameters": [ { "name": "day", "in": "path", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "mood": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 5, "description": "How the day felt: 1 worst — 5 best." }, { "type": "null" } ] }, "note": { "type": "string", "maxLength": 10000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "mood": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "1 worst — 5 best, or `null` for a day left unrated." }, "note": { "type": "string" } }, "required": [ "day", "mood", "note" ], "additionalProperties": false } }, "required": [ "entry" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/habits": { "get": { "operationId": "listHabits", "summary": "List your habits", "description": "Every habit, oldest first. Archived ones only when asked for.", "tags": [ "Habits" ], "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "habits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "startsOn": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The anchor every occurrence is expanded from." }, "rule": { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit" ], "additionalProperties": false, "description": "A habit's rule: the task's repeat grammar without a mode, phased on `startsOn`." }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "check" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quantity" }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000 }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "kind", "amount", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "minutes" }, "minutes": { "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "kind", "minutes" ], "additionalProperties": false } ], "description": "What one occurrence asks for: a tick, a quantity in a unit, or minutes." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "archivedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "name", "startsOn", "rule", "target", "createdAt", "archivedAt" ], "additionalProperties": false } } }, "required": [ "habits" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createHabit", "summary": "Create a habit", "description": "A name, the day it starts, a rule, and a target. The rule is the task's repeat grammar without a mode: a habit is always phased on the day it starts.", "tags": [ "Habits" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "rule": { "type": "object", "description": "A habit's rule: the task's repeat grammar without a mode, phased on `startsOn`.", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit" ] }, "startsOn": { "type": "string", "description": "Local day key, `YYYY-MM-DD`.", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "target": { "description": "What one occurrence asks for: a tick, a quantity in a unit, or minutes.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "check" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quantity" }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000 }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "kind", "amount", "unit" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "minutes" }, "minutes": { "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "kind", "minutes" ] } ] } }, "required": [ "name", "rule", "startsOn", "target" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "habit": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "startsOn": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The anchor every occurrence is expanded from." }, "rule": { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit" ], "additionalProperties": false, "description": "A habit's rule: the task's repeat grammar without a mode, phased on `startsOn`." }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "check" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quantity" }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000 }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "kind", "amount", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "minutes" }, "minutes": { "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "kind", "minutes" ], "additionalProperties": false } ], "description": "What one occurrence asks for: a tick, a quantity in a unit, or minutes." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "archivedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "name", "startsOn", "rule", "target", "createdAt", "archivedAt" ], "additionalProperties": false } }, "required": [ "habit" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/habits/{habitId}": { "patch": { "operationId": "updateHabit", "summary": "Update a habit", "description": "Any of the name, the start day, the rule or the target. History is untouched.", "tags": [ "Habits" ], "parameters": [ { "name": "habitId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "rule": { "type": "object", "description": "A habit's rule: the task's repeat grammar without a mode, phased on `startsOn`.", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit" ] }, "startsOn": { "type": "string", "description": "Local day key, `YYYY-MM-DD`.", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "target": { "description": "What one occurrence asks for: a tick, a quantity in a unit, or minutes.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "check" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quantity" }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000 }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "kind", "amount", "unit" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "minutes" }, "minutes": { "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "kind", "minutes" ] } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "habit": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "startsOn": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The anchor every occurrence is expanded from." }, "rule": { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit" ], "additionalProperties": false, "description": "A habit's rule: the task's repeat grammar without a mode, phased on `startsOn`." }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "check" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quantity" }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000 }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "kind", "amount", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "minutes" }, "minutes": { "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "kind", "minutes" ], "additionalProperties": false } ], "description": "What one occurrence asks for: a tick, a quantity in a unit, or minutes." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "archivedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "name", "startsOn", "rule", "target", "createdAt", "archivedAt" ], "additionalProperties": false } }, "required": [ "habit" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/habits/{habitId}/archive": { "post": { "operationId": "archiveHabit", "summary": "Archive a habit", "description": "Takes it out of the list and out of what is due. Its completions stay, so what was done can still be counted. Archiving twice is a no-op.", "tags": [ "Habits" ], "parameters": [ { "name": "habitId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "habit": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "startsOn": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The anchor every occurrence is expanded from." }, "rule": { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit" ], "additionalProperties": false, "description": "A habit's rule: the task's repeat grammar without a mode, phased on `startsOn`." }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "check" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quantity" }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000 }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "kind", "amount", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "minutes" }, "minutes": { "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "kind", "minutes" ], "additionalProperties": false } ], "description": "What one occurrence asks for: a tick, a quantity in a unit, or minutes." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "archivedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "name", "startsOn", "rule", "target", "createdAt", "archivedAt" ], "additionalProperties": false } }, "required": [ "habit" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/habits/{habitId}/completions/{day}": { "put": { "operationId": "completeHabit", "summary": "Complete a habit for a day", "description": "Records the occurrence, with what was done for a measured target. Doing it again for the same day updates the one record rather than adding a second. Refused on a day the habit is not due, and on an archived habit.", "tags": [ "Habits" ], "parameters": [ { "name": "day", "in": "path", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "habitId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "maximum": 100000 }, "minutes": { "type": "integer", "minimum": 0, "maximum": 1440 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "completion": { "type": "object", "properties": { "id": { "type": "string" }, "habitId": { "type": "string" }, "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "amount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What was done, for a quantity target." }, "minutes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What was done, for a minutes target." }, "completedAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "habitId", "day", "amount", "minutes", "completedAt" ], "additionalProperties": false } }, "required": [ "completion" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "uncompleteHabit", "summary": "Undo a day's completion", "description": "Removes the occurrence's record. Not found when there was none.", "tags": [ "Habits" ], "parameters": [ { "name": "day", "in": "path", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "habitId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/habits/completions": { "get": { "operationId": "listHabitCompletions", "summary": "What was done, over a window", "description": "Every completion between two days inclusive, oldest first, archived habits included: the ledger the Logbook and the Stats read.", "tags": [ "Habits" ], "parameters": [ { "name": "since", "in": "query", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "until", "in": "query", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "completions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "habitId": { "type": "string" }, "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "amount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What was done, for a quantity target." }, "minutes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What was done, for a minutes target." }, "completedAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "habitId", "day", "amount", "minutes", "completedAt" ], "additionalProperties": false } } }, "required": [ "completions" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/habits/due/{day}": { "get": { "operationId": "listDueHabits", "summary": "What is due on a day", "description": "The habits whose rule fires on that day, each with its completion for the day if any. Archived habits are never due.", "tags": [ "Habits" ], "parameters": [ { "name": "day", "in": "path", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "habits": { "type": "array", "items": { "type": "object", "properties": { "habit": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "startsOn": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The anchor every occurrence is expanded from." }, "rule": { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit" ], "additionalProperties": false, "description": "A habit's rule: the task's repeat grammar without a mode, phased on `startsOn`." }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "check" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "quantity" }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000 }, "unit": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "kind", "amount", "unit" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "minutes" }, "minutes": { "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "kind", "minutes" ], "additionalProperties": false } ], "description": "What one occurrence asks for: a tick, a quantity in a unit, or minutes." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "archivedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "name", "startsOn", "rule", "target", "createdAt", "archivedAt" ], "additionalProperties": false }, "completion": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "habitId": { "type": "string" }, "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "amount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What was done, for a quantity target." }, "minutes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What was done, for a minutes target." }, "completedAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "habitId", "day", "amount", "minutes", "completedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "habit", "completion" ], "additionalProperties": false } } }, "required": [ "habits" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/stats": { "get": { "operationId": "getStats", "summary": "Read the raw activity events", "description": "Completions and sessions since `since`, plus every day plan, all unaggregated. Bucketing by day or hour happens in the caller's timezone, so the server returns moments rather than buckets — an hour histogram computed here would be wrong for everyone outside UTC. Plans are keyed by local day, which `since` cannot be compared against without that same timezone, so they are not windowed.", "tags": [ "Stats" ], "parameters": [ { "name": "since", "in": "query", "required": true, "description": "Epoch milliseconds.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "completions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "completedAt": { "type": "number", "description": "Epoch milliseconds." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "completedAt", "projectId", "areaId" ], "additionalProperties": false } }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "startedAt": { "type": "number", "description": "Epoch milliseconds." }, "endedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` while the session is still running." }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "What the activity feed may show of it. Private until shared at the session's end." } }, "required": [ "id", "taskId", "title", "startedAt", "endedAt", "visibility" ], "additionalProperties": false } }, "plans": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "taskIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "day", "taskIds" ], "additionalProperties": false } } }, "required": [ "completions", "sessions", "plans" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/users/me": { "get": { "operationId": "getMe", "summary": "The signed-in account", "description": "The caller's own profile. Distinct from the session endpoint, which says who you are but not when you may next change your username — a rule this API enforces and only this API knows the shape of.\n\n`nextUsernameChangeAt` is `null` when the username has never been set, which is the one case with no cooldown.", "tags": [ "Users" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "me": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usernameUpdatedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "nextUsernameChangeAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "When the username may next change. `null` when it has never been set." } }, "required": [ "id", "name", "email", "username", "image", "usernameUpdatedAt", "nextUsernameChangeAt" ], "additionalProperties": false } }, "required": [ "me" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/users/search": { "get": { "operationId": "searchUsers", "summary": "Find someone to share with", "description": "Deliberately narrow: a username prefix, or a **whole** email address. There is no fuzzy match and no name search, because a directory of everyone is what this must not be. An address is echoed back only when it was already known to the caller — a prefix search never reveals one. At most 8 are returned.", "tags": [ "Users" ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false } } }, "required": [ "users" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/leaderboard": { "get": { "operationId": "getLeaderboard", "summary": "The week's board", "description": "Who opted in, ranked on verified focus time and consistency — never on how many tasks they ticked — under a named, versioned rule. Global, or only the people you follow and you. This week, or last week's recap.", "tags": [ "Profiles" ], "parameters": [ { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "global", "following" ] } }, { "name": "week", "in": "query", "required": true, "description": "This week, or last week's recap. Weeks start on Monday, UTC.", "schema": { "type": "string", "enum": [ "current", "previous" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "leaderboard": { "type": "object", "properties": { "version": { "type": "string", "description": "The ranking rule this board was ranked under." }, "scope": { "type": "string", "enum": [ "global", "following" ] }, "week": { "type": "string", "enum": [ "current", "previous" ], "description": "This week, or last week's recap. Weeks start on Monday, UTC." }, "weekStart": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Competition ranking: equal activity shares a rank." }, "username": { "type": "string" }, "name": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "focusMinutes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "streakDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The longest run of active days in the week." }, "isMe": { "type": "boolean" } }, "required": [ "rank", "username", "name", "image", "focusMinutes", "activeDays", "streakDays", "isMe" ], "additionalProperties": false } }, "me": { "anyOf": [ { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Competition ranking: equal activity shares a rank." }, "username": { "type": "string" }, "name": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "focusMinutes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "streakDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The longest run of active days in the week." }, "isMe": { "type": "boolean" } }, "required": [ "rank", "username", "name", "image", "focusMinutes", "activeDays", "streakDays", "isMe" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` unless you opted in." } }, "required": [ "version", "scope", "week", "weekStart", "entries", "me" ], "additionalProperties": false } }, "required": [ "leaderboard" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/people/{username}": { "get": { "operationId": "getPublicProfile", "summary": "Someone's profile", "description": "A public profile, or your own whatever its visibility. A private one is not found.", "tags": [ "Profiles" ], "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "username": { "type": "string" }, "name": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "foundingNumber": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Signup order: the first account is 1." }, "isFoundingMember": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "`null` while the founding cutoff is not named." }, "followers": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "following": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFollowed": { "type": "boolean", "description": "Whether the caller follows this profile." }, "stats": { "anyOf": [ { "type": "object", "properties": { "focusMinutesLast7Days": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeDaysLast28": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "streakDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "focusMinutesLast7Days", "activeDaysLast28", "streakDays" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` when the profile is not public." } }, "required": [ "username", "name", "image", "foundingNumber", "isFoundingMember", "followers", "following", "isFollowed", "stats" ], "additionalProperties": false } }, "required": [ "profile" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/people/{username}/follow": { "post": { "operationId": "followProfile", "summary": "Follow someone", "description": "Only a public profile can be followed, and not your own. Following twice is a no-op.", "tags": [ "Profiles" ], "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "username": { "type": "string" }, "name": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "foundingNumber": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Signup order: the first account is 1." }, "isFoundingMember": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "`null` while the founding cutoff is not named." }, "followers": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "following": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFollowed": { "type": "boolean", "description": "Whether the caller follows this profile." }, "stats": { "anyOf": [ { "type": "object", "properties": { "focusMinutesLast7Days": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeDaysLast28": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "streakDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "focusMinutesLast7Days", "activeDaysLast28", "streakDays" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` when the profile is not public." } }, "required": [ "username", "name", "image", "foundingNumber", "isFoundingMember", "followers", "following", "isFollowed", "stats" ], "additionalProperties": false } }, "required": [ "profile" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "unfollowProfile", "summary": "Stop following someone", "description": "Works whatever their visibility now. Not found when you did not follow them.", "tags": [ "Profiles" ], "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/profiles/me": { "get": { "operationId": "getMyProfile", "summary": "Your profile", "description": "Your handle, whether you are visible, your founding number from signup order, and how many follow you and you follow.", "tags": [ "Profiles" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "private", "public" ], "description": "Private until its owner says otherwise." }, "leaderboard": { "type": "boolean", "description": "Opted into the leaderboards. Off by default." }, "foundingNumber": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "isFoundingMember": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "followers": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "following": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "username", "name", "image", "visibility", "leaderboard", "foundingNumber", "isFoundingMember", "followers", "following" ], "additionalProperties": false } }, "required": [ "profile" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/profiles/me/followers": { "get": { "operationId": "listFollowers", "summary": "Who follows you", "description": "Each as a profile; a private follower shows a handle and no stats.", "tags": [ "Profiles" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "people": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "name": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "foundingNumber": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Signup order: the first account is 1." }, "isFoundingMember": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "`null` while the founding cutoff is not named." }, "followers": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "following": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFollowed": { "type": "boolean", "description": "Whether the caller follows this profile." }, "stats": { "anyOf": [ { "type": "object", "properties": { "focusMinutesLast7Days": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeDaysLast28": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "streakDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "focusMinutesLast7Days", "activeDaysLast28", "streakDays" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` when the profile is not public." } }, "required": [ "username", "name", "image", "foundingNumber", "isFoundingMember", "followers", "following", "isFollowed", "stats" ], "additionalProperties": false } } }, "required": [ "people" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/profiles/me/following": { "get": { "operationId": "listFollowing", "summary": "Who you follow", "description": "Each as a profile; one that went private since shows a handle and no stats.", "tags": [ "Profiles" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "people": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "name": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "foundingNumber": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Signup order: the first account is 1." }, "isFoundingMember": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "`null` while the founding cutoff is not named." }, "followers": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "following": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFollowed": { "type": "boolean", "description": "Whether the caller follows this profile." }, "stats": { "anyOf": [ { "type": "object", "properties": { "focusMinutesLast7Days": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "activeDaysLast28": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "streakDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "focusMinutesLast7Days", "activeDaysLast28", "streakDays" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` when the profile is not public." } }, "required": [ "username", "name", "image", "foundingNumber", "isFoundingMember", "followers", "following", "isFollowed", "stats" ], "additionalProperties": false } } }, "required": [ "people" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/profiles/me/visibility": { "put": { "operationId": "setProfileVisibility", "summary": "Open or close your profile", "description": "Public lets anyone read your handle, your verified focus and your consistency — never a task, a note or a project. Private, the default, hides the profile from everyone but you; who follows you is kept either way. The leaderboards are a separate opt-in, off by default.", "tags": [ "Profiles" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "leaderboard": { "type": "boolean", "description": "Opt into, or out of, the leaderboards." }, "visibility": { "type": "string", "description": "Private until its owner says otherwise.", "enum": [ "private", "public" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "private", "public" ], "description": "Private until its owner says otherwise." }, "leaderboard": { "type": "boolean", "description": "Opted into the leaderboards. Off by default." }, "foundingNumber": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "isFoundingMember": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "followers": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "following": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "username", "name", "image", "visibility", "leaderboard", "foundingNumber", "isFoundingMember", "followers", "following" ], "additionalProperties": false } }, "required": [ "profile" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "The workspaces you are in", "description": "Your own personal workspace first — every account has one from signup — then every team you own or sit in, oldest first, each with your role and the plan its owner holds.", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The segment under the site's root: the owner's handle for a personal workspace, the team's own slug otherwise. `null` while a personal workspace's owner has no handle." }, "logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA name; `null` means each person's own." }, "isPersonal": { "type": "boolean", "description": "Minted at signup, named after the person, never handed over." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." }, "plan": { "type": "string", "enum": [ "free", "pro", "team" ], "description": "The owner's plan, read when asked; it is what pays the seats." }, "whoCanInvite": { "type": "string", "enum": [ "admins", "everyone" ], "description": "Who may invite into the workspace: its admins, or everyone in it." }, "newAreasShared": { "type": "boolean", "description": "New areas open to everyone in the workspace, at view." } }, "required": [ "id", "name", "address", "logo", "timezone", "isPersonal", "role", "plan", "whoCanInvite", "newAreasShared" ], "additionalProperties": false } } }, "required": [ "workspaces" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createWorkspace", "summary": "Start a team workspace", "description": "You become its owner. The address follows the handle rules and must be free among both handles and workspaces. Your personal workspace is not created this way: it exists.", "tags": [ "Workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "slug": { "type": "string", "description": "The team's segment under the site's root. Handle rules; one namespace with handles." } }, "required": [ "name", "slug" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The segment under the site's root: the owner's handle for a personal workspace, the team's own slug otherwise. `null` while a personal workspace's owner has no handle." }, "logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA name; `null` means each person's own." }, "isPersonal": { "type": "boolean", "description": "Minted at signup, named after the person, never handed over." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." }, "plan": { "type": "string", "enum": [ "free", "pro", "team" ], "description": "The owner's plan, read when asked; it is what pays the seats." }, "whoCanInvite": { "type": "string", "enum": [ "admins", "everyone" ], "description": "Who may invite into the workspace: its admins, or everyone in it." }, "newAreasShared": { "type": "boolean", "description": "New areas open to everyone in the workspace, at view." } }, "required": [ "id", "name", "address", "logo", "timezone", "isPersonal", "role", "plan", "whoCanInvite", "newAreasShared" ], "additionalProperties": false } }, "required": [ "workspace" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces/{workspaceId}": { "get": { "operationId": "getWorkspace", "summary": "One workspace", "description": "As you see it: your role, its address, its plan. Not found unless you are in it.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The segment under the site's root: the owner's handle for a personal workspace, the team's own slug otherwise. `null` while a personal workspace's owner has no handle." }, "logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA name; `null` means each person's own." }, "isPersonal": { "type": "boolean", "description": "Minted at signup, named after the person, never handed over." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." }, "plan": { "type": "string", "enum": [ "free", "pro", "team" ], "description": "The owner's plan, read when asked; it is what pays the seats." }, "whoCanInvite": { "type": "string", "enum": [ "admins", "everyone" ], "description": "Who may invite into the workspace: its admins, or everyone in it." }, "newAreasShared": { "type": "boolean", "description": "New areas open to everyone in the workspace, at view." } }, "required": [ "id", "name", "address", "logo", "timezone", "isPersonal", "role", "plan", "whoCanInvite", "newAreasShared" ], "additionalProperties": false } }, "required": [ "workspace" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "updateWorkspace", "summary": "Rename or re-address a workspace", "description": "Renaming is the owner's; the address, the logo, the time zone and who may invite are an admin's too. A personal workspace keeps its owner's handle as its address and cannot be given another.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "logo": { "description": "A square picture; `null` removes it.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "newAreasShared": { "type": "boolean" }, "slug": { "type": "string", "description": "The team's segment under the site's root. Handle rules; one namespace with handles." }, "timezone": { "anyOf": [ { "type": "string", "description": "An IANA time zone name, such as `Europe/Paris`." }, { "type": "null" } ] }, "whoCanInvite": { "type": "string", "description": "Who may invite into the workspace: its admins, or everyone in it.", "enum": [ "admins", "everyone" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The segment under the site's root: the owner's handle for a personal workspace, the team's own slug otherwise. `null` while a personal workspace's owner has no handle." }, "logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA name; `null` means each person's own." }, "isPersonal": { "type": "boolean", "description": "Minted at signup, named after the person, never handed over." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." }, "plan": { "type": "string", "enum": [ "free", "pro", "team" ], "description": "The owner's plan, read when asked; it is what pays the seats." }, "whoCanInvite": { "type": "string", "enum": [ "admins", "everyone" ], "description": "Who may invite into the workspace: its admins, or everyone in it." }, "newAreasShared": { "type": "boolean", "description": "New areas open to everyone in the workspace, at view." } }, "required": [ "id", "name", "address", "logo", "timezone", "isPersonal", "role", "plan", "whoCanInvite", "newAreasShared" ], "additionalProperties": false } }, "required": [ "workspace" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteWorkspace", "summary": "Delete a team workspace", "description": "Owner only. Everything filed in it goes with it. A personal workspace cannot be deleted; deleting the account is what removes it. Requires your app session; delegated credentials and the coach are refused.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces/{workspaceId}/invites/{inviteId}/revoke": { "post": { "operationId": "revokeWorkspaceInvite", "summary": "Cancel a pending invitation", "description": "Owner or admin. The link stops working immediately.", "tags": [ "Workspaces" ], "parameters": [ { "name": "inviteId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces/{workspaceId}/join-link": { "put": { "operationId": "setWorkspaceJoinLink", "summary": "Switch the join link on or off", "description": "Owner or admin. Switching it on mints a fresh link, returned **once**; switching it off stops the old one at once. Anyone holding the link sits down as a member while a seat is spare.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "joinPath": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where to send people. Shown once; `null` when off." } }, "required": [ "joinPath" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces/{workspaceId}/leave": { "post": { "operationId": "leaveWorkspace", "summary": "Leave a workspace", "description": "Your tasks stay with the team. The owner cannot leave: hand the workspace over first.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "left": { "type": "boolean" } }, "required": [ "left" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces/{workspaceId}/members": { "get": { "operationId": "listWorkspaceMembers", "summary": "Who is in a workspace", "description": "The owner, everyone seated, the seats the plan holds, and whether you may invite. Pending invitations are listed to the owner and the admins only — they carry a link that grants a seat — and never with their link.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." }, "joinedAt": { "type": "number", "description": "When they sat down; for the owner, the workspace's birth." } }, "required": [ "id", "username", "name", "email", "image", "role", "joinedAt" ], "additionalProperties": false }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." }, "joinedAt": { "type": "number", "description": "When they sat down; for the owner, the workspace's birth." } }, "required": [ "id", "username", "name", "email", "image", "role", "joinedAt" ], "additionalProperties": false } }, "invites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "invitePath": { "type": "string", "description": "Where to send them. Carries the token, so treat it as one." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "email", "role", "invitePath", "createdAt" ], "additionalProperties": false } }, "seats": { "anyOf": [ { "type": "object", "properties": { "included": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "included", "used" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` unless the owner holds a team plan." }, "canInvite": { "type": "boolean" }, "joinLinkOn": { "type": "boolean", "description": "Whether the join link is on; the link itself is shown once, when switched on." } }, "required": [ "owner", "members", "invites", "seats", "canInvite", "joinLinkOn" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "inviteWorkspaceMember", "summary": "Seat someone, by handle or by email", "description": "`target` is a handle or an email address. A matching account sits down at once and takes a seat; an address that matches nobody produces an invitation link to send them. Only while a seat is spare, and only for those the workspace lets invite.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member" ], "default": "member" }, "target": { "type": "string", "minLength": 1, "maxLength": 254 } }, "required": [ "target" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "member" }, "member": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." }, "joinedAt": { "type": "number", "description": "When they sat down; for the owner, the workspace's birth." } }, "required": [ "id", "username", "name", "email", "image", "role", "joinedAt" ], "additionalProperties": false } }, "required": [ "kind", "member" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "invite" }, "invite": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "invitePath": { "type": "string", "description": "Where to send them. Carries the token, so treat it as one." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "email", "role", "invitePath", "createdAt" ], "additionalProperties": false } }, "required": [ "kind", "invite" ], "additionalProperties": false } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces/{workspaceId}/members/{username}": { "patch": { "operationId": "setWorkspaceMemberRole", "summary": "Change someone's role", "description": "Owner or admin. The owner has no role to change: handing over is its own operation.", "tags": [ "Workspaces" ], "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member" ] } }, "required": [ "role" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." }, "joinedAt": { "type": "number", "description": "When they sat down; for the owner, the workspace's birth." } }, "required": [ "id", "username", "name", "email", "image", "role", "joinedAt" ], "additionalProperties": false } }, "required": [ "member" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "removeWorkspaceMember", "summary": "Take someone's seat away", "description": "Owner or admin. Their tasks stay in the workspace; their seat is free at once. Not found when they held none.", "tags": [ "Workspaces" ], "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces/{workspaceId}/transfer": { "post": { "operationId": "transferWorkspace", "summary": "Hand a team over", "description": "Owner only, to someone already in the workspace, by handle. You stay as an admin. A personal workspace is never handed over. Requires your app session; delegated credentials and the coach are refused.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" } }, "required": [ "username" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The segment under the site's root: the owner's handle for a personal workspace, the team's own slug otherwise. `null` while a personal workspace's owner has no handle." }, "logo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA name; `null` means each person's own." }, "isPersonal": { "type": "boolean", "description": "Minted at signup, named after the person, never handed over." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." }, "plan": { "type": "string", "enum": [ "free", "pro", "team" ], "description": "The owner's plan, read when asked; it is what pays the seats." }, "whoCanInvite": { "type": "string", "enum": [ "admins", "everyone" ], "description": "Who may invite into the workspace: its admins, or everyone in it." }, "newAreasShared": { "type": "boolean", "description": "New areas open to everyone in the workspace, at view." } }, "required": [ "id", "name", "address", "logo", "timezone", "isPersonal", "role", "plan", "whoCanInvite", "newAreasShared" ], "additionalProperties": false } }, "required": [ "workspace" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces/invites/accept": { "post": { "operationId": "acceptWorkspaceInvite", "summary": "Accept an invitation into a workspace", "description": "Accepts a link, but **only** for the account carrying the address it was sent to; forwarded, it grants nothing. Refused when every seat has been taken since it was sent.", "tags": [ "Workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." } }, "required": [ "workspaceId", "role" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces/join": { "post": { "operationId": "joinWorkspace", "summary": "Join a workspace by its link", "description": "Sits you down as a member while the link is on and a seat is spare.", "tags": [ "Workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Ascending. `owner` is not grantable: it is what owning the workspace means." } }, "required": [ "workspaceId", "role" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/access-invites/accept": { "post": { "operationId": "acceptAccessInvite", "summary": "Accept an invitation to a project or an area", "description": "Accepts a link, but **only** for the account carrying the address it was sent to; forwarded, it grants nothing. Outside the target's workspace, the level is Can comment at most.", "tags": [ "Access" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "targetKind": { "type": "string", "enum": [ "project", "area" ], "description": "What is shared: a project, or an area and every project in it." }, "targetId": { "type": "string" }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." } }, "required": [ "targetKind", "targetId", "role" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/access/{targetKind}/{targetId}": { "get": { "operationId": "getAccess", "summary": "Who reaches a project or an area", "description": "The owner, everyone granted on it with their level, the workspace-wide row, whether a public link is on, how many tasks it holds, and your own role. Pending invitations are listed to those who may manage it — they carry a link that grants access — and never with their link.", "tags": [ "Access" ], "parameters": [ { "name": "targetId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "targetKind", "in": "path", "required": true, "description": "What is shared: a project, or an area and every project in it.", "schema": { "type": "string", "enum": [ "project", "area" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Yours." }, "canManage": { "type": "boolean", "description": "The owner, or an owner or admin of the target's workspace, may change who reaches it." }, "owner": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "membershipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The row to patch or delete. `null` for the owner, who has no membership." }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." } }, "required": [ "id", "username", "name", "email", "image", "membershipId", "role" ], "additionalProperties": false }, "people": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accessId": { "type": "string", "description": "The grant to patch or delete." }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." }, "isGuest": { "type": "boolean", "description": "Not seated in the target's workspace: reaches this one thing, at Can comment at most." } }, "required": [ "id", "username", "name", "email", "image", "accessId", "role", "isGuest" ], "additionalProperties": false } }, "invites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." }, "invitePath": { "type": "string", "description": "Where to send them. Carries the token, so treat it as one." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "email", "role", "invitePath", "createdAt" ], "additionalProperties": false }, "description": "Pending, listed to those who may manage; never with a link." }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "access": { "type": "string", "enum": [ "none", "view", "edit" ], "description": "What everyone in the target's workspace may do with it: nothing, read, or edit." }, "plan": { "type": "string", "enum": [ "free", "pro", "team" ], "description": "The workspace owner's plan; Pro never sees the word workspace." } }, "required": [ "id", "name", "access", "plan" ], "additionalProperties": false }, "link": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "targetKind": { "type": "string", "enum": [ "task", "project", "area" ], "description": "What the link points at." }, "targetId": { "type": "string" }, "label": { "type": "string", "description": "The name of what is shared, as it stands today." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "targetKind", "targetId", "label", "email", "createdAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "The public link, when one is on; never its address." }, "taskCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "role", "canManage", "owner", "people", "invites", "workspace", "link", "taskCount" ], "additionalProperties": false } }, "required": [ "access" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "grantAccess", "summary": "Give someone access, by handle or by email", "description": "`target` is a handle or an email address. A matching account is added at once; an address that matches nobody produces an invitation link to send them. Granting again changes the level. Someone outside the target's workspace is a guest: the level is capped at Can comment, and `clampedToGuest` says when it was.", "tags": [ "Access" ], "parameters": [ { "name": "targetId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "targetKind", "in": "path", "required": true, "description": "What is shared: a project, or an area and every project in it.", "schema": { "type": "string", "enum": [ "project", "area" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "reader", "commenter", "editor" ] }, "target": { "type": "string", "minLength": 1, "maxLength": 254 } }, "required": [ "role", "target" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "member" }, "member": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accessId": { "type": "string", "description": "The grant to patch or delete." }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." }, "isGuest": { "type": "boolean", "description": "Not seated in the target's workspace: reaches this one thing, at Can comment at most." } }, "required": [ "id", "username", "name", "email", "image", "accessId", "role", "isGuest" ], "additionalProperties": false }, "clampedToGuest": { "type": "boolean" } }, "required": [ "kind", "member", "clampedToGuest" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "invite" }, "invite": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." }, "invitePath": { "type": "string", "description": "Where to send them. Carries the token, so treat it as one." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "email", "role", "invitePath", "createdAt" ], "additionalProperties": false } }, "required": [ "kind", "invite" ], "additionalProperties": false } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/access/{targetKind}/{targetId}/invites/{inviteId}/revoke": { "post": { "operationId": "revokeAccessInvite", "summary": "Cancel a pending invitation", "description": "The link stops working immediately.", "tags": [ "Access" ], "parameters": [ { "name": "inviteId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "targetId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "targetKind", "in": "path", "required": true, "description": "What is shared: a project, or an area and every project in it.", "schema": { "type": "string", "enum": [ "project", "area" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/access/{targetKind}/{targetId}/people/{accessId}": { "patch": { "operationId": "setAccessRole", "summary": "Change someone's level", "description": "A guest stays at Can comment at most. The owner's level is not a grant.", "tags": [ "Access" ], "parameters": [ { "name": "accessId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "targetId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "targetKind", "in": "path", "required": true, "description": "What is shared: a project, or an area and every project in it.", "schema": { "type": "string", "enum": [ "project", "area" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "reader", "commenter", "editor" ] } }, "required": [ "role" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accessId": { "type": "string", "description": "The grant to patch or delete." }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." }, "isGuest": { "type": "boolean", "description": "Not seated in the target's workspace: reaches this one thing, at Can comment at most." } }, "required": [ "id", "username", "name", "email", "image", "accessId", "role", "isGuest" ], "additionalProperties": false } }, "required": [ "member" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "revokeAccess", "summary": "Take someone's access away", "description": "Access stops on their next request.", "tags": [ "Access" ], "parameters": [ { "name": "accessId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "targetId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "targetKind", "in": "path", "required": true, "description": "What is shared: a project, or an area and every project in it.", "schema": { "type": "string", "enum": [ "project", "area" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/access/{targetKind}/{targetId}/workspace": { "put": { "operationId": "setWorkspaceAccess", "summary": "Open or close the target to everyone in its workspace", "description": "The \"Everyone in \" row: `view` lets whoever sits in the workspace read it, `edit` lets them edit, `none` closes it to all but the people granted. Never reaches anyone outside the workspace.", "tags": [ "Access" ], "parameters": [ { "name": "targetId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "targetKind", "in": "path", "required": true, "description": "What is shared: a project, or an area and every project in it.", "schema": { "type": "string", "enum": [ "project", "area" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "string", "description": "What everyone in the target's workspace may do with it: nothing, read, or edit.", "enum": [ "none", "view", "edit" ] } }, "required": [ "access" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Yours." }, "canManage": { "type": "boolean", "description": "The owner, or an owner or admin of the target's workspace, may change who reaches it." }, "owner": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "membershipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The row to patch or delete. `null` for the owner, who has no membership." }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." } }, "required": [ "id", "username", "name", "email", "image", "membershipId", "role" ], "additionalProperties": false }, "people": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accessId": { "type": "string", "description": "The grant to patch or delete." }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." }, "isGuest": { "type": "boolean", "description": "Not seated in the target's workspace: reaches this one thing, at Can comment at most." } }, "required": [ "id", "username", "name", "email", "image", "accessId", "role", "isGuest" ], "additionalProperties": false } }, "invites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." }, "invitePath": { "type": "string", "description": "Where to send them. Carries the token, so treat it as one." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "email", "role", "invitePath", "createdAt" ], "additionalProperties": false }, "description": "Pending, listed to those who may manage; never with a link." }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "access": { "type": "string", "enum": [ "none", "view", "edit" ], "description": "What everyone in the target's workspace may do with it: nothing, read, or edit." }, "plan": { "type": "string", "enum": [ "free", "pro", "team" ], "description": "The workspace owner's plan; Pro never sees the word workspace." } }, "required": [ "id", "name", "access", "plan" ], "additionalProperties": false }, "link": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "targetKind": { "type": "string", "enum": [ "task", "project", "area" ], "description": "What the link points at." }, "targetId": { "type": "string" }, "label": { "type": "string", "description": "The name of what is shared, as it stands today." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "targetKind", "targetId", "label", "email", "createdAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "The public link, when one is on; never its address." }, "taskCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "role", "canManage", "owner", "people", "invites", "workspace", "link", "taskCount" ], "additionalProperties": false } }, "required": [ "access" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/access/shared": { "get": { "operationId": "listSharedTargets", "summary": "What is shared with you", "description": "Every project or area you reach and do not own: through a grant, or through the workspace-wide row in a workspace you sit in. Each with your level, whose it is, and where it lives — the \"Shared with you\" section of the sidebar.", "tags": [ "Access" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "targetId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Yours on it." }, "sharer": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false, "description": "Whose it is." }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "Where it lives." }, "targetKind": { "type": "string", "const": "project" }, "project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "done", "archived" ] }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "type": "string" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this project.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "name", "areaId", "status", "deadline", "notes", "order" ], "additionalProperties": false } }, "required": [ "targetId", "name", "role", "sharer", "workspace", "targetKind", "project" ], "additionalProperties": false }, { "type": "object", "properties": { "targetId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Yours on it." }, "sharer": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false, "description": "Whose it is." }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "Where it lives." }, "targetKind": { "type": "string", "const": "area" }, "area": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hue": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 360, "description": "Anodized metal hue angle from 0 to 360 degrees." }, { "type": "null" } ] }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phosphor icon name." }, "notes": { "type": "string" }, "archived": { "type": "boolean" }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "accessRole": { "description": "Your effective role on this area.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "name", "hue", "icon", "notes", "archived", "order" ], "additionalProperties": false } }, "required": [ "targetId", "name", "role", "sharer", "workspace", "targetKind", "area" ], "additionalProperties": false } ] } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "archived" ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "when": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "today" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "anytime" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "someday" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "date" }, "date": { "type": "string" }, "hasTime": { "type": "boolean" }, "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "date", "hasTime" ], "additionalProperties": false } ], "description": "How the task is scheduled (distinct from its `deadline`)." }, "deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Due date `YYYY-MM-DD`, or `null`." }, "projectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "areaId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headingId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Heading grouping the task, or `null` if it sits above them all." }, "tags": { "type": "array", "items": { "type": "string" } }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "done": { "type": "boolean" } }, "required": [ "id", "label", "done" ], "additionalProperties": false } }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationMin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "task", "event" ] }, "repeat": { "anyOf": [ { "type": "object", "properties": { "every": { "type": "integer", "minimum": 1, "maximum": 365, "description": "The multiplier: 2 × week." }, "unit": { "type": "string", "enum": [ "day", "week", "month", "year" ] }, "mode": { "type": "string", "enum": [ "calendar", "after" ], "description": "`calendar`: the next one starts from the scheduled date. `after`: from ticking." }, "weekdays": { "description": "ISO weekdays (1 = Monday … 7 = Sunday) the weekly rule fires on. Only valid with unit \"week\".", "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } } }, "required": [ "every", "unit", "mode" ], "additionalProperties": false, "description": "Repeat rule. Ticking the task creates the next occurrence." }, { "type": "null" } ] }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." }, "order": { "type": "number", "description": "Manual position. Fractional values are valid; lower sorts first." }, "notePath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of a note in the local markdown vault, relative to its root (`Projects/Launch.md`). When set, the app shows that note **instead of** the `notes` field. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "conversationPath": { "anyOf": [ { "type": "string", "maxLength": 1024, "description": "Path of the Atelier conversation this task is delegated to, relative to the vault root (`Agents/Reel scripter/Conversations/….md`). The agent is derived from the path. Do not invent one: it names a file on the user's machine." }, { "type": "null" } ] }, "assigneeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who it is assigned to: one person who reaches the task, or nobody." }, "assignee": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "username", "name", "email", "image" ], "additionalProperties": false }, { "type": "null" } ], "description": "The same person, as the row draws them." }, "accessRole": { "description": "Your effective role on this task.", "type": "string", "enum": [ "owner", "editor", "commenter", "reader" ] } }, "required": [ "id", "title", "notes", "status", "priority", "when", "deadline", "projectId", "areaId", "headingId", "tags", "checklist", "completedAt", "durationMin", "kind", "repeat", "visibility", "order", "notePath", "conversationPath", "assigneeId", "assignee" ], "additionalProperties": false }, "description": "The open tasks of those targets, in their order, up to one page; the paginated list is `listTasks` with `sharedWithMe`. Here so a page draws in one read." } }, "required": [ "targets", "tasks" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/workspaces/{workspaceId}/guests": { "get": { "operationId": "listWorkspaceGuests", "summary": "The guests of a workspace", "description": "Everyone from outside the workspace who reaches something in it, with what they reach. Owner and admins only: a guest takes no seat and is not on the members page.", "tags": [ "Access" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "guests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reaches": { "type": "array", "items": { "type": "object", "properties": { "targetKind": { "type": "string", "enum": [ "project", "area" ], "description": "What is shared: a project, or an area and every project in it." }, "targetId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." } }, "required": [ "targetKind", "targetId", "name", "role" ], "additionalProperties": false } } }, "required": [ "id", "username", "name", "email", "image", "reaches" ], "additionalProperties": false } } }, "required": [ "guests" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/activity": { "get": { "operationId": "listActivity", "summary": "The feed", "description": "Finished sessions shared by the people you follow, and your own, newest first. A public one names the task; an anonymized one names only where it lived; a private one is not here.", "tags": [ "Activity" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "startedAt": { "type": "number", "description": "Epoch milliseconds." }, "endedAt": { "type": "number", "description": "Epoch milliseconds." }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." } }, "required": [ "id", "startedAt", "endedAt", "visibility" ], "additionalProperties": false }, "person": { "type": "object", "properties": { "username": { "type": "string" }, "name": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "username", "name", "image" ], "additionalProperties": false }, "minutes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The task's title; the owner always sees it; a follower only when the session is public." }, "container": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The project or area the task lived in, whatever the visibility." }, "flames": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "flamed": { "type": "boolean", "description": "Whether the caller sent one." }, "isMe": { "type": "boolean" } }, "required": [ "session", "person", "minutes", "title", "container", "flames", "flamed", "isMe" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/sessions/{sessionId}/flames": { "post": { "operationId": "sendFlame", "summary": "Send a flame", "description": "The one reaction. One per person per session; a second is a no-op. Only on a session you can see, and never on your own.", "tags": [ "Activity" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "startedAt": { "type": "number", "description": "Epoch milliseconds." }, "endedAt": { "type": "number", "description": "Epoch milliseconds." }, "visibility": { "type": "string", "enum": [ "public", "anonymized", "private" ], "description": "Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private." } }, "required": [ "id", "startedAt", "endedAt", "visibility" ], "additionalProperties": false }, "person": { "type": "object", "properties": { "username": { "type": "string" }, "name": { "type": "string" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "username", "name", "image" ], "additionalProperties": false }, "minutes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The task's title; the owner always sees it; a follower only when the session is public." }, "container": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The project or area the task lived in, whatever the visibility." }, "flames": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "flamed": { "type": "boolean", "description": "Whether the caller sent one." }, "isMe": { "type": "boolean" } }, "required": [ "session", "person", "minutes", "title", "container", "flames", "flamed", "isMe" ], "additionalProperties": false } }, "required": [ "item" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tokens": { "get": { "operationId": "listApiTokens", "summary": "List your API tokens", "description": "Newest first. The token itself is **not** here and cannot be: only its hash is stored, so a lost token is replaced rather than recovered.", "tags": [ "Tokens" ], "parameters": [ { "name": "includeRevoked", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "lastUsedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` if it has never been presented." }, "revokedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "label", "createdAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false } } }, "required": [ "tokens" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createApiToken", "summary": "Create an API token", "description": "Returns the token in `secret`, **once**. It is not recoverable afterwards, so it has to be stored by the caller at this point or created again. Requires your app session; delegated credentials and the coach are refused.", "tags": [ "Tokens" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 200 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "lastUsedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` if it has never been presented." }, "revokedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "label", "createdAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false }, "secret": { "type": "string", "description": "The bearer token. Shown once and never again." } }, "required": [ "token", "secret" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tokens/{tokenId}/revoke": { "post": { "operationId": "revokeApiToken", "summary": "Revoke an API token", "description": "Takes effect on the next request that presents it. The row is kept rather than deleted, so a revoked token stays visible with the moment it was last used — which is what makes a leak legible after the fact.", "tags": [ "Tokens" ], "parameters": [ { "name": "tokenId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "lastUsedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` if it has never been presented." }, "revokedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "label", "createdAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false } }, "required": [ "token" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/referrals": { "get": { "operationId": "listReferralInvites", "summary": "List your invites", "description": "Every grant you made, newest first, with how many more you may make. The code itself is **not** here and cannot be: only its hash is stored, so a lost code is replaced, not recovered.", "tags": [ "Referrals" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "expiresAt": { "type": "number", "description": "Epoch milliseconds." }, "redeemedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` while the code is unredeemed." }, "status": { "type": "string", "enum": [ "open", "redeemed", "expired" ], "description": "Derived from the two instants and the clock." } }, "required": [ "id", "createdAt", "expiresAt", "redeemedAt", "status" ], "additionalProperties": false } }, "remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Grants you may still make." } }, "required": [ "invites", "remaining" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createReferralInvite", "summary": "Create an invite", "description": "Mints a code and returns it in `code`, **once**. Only a person who has had a free trial may grant one, and only up to the allowance; the code expires on its own.", "tags": [ "Referrals" ], "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invite": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "expiresAt": { "type": "number", "description": "Epoch milliseconds." }, "redeemedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` while the code is unredeemed." }, "status": { "type": "string", "enum": [ "open", "redeemed", "expired" ], "description": "Derived from the two instants and the clock." } }, "required": [ "id", "createdAt", "expiresAt", "redeemedAt", "status" ], "additionalProperties": false }, "code": { "type": "string", "description": "The code to hand over. Shown once and never again." } }, "required": [ "invite", "code" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/referrals/redeem": { "post": { "operationId": "redeemReferralInvite", "summary": "Redeem an invite code", "description": "Records you as the person the code was for. A code redeems once, before it expires, and never by the person who made it.", "tags": [ "Referrals" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "code" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invite": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "expiresAt": { "type": "number", "description": "Epoch milliseconds." }, "redeemedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "`null` while the code is unredeemed." }, "status": { "type": "string", "enum": [ "open", "redeemed", "expired" ], "description": "Derived from the two instants and the clock." } }, "required": [ "id", "createdAt", "expiresAt", "redeemedAt", "status" ], "additionalProperties": false } }, "required": [ "invite" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/files": { "get": { "operationId": "listFiles", "summary": "List an entity's attachments", "description": "The links attached to a task, project or area, newest first.", "tags": [ "Files" ], "parameters": [ { "name": "parentId", "in": "query", "required": true, "description": "Id of the parent task, project or area.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "parentKind", "in": "query", "required": true, "description": "Which kind of entity carries the comments.", "schema": { "type": "string", "enum": [ "task", "project", "area" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "preview": { "anyOf": [ { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "siteName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "title", "description", "image", "siteName" ], "additionalProperties": false }, { "type": "null" } ], "description": "OpenGraph card, filled in out of band. `null` until it is." }, "canRemove": { "type": "boolean" }, "external": { "type": "boolean" } }, "required": [ "id", "name", "url", "mime", "createdAt", "preview", "canRemove", "external" ], "additionalProperties": false } } }, "required": [ "files" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "addFileLink", "summary": "Attach a link", "description": "Attaches an external link to a task, project or area. A minimal preview — the address and the site it points at — is stored immediately; the rest of the card is filled in out of band, so a site that refuses the request costs nothing.", "tags": [ "Files" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "parentId": { "type": "string", "description": "Id of the parent task, project or area.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "parentKind": { "type": "string", "description": "Which kind of entity carries the comments.", "enum": [ "task", "project", "area" ] }, "url": { "type": "string", "description": "An `http` or `https` address.", "maxLength": 2048, "format": "uri" } }, "required": [ "parentId", "parentKind", "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "preview": { "anyOf": [ { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "siteName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "title", "description", "image", "siteName" ], "additionalProperties": false }, { "type": "null" } ], "description": "OpenGraph card, filled in out of band. `null` until it is." }, "canRemove": { "type": "boolean" }, "external": { "type": "boolean" } }, "required": [ "id", "name", "url", "mime", "createdAt", "preview", "canRemove", "external" ], "additionalProperties": false } }, "required": [ "file" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/files/{fileId}": { "delete": { "operationId": "removeFile", "summary": "Remove an attachment", "description": "Detaches a link. Nothing else is touched.", "tags": [ "Files" ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/files/store": { "get": { "operationId": "getFileStoreStatus", "summary": "Whether this server has somewhere to put a file", "description": "`configured` means the deployment has a blob store, so the upload route answers with a token rather than a refusal: a profile picture can be offered only when it is true. `attachments` means files can be attached to a task, project or area (Vercel Blob, an S3-compatible bucket or a local directory); when false, attachments stay links.", "tags": [ "Files" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "attachments": { "type": "boolean" } }, "required": [ "configured", "attachments" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/connections": { "get": { "operationId": "listConnections", "summary": "List the applications you have connected", "description": "Everything holding a live grant, most recently used first.", "tags": [ "Connections" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "clientName": { "type": "string" }, "clientUri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scope": { "type": "string" }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "lastUsedAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "clientName", "clientUri", "scope", "createdAt", "lastUsedAt" ], "additionalProperties": false } } }, "required": [ "connections" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/connections/{connectionId}/revoke": { "post": { "operationId": "revokeConnection", "summary": "Disconnect an application", "description": "Cuts the grant and deletes every token issued under it, so access stops on the next request rather than when the current token happens to expire.", "tags": [ "Connections" ], "parameters": [ { "name": "connectionId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/connections/requests/{requestId}": { "get": { "operationId": "getConsentRequest", "summary": "Describe a pending consent request", "description": "What the consent screen shows, and nothing more: who is asking, where they will be sent back to, and whether you have approved them before. Returns 404 once the request has been answered or has expired — a consent screen for a dead request is a trap.", "tags": [ "Connections" ], "parameters": [ { "name": "requestId", "in": "path", "required": true, "description": "The consent request's opaque id.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "clientName": { "type": "string" }, "redirectHost": { "type": "string" }, "localOnly": { "type": "boolean", "description": "`true` when the callback is on this machine." }, "connectedSince": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "When this application was last approved, or `null` if never." } }, "required": [ "clientName", "redirectHost", "localOnly", "connectedSince" ], "additionalProperties": false } }, "required": [ "request" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "decideConsentRequest", "summary": "Approve or refuse a consent request", "description": "Answers the request and returns where to send the browser next. The client is told either way — a refusal that simply stops leaves it waiting forever. Requires your app session; delegated credentials and the coach are refused.", "tags": [ "Connections" ], "parameters": [ { "name": "requestId", "in": "path", "required": true, "description": "The consent request's opaque id.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "approve": { "type": "boolean", "description": "`false` refuses, and says so to the client." } }, "required": [ "approve" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectTo": { "type": "string", "format": "uri", "description": "Where the browser continues. Already carries `state`." } }, "required": [ "redirectTo" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/invites/accept": { "post": { "operationId": "acceptInvite", "summary": "Accept an invitation", "description": "Accepts a link, but **only** for the account carrying the address it was sent to. An invitation forwarded to someone else grants them nothing.", "tags": [ "Collaborators" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." } }, "required": [ "taskId", "role" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/{taskId}/access": { "get": { "operationId": "getTaskAccess", "summary": "Who can see this task", "description": "The owner, everyone it is shared with, and your own role. Pending invitations are included only for the owner — they carry a link that grants access, so they are not something a reader may enumerate.", "tags": [ "Collaborators" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." }, "canManage": { "type": "boolean" }, "owner": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "membershipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The row to patch or delete. `null` for the owner, who has no membership." }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." } }, "required": [ "id", "username", "name", "email", "image", "membershipId", "role" ], "additionalProperties": false }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "membershipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The row to patch or delete. `null` for the owner, who has no membership." }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." } }, "required": [ "id", "username", "name", "email", "image", "membershipId", "role" ], "additionalProperties": false } }, "invites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." }, "invitePath": { "type": "string", "description": "Where to send them. Carries the token, so treat it as one." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "email", "role", "invitePath", "createdAt" ], "additionalProperties": false } } }, "required": [ "role", "canManage", "owner", "members", "invites" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "shareTask", "summary": "Share a task with someone", "description": "`target` is a username or an email address. A matching account is added immediately; an email that matches nobody produces an invitation link to send them. Sharing again with the same person changes their role rather than adding them twice.", "tags": [ "Collaborators" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "reader", "commenter", "editor" ] }, "target": { "type": "string", "minLength": 1, "maxLength": 254 } }, "required": [ "role", "target" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "member" }, "member": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "membershipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The row to patch or delete. `null` for the owner, who has no membership." }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." } }, "required": [ "id", "username", "name", "email", "image", "membershipId", "role" ], "additionalProperties": false } }, "required": [ "kind", "member" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "invite" }, "invite": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." }, "invitePath": { "type": "string", "description": "Where to send them. Carries the token, so treat it as one." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "email", "role", "invitePath", "createdAt" ], "additionalProperties": false } }, "required": [ "kind", "invite" ], "additionalProperties": false } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/{taskId}/access/{membershipId}": { "patch": { "operationId": "setCollaboratorRole", "summary": "Change a collaborator's role", "description": "Owner only. The owner's own role cannot be changed; it is not a membership.", "tags": [ "Collaborators" ], "parameters": [ { "name": "membershipId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "reader", "commenter", "editor" ] } }, "required": [ "role" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "membershipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The row to patch or delete. `null` for the owner, who has no membership." }, "role": { "type": "string", "enum": [ "reader", "commenter", "editor", "owner" ], "description": "Ascending. `owner` is not grantable: it is what owning the task means." } }, "required": [ "id", "username", "name", "email", "image", "membershipId", "role" ], "additionalProperties": false } }, "required": [ "member" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "removeCollaborator", "summary": "Stop sharing with someone", "description": "Owner only. Access stops on their next request.", "tags": [ "Collaborators" ], "parameters": [ { "name": "membershipId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/tasks/{taskId}/invites/{inviteId}/revoke": { "post": { "operationId": "revokeInvite", "summary": "Cancel a pending invitation", "description": "Owner only. The link stops working immediately.", "tags": [ "Collaborators" ], "parameters": [ { "name": "inviteId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "taskId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/link-previews": { "get": { "operationId": "getLinkPreview", "summary": "Resolve safe link metadata", "description": "Returns bounded metadata for one public HTTP(S) page. Private-network destinations and redirects are blocked; unavailable pages remain a typed fallback.", "tags": [ "Links" ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 2048, "format": "uri" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "oneOf": [ { "type": "object", "properties": { "outcome": { "type": "string", "const": "resolved" }, "preview": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "siteName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "favicon": { "anyOf": [ { "type": "string", "maxLength": 100000, "pattern": "^data:image\\/.*" }, { "type": "null" } ] } }, "required": [ "url", "title", "description", "image", "siteName", "favicon" ], "additionalProperties": false } }, "required": [ "outcome", "preview" ], "additionalProperties": false }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "blocked" } }, "required": [ "outcome" ], "additionalProperties": false }, { "type": "object", "properties": { "outcome": { "type": "string", "const": "unavailable" } }, "required": [ "outcome" ], "additionalProperties": false } ] } }, "required": [ "result" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/share-links": { "get": { "operationId": "listShareLinks", "summary": "List your public links", "description": "Everything you have published a link to, newest first, with the name of what it points at. The link itself is **not** here and cannot be: only its hash is stored.", "tags": [ "Links" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "targetKind": { "type": "string", "enum": [ "task", "project", "area" ], "description": "What the link points at." }, "targetId": { "type": "string" }, "label": { "type": "string", "description": "The name of what is shared, as it stands today." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "targetKind", "targetId", "label", "email", "createdAt" ], "additionalProperties": false } } }, "required": [ "links" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createShareLink", "summary": "Publish a public link", "description": "Returns the link in `url`, **once**. Publishing the same target again returns a fresh link and retires the previous one — a link that has been sent somewhere it should not have been is replaced, not reused.", "tags": [ "Links" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "Recorded when the link was sent to one person. Not enforced on opening.", "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "targetId": { "type": "string", "description": "Identifier of a row.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "targetKind": { "type": "string", "description": "What the link points at.", "enum": [ "task", "project", "area" ] } }, "required": [ "targetId", "targetKind" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "type": "object", "properties": { "id": { "type": "string" }, "targetKind": { "type": "string", "enum": [ "task", "project", "area" ], "description": "What the link points at." }, "targetId": { "type": "string" }, "label": { "type": "string", "description": "The name of what is shared, as it stands today." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "targetKind", "targetId", "label", "email", "createdAt" ], "additionalProperties": false }, "url": { "type": "string", "description": "The public address. Shown once and never again." } }, "required": [ "link", "url" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/share-links/{linkId}/revoke": { "post": { "operationId": "revokeShareLink", "summary": "Take a public link down", "description": "The address stops resolving immediately. Anyone holding it sees nothing.", "tags": [ "Links" ], "parameters": [ { "name": "linkId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/packages": { "get": { "operationId": "listPackages", "summary": "List what you have published", "description": "Your packages, newest first, each with the version currently published.", "tags": [ "Packages" ], "parameters": [ { "name": "includeUnpublished", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "packages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "note", "folder" ], "description": "An agent and its notes, a note on its own, or a folder of them." }, "slug": { "type": "string" }, "name": { "type": "string" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "latestVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fileCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Files in the version currently published." }, "published": { "type": "boolean", "description": "`false` once taken down. Existing installs are unaffected." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "updatedAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "kind", "slug", "name", "emoji", "summary", "latestVersion", "fileCount", "published", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "packages" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "publishPackage", "summary": "Publish a package, or a new version of one", "description": "Publishing to a slug you already used adds a version to that package rather than creating a second one, and un-retires it if it had been taken down. The public address is returned **once**, on the first publish: only a hash of its token is stored.", "tags": [ "Packages" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "changelog": { "type": "string", "default": "", "maxLength": 10000 }, "emoji": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "description": "Relative, `/`-separated, no `..`." }, "content": { "type": "string" } }, "required": [ "path", "content" ], "additionalProperties": false }, "minItems": 1, "maxItems": 64 }, "kind": { "type": "string", "description": "An agent and its notes, a note on its own, or a folder of them.", "enum": [ "agent", "note", "folder" ] }, "licence": { "description": "Chosen explicitly. Omitted means unlicensed: nothing is licensed on the author's behalf.", "anyOf": [ { "type": "string", "enum": [ "mit", "cc-by-4.0" ] }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "permissions": { "type": "array", "description": "Operation ids this version asks to be allowed to call, by name (`listTasks`). Enforced by the server at every execution boundary, never by the package. An id this API does not have is a 400.", "default": [], "items": { "type": "string" }, "maxItems": 32 }, "slug": { "type": "string", "minLength": 1, "maxLength": 80 }, "summary": { "type": "string", "default": "", "maxLength": 10000 } }, "required": [ "files", "kind", "name", "slug" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "note", "folder" ], "description": "An agent and its notes, a note on its own, or a folder of them." }, "slug": { "type": "string" }, "name": { "type": "string" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "latestVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fileCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Files in the version currently published." }, "published": { "type": "boolean", "description": "`false` once taken down. Existing installs are unaffected." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "updatedAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "kind", "slug", "name", "emoji", "summary", "latestVersion", "fileCount", "published", "createdAt", "updatedAt" ], "additionalProperties": false }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The public address, on the FIRST publish only. `null` afterwards." } }, "required": [ "package", "url" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/packages/{packageId}/unpublish": { "post": { "operationId": "unpublishPackage", "summary": "Take a package down", "description": "The public address stops resolving and nobody new can install it. **Existing installs are untouched**: what someone already has on their disk is theirs, and taking it back is not something publishing gave you the right to do.", "tags": [ "Packages" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "note", "folder" ], "description": "An agent and its notes, a note on its own, or a folder of them." }, "slug": { "type": "string" }, "name": { "type": "string" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "latestVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fileCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Files in the version currently published." }, "published": { "type": "boolean", "description": "`false` once taken down. Existing installs are unaffected." }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "updatedAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "kind", "slug", "name", "emoji", "summary", "latestVersion", "fileCount", "published", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "package" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/installs": { "get": { "operationId": "listInstalls", "summary": "What you have installed", "description": "Each install with the version you are on, and whether a newer one exists. A package its author took down still appears: what you installed is yours. File contents are not included — read one install's files with `getInstallFiles`.", "tags": [ "Installs" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "installs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "packageId": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "note", "folder" ], "description": "An agent and its notes, a note on its own, or a folder of them." }, "slug": { "type": "string" }, "name": { "type": "string" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "latestVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "`null` once the author has taken it down." }, "updateAvailable": { "type": "boolean" }, "publisher": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "official" ] }, "handle": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "kind", "handle", "displayName" ], "additionalProperties": false }, "installedAt": { "type": "number", "description": "Epoch milliseconds." }, "revoked": { "type": "boolean", "description": "The author took the package down. What is installed still works." } }, "required": [ "id", "packageId", "kind", "slug", "name", "emoji", "summary", "version", "latestVersion", "updateAvailable", "publisher", "installedAt", "revoked" ], "additionalProperties": false } } }, "required": [ "installs" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "installPackage", "summary": "Install a package from its address", "description": "Returns the files for the client to write. Installing something you already have is not an error: it returns what you are on rather than moving you, so re-opening a link never changes what is on your disk behind your back.", "tags": [ "Installs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "acceptedDigest": { "description": "The content digest of the preview whose permissions were accepted — **required**, because an install with nothing to compare against is an install nobody consented to. Send `null` only when the preview showed none, which is what a version frozen before digests existed reports. Anything other than an exact match with the version on offer is refused with 409 rather than quietly installing something else.", "anyOf": [ { "type": "string", "minLength": 64, "maxLength": 64 }, { "type": "null" } ] }, "packageId": { "type": "string", "description": "From a package already granted to you.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "token": { "type": "string", "description": "From a share link.", "minLength": 1, "maxLength": 128 } }, "required": [ "acceptedDigest" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "install": { "type": "object", "properties": { "id": { "type": "string" }, "packageId": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "note", "folder" ], "description": "An agent and its notes, a note on its own, or a folder of them." }, "slug": { "type": "string" }, "name": { "type": "string" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "latestVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "`null` once the author has taken it down." }, "updateAvailable": { "type": "boolean" }, "publisher": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "official" ] }, "handle": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "kind", "handle", "displayName" ], "additionalProperties": false }, "installedAt": { "type": "number", "description": "Epoch milliseconds." }, "revoked": { "type": "boolean", "description": "The author took the package down. What is installed still works." }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ], "additionalProperties": false } } }, "required": [ "id", "packageId", "kind", "slug", "name", "emoji", "summary", "version", "latestVersion", "updateAvailable", "publisher", "installedAt", "revoked", "files" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ], "additionalProperties": false } }, "alreadyInstalled": { "type": "boolean" } }, "required": [ "install", "files", "alreadyInstalled" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/installs/{installId}": { "delete": { "operationId": "uninstallPackage", "summary": "Uninstall", "description": "Forgets the install. The client removes the files it wrote.", "tags": [ "Installs" ], "parameters": [ { "name": "installId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "packageId": { "type": "string" } }, "required": [ "packageId" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/installs/{installId}/detach": { "post": { "operationId": "detachInstall", "summary": "Keep it, without the link", "description": "The package becomes an ordinary folder in your own vault: the files are returned for the client to keep, and the install is forgotten. No further updates, and nothing the author does afterwards reaches it.", "tags": [ "Installs" ], "parameters": [ { "name": "installId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ], "additionalProperties": false } } }, "required": [ "name", "slug", "files" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/installs/{installId}/files": { "get": { "operationId": "getInstallFiles", "summary": "Read the files of an install", "description": "The contents of the exact version installed, file by file. Separate from the install list so that listing what someone has does not ship every file body they hold. Answers 404 for an install belonging to another account. Writes nothing and installs nothing.", "tags": [ "Installs" ], "parameters": [ { "name": "installId", "in": "path", "required": true, "description": "The install to read, from `listInstalls`.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ], "additionalProperties": false } } }, "required": [ "files" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/installs/{installId}/update": { "get": { "operationId": "previewInstallUpdate", "summary": "What an update would bring", "description": "The newer version's files, changelog and permission differences, without applying anything. `permissions.added` is what the newer version asks for that its installer has never accepted: applying an update that adds any is refused until they are, because a manifest is not consent and an update is not a moment to grant something quietly.", "tags": [ "Installs" ], "parameters": [ { "name": "installId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "`null` when there is nothing newer." }, "changelog": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ], "additionalProperties": false } }, "permissions": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" }, "description": "Asked for by the newer version and never accepted." }, "removed": { "type": "array", "items": { "type": "string" }, "description": "Accepted before, and no longer asked for." }, "unchanged": { "type": "array", "items": { "type": "string" }, "description": "Asked for and already accepted." } }, "required": [ "added", "removed", "unchanged" ], "additionalProperties": false }, "contentDigest": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "version", "changelog", "files", "permissions", "contentDigest", "publishedAt" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "applyInstallUpdate", "summary": "Move an install to the latest version", "description": "Returns the files to write. A package that has been taken down cannot be updated, and neither can one whose newer version asks for more than its installer accepted — send `acceptedDigest` to accept the widened manifest, exactly as installing does.", "tags": [ "Installs" ], "parameters": [ { "name": "installId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "acceptedDigest": { "description": "The digest of the update preview whose permissions were accepted. Required only when the newer version asks for something the installer has never accepted; anything other than an exact match with the version on offer is refused with 409.", "anyOf": [ { "type": "string", "minLength": 64, "maxLength": 64 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "install": { "type": "object", "properties": { "id": { "type": "string" }, "packageId": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "note", "folder" ], "description": "An agent and its notes, a note on its own, or a folder of them." }, "slug": { "type": "string" }, "name": { "type": "string" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "latestVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "`null` once the author has taken it down." }, "updateAvailable": { "type": "boolean" }, "publisher": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "official" ] }, "handle": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "kind", "handle", "displayName" ], "additionalProperties": false }, "installedAt": { "type": "number", "description": "Epoch milliseconds." }, "revoked": { "type": "boolean", "description": "The author took the package down. What is installed still works." }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ], "additionalProperties": false } } }, "required": [ "id", "packageId", "kind", "slug", "name", "emoji", "summary", "version", "latestVersion", "updateAvailable", "publisher", "installedAt", "revoked", "files" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ], "additionalProperties": false } } }, "required": [ "install", "files" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/packages/{packageId}/grants": { "get": { "operationId": "listPackageGrants", "summary": "Who you sent a package to", "description": "Everyone named on this package, and whether they took it up.", "tags": [ "Installs" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "recipient": { "type": "string", "description": "The username or address it was sent to." }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked" ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "acceptedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "recipient", "status", "createdAt", "acceptedAt" ], "additionalProperties": false } } }, "required": [ "grants" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "grantPackageAccess", "summary": "Send a package to someone", "description": "`target` is a username or an email address. This records the send and puts the package in their list; it does **not** gate installation, which the package's address already allows. The address is not returned here — it was shown once, when the package was first published.", "tags": [ "Installs" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "minLength": 1, "maxLength": 254 } }, "required": [ "target" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant": { "type": "object", "properties": { "id": { "type": "string" }, "recipient": { "type": "string", "description": "The username or address it was sent to." }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked" ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." }, "acceptedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "recipient", "status", "createdAt", "acceptedAt" ], "additionalProperties": false } }, "required": [ "grant" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/packages/{packageId}/grants/{grantId}/revoke": { "post": { "operationId": "revokePackageGrant", "summary": "Take a send back", "description": "Removes the package from their list. **Anything already installed stays installed** — this un-sends a recommendation, it does not reach onto someone's disk.", "tags": [ "Installs" ], "parameters": [ { "name": "grantId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "packageId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/packages/preview": { "post": { "operationId": "previewPackage", "summary": "Read a package before installing it", "description": "Everything the address describes: the version on offer, its changelog, and **every file in full**. Writes nothing and installs nothing — the page that offers an agent has to be able to show what that agent says, because an installed agent runs on the caller's workspace with the caller's key.\n\nAnswers 404 for a token that is unknown or has been taken down. The author of a package may read their own, unlike installing it.\n\nA POST that reads: the token is the whole capability, and a query string is written to every access log and sent onward in a `Referer`.", "tags": [ "Installs" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The token from a package's public address.", "minLength": 1, "maxLength": 128 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "object", "properties": { "packageId": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "note", "folder" ], "description": "An agent and its notes, a note on its own, or a folder of them." }, "slug": { "type": "string" }, "name": { "type": "string" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The version on offer today, not any version already installed." }, "changelog": { "type": "string" }, "publishedAt": { "type": "number", "description": "Epoch milliseconds." }, "publisher": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "official" ] }, "handle": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "kind", "handle", "displayName" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ], "additionalProperties": false } }, "contentDigest": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewStatus": { "type": "string", "enum": [ "approved", "unreviewed" ] }, "approvedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] } }, "required": [ "packageId", "kind", "slug", "name", "emoji", "summary", "version", "changelog", "publishedAt", "publisher", "files", "contentDigest", "reviewStatus", "approvedAt" ], "additionalProperties": false } }, "required": [ "package" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/shared-with-me": { "get": { "operationId": "listSharedWithMe", "summary": "Packages sent to you", "description": "What someone named you on, installed or not. Matched by account and by the address on your account, so a package sent before you signed up appears once you do.", "tags": [ "Installs" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "packages": { "type": "array", "items": { "type": "object", "properties": { "packageId": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "note", "folder" ], "description": "An agent and its notes, a note on its own, or a folder of them." }, "name": { "type": "string" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "publisher": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "official" ] }, "handle": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "kind", "handle", "displayName" ], "additionalProperties": false }, "installed": { "type": "boolean" }, "contentDigest": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "packageId", "kind", "name", "emoji", "summary", "publisher", "installed", "contentDigest" ], "additionalProperties": false } } }, "required": [ "packages" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/billing": { "get": { "operationId": "getBillingStatus", "summary": "Read the current billing status", "description": "Returns subscription state synchronized from signed Creem webhooks. Provider customer, product, order and subscription identifiers are never returned.", "tags": [ "Billing" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "canManage": { "type": "boolean" }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "pro-monthly", "pro-annual", "pro-lifetime", "team-monthly", "team-annual", "team-lifetime" ] }, "status": { "type": "string", "enum": [ "pending", "active", "canceled", "expired", "past_due", "unpaid", "paused", "trialing", "scheduled_cancel", "unknown" ] }, "periodEnd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "units": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "product", "status", "periodEnd", "units" ], "additionalProperties": false } }, "purchases": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "pro-monthly", "pro-annual", "pro-lifetime", "team-monthly", "team-annual", "team-lifetime" ] }, "status": { "type": "string", "enum": [ "paid", "partially_refunded", "refunded", "disputed" ] }, "units": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "product", "status", "units" ], "additionalProperties": false } } }, "required": [ "configured", "canManage", "subscriptions", "purchases" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/billing/checkout": { "post": { "operationId": "createBillingCheckout", "summary": "Create a hosted subscription checkout", "description": "Creates a checkout for one configured recurring or lifetime product. The request id is an idempotency key; provider ids, customer and success URL are server-owned.", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "pro-monthly", "pro-annual", "pro-lifetime", "team-monthly", "team-annual", "team-lifetime" ] }, "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "units": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "product", "requestId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/billing/entitlements": { "get": { "operationId": "getEntitlements", "summary": "What your plan grants", "description": "Your plan, where it comes from, its features as of now, and the seats you hold when it is a team plan. A lifetime purchase keeps receiving what its plan gains and never becomes a higher plan on its own; a seat grants the holder's plan for as long as they hold it.", "tags": [ "Billing" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entitlement": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "free", "pro", "team" ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "subscription", "lifetime", "seat" ] }, { "type": "null" } ], "description": "Where the plan comes from; `null` on free." }, "features": { "type": "array", "items": { "type": "string", "enum": [ "username-reservation", "team-seats" ] }, "description": "The plan's features as of now, never frozen." }, "seats": { "anyOf": [ { "type": "object", "properties": { "included": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "members": { "type": "array", "items": { "type": "string" }, "description": "The seated people, by handle." } }, "required": [ "included", "used", "members" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` unless the account holds a team plan." } }, "required": [ "plan", "source", "features", "seats" ], "additionalProperties": false } }, "required": [ "entitlement" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/billing/portal": { "post": { "operationId": "createBillingPortal", "summary": "Create a hosted customer portal", "description": "Creates a portal only for the Creem customer id stored on the authenticated account. The caller cannot provide or override that id.", "tags": [ "Billing" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/billing/seats": { "post": { "operationId": "grantTeamSeat", "summary": "Seat someone on your team plan", "description": "Only while you hold a team plan with a seat to spare; never yourself. Seating someone twice is a no-op.", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" } }, "required": [ "username" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entitlement": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "free", "pro", "team" ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "subscription", "lifetime", "seat" ] }, { "type": "null" } ], "description": "Where the plan comes from; `null` on free." }, "features": { "type": "array", "items": { "type": "string", "enum": [ "username-reservation", "team-seats" ] }, "description": "The plan's features as of now, never frozen." }, "seats": { "anyOf": [ { "type": "object", "properties": { "included": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "members": { "type": "array", "items": { "type": "string" }, "description": "The seated people, by handle." } }, "required": [ "included", "used", "members" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` unless the account holds a team plan." } }, "required": [ "plan", "source", "features", "seats" ], "additionalProperties": false } }, "required": [ "entitlement" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/billing/seats/{username}": { "delete": { "operationId": "revokeTeamSeat", "summary": "Take a seat back", "description": "The person keeps whatever they bought themselves. Not found when they had no seat.", "tags": [ "Billing" ], "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entitlement": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "free", "pro", "team" ] }, "source": { "anyOf": [ { "type": "string", "enum": [ "subscription", "lifetime", "seat" ] }, { "type": "null" } ], "description": "Where the plan comes from; `null` on free." }, "features": { "type": "array", "items": { "type": "string", "enum": [ "username-reservation", "team-seats" ] }, "description": "The plan's features as of now, never frozen." }, "seats": { "anyOf": [ { "type": "object", "properties": { "included": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "members": { "type": "array", "items": { "type": "string" }, "description": "The seated people, by handle." } }, "required": [ "included", "used", "members" ], "additionalProperties": false }, { "type": "null" } ], "description": "`null` unless the account holds a team plan." } }, "required": [ "plan", "source", "features", "seats" ], "additionalProperties": false } }, "required": [ "entitlement" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/billing/subscription/product": { "post": { "operationId": "changeBillingSubscription", "summary": "Change the current recurring billing product", "description": "Changes the authenticated account's single current subscription through Creem's official upgrade endpoint. Upgrades and downgrades take effect immediately with proration-charge-immediately; lifetime products use checkout instead.", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "pro-monthly", "pro-annual", "team-monthly", "team-annual" ] } }, "required": [ "product" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true } }, "required": [ "accepted" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/billing/subscription/units": { "post": { "operationId": "updateBillingSubscriptionUnits", "summary": "Change the current Team subscription seat count", "description": "Changes the current Team subscription's units through Creem's official subscription item endpoint with immediate proration. Product and subscription ids remain server-owned.", "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "units": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "units" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true } }, "required": [ "accepted" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/calendar": { "get": { "operationId": "getCalendarStatus", "summary": "Whether Google Calendar is connected", "description": "`configured` means this deployment has a Google client, so connecting is possible. `connected` means the authorization has been completed. The refresh token is never returned.", "tags": [ "Calendar" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "connected": { "type": "boolean" } }, "required": [ "configured", "connected" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "disconnectCalendar", "summary": "Disconnect Google Calendar", "description": "Forgets the refresh token, so nothing further can be read. Reconnecting is one authorization away — there is nothing to re-enter.", "tags": [ "Calendar" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean", "const": false } }, "required": [ "connected" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/calendar/authorize": { "post": { "operationId": "startCalendarAuth", "summary": "Begin the Google authorization", "description": "Returns the URL to open. It carries a one-time `state` bound to your account, which the callback checks before accepting anything — without it, a callback would accept a code obtained by somebody else.", "tags": [ "Calendar" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/calendar/calendars": { "get": { "operationId": "listCalendars", "summary": "The calendars this account can see", "description": "The account's calendar list, primary first and then by name. Returns an empty list with `connected: false` rather than an error when Google is not connected: not being connected is a state the app draws, not a failure.", "tags": [ "Calendar" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "calendars": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google's own colour, as a hex string." }, "primary": { "type": "boolean" }, "canWrite": { "type": "boolean", "description": "Google says this account may write to the calendar." } }, "required": [ "id", "name", "color", "primary", "canWrite" ], "additionalProperties": false } } }, "required": [ "connected", "calendars" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/calendar/calendars/{calendarId}/events": { "post": { "operationId": "createCalendarEvent", "summary": "Create an event", "description": "Creates an event in the chosen calendar.\n\n`allDay` sends dates rather than instants, and the end is **exclusive** — a single all-day event ends the following day, which is how Google models it.\n\n`meet` asks Google to mint a real Meet link; the response carries it.\n\nGuests are emailed only when there are guests: notifying nobody still costs a round trip.", "tags": [ "Calendar" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Google's calendar id. `primary` is the account's own.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allDay": { "type": "boolean", "default": false }, "attendees": { "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "maxItems": 100 }, "description": { "type": "string" }, "end": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "location": { "type": "string" }, "meet": { "type": "boolean", "description": "Ask Google for a Meet link.", "default": false }, "start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 500 }, "timeZone": { "type": "string", "description": "IANA zone, e.g. `Europe/Paris`.", "minLength": 1 } }, "required": [ "end", "start", "summary", "timeZone" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "htmlLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "meetLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "eventId", "htmlLink", "meetLink" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/calendar/calendars/{calendarId}/events/{eventId}": { "get": { "operationId": "getCalendarEvent", "summary": "Everything about one event", "description": "Guests, video link, location and description — what the list deliberately omits because it would be fetched for every event to show a few.\n\n`meetLink` prefers Google's own conferencing data and falls back to a link found in the location or description, which is where a Zoom or Teams invitation usually is.\n\n`canRsvp` and `canEdit` say what this account may do, so the app does not offer a button Google will refuse.", "tags": [ "Calendar" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Google's calendar id. `primary` is the account's own.", "schema": { "type": "string", "minLength": 1 } }, { "name": "eventId", "in": "path", "required": true, "description": "Google's event id.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "htmlLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The event in Google Calendar." }, "meetLink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Video call, from Google's data or from the text." }, "recurring": { "type": "boolean" }, "start": { "type": "string" }, "end": { "type": "string" }, "organizer": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "self": { "type": "boolean" } }, "required": [ "name", "self" ], "additionalProperties": false }, { "type": "null" } ] }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "description": "Google's own value; `needsAction` when they have not answered." }, "self": { "type": "boolean" }, "organizer": { "type": "boolean" } }, "required": [ "email", "name", "status", "self", "organizer" ], "additionalProperties": false } }, "selfStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canRsvp": { "type": "boolean", "description": "You are a guest and not the organiser." }, "canEdit": { "type": "boolean", "description": "You organise it, so Google will accept a change." } }, "required": [ "title", "description", "location", "htmlLink", "meetLink", "recurring", "start", "end", "organizer", "attendees", "selfStatus", "canRsvp", "canEdit" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "event" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "renameCalendarEvent", "summary": "Rename an event", "description": "Changes the title. Guests are notified, because the title is what they see.", "tags": [ "Calendar" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Google's calendar id. `primary` is the account's own.", "schema": { "type": "string", "minLength": 1 } }, { "name": "eventId", "in": "path", "required": true, "description": "Google's event id.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "summary" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" } }, "required": [ "eventId" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteCalendarEvent", "summary": "Delete an event", "description": "Removes the event from Google. **This is not our archive**: there is no undo, and the guests lose it too.\n\nAn event already gone answers as a success, because the caller's intent is satisfied.", "tags": [ "Calendar" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Google's calendar id. `primary` is the account's own.", "schema": { "type": "string", "minLength": 1 } }, { "name": "eventId", "in": "path", "required": true, "description": "Google's event id.", "schema": { "type": "string", "minLength": 1 } }, { "name": "notify", "in": "query", "required": false, "description": "Email the guests.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" } }, "required": [ "eventId" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/calendar/calendars/{calendarId}/events/{eventId}/rsvp": { "post": { "operationId": "rsvpToCalendarEvent", "summary": "Answer an invitation", "description": "Sets **your own** attendance and tells the organiser.\n\nThe event is read back first so only your own line changes: Google's attendee list is patched whole, and sending a shortened one would drop every other guest.", "tags": [ "Calendar" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Google's calendar id. `primary` is the account's own.", "schema": { "type": "string", "minLength": 1 } }, { "name": "eventId", "in": "path", "required": true, "description": "Google's event id.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "string", "description": "An answer to an invitation.", "enum": [ "accepted", "declined", "tentative" ] } }, "required": [ "response" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" }, "response": { "type": "string", "enum": [ "accepted", "declined", "tentative" ], "description": "An answer to an invitation." } }, "required": [ "eventId", "response" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/calendar/calendars/{calendarId}/events/{eventId}/schedule": { "patch": { "operationId": "moveCalendarEvent", "summary": "Reschedule an event", "description": "Moves an event to new times — what dragging it in the calendar does. Guests are notified.", "tags": [ "Calendar" ], "parameters": [ { "name": "calendarId", "in": "path", "required": true, "description": "Google's calendar id. `primary` is the account's own.", "schema": { "type": "string", "minLength": 1 } }, { "name": "eventId", "in": "path", "required": true, "description": "Google's event id.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "end": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "timeZone": { "type": "string", "description": "IANA zone, e.g. `Europe/Paris`.", "minLength": 1 } }, "required": [ "end", "start", "timeZone" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string" } }, "required": [ "eventId" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/calendar/events": { "get": { "operationId": "listCalendarEvents", "summary": "Events in a window", "description": "Events from the chosen calendars between two instants, recurrences already expanded into their occurrences. Cancelled events are left out.\n\nWithout `calendarIds`, only the primary calendar is read. At most 25 calendars per call.\n\nA calendar that refuses the read is skipped rather than failing the whole window: one calendar the account lost access to must not blank the day.", "tags": [ "Calendar" ], "parameters": [ { "name": "calendarIds", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "description": "Google's calendar id. `primary` is the account's own." }, "maxItems": 25 } }, { "name": "timeMax", "in": "query", "required": true, "description": "End of the window, exclusive.", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "timeMin", "in": "query", "required": true, "description": "Start of the window, inclusive.", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "`calendarId:eventId`, unique across the window." }, "eventId": { "type": "string" }, "calendarId": { "type": "string" }, "title": { "type": "string" }, "start": { "type": "string", "description": "RFC 3339 instant, or a date when `allDay`." }, "end": { "type": "string", "description": "Exclusive. A date when `allDay`." }, "allDay": { "type": "boolean" }, "canEdit": { "type": "boolean", "description": "Provider-derived permission to move this occurrence." } }, "required": [ "id", "eventId", "calendarId", "title", "start", "end", "allDay", "canEdit" ], "additionalProperties": false } } }, "required": [ "connected", "events" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach": { "get": { "operationId": "getCoachStatus", "summary": "Whether the coach has a key", "description": "Reports only that a key exists — never the key, which is not readable once stored.", "tags": [ "Coach" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasKey": { "type": "boolean" }, "unread": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Messages from the coach you have not seen." }, "intensity": { "type": "string", "enum": [ "gentle", "steady", "driven", "relentless" ], "description": "How hard the coach pushes, from gentle to relentless." } }, "required": [ "hasKey", "unread", "intensity" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/intensity": { "put": { "operationId": "setCoachIntensity", "summary": "Choose how hard the coach pushes", "description": "Sets the coach's intensity for your account — one of four named steps, from gentle to relentless. It changes the voice of every reply, nudge and pep from the next one on; nothing already said is rewritten. Use it when the coach is too soft or too harsh.", "tags": [ "Coach" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "intensity": { "type": "string", "description": "The step to use from now on.", "enum": [ "gentle", "steady", "driven", "relentless" ] } }, "required": [ "intensity" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "intensity": { "type": "string", "enum": [ "gentle", "steady", "driven", "relentless" ] } }, "required": [ "intensity" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/key": { "put": { "operationId": "setCoachKey", "summary": "Store your Anthropic key", "description": "Encrypted at rest and never returned. Fails with a 409 when the server has no encryption key configured — storing it in the clear instead is not on offer.", "tags": [ "Coach" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "key" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasKey": { "type": "boolean", "const": true } }, "required": [ "hasKey" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "removeCoachKey", "summary": "Forget the key", "description": "The thread is kept. What was already said stays readable without a key.", "tags": [ "Coach" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hasKey": { "type": "boolean", "const": false } }, "required": [ "hasKey" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/latest": { "get": { "operationId": "getLatestCoachMessage", "summary": "The last thing the coach finished saying", "description": "For the banner at the top of the app. Skips a reply still being written, which would otherwise appear there half-formed.", "tags": [ "Coach" ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Epoch milliseconds.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "coach" ] }, "content": { "type": "string" }, "streamState": { "anyOf": [ { "type": "string", "enum": [ "thinking", "working", "composing" ] }, { "type": "null" } ] }, "isDump": { "type": "boolean" }, "agentKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "role", "content", "streamState", "isDump", "agentKey", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/messages": { "get": { "operationId": "listCoachMessages", "summary": "Read a thread", "description": "The most recent 60 messages, oldest first — a thread is read from the top, but it is the recent end that matters, so the newest are selected and then reversed.", "tags": [ "Coach" ], "parameters": [ { "name": "agentKey", "in": "query", "required": false, "description": "The agent whose thread this is. Absent means the coach's own.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "coach" ] }, "content": { "type": "string" }, "streamState": { "anyOf": [ { "type": "string", "enum": [ "thinking", "working", "composing" ] }, { "type": "null" } ] }, "isDump": { "type": "boolean" }, "agentKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "role", "content", "streamState", "isDump", "agentKey", "createdAt" ], "additionalProperties": false } }, "streaming": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "coach" ] }, "content": { "type": "string" }, "streamState": { "anyOf": [ { "type": "string", "enum": [ "thinking", "working", "composing" ] }, { "type": "null" } ] }, "isDump": { "type": "boolean" }, "agentKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "role", "content", "streamState", "isDump", "agentKey", "createdAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "The reply being written, if one is." } }, "required": [ "messages", "streaming" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "postCoachMessage", "summary": "Say something to the coach", "description": "Records what you said. It does **not** call the model — the reply arrives separately, so a slow or failing model never loses what you typed.", "tags": [ "Coach" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentKey": { "type": "string", "description": "The agent whose thread this is. Absent means the coach's own.", "maxLength": 200 }, "body": { "type": "string", "minLength": 1, "maxLength": 10000 }, "isDump": { "type": "boolean", "description": "A brain-dump: shown collapsed and kept out of the instruction history.", "default": false } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "coach" ] }, "content": { "type": "string" }, "streamState": { "anyOf": [ { "type": "string", "enum": [ "thinking", "working", "composing" ] }, { "type": "null" } ] }, "isDump": { "type": "boolean" }, "agentKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "role", "content", "streamState", "isDump", "agentKey", "createdAt" ], "additionalProperties": false } }, "required": [ "message" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "clearCoachThread", "summary": "Clear a thread", "description": "Deletes every message in this thread. The key and the day's plans are untouched.", "tags": [ "Coach" ], "parameters": [ { "name": "agentKey", "in": "query", "required": false, "description": "The agent whose thread this is. Absent means the coach's own.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cleared": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "cleared" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/nudge": { "post": { "operationId": "nudgeFromCoach", "summary": "One sentence, unprompted", "description": "Asks the coach for a single short sentence about what is happening — the card in the corner of the screen. No tools, no thinking: a sentence does not need to reason, and reasoning would eat the budget it has.\n\nReturns `null` rather than failing when no key is configured, because a nudge is an embellishment and its absence must not look like a broken app.", "tags": [ "Coach" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brief": { "type": "string", "minLength": 1, "maxLength": 2000 }, "kind": { "type": "string", "description": "Why it is speaking.", "minLength": 1, "maxLength": 200 } }, "required": [ "brief", "kind" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sentence": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "sentence" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/pep": { "post": { "operationId": "pepFromCoach", "summary": "One line, for a focus session", "description": "The shortest thing the coach says: one energetic line at the start of a focus session. Same shape as a nudge and deliberately not the same operation — the two are asked for at different moments and read differently.", "tags": [ "Coach" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "context" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sentence": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "sentence" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/plan/{day}": { "get": { "operationId": "getCoachDayPlan", "summary": "The coach's plan for a day", "description": "What it proposed, framed at the top of Today. `null` when it proposed nothing.", "tags": [ "Coach" ], "parameters": [ { "name": "day", "in": "path", "required": true, "description": "Local day key, `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "anyOf": [ { "type": "object", "properties": { "day": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Local day key, `YYYY-MM-DD`." }, "note": { "type": "string" }, "focusTaskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taskIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "day", "note", "focusTaskId", "taskIds", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "plan" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/reply": { "post": { "operationId": "generateCoachReply", "summary": "Ask the coach to answer what was said", "description": "Runs the model over the thread as it stands and writes its reply into it. Post the message first with `POST /coach/messages`: recording and answering are separate so a slow or failing model never loses what was typed.\n\nAnswers while it works. The reply is written progressively into a message that `GET /coach/stream` returns, so a caller can show what is happening instead of a blank wait; that message becomes the finished reply when this returns.\n\nThe coach acts as well as speaks: it may call delegable operations this API exposes, on behalf of the caller and with the caller's permissions. `actions` counts what it did.\n\nFails with a 409 when no Anthropic key is stored — the thread stays readable without one.", "tags": [ "Coach" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "description": "Required when `agentKey` names an agent: its instructions live on the caller's disk, not in this database.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "instructions": { "type": "string", "maxLength": 40000 }, "notes": { "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "body": { "type": "string", "maxLength": 40000 } }, "required": [ "name", "body" ], "additionalProperties": false }, "description": "Reference notes shipped with the agent, injected as its knowledge." } }, "required": [ "name", "instructions", "notes" ], "additionalProperties": false }, "agentKey": { "type": "string", "description": "The agent whose thread this is. Absent means the coach's own.", "maxLength": 200 }, "images": { "type": "array", "items": { "type": "object", "properties": { "mediaType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/gif", "image/webp" ], "description": "What the Messages API accepts. Anything else is refused here." }, "data": { "type": "string", "minLength": 1, "maxLength": 5592410, "description": "Base64, no prefix." } }, "required": [ "mediaType", "data" ], "additionalProperties": false }, "maxItems": 4 }, "mode": { "type": "string", "description": "A brain-dump: organise it into tasks and a plan now, without asking questions.", "const": "dump" }, "uiContext": { "type": "string", "description": "Where the person is — the view, project or task open in front of them.", "maxLength": 2000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "string" }, "actions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Tool calls the coach made. Zero means it only spoke." } }, "required": [ "reply", "actions" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/stream": { "get": { "operationId": "getActiveCoachStream", "summary": "The reply being written, if there is one", "description": "The coach message currently in flight, or `null`. Distinct from the latest message, which is the last **finished** one: a reply half-written is what the app shows a spinner for, and showing it as an answer would show half an answer.", "tags": [ "Coach" ], "parameters": [ { "name": "agentKey", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "coach" ] }, "content": { "type": "string" }, "streamState": { "anyOf": [ { "type": "string", "enum": [ "thinking", "working", "composing" ] }, { "type": "null" } ] }, "isDump": { "type": "boolean" }, "agentKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "id", "role", "content", "streamState", "isDump", "agentKey", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/unread": { "get": { "operationId": "countUnreadCoachMessages", "summary": "How many replies arrived since you last looked", "description": "Counts finished coach messages written after `since`. Replies still being written are not counted: a badge that appears before there is anything to read sends the person to an empty thread.", "tags": [ "Coach" ], "parameters": [ { "name": "since", "in": "query", "required": true, "description": "Epoch milliseconds.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "unread": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "unread" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/coach/usage": { "get": { "operationId": "getCoachUsage", "summary": "What your turns cost", "description": "Every call your account made to the model, newest first, with its token counts and its price in nano-dollars under the catalogue version it was recorded with — so a price change never rewrites a past turn. At most 500 turns; narrow with `since`.", "tags": [ "Coach" ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Epoch milliseconds.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogueVersion": { "type": "string", "description": "The version a turn recorded now would be priced under." }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "operationId": { "type": "string", "description": "The operation that made the call." }, "model": { "type": "string" }, "at": { "type": "number", "description": "Epoch milliseconds." }, "catalogueVersion": { "type": "string", "description": "The price catalogue this call is priced under." }, "tokens": { "type": "object", "properties": { "input": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cacheWrite5m": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cacheWrite1h": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cacheRead": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "output": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "input", "cacheWrite5m", "cacheWrite1h", "cacheRead", "output" ], "additionalProperties": false }, "costNanoUsd": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Nano-dollars. `null` when that catalogue version does not know the model." } }, "required": [ "id", "operationId", "model", "at", "catalogueVersion", "tokens", "costNanoUsd" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "tokens": { "type": "object", "properties": { "input": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cacheWrite5m": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cacheWrite1h": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cacheRead": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "output": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "input", "cacheWrite5m", "cacheWrite1h", "cacheRead", "output" ], "additionalProperties": false }, "costNanoUsd": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "`null` when any listed turn could not be priced." } }, "required": [ "tokens", "costNanoUsd" ], "additionalProperties": false } }, "required": [ "catalogueVersion", "events", "totals" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/marketplace/categories": { "get": { "operationId": "listCategories", "summary": "The catalogue's categories", "description": "The categories an Agent can be listed under, in the order they are shown. A retired category is not returned, while a listing that still names one keeps its historical label. Writes nothing.", "tags": [ "Marketplace" ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "slug", "label", "position" ], "additionalProperties": false } } }, "required": [ "categories" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/marketplace/discover": { "get": { "operationId": "discoverPackages", "summary": "Search the reviewed catalogue", "description": "Approved Agents somebody else published, most curated first. Matches the approved name, summary, publisher handle and declared integrations. Several categories **widen** the result (OR); text and categories **narrow** each other (AND).\n\nNever returns what you own, what you already installed, a version no reviewer approved, or anything suspended. Writes nothing.", "tags": [ "Marketplace" ], "parameters": [ { "name": "categories", "in": "query", "required": false, "description": "Category slugs. Several widen the result rather than narrowing it.", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 9 } }, { "name": "cursor", "in": "query", "required": false, "description": "From a previous page's `nextCursor`. Opaque: do not construct one.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "required": false, "description": "How many to return. The app asks for one page at a time.", "schema": { "type": "integer", "default": 24, "minimum": 1, "maximum": 48 } }, { "name": "query", "in": "query", "required": false, "description": "Free text over name, summary, publisher handle and declared integrations.", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "object", "properties": { "packageId": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "note", "folder" ], "description": "An agent and its notes, a note on its own, or a folder of them." }, "name": { "type": "string" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "publisher": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "official" ] }, "handle": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "kind", "handle", "displayName" ], "additionalProperties": false }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "label": { "type": "string" }, "position": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "slug", "label", "position" ], "additionalProperties": false } }, "licence": { "anyOf": [ { "type": "string", "enum": [ "mit", "cc-by-4.0" ] }, { "type": "null" } ] }, "integrations": { "type": "array", "items": { "type": "string" }, "description": "What the approved version declares it reaches." }, "installers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Accounts that installed it, counted once each. See `since`." }, "since": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ], "description": "When installer counting began, or `null` when nobody has installed it yet. Never a guess: earlier installs are not in the count, and inventing a start date would present an incomplete observation as a lifetime total." }, "approvedAt": { "type": "number", "description": "Epoch milliseconds." } }, "required": [ "packageId", "kind", "name", "emoji", "summary", "version", "publisher", "categories", "licence", "integrations", "installers", "since", "approvedAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Matches before `limit` is applied." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page, or null." } }, "required": [ "listings", "total", "nextCursor" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/marketplace/listings/{packageId}": { "get": { "operationId": "previewListing", "summary": "Read a catalogue entry before installing it", "description": "The **approved** version in full — its files, its licence, the permissions it declares and the publisher behind it — which is not always the newest one frozen. Discover has no share token, so this is the preview every install from the catalogue converges on.\n\nAnswers 404 for a package no reviewer approved and for a suspended one alike: neither is something a browser gets told about. Writes nothing and installs nothing.", "tags": [ "Marketplace" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "From `discoverPackages`.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "object", "properties": { "packageId": { "type": "string" }, "kind": { "type": "string", "enum": [ "agent", "note", "folder" ], "description": "An agent and its notes, a note on its own, or a folder of them." }, "slug": { "type": "string" }, "name": { "type": "string" }, "emoji": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The version on offer today, not any version already installed." }, "changelog": { "type": "string" }, "publishedAt": { "type": "number", "description": "Epoch milliseconds." }, "publisher": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "personal", "official" ] }, "handle": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "kind", "handle", "displayName" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ], "additionalProperties": false } }, "contentDigest": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewStatus": { "type": "string", "enum": [ "approved", "unreviewed" ] }, "approvedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "licence": { "anyOf": [ { "type": "string", "enum": [ "mit", "cc-by-4.0" ] }, { "type": "null" } ] }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "Operation ids the version declares it needs." } }, "required": [ "packageId", "kind", "slug", "name", "emoji", "summary", "version", "changelog", "publishedAt", "publisher", "files", "contentDigest", "reviewStatus", "approvedAt", "licence", "permissions" ], "additionalProperties": false } }, "required": [ "package" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/marketplace/listings/{packageId}/withdraw": { "post": { "operationId": "withdrawListing", "summary": "Take your Agent out of Discover", "description": "Stops offering it in Discover. **Existing installs keep working**: withdrawing un-lists, it does not reach onto anybody's disk or revoke what they already accepted.", "tags": [ "Marketplace" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawn": { "type": "boolean" } }, "required": [ "withdrawn" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/marketplace/packages/{packageId}/report": { "post": { "operationId": "reportPackage", "summary": "Report a package to the safety queue", "description": "Tells staff that something is wrong with a catalogue entry. One report per account per package: reporting twice replaces nothing and adds nothing, so a single account cannot weigh on the queue by clicking.\n\nAnswers the same whether or not anybody else has reported it. A count would tell the reporter whether theirs was the first, which is the author's business and not theirs.", "tags": [ "Marketplace" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "The catalogue entry being reported.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "What the reporter saw, in their own words.", "maxLength": 2000 }, "reason": { "type": "string", "description": "Which of the six kinds of problem this is.", "enum": [ "malicious", "deceptive", "stolen", "unsafe_permissions", "broken", "other" ] } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reported": { "type": "boolean", "const": true, "description": "Always true: a repeat report is not an error." } }, "required": [ "reported" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/marketplace/submissions": { "post": { "operationId": "submitForReview", "summary": "Offer a version for Discover", "description": "Submits one frozen version for review. The version must already be published, carry a licence and declare its permissions — nothing is licensed or declared on your behalf.\n\n**A submission does not disturb what Discover already serves**: the approved version stays live until a reviewer admits the new one. Submitting again replaces a pending submission for the same package.", "tags": [ "Marketplace" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packageId": { "type": "string", "description": "The package to submit.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "description": "Which frozen version to offer. Not necessarily the newest.", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "packageId", "version" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "submission": { "type": "object", "properties": { "packageId": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "state": { "type": "string", "enum": [ "none", "pending", "approved", "rejected" ], "description": "`none` when this package has never been submitted." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why it was rejected. Null unless it was." }, "licence": { "anyOf": [ { "type": "string", "enum": [ "mit", "cc-by-4.0" ] }, { "type": "null" } ] }, "submittedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "listedVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "packageId", "version", "state", "reason", "licence", "submittedAt", "decidedAt", "listedVersion" ], "additionalProperties": false } }, "required": [ "submission" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/marketplace/submissions/{packageId}": { "get": { "operationId": "getSubmissionStatus", "summary": "Where your submission stands", "description": "The decision on your latest submission and, when it was rejected, the reason given. Also says which version Discover is serving, which is not always the one under review.", "tags": [ "Marketplace" ], "parameters": [ { "name": "packageId", "in": "path", "required": true, "description": "Identifier of a row.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "submission": { "type": "object", "properties": { "packageId": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "state": { "type": "string", "enum": [ "none", "pending", "approved", "rejected" ], "description": "`none` when this package has never been submitted." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why it was rejected. Null unless it was." }, "licence": { "anyOf": [ { "type": "string", "enum": [ "mit", "cc-by-4.0" ] }, { "type": "null" } ] }, "submittedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "number", "description": "Epoch milliseconds." }, { "type": "null" } ] }, "listedVersion": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "packageId", "version", "state", "reason", "licence", "submittedAt", "decidedAt", "listedVersion" ], "additionalProperties": false } }, "required": [ "submission" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v2/marketplace/views": { "post": { "operationId": "recordPackageView", "summary": "Record that a catalogue entry was opened", "description": "Counts one view per account per package per day, so opening the same card twice is one view rather than two. The viewer is stored as a hash and a share token is never written alongside it — an analytics table that held one would be a list of working private links.", "tags": [ "Marketplace" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "packageId": { "type": "string", "description": "The catalogue entry that was opened.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "packageId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recorded": { "type": "boolean", "description": "False when this viewer already counted today." } }, "required": [ "recorded" ], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A `pc_…` token generated from Settings > API & MCP." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable code." }, "message": { "type": "string", "description": "Human-readable message." }, "details": { "type": "array", "description": "Per-field detail, present on validation errors.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } }, "responses": { "BadRequest": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid request — unreadable body, out-of-range field or unknown parameter." }, "Conflict": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflicts with the resource's current state." }, "Forbidden": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Readable resource, but your role does not permit this action." }, "NotFound": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Resource does not exist **or** belongs to another account — the API never distinguishes the two." }, "TooManyRequests": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Too many requests. `Retry-After` says how many seconds to wait." }, "Unauthorized": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Token missing, unknown or revoked." }, "Unprocessable": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Well-formed but unusable request — an empty title once parsed, for instance." } } } }