{ "schemaVersion": "1.0", "name": "Plane", "displayName": "Plane", "description": "Plane is an AI-native project management platform. Agents can create and query work items, plan cycles, modules and initiatives, write wiki pages, triage intake requests, and track customers, over MCP or REST, acting as a signed-in user with scoped permissions and full activity history.", "url": "https://plane.so", "version": "v1", "provider": { "name": "Plane Software, Inc.", "url": "https://plane.so", "repositoryUrl": "https://github.com/makeplane/plane", "statusUrl": "https://status.plane.so" }, "documentation": { "product": "https://docs.plane.so", "developer": "https://developers.plane.so", "apiReference": "https://developers.plane.so/api-reference/introduction", "llmsTxt": "https://plane.so/llms.txt" }, "deployments": [ "cloud", "self-hosted", "air-gapped" ], "interfaces": [ { "type": "mcp", "name": "Plane MCP server", "description": "28 resource tools covering 183 actions. Recommended for tool-calling agents.", "url": "https://mcp.plane.so/http/mcp", "transport": "streamable-http", "auth": [ "oauth2" ], "documentUrl": "https://plane.so/.well-known/mcp.json", "documentationUrl": "https://developers.plane.so/dev-tools/mcp-server" }, { "type": "mcp", "name": "Plane MCP server (token auth)", "description": "Same tools, authenticated with a personal access token. For automations, CI, and headless agents.", "url": "https://mcp.plane.so/http/api-key/mcp", "transport": "streamable-http", "auth": [ "bearer" ], "documentUrl": "https://plane.so/.well-known/mcp.json", "documentationUrl": "https://developers.plane.so/dev-tools/mcp-server" }, { "type": "openapi", "name": "Plane REST API", "description": "Cursor-paginated REST API with sparse field sets and relation expansion.", "url": "https://api.plane.so/api/v1", "specUrl": "https://plane.so/openapi.json", "specVersion": "3.1.0", "auth": [ "api-key", "oauth2" ], "documentationUrl": "https://developers.plane.so/api-reference/introduction" }, { "type": "a2a", "name": "Agent card", "description": "A2A-shaped description of the same capabilities. The underlying transport is MCP, not A2A JSON-RPC.", "url": "https://plane.so/.well-known/agent-card.json" }, { "type": "webhooks", "name": "Plane webhooks", "description": "Project, work item, cycle, module, and comment events. Payloads carry delivery and event identifiers and an HMAC-SHA256 signature, and are retried after a failed delivery.", "documentationUrl": "https://developers.plane.so/webhooks" } ], "auth": { "required": true, "anonymousAccess": false, "methods": [ { "id": "api-key", "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Workspace API key. Created in workspace settings and scoped to that workspace.", "appliesTo": [ "openapi" ], "documentationUrl": "https://developers.plane.so/api-reference/introduction" }, { "id": "personal-access-token", "type": "http", "scheme": "bearer", "description": "Personal access token sent as `Authorization: Bearer ` alongside an `x-workspace-slug` header. Used by the token-auth MCP endpoint.", "additionalHeaders": [ "x-workspace-slug" ], "appliesTo": [ "mcp" ], "documentationUrl": "https://developers.plane.so/dev-tools/mcp-server" }, { "id": "oauth2-mcp", "type": "oauth2", "flow": "authorization_code", "pkce": [ "S256" ], "issuer": "https://mcp.plane.so/", "authorizationUrl": "https://mcp.plane.so/authorize", "tokenUrl": "https://mcp.plane.so/token", "registrationUrl": "https://mcp.plane.so/register", "dynamicClientRegistration": true, "scopes": { "read": "Read workspace data", "write": "Create and modify workspace data" }, "metadataUrl": "https://mcp.plane.so/.well-known/oauth-authorization-server", "resourceMetadataUrl": "https://mcp.plane.so/.well-known/oauth-protected-resource/http/mcp", "description": "OAuth for the hosted MCP server. The user signs in to Plane and selects a workspace; the connection stays bound to it.", "appliesTo": [ "mcp" ] }, { "id": "oauth2-app", "type": "oauth2", "flow": [ "client_credentials", "authorization_code" ], "authorizationUrl": "https://api.plane.so/auth/o/authorize-app/", "tokenUrl": "https://api.plane.so/auth/o/token/", "refreshUrl": "https://api.plane.so/auth/o/token/", "description": "Bot and user tokens issued to a registered Plane app, sent as `Authorization: Bearer `. Register the app in workspace settings to receive its client credentials, then request only the scopes it needs.", "registrationUrl": "https://developers.plane.so/dev-tools/build-plane-app/create-oauth-application", "scopes": { "agents.run_activities:read": "Read agent run activities", "agents.run_activities:write": "Create and update agent run activities", "agents.runs:read": "Read agent runs", "agents.runs:write": "Create and update agent runs", "assets:read": "Read assets", "assets:write": "Create and update assets", "customers.properties:read": "Read customer properties", "customers.properties:write": "Create and update customer properties", "customers.property_values:read": "Read customer property values", "customers.property_values:write": "Create and update customer property values", "customers.requests:read": "Read customer requests", "customers.requests:write": "Create and update customer requests", "customers.work_items:read": "Read customer work items", "customers.work_items:write": "Create and update customer work items", "customers:read": "Read customers", "customers:write": "Create and update customers", "initiatives.epics:read": "Read initiative epics", "initiatives.epics:write": "Create and update initiative epics", "initiatives.labels:read": "Read initiative labels", "initiatives.labels:write": "Create and update initiative labels", "initiatives.projects:read": "Read initiative projects", "initiatives.projects:write": "Create and update initiative projects", "initiatives:read": "Read initiatives", "initiatives:write": "Create and update initiatives", "profile:read": "Read user profile", "projects.cycles:read": "Read project cycles", "projects.cycles:write": "Create and update project cycles", "projects.epics:read": "Read project epics", "projects.epics:write": "Create and update project epics", "projects.estimates:read": "Read project estimates", "projects.estimates:write": "Create and update project estimates", "projects.features:read": "Read project features", "projects.features:write": "Create and update project features", "projects.intakes:read": "Read project intakes", "projects.intakes:write": "Create and update project intakes", "projects.labels:read": "Read project labels", "projects.labels:write": "Create and update project labels", "projects.members:read": "Read project members", "projects.members:write": "Manage project members", "projects.milestones:read": "Read project milestones", "projects.milestones:write": "Create and update project milestones", "projects.modules:read": "Read project modules", "projects.modules:write": "Create and update project modules", "projects.pages:read": "Read project pages", "projects.pages:write": "Create and update project pages", "projects.states:read": "Read project states", "projects.states:write": "Create and update project states", "projects.work_item_properties:read": "Read work item properties", "projects.work_item_properties:write": "Create and update work item properties", "projects.work_item_property_options:read": "Read work item property options", "projects.work_item_property_options:write": "Create and update work item property options", "projects.work_item_property_values:read": "Read work item property values", "projects.work_item_property_values:write": "Create and update work item property values", "projects.work_item_types:read": "Read work item types", "projects.work_item_types:write": "Create and update work item types", "projects.work_items.activities:read": "Read work item activities", "projects.work_items.activities:write": "Create and update work item activities", "projects.work_items.attachments:read": "Read work item attachments", "projects.work_items.attachments:write": "Create and update work item attachments", "projects.work_items.comments:read": "Read work item comments", "projects.work_items.comments:write": "Create and update work item comments", "projects.work_items.links:read": "Read work item links", "projects.work_items.links:write": "Create and update work item links", "projects.work_items.relations:read": "Read work item relations", "projects.work_items.relations:write": "Create and update work item relations", "projects.work_items.worklogs:read": "Read work item worklogs", "projects.work_items.worklogs:write": "Create and update work item worklogs", "projects.work_items:read": "Read project work items", "projects.work_items:write": "Create and update project work items", "projects:read": "Read projects", "projects:write": "Create and update projects", "stickies:read": "Read stickies", "stickies:write": "Create and update stickies", "teamspaces.members:read": "Read teamspace members", "teamspaces.members:write": "Create and update teamspace members", "teamspaces.projects:read": "Read teamspace projects", "teamspaces.projects:write": "Create and update teamspace projects", "teamspaces:read": "Read teamspaces", "teamspaces:write": "Create and update teamspaces", "wiki.pages:read": "Read wiki pages", "wiki.pages:write": "Create and update wiki pages", "workspaces.features:read": "Read workspace features", "workspaces.features:write": "Create and update workspace features", "workspaces.group_sync:read": "Read identity provider group mappings", "workspaces.group_sync:write": "Create and update identity provider group mappings", "workspaces.members:read": "Read workspace members", "workspaces.members:write": "Manage workspace members" }, "appliesTo": [ "openapi" ], "documentationUrl": "https://developers.plane.so/dev-tools/build-plane-app/overview" } ], "scopes": { "agents.run_activities:read": "Read agent run activities", "agents.run_activities:write": "Create and update agent run activities", "agents.runs:read": "Read agent runs", "agents.runs:write": "Create and update agent runs", "assets:read": "Read assets", "assets:write": "Create and update assets", "customers.properties:read": "Read customer properties", "customers.properties:write": "Create and update customer properties", "customers.property_values:read": "Read customer property values", "customers.property_values:write": "Create and update customer property values", "customers.requests:read": "Read customer requests", "customers.requests:write": "Create and update customer requests", "customers.work_items:read": "Read customer work items", "customers.work_items:write": "Create and update customer work items", "customers:read": "Read customers", "customers:write": "Create and update customers", "initiatives.epics:read": "Read initiative epics", "initiatives.epics:write": "Create and update initiative epics", "initiatives.labels:read": "Read initiative labels", "initiatives.labels:write": "Create and update initiative labels", "initiatives.projects:read": "Read initiative projects", "initiatives.projects:write": "Create and update initiative projects", "initiatives:read": "Read initiatives", "initiatives:write": "Create and update initiatives", "profile:read": "Read user profile", "projects.cycles:read": "Read project cycles", "projects.cycles:write": "Create and update project cycles", "projects.epics:read": "Read project epics", "projects.epics:write": "Create and update project epics", "projects.estimates:read": "Read project estimates", "projects.estimates:write": "Create and update project estimates", "projects.features:read": "Read project features", "projects.features:write": "Create and update project features", "projects.intakes:read": "Read project intakes", "projects.intakes:write": "Create and update project intakes", "projects.labels:read": "Read project labels", "projects.labels:write": "Create and update project labels", "projects.members:read": "Read project members", "projects.members:write": "Manage project members", "projects.milestones:read": "Read project milestones", "projects.milestones:write": "Create and update project milestones", "projects.modules:read": "Read project modules", "projects.modules:write": "Create and update project modules", "projects.pages:read": "Read project pages", "projects.pages:write": "Create and update project pages", "projects.states:read": "Read project states", "projects.states:write": "Create and update project states", "projects.work_item_properties:read": "Read work item properties", "projects.work_item_properties:write": "Create and update work item properties", "projects.work_item_property_options:read": "Read work item property options", "projects.work_item_property_options:write": "Create and update work item property options", "projects.work_item_property_values:read": "Read work item property values", "projects.work_item_property_values:write": "Create and update work item property values", "projects.work_item_types:read": "Read work item types", "projects.work_item_types:write": "Create and update work item types", "projects.work_items.activities:read": "Read work item activities", "projects.work_items.activities:write": "Create and update work item activities", "projects.work_items.attachments:read": "Read work item attachments", "projects.work_items.attachments:write": "Create and update work item attachments", "projects.work_items.comments:read": "Read work item comments", "projects.work_items.comments:write": "Create and update work item comments", "projects.work_items.links:read": "Read work item links", "projects.work_items.links:write": "Create and update work item links", "projects.work_items.relations:read": "Read work item relations", "projects.work_items.relations:write": "Create and update work item relations", "projects.work_items.worklogs:read": "Read work item worklogs", "projects.work_items.worklogs:write": "Create and update work item worklogs", "projects.work_items:read": "Read project work items", "projects.work_items:write": "Create and update project work items", "projects:read": "Read projects", "projects:write": "Create and update projects", "stickies:read": "Read stickies", "stickies:write": "Create and update stickies", "teamspaces.members:read": "Read teamspace members", "teamspaces.members:write": "Create and update teamspace members", "teamspaces.projects:read": "Read teamspace projects", "teamspaces.projects:write": "Create and update teamspace projects", "teamspaces:read": "Read teamspaces", "teamspaces:write": "Create and update teamspaces", "wiki.pages:read": "Read wiki pages", "wiki.pages:write": "Create and update wiki pages", "workspaces.features:read": "Read workspace features", "workspaces.features:write": "Create and update workspace features", "workspaces.group_sync:read": "Read identity provider group mappings", "workspaces.group_sync:write": "Create and update identity provider group mappings", "workspaces.members:read": "Read workspace members", "workspaces.members:write": "Manage workspace members" }, "scopeDocumentationUrl": "https://developers.plane.so/dev-tools/build-plane-app/oauth-scopes", "permissionModel": "Credentials act as a workspace member and inherit that member's role and project access. Scopes narrow what a token may do; they never widen it beyond the member's permissions." }, "rateLimit": { "requests": 60, "window": "1m", "windowSeconds": 60, "scope": "per API key or OAuth token", "headers": { "remaining": "X-RateLimit-Remaining", "reset": "X-RateLimit-Reset" }, "appliesTo": [ "openapi", "mcp" ], "documentationUrl": "https://developers.plane.so/api-reference/introduction" }, "pricing": { "model": "per-seat subscription", "currency": "USD", "unit": "seat", "freeTier": true, "billingPeriods": [ "monthly", "annual" ], "url": "https://plane.so/pricing", "documentUrl": "https://plane.so/pricing.json", "salesContact": "sales@plane.so", "products": [ { "id": "free", "name": "Free", "custom": false, "currency": "USD", "unit": "seat", "amount": 0, "prices": [ { "interval": "month", "unitAmount": 0, "currency": "USD" }, { "interval": "year", "unitAmount": 0, "currency": "USD" } ] }, { "id": "pro", "name": "Pro", "custom": false, "currency": "USD", "unit": "seat", "amount": 6, "prices": [ { "interval": "month", "unitAmount": 8, "currency": "USD" }, { "interval": "year", "unitAmount": 6, "currency": "USD" } ], "aiCredits": { "perSeat": 500, "note": "Credits are issued monthly per seat. Agents draw from a separate workspace pool." } }, { "id": "business", "name": "Business", "custom": false, "currency": "USD", "unit": "seat", "amount": 13, "prices": [ { "interval": "month", "unitAmount": 15, "currency": "USD" }, { "interval": "year", "unitAmount": 13, "currency": "USD" } ], "aiCredits": { "perSeat": 1000, "note": "Credits are issued monthly per seat, with per-agent limits and usage reports." } }, { "id": "enterprise-grid", "name": "Enterprise Grid", "custom": true, "currency": "USD", "unit": "seat", "amount": null, "prices": [], "aiCredits": { "flexible": true, "note": "Custom credit allocations, usage controls, and priority support.", "comingSoon": true } } ], "aiCreditPolicy": { "rollover": false, "rolloverNote": "Allowances reset on the first day of each calendar month at 00:00 UTC, not on the billing date; unused credits do not carry over.", "agentAllowance": "AI agents draw from a separate, workspace-level pool sized by the plan and its paid seats, rather than from any one member's per-seat credits. The Free plan has no agent pool.", "usageWarningThresholdPercent": 80, "usageWarningNote": "As a member approaches their allowance, at around 80% used, Plane shows a warning.", "overage": { "available": false, "default": "off", "off": "Plane AI features pause for that member until the allowance resets at the start of the next month. When the agent pool is used up, agent runs stop until the same reset." }, "documentationUrl": "https://docs.plane.so/ai/plane-ai-credits" } }, "contact": { "support": "support@plane.so", "sales": "sales@plane.so", "legal": "legal@plane.so", "supportUrl": "https://plane.so/contact", "salesUrl": "https://plane.so/talk-to-sales", "issuesUrl": "https://github.com/makeplane/plane/issues", "statusUrl": "https://status.plane.so" }, "legal": { "termsOfService": "https://plane.so/legals/terms-and-conditions", "privacyPolicy": "https://plane.so/legals/privacy-policy", "acceptableUsePolicy": "https://plane.so/legals/acceptable-use-policy", "aiTerms": "https://plane.so/legals/ai-terms", "dataProcessingAddendum": "https://plane.so/legals/dpa", "subProcessors": "https://plane.so/legals/sub-processors", "security": "https://plane.so/security" }, "signup": { "url": "https://app.plane.so/sign-up", "selfHostUrl": "https://developers.plane.so/self-hosting/overview" }, "onboarding": { "freeTier": true, "selfServeApiKeys": true, "creditCardRequired": false, "anonymousAccess": false, "dedicatedSandbox": false, "signupUrl": "https://app.plane.so/sign-up", "apiKeyUrl": "https://app.plane.so/profile/api-tokens", "apiKeyDocumentationUrl": "https://developers.plane.so/api-reference/introduction", "appRegistrationUrl": "https://developers.plane.so/dev-tools/build-plane-app/create-oauth-application", "testEnvironment": "A free-plan workspace or a self-hosted instance; both expose the same API surface.", "pricingUrl": "https://plane.so/pricing.json" }, "sdks": [ { "language": "TypeScript", "registry": "npm", "package": "@makeplane/plane-node-sdk", "install": "npm install @makeplane/plane-node-sdk", "repositoryUrl": "https://github.com/makeplane/plane-node-sdk", "registryUrl": "https://www.npmjs.com/package/@makeplane/plane-node-sdk" }, { "language": "Python", "registry": "PyPI", "package": "plane-sdk", "install": "pip install plane-sdk", "registryUrl": "https://pypi.org/project/plane-sdk/" } ], "capabilities": [ { "id": "search-work-items", "name": "Search work items", "description": "Find work items across a workspace by free-text query or a Plane Query Language (PQL) filter, without knowing project ids up front.", "tags": [ "work-items", "search", "read-only" ], "scopes": [ "projects.work_items:read" ], "mcp": { "tool": "workitem", "action": "search" }, "rest": { "operationId": "searchWorkItems", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "query": { "type": "string", "minLength": 1, "description": "Free-text search across work item names and identifiers." }, "pql": { "type": "string", "description": "Optional PQL filter, e.g. `stateGroup = \"started\" AND assignee = @me`. Call the PQL reference first." }, "cursor": { "type": "string", "description": "Cursor from a previous response, formatted `value:offset:is_prev`." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "order_by": { "type": "string", "description": "Field to sort by. Prefix with `-` for descending order." } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/WorkItem" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "Find every open work item mentioning \"SSO\" across the workspace.", "Which work items assigned to me are overdue?" ] }, { "id": "list-work-items", "name": "List work items in a project", "description": "Page through the work items in one project, optionally filtered with PQL and narrowed to a sparse field set.", "tags": [ "work-items", "read-only" ], "scopes": [ "projects.work_items:read" ], "mcp": { "tool": "workitem", "action": "list" }, "rest": { "operationId": "listWorkItems", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "pql": { "type": "string" }, "expand": { "type": "string", "description": "Comma-separated related fields to inline, e.g. `assignees,labels`." }, "fields": { "type": "string", "description": "Comma-separated sparse field set." }, "cursor": { "type": "string", "description": "Cursor from a previous response, formatted `value:offset:is_prev`." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "order_by": { "type": "string", "description": "Field to sort by. Prefix with `-` for descending order." } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/WorkItem" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "List the unfinished work items in the Engineering project, newest first." ] }, { "id": "find-work-item-by-identifier", "name": "Find a work item by its readable identifier", "description": "Retrieve a work item from the identifier people actually use, such as ENG-42, without first resolving a UUID. This is the only work item action that accepts a readable identifier — every other action takes the work item's UUID.", "tags": [ "work-items", "read-only", "prerequisite" ], "scopes": [ "projects.work_items:read" ], "mcp": { "tool": "workitem", "action": "retrieve_by_identifier" }, "rest": { "operationId": "getWorkItemByIdentifier", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "work_item_identifier" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "work_item_identifier": { "type": "string", "pattern": "^[A-Za-z0-9]+-[0-9]+$", "description": "The project identifier and sequence number joined by a hyphen, e.g. `ENG-42`.", "examples": [ "ENG-42" ] }, "expand": { "type": "string", "description": "Comma-separated related fields to inline, e.g. `assignees,labels`." }, "fields": { "type": "string", "description": "Comma-separated sparse field set." } } }, "outputSchema": { "$ref": "#/$defs/WorkItem" }, "examples": [ "What is the status of ENG-42?", "Summarise ENG-42 and tell me who owns it." ] }, { "id": "create-work-item", "name": "Create a work item", "description": "Open a new work item in a project with a name, description, priority, state, assignees, labels, and dates.", "tags": [ "work-items", "write" ], "scopes": [ "projects.work_items:write" ], "mcp": { "tool": "workitem", "action": "create" }, "rest": { "operationId": "createWorkItem", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "name" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description_html": { "type": "string", "description": "Rich-text body. Wins over `description_stripped`." }, "description_stripped": { "type": "string", "description": "Plain-text body, wrapped into HTML on save." }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low", "none" ], "default": "none" }, "state": { "type": "string", "format": "uuid", "description": "Workflow state id. List the project states first if you only have a name." }, "assignees": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "labels": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "type_id": { "type": "string", "format": "uuid" }, "parent": { "type": "string", "format": "uuid" }, "estimate_point": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "target_date": { "type": "string", "format": "date" }, "is_draft": { "type": "boolean", "default": false }, "external_source": { "type": "string", "description": "Name of the originating system, for idempotent syncs." }, "external_id": { "type": "string", "description": "Identifier in the originating system." } } }, "outputSchema": { "$ref": "#/$defs/WorkItem" }, "examples": [ "Create an urgent bug in the Engineering project titled \"Login returns 500\" and assign it to me." ] }, { "id": "update-work-item", "name": "Update a work item", "description": "Change any subset of a work item — state, priority, dates, description, assignees, labels. Only the fields passed are modified.", "tags": [ "work-items", "write" ], "scopes": [ "projects.work_items:write" ], "mcp": { "tool": "workitem", "action": "update" }, "rest": { "operationId": "updateWorkItem", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "work_item_id" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "work_item_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 255 }, "description_html": { "type": "string" }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low", "none" ] }, "state": { "type": "string", "format": "uuid" }, "assignees": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "labels": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "start_date": { "type": "string", "format": "date" }, "target_date": { "type": "string", "format": "date" } } }, "outputSchema": { "$ref": "#/$defs/WorkItem" }, "examples": [ "Move ENG-42 to In Progress and set its target date to next Friday." ] }, { "id": "comment-on-work-item", "name": "Comment on a work item", "description": "Post, edit, or read comments on a work item so an agent can report progress where the work lives.", "tags": [ "work-items", "collaboration", "write" ], "scopes": [ "projects.work_items.comments:write" ], "mcp": { "tool": "workitem_comment", "action": "create" }, "rest": { "operationId": "createWorkItemComment", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "work_item_id", "comment_html" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "work_item_id": { "type": "string", "format": "uuid" }, "comment_html": { "type": "string", "minLength": 1 }, "access": { "type": "string", "enum": [ "INTERNAL", "EXTERNAL" ], "default": "INTERNAL" }, "parent": { "type": "string", "format": "uuid", "description": "Reply to an existing comment." } } }, "outputSchema": { "$ref": "#/$defs/WorkItemComment" }, "examples": [ "Comment on ENG-42 with a summary of what I changed and link the pull request." ] }, { "id": "log-time", "name": "Log time against a work item", "description": "Record a work log with a duration in minutes, and read back the logs on a work item.", "tags": [ "time-tracking", "write" ], "scopes": [ "projects.work_items.worklogs:write" ], "mcp": { "tool": "work_log", "action": "create" }, "rest": { "operationId": "createWorkLog", "specUrl": "https://plane.so/openapi.json" }, "requiresFeature": { "name": "Time tracking", "minimumPlan": "Pro" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "work_item_id", "duration" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "work_item_id": { "type": "string", "format": "uuid" }, "duration": { "type": "integer", "minimum": 1, "description": "Minutes spent." }, "description": { "type": "string" } } }, "outputSchema": { "$ref": "#/$defs/WorkLog" }, "examples": [ "Log 90 minutes against ENG-42 for the migration work." ] }, { "id": "list-projects", "name": "List projects", "description": "Enumerate the projects in a workspace with their ids, identifiers, and enabled features.", "tags": [ "projects", "read-only" ], "scopes": [ "projects:read" ], "mcp": { "tool": "project", "action": "list" }, "rest": { "operationId": "listProjects", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "cursor": { "type": "string", "description": "Cursor from a previous response, formatted `value:offset:is_prev`." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "order_by": { "type": "string", "description": "Field to sort by. Prefix with `-` for descending order." } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/Project" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "What projects exist in this workspace and which ones am I a member of?" ] }, { "id": "create-project", "name": "Create a project", "description": "Set up a project with a name, short identifier, lead, timezone, and the feature modules it should use.", "tags": [ "projects", "write" ], "scopes": [ "projects:write" ], "mcp": { "tool": "project", "action": "create" }, "rest": { "operationId": "createProject", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "name", "identifier" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "identifier": { "type": "string", "minLength": 1, "maxLength": 12, "description": "Short prefix for work item ids, e.g. `ENG`." }, "description": { "type": "string" }, "project_lead": { "type": "string", "format": "uuid" }, "default_assignee": { "type": "string", "format": "uuid" }, "timezone": { "type": "string", "description": "IANA timezone name." }, "cycle_view": { "type": "boolean" }, "module_view": { "type": "boolean" }, "page_view": { "type": "boolean" }, "intake_view": { "type": "boolean" }, "is_time_tracking_enabled": { "type": "boolean" } } }, "outputSchema": { "$ref": "#/$defs/Project" }, "examples": [ "Create a project called Platform with identifier PLAT and cycles enabled." ] }, { "id": "plan-cycle", "name": "Plan a cycle", "description": "Create a time-boxed cycle, list what is in it, and move work items in or out — the sprint-planning loop.", "tags": [ "planning", "cycles", "write" ], "scopes": [ "projects.cycles:write" ], "mcp": { "tool": "cycle", "action": "create" }, "rest": { "operationId": "createCycle", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "name" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "owned_by": { "type": "string", "format": "uuid" }, "timezone": { "type": "string" } } }, "outputSchema": { "$ref": "#/$defs/Cycle" }, "examples": [ "Open a two-week cycle in Engineering starting Monday and add the three highest-priority bugs." ] }, { "id": "plan-module", "name": "Plan a module", "description": "Group related work into a module with a lead, members, dates, and a delivery status.", "tags": [ "planning", "modules", "write" ], "scopes": [ "projects.modules:write" ], "mcp": { "tool": "module", "action": "create" }, "rest": { "operationId": "createModule", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "name" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "backlog", "planned", "in-progress", "paused", "completed", "cancelled" ] }, "lead": { "type": "string", "format": "uuid" }, "members": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "start_date": { "type": "string", "format": "date" }, "target_date": { "type": "string", "format": "date" } } }, "outputSchema": { "$ref": "#/$defs/Module" }, "examples": [ "Create a module for the billing rewrite, lead it with Priya, and target end of quarter." ] }, { "id": "track-initiative", "name": "Track an initiative", "description": "Create and update workspace initiatives, and attach the projects and epics that roll up into them.", "tags": [ "planning", "initiatives", "write" ], "scopes": [ "initiatives:write" ], "mcp": { "tool": "initiative", "action": "create" }, "rest": { "operationId": "createInitiative", "specUrl": "https://plane.so/openapi.json" }, "requiresFeature": { "name": "Initiatives", "minimumPlan": "Pro" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description_html": { "type": "string" }, "lead": { "type": "string", "format": "uuid" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } } }, "outputSchema": { "$ref": "#/$defs/Initiative" }, "examples": [ "Create an initiative for FY26 platform reliability and link the Platform and Infra projects." ] }, { "id": "manage-wiki-pages", "name": "Read and write wiki pages", "description": "List and create pages at workspace (wiki) or project scope, so an agent can file specs and notes next to the work.", "tags": [ "knowledge", "pages", "write" ], "scopes": [ "wiki.pages:write", "projects.pages:write" ], "mcp": { "tool": "page", "action": "create" }, "rest": { "operationId": "createProjectPage", "specUrl": "https://plane.so/openapi.json" }, "requiresFeature": { "name": "Workspace wiki", "minimumPlan": "Pro", "note": "Applies to workspace-scoped wiki pages only — project pages are available on every plan. Nested pages require Business." }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "name", "description_html" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid", "description": "Omit to create a workspace wiki page instead of a project page." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description_html": { "type": "string" }, "access": { "type": "integer", "enum": [ 0, 1 ], "description": "0 public within the workspace, 1 private to the author." }, "is_locked": { "type": "boolean" } } }, "outputSchema": { "$ref": "#/$defs/Page" }, "examples": [ "Write up the incident timeline as a page in the Platform project." ] }, { "id": "triage-intake", "name": "Triage the intake queue", "description": "Read the intake queue for a project and accept, reject, or convert submitted requests into work items.", "tags": [ "intake", "triage", "write" ], "scopes": [ "projects.intakes:write" ], "mcp": { "tool": "intake", "action": "list" }, "rest": { "operationId": "listIntakeWorkItems", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "cursor": { "type": "string", "description": "Cursor from a previous response, formatted `value:offset:is_prev`." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "order_by": { "type": "string", "description": "Field to sort by. Prefix with `-` for descending order." } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/IntakeWorkItem" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "Summarise everything waiting in the Support intake queue and flag likely duplicates." ] }, { "id": "manage-customers", "name": "Manage customers and requests", "description": "Create customer records, log their requests, and link the work items that deliver against them.", "tags": [ "customers", "write" ], "scopes": [ "customers:write", "customers.requests:write" ], "mcp": { "tool": "customer", "action": "create" }, "rest": { "operationId": "createCustomer", "specUrl": "https://plane.so/openapi.json" }, "requiresFeature": { "name": "Customers", "minimumPlan": "Business" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "type": "string", "format": "email" }, "domain": { "type": "string" }, "website_url": { "type": "string", "format": "uri" }, "employees": { "type": "integer", "minimum": 0 }, "stage": { "type": "string" }, "contract_status": { "type": "string" }, "description_html": { "type": "string" } } }, "outputSchema": { "$ref": "#/$defs/Customer" }, "examples": [ "Add Acme Corp as a customer and link the two feature requests they raised." ] }, { "id": "resolve-members", "name": "Resolve workspace members", "description": "Look up workspace and project members and their roles, so names in a prompt can be turned into the ids other capabilities require.", "tags": [ "members", "read-only", "prerequisite" ], "scopes": [ "workspaces.members:read" ], "mcp": { "tool": "member", "action": "list_workspace" }, "rest": { "operationId": "listWorkspaceMembers", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "display_name": { "type": "string" }, "email": { "type": "string" }, "role_slug": { "type": "string", "description": "Filter by role, e.g. `admin`, `member`, `guest`." }, "is_active": { "type": "boolean" }, "cursor": { "type": "string", "description": "Cursor from a previous response, formatted `value:offset:is_prev`." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "order_by": { "type": "string", "description": "Field to sort by. Prefix with `-` for descending order." } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/Member" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "Who are the admins of this workspace?" ] }, { "id": "get-current-user", "name": "Identify the current user", "description": "Resolve who the credential authenticates as, including whether it is a bot. Call this to attribute work and to interpret `@me` in a PQL filter.", "tags": [ "members", "read-only", "prerequisite" ], "scopes": [ "profile:read" ], "mcp": { "tool": "member", "action": "me" }, "rest": { "operationId": "getCurrentUser", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "additionalProperties": false, "properties": {} }, "outputSchema": { "$ref": "#/$defs/CurrentUser" }, "examples": [ "Who am I connected as, and is this a bot account?" ] }, { "id": "get-pql-reference", "name": "Retrieve the query language reference", "description": "Fetch the Plane Query Language syntax reference — operators, functions, fields, and worked examples. Call this before composing a `pql` filter for any capability that accepts one.", "tags": [ "query", "read-only", "prerequisite" ], "scopes": [], "mcp": { "tool": "get_pql_reference" }, "alternateInterface": { "kind": "mcp-only", "note": "Exposed as an MCP tool. There is no REST equivalent; the same syntax is documented for humans.", "documentationUrl": "https://docs.plane.so/core-concepts/issues/plane-query-language" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "additionalProperties": false, "properties": { "detail": { "type": "string", "enum": [ "full", "brief" ], "default": "full", "description": "`full` gives operators, functions and examples; `brief` gives a compact field and operator list." } } }, "outputSchema": { "type": "object", "properties": { "reference": { "type": "string", "description": "The PQL reference as text." } } }, "examples": [ "Show me the PQL syntax for overdue, in-progress work assigned to me." ] }, { "id": "list-workflow-states", "name": "List workflow states", "description": "Read a project's workflow states and their groups. Call this to turn a state name such as \"In Progress\" into the id that creating and updating work items requires.", "tags": [ "workspace", "states", "read-only", "prerequisite" ], "scopes": [ "projects.states:read" ], "mcp": { "tool": "state", "action": "list" }, "rest": { "operationId": "listStates", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "cursor": { "type": "string", "description": "Cursor from a previous response, formatted `value:offset:is_prev`." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "order_by": { "type": "string", "description": "Field to sort by. Prefix with `-` for descending order." } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/State" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "What states does the Engineering project have, and which one counts as done?" ] }, { "id": "list-labels", "name": "List labels", "description": "Read a project's labels. Call this to turn label names into the ids that creating and updating work items requires.", "tags": [ "workspace", "labels", "read-only", "prerequisite" ], "scopes": [ "projects.labels:read" ], "mcp": { "tool": "label", "action": "list" }, "rest": { "operationId": "listLabels", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "cursor": { "type": "string", "description": "Cursor from a previous response, formatted `value:offset:is_prev`." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "order_by": { "type": "string", "description": "Field to sort by. Prefix with `-` for descending order." } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/Label" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "Which labels exist in the Platform project?" ] }, { "id": "read-work-item-activity", "name": "Read a work item's history", "description": "Page through the change history of a work item — state moves, reassignments, field edits — to summarise what happened and when.", "tags": [ "work-items", "audit", "read-only" ], "scopes": [ "projects.work_items.activities:read" ], "mcp": { "tool": "workitem_activity", "action": "list" }, "rest": { "operationId": "listWorkItemActivities", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "work_item_id" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "work_item_id": { "type": "string", "format": "uuid" }, "cursor": { "type": "string", "description": "Cursor from a previous response, formatted `value:offset:is_prev`." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "order_by": { "type": "string", "description": "Field to sort by. Prefix with `-` for descending order." } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/WorkItemActivity" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "Summarise what changed on ENG-42 this week, including state changes and reassignments." ] }, { "id": "relate-work-items", "name": "Relate work items", "description": "Create a typed relation between two work items — blocking, blocked by, duplicate, relates to, or a custom workspace relation type — so dependencies are explicit.", "tags": [ "work-items", "dependencies", "write" ], "scopes": [ "projects.work_items:write" ], "mcp": { "tool": "workitem_relation", "action": "create" }, "rest": { "operationId": "createWorkItemRelation", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "work_item_id", "relation_type", "related_work_item_ids" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "work_item_id": { "type": "string", "format": "uuid" }, "relation_type": { "type": "string", "description": "Relation kind. List the workspace relation definitions first to discover custom types.", "examples": [ "blocked_by", "blocks", "duplicate", "relates_to" ] }, "related_work_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } } }, "outputSchema": { "type": "array", "items": { "$ref": "#/$defs/WorkItemRelation" } }, "examples": [ "Mark ENG-42 as blocked by ENG-17." ] }, { "id": "link-work-item", "name": "Attach an external link to a work item", "description": "Add a titled external URL to a work item — a pull request, a dashboard, a design file — and read back the links already on it.", "tags": [ "work-items", "links", "write" ], "scopes": [ "projects.work_items.links:write" ], "mcp": { "tool": "workitem_link", "action": "create" }, "rest": { "operationId": "createWorkItemLink", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "work_item_id", "url" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "work_item_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" } } }, "outputSchema": { "$ref": "#/$defs/WorkItemLink" }, "examples": [ "Link the pull request for this fix to ENG-42." ] }, { "id": "attach-file-to-work-item", "name": "Attach a file to a work item", "description": "Upload a file to a work item. Request presigned upload credentials, POST the file to the returned URL, then confirm the upload. Over MCP the `upload_from_url` action does all three in one call.", "tags": [ "work-items", "attachments", "write" ], "scopes": [ "projects.work_items.attachments:write" ], "mcp": { "tool": "workitem_attachment", "action": "upload_from_url" }, "rest": { "operationId": "createWorkItemAttachmentUpload", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "work_item_id", "name", "size", "type" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "work_item_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "File name including its extension." }, "size": { "type": "integer", "minimum": 1, "description": "File size in bytes." }, "type": { "type": "string", "description": "MIME type, e.g. `image/png`." }, "external_source": { "type": "string" }, "external_id": { "type": "string" } } }, "outputSchema": { "$ref": "#/$defs/WorkItemAttachmentUpload" }, "examples": [ "Attach the failing test log to ENG-42." ] }, { "id": "manage-work-item-types", "name": "Manage work item types", "description": "List and create the work item types in a project — Bug, Story, Epic and any custom type — each with its own icon and custom properties. Prefer the MCP `resolve` action over `create`: it finds an existing type or creates one without duplicating, which is also the only way to get a usable type in a workspace that centrally governs its type vocabulary and refuses project-scoped writes. `import_to_project` links existing workspace types to a project.", "tags": [ "work-items", "configuration", "write", "prerequisite" ], "scopes": [ "projects.work_item_types:write" ], "mcp": { "tool": "workitem_type", "action": "resolve" }, "rest": { "operationId": "createWorkItemType", "specUrl": "https://plane.so/openapi.json" }, "requiresFeature": { "name": "Work item types", "minimumPlan": "Pro" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "name" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid", "description": "Omit for the workspace's own set of types rather than one project's." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "is_active": { "type": "boolean" }, "logo_props": { "type": "object", "additionalProperties": true } } }, "outputSchema": { "$ref": "#/$defs/WorkItemType" }, "examples": [ "Add an Incident work item type to the Platform project." ] }, { "id": "set-custom-property-values", "name": "Read and write custom property values", "description": "Set or read the value of a work item's custom properties, so an agent can populate the fields a team actually tracks rather than only the built-in ones.", "tags": [ "work-items", "custom-fields", "write" ], "scopes": [ "projects.work_item_property_values:write" ], "mcp": { "tool": "workitem_property", "action": "set_value" }, "rest": { "operationId": "setWorkItemPropertyValues", "specUrl": "https://plane.so/openapi.json" }, "requiresFeature": { "name": "Work item properties", "minimumPlan": "Pro" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "work_item_id", "property_id", "values" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "work_item_id": { "type": "string", "format": "uuid" }, "property_id": { "type": "string", "format": "uuid", "description": "List the work item type's properties first to find this id." }, "values": { "type": "array", "minItems": 1, "description": "One entry per value. Multi-select properties accept several.", "items": { "type": "string" } } } }, "outputSchema": { "type": "array", "items": { "$ref": "#/$defs/WorkItemPropertyValue" } }, "examples": [ "Set the Severity property on ENG-42 to S1." ] }, { "id": "manage-estimates", "name": "Manage estimates", "description": "Create a project's estimation system and read its points, so the `estimate_point` id required when sizing a work item can be resolved.", "tags": [ "planning", "estimates", "write", "prerequisite" ], "scopes": [ "projects.estimates:write" ], "mcp": { "tool": "project_estimate", "action": "create" }, "rest": { "operationId": "createEstimate", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "name", "type" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "points", "categories", "time" ] }, "estimate_points": { "type": "array", "description": "The selectable values, in order.", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "integer" }, "value": { "type": "string" } } } } } }, "outputSchema": { "$ref": "#/$defs/Estimate" }, "examples": [ "Set up Fibonacci story points on the Engineering project." ] }, { "id": "manage-epics", "name": "Manage epics", "description": "Create epics and attach the work items that roll up into them. Plane models an epic as a work item whose type is named Epic, so over MCP there is no epic tool: resolve the Epic type with `workitem_type resolve`, pass the returned id as `type_id` to `workitem create`, then list epics with `pql='type = \"\"'` and an epic's children with `pql='childOf(\"ENG-12\")'`. REST has dedicated epic paths that do this for you.", "tags": [ "planning", "epics", "write" ], "scopes": [ "projects.epics:write" ], "mcp": { "tool": "workitem", "action": "create" }, "rest": { "operationId": "createEpic", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "name" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description_html": { "type": "string" }, "state_id": { "type": "string", "format": "uuid" }, "parent_id": { "type": "string", "format": "uuid" }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low", "none" ] }, "assignee_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "label_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "start_date": { "type": "string", "format": "date" }, "target_date": { "type": "string", "format": "date" } } }, "outputSchema": { "$ref": "#/$defs/Epic" }, "examples": [ "Create an epic for the billing rewrite and move the five related bugs under it." ] }, { "id": "plan-milestone", "name": "Plan a milestone", "description": "Create dated checkpoints in a project and attach the work items that must land by each one.", "tags": [ "planning", "milestones", "write" ], "scopes": [ "projects.milestones:write" ], "mcp": { "tool": "milestone", "action": "create" }, "rest": { "operationId": "createMilestone", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "title" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "target_date": { "type": "string", "format": "date" } } }, "outputSchema": { "$ref": "#/$defs/Milestone" }, "examples": [ "Add a Beta milestone to the Platform project targeting 15 March." ] }, { "id": "manage-cycle-work-items", "name": "Fill and close out a cycle", "description": "Add work items to a cycle, list what is in it, transfer unfinished work to the next cycle, and complete or archive it — the rest of the sprint loop beyond creating the cycle.", "tags": [ "planning", "cycles", "write" ], "scopes": [ "projects.cycles:write" ], "mcp": { "tool": "cycle", "action": "manage_workitems" }, "rest": { "operationId": "addCycleWorkItems", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "cycle_id", "work_item_ids" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "cycle_id": { "type": "string", "format": "uuid" }, "work_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/WorkItem" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "Put the three highest-priority bugs into the current cycle." ] }, { "id": "manage-module-work-items", "name": "Fill a module", "description": "Add work items to a module and list what it already contains.", "tags": [ "planning", "modules", "write" ], "scopes": [ "projects.modules:write" ], "mcp": { "tool": "module", "action": "manage_workitems" }, "rest": { "operationId": "addModuleWorkItems", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "module_id", "work_item_ids" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "module_id": { "type": "string", "format": "uuid" }, "work_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/WorkItem" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "Move everything labelled billing into the billing module." ] }, { "id": "submit-intake-request", "name": "Submit and resolve an intake request", "description": "File a request into a project intake queue, then accept, reject, snooze, or mark it duplicate. Pairs with reading the queue.", "tags": [ "intake", "triage", "write" ], "scopes": [ "projects.intakes:write" ], "mcp": { "tool": "intake", "action": "create" }, "rest": { "operationId": "createIntakeWorkItem", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id", "issue" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "issue": { "type": "object", "required": [ "name" ], "description": "The work item to submit for triage.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description_html": { "type": "string" }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low", "none" ] } } } } }, "outputSchema": { "$ref": "#/$defs/IntakeWorkItem" }, "examples": [ "File this bug report into the Support intake queue." ] }, { "id": "manage-customer-requests", "name": "Log customer requests", "description": "Record what a customer asked for and link the work items that deliver it, so commitments are traceable back to the account.", "tags": [ "customers", "write" ], "scopes": [ "customers.requests:write", "customers.work_items:write" ], "mcp": { "tool": "customer_request", "action": "create" }, "rest": { "operationId": "createCustomerRequest", "specUrl": "https://plane.so/openapi.json" }, "requiresFeature": { "name": "Customers", "minimumPlan": "Business" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "customer_id", "name" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "customer_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description_html": { "type": "string" }, "link": { "type": "string", "format": "uri", "description": "Where the request came from, e.g. a support ticket." }, "work_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "outputSchema": { "$ref": "#/$defs/CustomerRequest" }, "examples": [ "Log Acme's request for SAML and link the two work items covering it." ] }, { "id": "list-teamspaces", "name": "List teamspaces", "description": "Read the teamspaces in a workspace with their members and projects, to scope work to the right team.", "tags": [ "workspace", "teamspaces", "read-only" ], "scopes": [ "teamspaces:read" ], "rest": { "operationId": "listTeamspaces", "specUrl": "https://plane.so/openapi.json" }, "alternateInterface": { "kind": "rest-only", "note": "Available over REST. The MCP server has no teamspace tool; its `workspace` tool covers feature flags only.", "documentationUrl": "https://developers.plane.so/api-reference/teamspace/list-teamspaces" }, "requiresFeature": { "name": "Teamspaces", "minimumPlan": "Pro" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "cursor": { "type": "string", "description": "Cursor from a previous response, formatted `value:offset:is_prev`." }, "per_page": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "order_by": { "type": "string", "description": "Field to sort by. Prefix with `-` for descending order." } } }, "outputSchema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/$defs/Teamspace" } }, "total_count": { "type": "integer" }, "count": { "type": "integer" }, "total_pages": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "next_page_results": { "type": "boolean" }, "prev_page_results": { "type": "boolean" } } }, "examples": [ "Which teamspaces exist and which projects belong to each?" ] }, { "id": "manage-releases", "name": "Manage releases and changelogs", "description": "Create releases, attach the work items shipping in them, manage release tags and labels, and generate or edit the changelog.", "tags": [ "releases", "write" ], "scopes": [], "mcp": { "tool": "release", "action": "create" }, "alternateInterface": { "kind": "mcp-only", "note": "Available through the MCP `release`, `release_tag`, and `release_label` tools. No public REST endpoints are documented for releases yet.", "documentationUrl": "https://developers.plane.so/dev-tools/mcp-server-tools" }, "requiresFeature": { "name": "Releases", "note": "Gated by the Plane API and your plan; the error names the feature when it is unavailable." }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description_html": { "type": "string" }, "released_at": { "type": "string", "format": "date-time" }, "work_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "outputSchema": { "$ref": "#/$defs/Release" }, "examples": [ "Cut a 2.4.0 release with everything completed in the current cycle and draft the changelog." ] }, { "id": "report-agent-run-activity", "name": "Report progress as a Plane agent", "description": "For agents installed as Plane apps: post thoughts, actions, responses, elicitations, and errors into the Agent Run created when a user @mentions the agent on a work item. Thoughts and actions are ephemeral; a response becomes a visible comment.", "tags": [ "agents", "collaboration", "write" ], "scopes": [ "agents.runs:write", "agents.run_activities:write" ], "alternateInterface": { "kind": "sdk", "note": "Reached through the official SDKs as `agentRuns.activities.create(workspaceSlug, agentRunId, ...)` using the app's bot token. Plane Agents, now available, and the REST paths are not part of the published API reference.", "documentationUrl": "https://developers.plane.so/dev-tools/agents/overview" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "agent_run_id", "type", "content" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "agent_run_id": { "type": "string", "format": "uuid", "description": "From the webhook that triggered this run." }, "type": { "type": "string", "enum": [ "thought", "action", "response", "elicitation", "error" ], "description": "`thought` and `action` are ephemeral; `response` posts a comment; `elicitation` asks the user a question." }, "content": { "type": "object", "description": "Shape depends on `type`. See the signals and content payload reference.", "additionalProperties": true }, "signal": { "type": "string", "enum": [ "continue", "complete", "failed" ], "description": "Whether the run stays open after this activity." } } }, "outputSchema": { "$ref": "#/$defs/AgentRunActivity" }, "examples": [ "Reply in the Agent Run with the fix I applied and mark the run complete." ] }, { "id": "count-work-items", "name": "Count and group work items", "description": "Aggregate work item counts across a workspace or project, grouped and sub-grouped by state, priority, assignee, label, type, cycle, module, milestone, release, creator, or date. This is the reporting primitive: Plane's Dashboards and Analytics views themselves have no public API, so an agent answers \"how many, broken down by what\" with this.", "tags": [ "work-items", "reporting", "read-only" ], "scopes": [ "projects.work_items:read" ], "mcp": { "tool": "workitem", "action": "count" }, "alternateInterface": { "kind": "mcp-only", "note": "Exposed as the MCP `workitem` count action. No REST count endpoint is documented; over REST, read `total_count` from a filtered list response instead.", "documentationUrl": "https://developers.plane.so/dev-tools/mcp-server-tools#work-items" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid", "description": "Omit to count across the whole workspace." }, "pql": { "type": "string", "description": "Optional PQL filter. Call the PQL reference first." }, "group_by": { "type": "string", "description": "Grouping key. These are grouping keys only — they are not PQL filter fields.", "enum": [ "state_id", "state__group", "priority", "project_id", "type_id", "labels__id", "assignees__id", "issue_module__module_id", "release_work_items__release_id", "cycle_id", "milestone_id", "created_by", "target_date", "start_date" ] }, "sub_group_by": { "type": "string", "description": "Second grouping key, from the same set as `group_by`.", "enum": [ "state_id", "state__group", "priority", "project_id", "type_id", "labels__id", "assignees__id", "issue_module__module_id", "release_work_items__release_id", "cycle_id", "milestone_id", "created_by", "target_date", "start_date" ] } } }, "outputSchema": { "$ref": "#/$defs/WorkItemCountBreakdown" }, "examples": [ "How many open work items are there per assignee in the Engineering project?", "Break down this cycle by state group and priority." ] }, { "id": "summarise-logged-time", "name": "Summarise logged time", "description": "Total the time logged against every work item in a project, for timesheet and capacity reporting. Pairs with logging time on an individual work item.", "tags": [ "time-tracking", "reporting", "read-only" ], "scopes": [ "projects.work_items.worklogs:read" ], "mcp": { "tool": "project", "action": "worklog_summary" }, "rest": { "operationId": "getProjectWorklogTotals", "specUrl": "https://plane.so/openapi.json" }, "requiresFeature": { "name": "Time tracking", "minimumPlan": "Pro" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" } } }, "outputSchema": { "type": "array", "items": { "$ref": "#/$defs/WorkLogTotal" } }, "examples": [ "How much time has been logged per work item in the Platform project this month?" ] }, { "id": "manage-project-features", "name": "Read and toggle project features", "description": "Read or change which feature modules a project has enabled — epics, modules, cycles, views, pages, intake, work item types. Check this before calling a capability that depends on a module being on.", "tags": [ "projects", "configuration", "write", "prerequisite" ], "scopes": [ "projects.features:write" ], "mcp": { "tool": "project", "action": "update_features" }, "rest": { "operationId": "updateProjectFeatures", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "project_id" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_id": { "type": "string", "format": "uuid" }, "epics": { "type": "boolean" }, "modules": { "type": "boolean" }, "cycles": { "type": "boolean" }, "views": { "type": "boolean" }, "pages": { "type": "boolean" }, "intakes": { "type": "boolean" }, "work_item_types": { "type": "boolean" } } }, "outputSchema": { "$ref": "#/$defs/ProjectFeatures" }, "examples": [ "Are cycles enabled on the Platform project? If not, turn them on." ] }, { "id": "manage-workspace-features", "name": "Read and toggle workspace features", "description": "Read or change which workspace-level features are enabled — initiatives, teamspaces, customers, wiki, project grouping, and Plane AI.", "tags": [ "workspace", "configuration", "write", "prerequisite" ], "scopes": [ "workspaces.features:write" ], "mcp": { "tool": "workspace", "action": "update_features" }, "rest": { "operationId": "updateWorkspaceFeatures", "specUrl": "https://plane.so/openapi.json" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "project_grouping": { "type": "boolean" }, "initiatives": { "type": "boolean" }, "teams": { "type": "boolean", "description": "Teamspaces." }, "customers": { "type": "boolean" }, "wiki": { "type": "boolean" }, "pi": { "type": "boolean", "description": "Plane AI." } } }, "outputSchema": { "$ref": "#/$defs/WorkspaceFeatures" }, "examples": [ "Which workspace features are on, and is Plane AI enabled?" ] }, { "id": "map-identity-provider-groups", "name": "Map identity provider groups to roles", "description": "List and create mappings from identity provider groups to Plane roles, at workspace or project scope. This is the one integration-shaped API Plane exposes — the native integrations (GitHub, GitLab, Slack, Sentry, Bitbucket) are configured in workspace settings and have no public endpoints.", "tags": [ "workspace", "identity", "integration", "write" ], "scopes": [ "workspaces.group_sync:write" ], "rest": { "operationId": "createIdpWorkspaceGroupMapping", "specUrl": "https://plane.so/openapi.json" }, "alternateInterface": { "kind": "rest-only", "note": "Available over REST only. The MCP server has no group-sync tool.", "documentationUrl": "https://developers.plane.so/api-reference/idp-group-sync/overview" }, "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "idp_group_name", "role" ], "additionalProperties": false, "properties": { "workspace_slug": { "type": "string", "description": "Workspace identifier from the workspace URL, e.g. `my-team`. Implied by the credential on MCP." }, "idp_group_name": { "type": "string", "description": "Group name as it appears in the identity provider." }, "role": { "type": "string", "description": "Plane role to grant members of that group." } } }, "outputSchema": { "$ref": "#/$defs/IdpGroupMapping" }, "examples": [ "Map the engineering-all IdP group to the Member role in this workspace." ] } ], "limitations": [ { "area": "Dashboards and Analytics", "reason": "Dashboards, widgets, and the Analytics views are UI-only; no REST endpoints or MCP tools are published for reading or building them.", "workaround": "Use the `count-work-items` capability for grouped counts and `summarise-logged-time` for time totals, then render the numbers yourself.", "documentationUrl": "https://docs.plane.so/dashboards" }, { "area": "Native integrations", "reason": "GitHub, GitLab, Slack, Sentry, Bitbucket, Cursor, and Draw.io are connected in workspace settings. There is no public API to install, configure, or query them.", "workaround": "Build a Plane app with OAuth and webhooks for your own integration, or use `map-identity-provider-groups` for identity group sync.", "documentationUrl": "https://developers.plane.so/dev-tools/build-plane-app/overview" }, { "area": "Automations, Plane Runner, and Workflows & Approvals", "reason": "Configured in the product. No endpoints are published for defining rules, scripts, or approval gates.", "workaround": "Toggle the workflows feature with `manage-project-features`; drive state changes with `update-work-item`.", "documentationUrl": "https://docs.plane.so/automations/overview" }, { "area": "Plane AI (Pi Chat), AI Skills, and AI usage monitoring", "reason": "No public API for prompting Plane AI, managing saved AI Skills, or reading the in-product AI usage dashboard (monthly meter, trend chart, per-member/feature/project breakdown).", "workaround": "Enable or check Plane AI with `manage-workspace-features` (`pi`); build your own agent with `report-agent-run-activity`. Credit amounts and policy (rollover, overage) are published in `/pricing.json`, but live consumption is not queryable.", "documentationUrl": "https://docs.plane.so/ai/plane-ai-credits" }, { "area": "Notifications, exports, importers, and bulk operations", "reason": "Product features without published endpoints.", "workaround": "Page through list capabilities and act per work item.", "documentationUrl": "https://docs.plane.so" } ], "$defs": { "WorkItem": { "type": "object", "title": "Work item", "description": "A task, bug, or story. Epics are work items of an epic type.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description_html": { "type": [ "string", "null" ] }, "sequence_id": { "type": "integer", "description": "Per-project counter behind the human identifier, e.g. 42 in ENG-42." }, "project": { "type": "string", "format": "uuid" }, "state": { "type": [ "string", "null" ], "format": "uuid" }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low", "none" ] }, "assignees": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "labels": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "type_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent": { "type": [ "string", "null" ], "format": "uuid" }, "estimate_point": { "type": [ "string", "null" ], "format": "uuid" }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "target_date": { "type": [ "string", "null" ], "format": "date" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_draft": { "type": "boolean" }, "external_source": { "type": [ "string", "null" ] }, "external_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkItemComment": { "type": "object", "title": "Work item comment", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "comment_html": { "type": [ "string", "null" ] }, "access": { "type": "string", "enum": [ "INTERNAL", "EXTERNAL" ] }, "issue": { "type": "string", "format": "uuid" }, "parent": { "type": [ "string", "null" ], "format": "uuid" }, "actor": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkLog": { "type": "object", "title": "Work log", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "duration": { "type": "integer", "description": "Minutes logged." }, "description": { "type": [ "string", "null" ] }, "issue_id": { "type": "string", "format": "uuid" }, "logged_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Project": { "type": "object", "title": "Project", "required": [ "id", "name", "identifier" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "identifier": { "type": "string", "description": "Short prefix used in work item identifiers, e.g. `ENG`." }, "description": { "type": [ "string", "null" ] }, "network": { "type": "integer", "enum": [ 0, 2 ], "description": "0 private to members, 2 visible to the whole workspace." }, "project_lead": { "type": [ "string", "null" ], "format": "uuid" }, "default_assignee": { "type": [ "string", "null" ], "format": "uuid" }, "timezone": { "type": "string" }, "cycle_view": { "type": "boolean" }, "module_view": { "type": "boolean" }, "page_view": { "type": "boolean" }, "intake_view": { "type": "boolean" }, "is_time_tracking_enabled": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Cycle": { "type": "object", "title": "Cycle", "description": "A time-boxed iteration within a project.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": "string", "enum": [ "draft", "upcoming", "current", "completed" ] }, "owned_by": { "type": "string", "format": "uuid" }, "project": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Module": { "type": "object", "title": "Module", "description": "A grouping of related work within a project.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "backlog", "planned", "in-progress", "paused", "completed", "cancelled" ] }, "lead": { "type": [ "string", "null" ], "format": "uuid" }, "members": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "target_date": { "type": [ "string", "null" ], "format": "date" }, "project": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Milestone": { "type": "object", "title": "Milestone", "required": [ "id", "title" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "target_date": { "type": [ "string", "null" ], "format": "date" }, "project": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Epic": { "type": "object", "title": "Epic", "description": "A large body of work that parents other work items.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description_html": { "type": [ "string", "null" ] }, "state_id": { "type": [ "string", "null" ], "format": "uuid" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "priority": { "type": "string", "enum": [ "urgent", "high", "medium", "low", "none" ] }, "assignee_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "label_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "target_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Initiative": { "type": "object", "title": "Initiative", "description": "A workspace-level goal that projects and epics roll up into.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description_html": { "type": [ "string", "null" ] }, "lead": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "type": [ "string", "null" ], "format": "uuid" }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "State": { "type": "object", "title": "Workflow state", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "group": { "type": "string", "enum": [ "backlog", "unstarted", "started", "completed", "cancelled" ] }, "description": { "type": [ "string", "null" ] }, "sequence": { "type": "number" }, "default": { "type": "boolean" }, "is_triage": { "type": "boolean" }, "project": { "type": "string", "format": "uuid" } } }, "Label": { "type": "object", "title": "Label", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "parent": { "type": [ "string", "null" ], "format": "uuid" }, "sort_order": { "type": "number" }, "project": { "type": "string", "format": "uuid" } } }, "Page": { "type": "object", "title": "Page", "description": "A document at workspace (wiki) or project scope.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description_html": { "type": [ "string", "null" ] }, "access": { "type": "integer", "enum": [ 0, 1 ] }, "is_locked": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" }, "owned_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "IntakeWorkItem": { "type": "object", "title": "Intake work item", "description": "A submitted request awaiting triage.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "integer", "enum": [ -2, -1, 0, 1, 2 ], "description": "-2 pending, -1 rejected, 0 snoozed, 1 accepted, 2 duplicate." }, "snoozed_till": { "type": [ "string", "null" ], "format": "date-time" }, "duplicate_to": { "type": [ "string", "null" ], "format": "uuid" }, "source": { "type": [ "string", "null" ], "description": "Where the request came in from, e.g. `in-app`, `email`, `forms`." }, "issue": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Customer": { "type": "object", "title": "Customer", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "domain": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ], "format": "uri" }, "employees": { "type": [ "integer", "null" ] }, "stage": { "type": [ "string", "null" ] }, "contract_status": { "type": [ "string", "null" ] }, "revenue": { "type": [ "string", "null" ] }, "description_html": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Member": { "type": "object", "title": "Workspace member", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "member": { "type": "object", "description": "The user record for this membership.", "additionalProperties": true }, "display_name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "role_slug": { "type": "string", "description": "Role within the namespace, e.g. `admin`, `member`, `guest`." }, "is_active": { "type": "boolean" }, "is_bot": { "type": "boolean" } } }, "WorkItemActivity": { "type": "object", "title": "Work item activity", "description": "One entry in a work item's change history.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "field": { "type": [ "string", "null" ], "description": "Which field changed, e.g. `state`, `priority`, `assignees`." }, "verb": { "type": "string", "description": "What happened, e.g. `created`, `updated`." }, "old_value": { "type": [ "string", "null" ] }, "new_value": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ], "description": "Human-readable summary of the change." }, "actor": { "type": "string", "format": "uuid" }, "issue": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "WorkItemLink": { "type": "object", "title": "Work item link", "description": "An external URL attached to a work item.", "required": [ "id", "url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "title": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": true }, "issue": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkItemAttachment": { "type": "object", "title": "Work item attachment", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "asset": { "type": "string", "description": "Storage key for the uploaded file." }, "attributes": { "type": "object", "description": "File metadata.", "properties": { "name": { "type": "string" }, "size": { "type": "integer" }, "type": { "type": "string" } } }, "issue_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "WorkItemAttachmentUpload": { "type": "object", "title": "Attachment upload credentials", "description": "Presigned target to POST the file to, followed by a completion call.", "properties": { "upload_data": { "type": "object", "description": "Presigned URL and the form fields to send with the file.", "properties": { "url": { "type": "string", "format": "uri" }, "fields": { "type": "object", "additionalProperties": true } } }, "asset_id": { "type": "string", "format": "uuid" }, "asset_url": { "type": "string" } } }, "WorkItemRelation": { "type": "object", "title": "Work item relation", "description": "A typed link between two work items, such as blocking or duplicate.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "relation_type": { "type": "string", "description": "Relation kind. Workspaces can also define custom relation types.", "examples": [ "blocked_by", "blocks", "duplicate", "relates_to" ] }, "issue": { "type": "string", "format": "uuid" }, "related_issue": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "WorkItemType": { "type": "object", "title": "Work item type", "description": "A type that gives work items their own icon and custom properties.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "logo_props": { "type": "object", "additionalProperties": true }, "is_active": { "type": "boolean" }, "is_epic": { "type": "boolean" }, "is_default": { "type": "boolean" }, "level": { "type": "integer" }, "project_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkItemPropertyValue": { "type": "object", "title": "Custom property value", "description": "The value of one custom property on one work item.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "property": { "type": "string", "format": "uuid" }, "value": { "description": "Shape depends on the property type — text, number, date, boolean, or option id." }, "value_text": { "type": [ "string", "null" ] }, "value_option": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Estimate": { "type": "object", "title": "Estimate", "description": "A project's estimation system.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "points", "categories", "time" ] }, "last_used": { "type": "boolean" }, "project": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "EstimatePoint": { "type": "object", "title": "Estimate point", "description": "One selectable value in an estimate system.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "integer" }, "value": { "type": "string" }, "estimate": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "CustomerRequest": { "type": "object", "title": "Customer request", "description": "Something a customer asked for, linkable to the work items that deliver it.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description_html": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ], "format": "uri" }, "customer_id": { "type": "string", "format": "uuid" }, "work_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Teamspace": { "type": "object", "title": "Teamspace", "description": "A group of members and projects that share a space.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description_html": { "type": [ "string", "null" ] }, "lead_id": { "type": [ "string", "null" ], "format": "uuid" }, "member_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "project_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "logo_props": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CurrentUser": { "type": "object", "title": "Current user", "description": "The user or bot the credential authenticates as.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": [ "string", "null" ], "format": "email" }, "display_name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "is_bot": { "type": "boolean" }, "last_workspace_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "Release": { "type": "object", "title": "Release", "description": "A release in the workspace, with its tags, labels, and changelog.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description_html": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "released_at": { "type": [ "string", "null" ], "format": "date-time" }, "changelog": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AgentRunActivity": { "type": "object", "title": "Agent run activity", "description": "One unit of communication inside an Agent Run. Thoughts and actions are ephemeral; a response becomes a visible comment.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "prompt", "thought", "action", "response", "elicitation", "error" ] }, "content": { "type": "object", "additionalProperties": true }, "signal": { "type": [ "string", "null" ], "enum": [ "continue", "complete", "failed", null ] }, "agent_run": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "WorkItemCountBreakdown": { "type": "object", "title": "Work item count breakdown", "description": "Aggregated work item counts, optionally grouped and sub-grouped. The closest thing Plane exposes programmatically to a dashboard figure.", "properties": { "count": { "type": "integer", "description": "Total matching work items." }, "group_by": { "type": [ "string", "null" ] }, "sub_group_by": { "type": [ "string", "null" ] }, "groups": { "type": "array", "description": "One entry per group when `group_by` is set.", "items": { "type": "object", "properties": { "key": { "type": [ "string", "null" ], "description": "The grouping value, e.g. a state id or a priority." }, "count": { "type": "integer" }, "sub_groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": [ "string", "null" ] }, "count": { "type": "integer" } } } } } } } } }, "WorkLogTotal": { "type": "object", "title": "Work log total", "description": "Total time logged against one work item, in minutes.", "properties": { "issue_id": { "type": "string", "format": "uuid" }, "duration": { "type": "integer", "description": "Total minutes logged." } } }, "ProjectFeatures": { "type": "object", "title": "Project features", "description": "Which feature modules are enabled on a project. Read this before calling a capability that depends on one.", "properties": { "epics": { "type": "boolean" }, "modules": { "type": "boolean" }, "cycles": { "type": "boolean" }, "views": { "type": "boolean" }, "pages": { "type": "boolean" }, "intakes": { "type": "boolean" }, "work_item_types": { "type": "boolean" } } }, "WorkspaceFeatures": { "type": "object", "title": "Workspace features", "description": "Which workspace-level features are enabled, including Plane AI (`pi`).", "properties": { "project_grouping": { "type": "boolean" }, "initiatives": { "type": "boolean" }, "teams": { "type": "boolean", "description": "Teamspaces." }, "customers": { "type": "boolean" }, "wiki": { "type": "boolean" }, "pi": { "type": "boolean", "description": "Plane AI." } } }, "IdpGroupMapping": { "type": "object", "title": "Identity provider group mapping", "description": "Maps a group from your identity provider to a Plane role, at workspace or project scope.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "idp_group_name": { "type": "string", "description": "Group name as it appears in the identity provider." }, "role": { "type": "string", "description": "Plane role granted to members of that group." }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Set on project mappings only." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "title": "Error", "description": "An error. Read `error` or `detail`, whichever is present, for the message; `error_code` is the stable machine-readable code where the endpoint sets one.", "properties": { "error": { "type": "string", "description": "Human-readable message. Set on request, throttling, and not-found failures." }, "error_code": { "type": "string", "description": "Stable code for programmatic handling, where the endpoint sets one." }, "detail": { "type": "string", "description": "Human-readable message. Set on authentication and permission failures." } } } } }