{ "openapi": "3.0.3", "info": { "title": "MyPlanner REST API", "version": "1.0.0", "description": "Build integrations for MyPlanner boards, tables, tasks, subitems, updates, columns, calendars, and webhooks. Create a personal token in **MyPlanner → Integrate → API tokens**, then select **Authorize** and enter the token. All resources are scoped to the token owner. Routes also support the query fallback `rest.php?path=/boards` when a host does not preserve PATH_INFO." }, "servers": [ { "url": "https://myplanner.dev/app/rest.php", "description": "Production" } ], "externalDocs": { "description": "MyPlanner agent integration guide", "url": "https://github.com/jvx/myplanner-agent-skill" }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Identity", "description": "Token identity and discovery" }, { "name": "Boards", "description": "Planning workspaces" }, { "name": "Tables", "description": "Task groups shown as tables" }, { "name": "Tasks", "description": "Top-level tasks and values" }, { "name": "Subitems", "description": "Checkable children of tasks" }, { "name": "Updates", "description": "Durable task notes" }, { "name": "Columns", "description": "Board-defined fields" }, { "name": "Calendar", "description": "Board Google Calendar configuration" }, { "name": "Webhooks", "description": "Signed event delivery" } ], "paths": { "/me": { "get": { "tags": [ "Identity" ], "summary": "Get token identity", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "token_id": { "$ref": "#/components/schemas/ResourceId" }, "label": { "type": "string" }, "user": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events": { "get": { "tags": [ "Identity" ], "summary": "List supported webhook events", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards": { "get": { "tags": [ "Boards" ], "summary": "List boards", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "boards": { "type": "array", "items": { "$ref": "#/components/schemas/Board" } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Boards" ], "summary": "Create a board", "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "example": { "name": "Launch plan" } } } } } }, "/boards/{boardId}": { "patch": { "tags": [ "Boards" ], "summary": "Update a board", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "hide_time_myplanner": { "type": "boolean", "description": "Hide stored times throughout MyPlanner while preserving their underlying values." }, "hide_time_google_calendar": { "type": "boolean", "description": "Sync dated entries to Google Calendar as all-day events without times." }, "hide_time_shared_viewers": { "type": "boolean", "description": "Redact times from MyPlanner responses and views for users who are not the board owner." } } }, "example": { "name": "Operations", "hide_time_myplanner": false, "hide_time_google_calendar": true, "hide_time_shared_viewers": true } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "put": { "tags": [ "Boards" ], "summary": "Update a board", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "hide_time_myplanner": { "type": "boolean", "description": "Hide stored times throughout MyPlanner while preserving their underlying values." }, "hide_time_google_calendar": { "type": "boolean", "description": "Sync dated entries to Google Calendar as all-day events without times." }, "hide_time_shared_viewers": { "type": "boolean", "description": "Redact times from MyPlanner responses and views for users who are not the board owner." } } }, "example": { "name": "Operations", "hide_time_myplanner": false, "hide_time_google_calendar": true, "hide_time_shared_viewers": true } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "get": { "tags": [ "Boards" ], "summary": "Get board structure", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Board" }, { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/Column" } } } } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Returns the board together with its tables and columns.", "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "delete": { "tags": [ "Boards" ], "summary": "Delete a board", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Permanently deletes the board and its contained resources.", "parameters": [ { "$ref": "#/components/parameters/boardId" } ] } }, "/boards/{boardId}/groups": { "get": { "tags": [ "Tables" ], "summary": "List tables", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "post": { "tags": [ "Tables" ], "summary": "Create a table", "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" } } }, "example": { "name": "Backlog", "color": "#579bfc" } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] } }, "/groups/{groupId}": { "get": { "tags": [ "Tables" ], "summary": "Get a table", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/groupId" } ] }, "patch": { "tags": [ "Tables" ], "summary": "Update a table", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "collapsed": { "type": "boolean" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/groupId" } ] }, "put": { "tags": [ "Tables" ], "summary": "Update a table", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "collapsed": { "type": "boolean" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/groupId" } ] }, "delete": { "tags": [ "Tables" ], "summary": "Delete a table", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Permanently deletes the table and its tasks.", "parameters": [ { "$ref": "#/components/parameters/groupId" } ] } }, "/boards/{boardId}/items": { "get": { "tags": [ "Tasks" ], "summary": "List board tasks", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "post": { "tags": [ "Tasks" ], "summary": "Create a task", "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Item" }, { "$ref": "#/components/schemas/MutationFeedback" } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "group_id": { "$ref": "#/components/schemas/ResourceId" }, "column_values": { "$ref": "#/components/schemas/ColumnValuesInput" } }, "required": [ "name" ] }, "example": { "name": "Call supplier", "group_id": 123, "column_values": { "45": "2026-08-17" } } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] } }, "/boards/{boardId}/items/missing-descriptions": { "get": { "tags": [ "Tasks" ], "summary": "List tasks missing Text", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "text_column": { "allOf": [ { "$ref": "#/components/schemas/Column" } ], "nullable": true }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "item", "subtask" ] }, "item_id": { "$ref": "#/components/schemas/ResourceId" }, "subtask_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "parent_name": { "type": "string", "nullable": true }, "group_id": { "$ref": "#/components/schemas/ResourceId" }, "group_name": { "type": "string" }, "position": { "type": "integer" } } } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] } }, "/boards/{boardId}/items/no-text": { "get": { "tags": [ "Tasks" ], "summary": "List tasks missing Text (legacy alias)", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "text_column": { "allOf": [ { "$ref": "#/components/schemas/Column" } ], "nullable": true }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "item", "subtask" ] }, "item_id": { "$ref": "#/components/schemas/ResourceId" }, "subtask_id": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "parent_name": { "type": "string", "nullable": true }, "group_id": { "$ref": "#/components/schemas/ResourceId" }, "group_name": { "type": "string" }, "position": { "type": "integer" } } } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] } }, "/items/{itemId}": { "get": { "tags": [ "Tasks" ], "summary": "Get a task", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" } ] }, "patch": { "tags": [ "Tasks" ], "summary": "Update a task", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "group_id": { "$ref": "#/components/schemas/ResourceId" }, "column_values": { "$ref": "#/components/schemas/ColumnValuesInput" }, "scope": { "type": "string", "enum": [ "this_occurrence" ], "default": "this_occurrence" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" } ] }, "put": { "tags": [ "Tasks" ], "summary": "Update a task", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "group_id": { "$ref": "#/components/schemas/ResourceId" }, "column_values": { "$ref": "#/components/schemas/ColumnValuesInput" }, "scope": { "type": "string", "enum": [ "this_occurrence" ], "default": "this_occurrence" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" } ] }, "delete": { "tags": [ "Tasks" ], "summary": "Delete a task", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "$ref": "#/components/schemas/MutationFeedback" } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" } ] } }, "/items/{itemId}/values/{columnId}": { "put": { "tags": [ "Tasks" ], "summary": "Set one task column value", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Item" }, { "$ref": "#/components/schemas/MutationFeedback" } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "example": { "value": "Done" } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" }, { "$ref": "#/components/parameters/columnId" } ], "description": "Sets one column value. Omitting the body, sending `null`, or sending an empty value clears the stored value." }, "patch": { "tags": [ "Tasks" ], "summary": "Set one task column value", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Item" }, { "$ref": "#/components/schemas/MutationFeedback" } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "example": { "value": "Done" } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" }, { "$ref": "#/components/parameters/columnId" } ], "description": "Sets one column value. Omitting the body, sending `null`, or sending an empty value clears the stored value." }, "post": { "tags": [ "Tasks" ], "summary": "Set one task column value", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Item" }, { "$ref": "#/components/schemas/MutationFeedback" } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "example": { "value": "Done" } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" }, { "$ref": "#/components/parameters/columnId" } ], "description": "Sets one column value. Omitting the body, sending `null`, or sending an empty value clears the stored value." } }, "/items/{itemId}/subtasks": { "get": { "tags": [ "Subitems" ], "summary": "List subitems", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "subtasks": { "type": "array", "items": { "$ref": "#/components/schemas/Subtask" } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" } ] }, "post": { "tags": [ "Subitems" ], "summary": "Create a subitem", "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subtask" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "column_values": { "$ref": "#/components/schemas/ColumnValuesInput" } }, "required": [ "title" ] }, "example": { "title": "Call vendor", "column_values": { "45": "2026-08-17" } } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" } ] } }, "/subtasks/{subtaskId}": { "patch": { "tags": [ "Subitems" ], "summary": "Update a subitem", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The requested entire-series subitem rename could not be applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "is_done": { "type": "boolean" }, "column_values": { "$ref": "#/components/schemas/ColumnValuesInput" }, "scope": { "type": "string", "enum": [ "this_occurrence", "entire_series" ], "default": "this_occurrence", "description": "entire_series is accepted only for a title-only change on a visible recurring subitem." } } } } } }, "parameters": [ { "$ref": "#/components/parameters/subtaskId" } ], "description": "Updates one subitem occurrence by default. A title-only request may use `scope: entire_series` to rename matching current and future occurrences." }, "put": { "tags": [ "Subitems" ], "summary": "Update a subitem", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The requested entire-series subitem rename could not be applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "is_done": { "type": "boolean" }, "column_values": { "$ref": "#/components/schemas/ColumnValuesInput" }, "scope": { "type": "string", "enum": [ "this_occurrence", "entire_series" ], "default": "this_occurrence", "description": "entire_series is accepted only for a title-only change on a visible recurring subitem." } } } } } }, "parameters": [ { "$ref": "#/components/parameters/subtaskId" } ], "description": "Updates one subitem occurrence by default. A title-only request may use `scope: entire_series` to rename matching current and future occurrences." }, "delete": { "tags": [ "Subitems" ], "summary": "Delete a subitem", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "$ref": "#/components/schemas/MutationFeedback" } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/subtaskId" } ] } }, "/subtasks/{subtaskId}/values/{columnId}": { "put": { "tags": [ "Subitems" ], "summary": "Set one subitem column value", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "$ref": "#/components/schemas/MutationFeedback" } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "example": { "value": "Done" } } } }, "parameters": [ { "$ref": "#/components/parameters/subtaskId" }, { "$ref": "#/components/parameters/columnId" } ], "description": "Sets one column value. Omitting the body, sending `null`, or sending an empty value clears the stored value." }, "patch": { "tags": [ "Subitems" ], "summary": "Set one subitem column value", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "$ref": "#/components/schemas/MutationFeedback" } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "example": { "value": "Done" } } } }, "parameters": [ { "$ref": "#/components/parameters/subtaskId" }, { "$ref": "#/components/parameters/columnId" } ], "description": "Sets one column value. Omitting the body, sending `null`, or sending an empty value clears the stored value." }, "post": { "tags": [ "Subitems" ], "summary": "Set one subitem column value", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Success" }, { "$ref": "#/components/schemas/MutationFeedback" } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "example": { "value": "Done" } } } }, "parameters": [ { "$ref": "#/components/parameters/subtaskId" }, { "$ref": "#/components/parameters/columnId" } ], "description": "Sets one column value. Omitting the body, sending `null`, or sending an empty value clears the stored value." } }, "/items/{itemId}/updates": { "get": { "tags": [ "Updates" ], "summary": "List task updates", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "updates": { "type": "array", "items": { "$ref": "#/components/schemas/Update" } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" } ] }, "post": { "tags": [ "Updates" ], "summary": "Create a task update", "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Update" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1 } }, "required": [ "body" ] }, "example": { "body": "Waiting on supplier confirmation." } } } }, "parameters": [ { "$ref": "#/components/parameters/itemId" } ] } }, "/updates/{updateId}": { "delete": { "tags": [ "Updates" ], "summary": "Delete an update", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/updateId" } ] } }, "/boards/{boardId}/columns": { "get": { "tags": [ "Columns" ], "summary": "List columns", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/Column" } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "post": { "tags": [ "Columns" ], "summary": "Create a column", "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Column" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "status", "text", "people", "date", "priority", "number" ] } }, "required": [ "title", "type" ] }, "example": { "title": "Estimate", "type": "number" } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] } }, "/columns/{columnId}": { "patch": { "tags": [ "Columns" ], "summary": "Rename a column", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Column" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/columnId" } ] }, "put": { "tags": [ "Columns" ], "summary": "Rename a column", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Column" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/columnId" } ] }, "delete": { "tags": [ "Columns" ], "summary": "Delete a column", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/columnId" } ] } }, "/boards/{boardId}/calendar": { "get": { "tags": [ "Calendar" ], "summary": "Get calendar integration", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "integration": { "allOf": [ { "$ref": "#/components/schemas/CalendarIntegration" } ], "nullable": true } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "put": { "tags": [ "Calendar" ], "summary": "Save calendar integration", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "integration": { "$ref": "#/components/schemas/CalendarIntegration" } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Calendar integration changed concurrently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Calendar integration could not be saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "calendar_id": { "type": "string", "minLength": 1 }, "calendar_name": { "type": "string" }, "date_column_id": { "type": "integer", "nullable": true }, "title_template": { "type": "string", "default": "{item}" }, "sync_direction": { "type": "string", "enum": [ "planner_to_calendar", "calendar_to_planner", "two_way" ], "default": "planner_to_calendar" }, "is_active": { "type": "boolean", "default": true } }, "required": [ "calendar_id" ] }, "example": { "calendar_id": "primary", "calendar_name": "Operations", "date_column_id": 45, "sync_direction": "two_way" } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "patch": { "tags": [ "Calendar" ], "summary": "Save calendar integration", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "integration": { "$ref": "#/components/schemas/CalendarIntegration" } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Calendar integration changed concurrently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Calendar integration could not be saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "calendar_id": { "type": "string", "minLength": 1 }, "calendar_name": { "type": "string" }, "date_column_id": { "type": "integer", "nullable": true }, "title_template": { "type": "string", "default": "{item}" }, "sync_direction": { "type": "string", "enum": [ "planner_to_calendar", "calendar_to_planner", "two_way" ], "default": "planner_to_calendar" }, "is_active": { "type": "boolean", "default": true } }, "required": [ "calendar_id" ] }, "example": { "calendar_id": "primary", "calendar_name": "Operations", "date_column_id": 45, "sync_direction": "two_way" } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "post": { "tags": [ "Calendar" ], "summary": "Save calendar integration", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "integration": { "$ref": "#/components/schemas/CalendarIntegration" } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Calendar integration changed concurrently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Calendar integration could not be saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "calendar_id": { "type": "string", "minLength": 1 }, "calendar_name": { "type": "string" }, "date_column_id": { "type": "integer", "nullable": true }, "title_template": { "type": "string", "default": "{item}" }, "sync_direction": { "type": "string", "enum": [ "planner_to_calendar", "calendar_to_planner", "two_way" ], "default": "planner_to_calendar" }, "is_active": { "type": "boolean", "default": true } }, "required": [ "calendar_id" ] }, "example": { "calendar_id": "primary", "calendar_name": "Operations", "date_column_id": 45, "sync_direction": "two_way" } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "delete": { "tags": [ "Calendar" ], "summary": "Disconnect calendar integration", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Calendar integration changed concurrently", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Google notification channel could not be stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Calendar integration could not be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] } }, "/boards/{boardId}/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Register a webhook", "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Signing secret. Returned only once." } } } ] } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Challenge verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "MyPlanner sends a JSON challenge to the URL. Return the same challenge as raw text or JSON. Deliveries are signed with `X-Planner-Signature: sha256=`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "event": { "type": "string", "enum": [ "create_item", "change_name", "change_column_value", "change_specific_column_value", "item_deleted", "move_item_to_group", "create_update", "delete_update" ] }, "config": { "type": "object", "description": "For change_specific_column_value, config.columnId is required.", "properties": { "columnId": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] } }, "additionalProperties": true } }, "required": [ "url", "event" ], "oneOf": [ { "title": "Standard event", "properties": { "event": { "type": "string", "enum": [ "create_item", "change_name", "change_column_value", "item_deleted", "move_item_to_group", "create_update", "delete_update" ] } } }, { "title": "Specific column change", "required": [ "config" ], "properties": { "event": { "type": "string", "enum": [ "change_specific_column_value" ] }, "config": { "type": "object", "required": [ "columnId" ], "properties": { "columnId": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] } }, "additionalProperties": true } } } ] }, "example": { "url": "https://example.com/myplanner-hook", "event": "create_item" } } } }, "parameters": [ { "$ref": "#/components/parameters/boardId" } ] } }, "/webhooks/{webhookId}": { "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/webhookId" } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Success" } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/webhookId" } ] } }, "/webhooks/{webhookId}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List recent webhook deliveries", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "event": { "type": "string" }, "response_code": { "$ref": "#/components/schemas/DatabaseInteger" }, "duration_ms": { "$ref": "#/components/schemas/DatabaseInteger" }, "created_at": { "type": "string" } } } } } } } } }, "401": { "description": "Missing or invalid API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/webhookId" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "personal API token", "description": "Personal token generated in MyPlanner under Integrate → API tokens." } }, "parameters": { "boardId": { "name": "boardId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, "groupId": { "name": "groupId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, "itemId": { "name": "itemId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, "subtaskId": { "name": "subtaskId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, "updateId": { "name": "updateId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, "columnId": { "name": "columnId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } }, "webhookId": { "name": "webhookId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ResourceId" } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } }, "example": { "error": "Missing or invalid API token." } }, "Success": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "example": true } } }, "Board": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "uuid": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "hide_time_myplanner": { "type": "boolean", "default": false, "description": "Show scheduled dates without times in MyPlanner board views." }, "hide_time_google_calendar": { "type": "boolean", "default": false, "description": "Project timed tasks and subtasks to Google Calendar as all-day events." }, "hide_time_shared_viewers": { "type": "boolean", "default": false, "description": "Server-redact scheduled times for non-owner board viewers." }, "created_by": { "type": "string" }, "created_at": { "type": "string", "nullable": true } } }, "Group": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "board_id": { "$ref": "#/components/schemas/ResourceId" }, "name": { "type": "string" }, "color": { "type": "string", "example": "#579bfc" }, "position": { "$ref": "#/components/schemas/DatabaseInteger" }, "collapsed": { "$ref": "#/components/schemas/DatabaseInteger" } } }, "Column": { "type": "object", "required": [ "id", "title", "type" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "board_id": { "$ref": "#/components/schemas/ResourceId" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "status", "text", "people", "date", "priority", "number" ] }, "settings": { "type": "object", "nullable": true, "additionalProperties": true }, "position": { "$ref": "#/components/schemas/DatabaseInteger" } } }, "ColumnValue": { "type": "object", "required": [ "column_id", "title", "type", "value" ], "properties": { "column_id": { "$ref": "#/components/schemas/ResourceId" }, "title": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string", "nullable": true } } }, "Recurrence": { "type": "object", "required": [ "is_recurring" ], "properties": { "is_recurring": { "type": "integer", "enum": [ 0, 1 ] }, "series_id": { "$ref": "#/components/schemas/ResourceId" }, "scope_options": { "type": "array", "items": { "type": "string" } }, "original_start_type": { "type": "string", "nullable": true }, "original_start_value": { "type": "string", "nullable": true }, "is_exception": { "type": "integer", "enum": [ 0, 1 ] }, "provider": { "type": "string", "enum": [ "native", "google" ] }, "source": { "type": "string" } } }, "Item": { "type": "object", "required": [ "id", "board_id", "group_id", "name", "column_values", "recurrence" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "board_id": { "$ref": "#/components/schemas/ResourceId" }, "group_id": { "$ref": "#/components/schemas/ResourceId" }, "name": { "type": "string" }, "position": { "$ref": "#/components/schemas/DatabaseInteger" }, "created_by": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "nullable": true }, "column_values": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnValue" } }, "recurrence": { "$ref": "#/components/schemas/Recurrence" } } }, "Subtask": { "type": "object", "required": [ "id", "item_id", "title", "is_done" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "item_id": { "$ref": "#/components/schemas/ResourceId" }, "title": { "type": "string" }, "is_done": { "oneOf": [ { "type": "boolean" }, { "type": "integer", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "0", "1" ] } ] }, "position": { "$ref": "#/components/schemas/DatabaseInteger" }, "created_by": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "nullable": true }, "values": { "type": "object", "additionalProperties": { "type": "string", "nullable": true } } } }, "Update": { "type": "object", "required": [ "id", "body" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "item_id": { "$ref": "#/components/schemas/ResourceId" }, "author": { "type": "string" }, "body": { "type": "string" }, "created_at": { "type": "string" } } }, "CalendarIntegration": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "board_id": { "$ref": "#/components/schemas/ResourceId" }, "provider": { "type": "string", "example": "google" }, "calendar_id": { "type": "string" }, "calendar_name": { "type": "string" }, "date_column_id": { "description": "Date column ID, or null when no column is selected. Legacy save responses may encode it as a numeric string.", "nullable": true, "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "title_template": { "type": "string", "example": "{item}" }, "sync_direction": { "type": "string", "enum": [ "planner_to_calendar", "calendar_to_planner", "two_way" ] }, "is_active": { "description": "Whether synchronization is enabled. Legacy save responses may encode it as 0 or 1 strings.", "oneOf": [ { "type": "boolean" }, { "type": "integer", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "0", "1" ] } ] }, "created_by": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, "Webhook": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "board_id": { "$ref": "#/components/schemas/ResourceId" }, "url": { "type": "string", "format": "uri" }, "event": { "type": "string" }, "config": { "type": "object", "nullable": true, "additionalProperties": true }, "is_active": { "$ref": "#/components/schemas/DatabaseInteger" }, "fail_count": { "$ref": "#/components/schemas/DatabaseInteger" }, "created_by": { "type": "string" }, "created_at": { "type": "string" } } }, "MutationFeedback": { "type": "object", "properties": { "board_id": { "$ref": "#/components/schemas/ResourceId" }, "change_event_id": { "$ref": "#/components/schemas/ResourceId" }, "webhooks": { "type": "object", "properties": { "active": { "type": "integer" }, "matched": { "type": "integer" }, "delivered": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } } }, "calendar_sync": { "type": "object", "additionalProperties": true }, "recurrence_sync": { "type": "object", "additionalProperties": true } } }, "ColumnValuesInput": { "type": "object", "description": "Map numeric column IDs to values. Use an empty string or null to clear a value.", "additionalProperties": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "DatabaseInteger": { "description": "An integer. Legacy read responses may encode database integers as numeric strings.", "oneOf": [ { "type": "integer" }, { "type": "string", "pattern": "^-?[0-9]+$" } ] }, "ResourceId": { "description": "A positive resource identifier. Legacy read responses may encode IDs as numeric strings.", "oneOf": [ { "type": "integer", "format": "int64", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] } } } }