Back to Details

plane-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Plane API Integration

Plane API 集成

This skill enables interaction with a self-hosted Plane.so instance using the 
plane.py
CLI tool.
此技能支持使用
plane.py
CLI工具与自托管的Plane.so实例进行交互。

Setup

配置

The user must set these environment variables:
bash
export PLANE_API_URL="https://plane.example.com"
export PLANE_API_KEY="plane_api_..."
export PLANE_WORKSPACE_SLUG="my-team"  # Optional, can pass --workspace instead
用户必须设置以下环境变量：
bash
export PLANE_API_URL="https://plane.example.com"
export PLANE_API_KEY="plane_api_..."
export PLANE_WORKSPACE_SLUG="my-team"  # 可选，可通过--workspace参数替代

Using the CLI Tool

使用CLI工具

All operations use 
plane.py
located at 
~/.skills/plane-api/plane.py
.
所有操作均使用位于
~/.skills/plane-api/plane.py
的
plane.py
。

Check API Compatibility

检查API兼容性

First, verify the Plane instance supports the v1 API (requires Plane v0.20+):
bash
python ~/.skills/plane-api/plane.py check-version
首先，验证Plane实例是否支持v1 API（需要Plane v0.20及以上版本）：
bash
python ~/.skills/plane-api/plane.py check-version

List Projects

列出项目

bash
python ~/.skills/plane-api/plane.py projects
python ~/.skills/plane-api/plane.py projects --workspace other-team
bash
python ~/.skills/plane-api/plane.py projects
python ~/.skills/plane-api/plane.py projects --workspace other-team

List Work Items (Issues)

列出工作项（议题）

bash
python ~/.skills/plane-api/plane.py work-items <project_id>
bash
python ~/.skills/plane-api/plane.py work-items <project_id>

Create Work Item

创建工作项

bash
python ~/.skills/plane-api/plane.py create-work-item <project_id> "Issue title"
python ~/.skills/plane-api/plane.py create-work-item <project_id> "Bug fix" --priority high
python ~/.skills/plane-api/plane.py create-work-item <project_id> "Feature" --priority medium --state-id <uuid> --description "Details here"
Priority values: 
urgent
, 
high
, 
medium
, 
low
, 
none
bash
python ~/.skills/plane-api/plane.py create-work-item <project_id> "Issue title"
python ~/.skills/plane-api/plane.py create-work-item <project_id> "Bug fix" --priority high
python ~/.skills/plane-api/plane.py create-work-item <project_id> "Feature" --priority medium --state-id <uuid> --description "Details here"
优先级取值：
urgent
、
high
、
medium
、
low
、
none

List States

列出状态

Get available states to use when creating work items:
bash
python ~/.skills/plane-api/plane.py states <project_id>
获取创建工作项时可用的状态：
bash
python ~/.skills/plane-api/plane.py states <project_id>

List Cycles

列出周期

bash
python ~/.skills/plane-api/plane.py cycles <project_id>
bash
python ~/.skills/plane-api/plane.py cycles <project_id>

List Modules

列出模块

bash
python ~/.skills/plane-api/plane.py modules <project_id>
bash
python ~/.skills/plane-api/plane.py modules <project_id>

Typical Workflow

典型工作流

  1. Run 
    check-version
    to verify API access
  2. Run 
    projects
    to get project IDs
  3. Run 
    states <project_id>
    to get state UUIDs
  4. Run 
    create-work-item
    with the appropriate state and priority
  1. 运行
    check-version
    验证API访问权限
  2. 运行
    projects
    获取项目ID
  3. 运行
    states <project_id>
    获取状态UUID
  4. 使用合适的状态和优先级运行
    create-work-item

API Reference

API参考

For operations not covered by the CLI (like adding items to cycles/modules, creating labels, bulk operations), use curl directly:
bash
curl -H "X-API-Key: $PLANE_API_KEY" \
     -H "Content-Type: application/json" \
     "$PLANE_API_URL/api/v1/workspaces/$PLANE_WORKSPACE_SLUG/..."
Key endpoints:
  • GET /api/v1/workspaces/{slug}/projects/
    - List projects
  • GET /api/v1/workspaces/{slug}/projects/{id}/work-items/
    - List work items
  • POST /api/v1/workspaces/{slug}/projects/{id}/work-items/
    - Create work item
  • GET /api/v1/workspaces/{slug}/projects/{id}/states/
    - List states
  • GET /api/v1/workspaces/{slug}/projects/{id}/cycles/
    - List cycles
  • POST /api/v1/workspaces/{slug}/projects/{id}/cycles/{id}/work-items/
    - Add to cycle
  • GET /api/v1/workspaces/{slug}/projects/{id}/modules/
    - List modules
  • GET /api/v1/workspaces/{slug}/projects/{id}/labels/
    - List labels
Rate limit: 60 requests/minute per API key.
对于CLI未覆盖的操作（如将项添加到周期/模块、创建标签、批量操作），可直接使用curl：
bash
curl -H "X-API-Key: $PLANE_API_KEY" \
     -H "Content-Type: application/json" \
     "$PLANE_API_URL/api/v1/workspaces/$PLANE_WORKSPACE_SLUG/..."
核心端点：
  • GET /api/v1/workspaces/{slug}/projects/
    - 列出项目
  • GET /api/v1/workspaces/{slug}/projects/{id}/work-items/
    - 列出工作项
  • POST /api/v1/workspaces/{slug}/projects/{id}/work-items/
    - 创建工作项
  • GET /api/v1/workspaces/{slug}/projects/{id}/states/
    - 列出状态
  • GET /api/v1/workspaces/{slug}/projects/{id}/cycles/
    - 列出周期
  • POST /api/v1/workspaces/{slug}/projects/{id}/cycles/{id}/work-items/
    - 添加到周期
  • GET /api/v1/workspaces/{slug}/projects/{id}/modules/
    - 列出模块
  • GET /api/v1/workspaces/{slug}/projects/{id}/labels/
    - 列出标签
速率限制：每个API密钥每分钟最多60次请求。