开发者

使用 Planitude 构建

REST API、签名 Webhook 和 MCP 服务器:让你的系统与计划保持同步,响应每一次变更,并让 AI 助手处理你的项目。

与大多数 API 文档一样,代码、字段名和技术参考均为英文。

基础 URL: https://planitude.app

请求和响应均为 HTTPS 上的 JSON。工期和延迟以工作分钟计(8 小时工作日为 480),时间点为 UTC 的 ISO 8601,不含时间的日期为 YYYY-MM-DD。

请求
curl https://planitude.app/api/auth/me \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "user": {
    "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "email": "anna@example.com",
    "name": "Anna Rossi",
    "avatarUrl": null,
    "locale": "en",
    "emailVerified": true
  }
}

快速开始

三步完成第一个 Webhook,只需要一个终端。

  1. 创建 API 密钥

    打开个人资料 → API 密钥,选择读写并复制密钥:它以 pln_ 开头,只显示一次。请将它保存在环境变量中。

  2. 发起第一次调用

    列出你能看到的项目。密钥以你的身份操作:相同的项目,相同的角色。

  3. 接收 Webhook

    为公开的 HTTPS 端点订阅所需事件,立即发送一个测试事件并验证其签名。

1Terminal
export PLANITUDE_API_KEY="pln_…"
2
curl https://planitude.app/api/projects \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
预期结果200 OK
{
  "projects": [
    {
      "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
      "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
      "key": "WHX",
      "keyLocked": false,
      "name": "Warehouse expansion",
      "description": null,
      "startDate": "2026-10-05",
      "calendarId": null,
      "currency": "EUR",
      "scheduleFrom": "forward",
      "deadline": null,
      "color": null,
      "settings": {},
      "archivedAt": null,
      "createdBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "createdAt": "2026-10-01T08:30:12.418Z",
      "updatedAt": "2026-10-01T08:30:12.418Z",
      "workspaceName": "Acme Construction",
      "role": "owner",
      "taskCount": 12,
      "finishAt": "2026-10-07T15:00:00.000Z"
    }
  ]
}
3
curl -X POST https://planitude.app/api/webhooks \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/planitude",
  "events": [
    "task.created",
    "task.completed"
  ],
  "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8"
}'
示例载荷webhook.ping
{
  "id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
  "type": "webhook.ping",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-01T08:30:12.418Z",
  "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
  "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
  "actor": {
    "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "name": "Anna Rossi"
  },
  "data": {
    "message": "Planitude webhook test",
    "webhook": {
      "id": "1747ee7f-a395-4d3c-94b0-54b513d71d88",
      "name": "Warehouse sync",
      "events": [
        "task.created",
        "task.completed"
      ]
    }
  }
}

身份验证

在 Authorization 请求头中以 Bearer 令牌的形式携带个人 API 密钥来验证每个请求。密钥属于个人:它以你的身份、按你在每个项目中的角色操作,绝不会更多。你可以将密钥限制在一个工作区、设置有效期并随时撤销;每次调用都会记录在密钥旁。

范围

范围允许
readplanitude:read读取项目、任务、依赖、成员、评论、基准和 Webhook。
writeplanitude:write读取的全部权限,外加创建和修改项目、任务、依赖、评论、基准和 Webhook。

密钥和 OAuth 应用不能删除项目或任务:删除只能在 Web 应用中由人确认。指向错误 ID 的脚本无法清除计划。

面向第三方应用的 OAuth 2.1

代表他人操作的应用使用 OAuth 2.1:带 PKCE(S256)的授权码、每次使用都会轮换的刷新令牌、动态客户端注册(RFC 7591)。请求资源 https://planitude.app/api 以及范围 planitude:read 或 planitude:write。

端点发布在标准的发现文档中,OAuth 库可以自动完成配置。

  • https://planitude.app/.well-known/oauth-authorization-server
  • https://planitude.app/.well-known/oauth-protected-resource

最佳实践

  • 将密钥保存在环境变量或密钥管理器中,切勿放在代码或代码仓库里。密钥以 pln_ 开头,便于密钥扫描工具识别。
  • 只读取时使用只读密钥,每个集成使用单独的密钥:撤销一个不会影响其他。
  • 为脚本使用的密钥设置有效期并定期轮换。
  • 从你的服务器调用 API,而不是从浏览器:前端代码中的密钥就是公开的密钥。
Bearercurl
curl https://planitude.app/api/projects \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
OAuth 2.1/.well-known/oauth-authorization-server
{
  "issuer": "https://planitude.app",
  "authorization_endpoint": "https://planitude.app/oauth/authorize",
  "token_endpoint": "https://planitude.app/api/oauth/token",
  "registration_endpoint": "https://planitude.app/api/oauth/register",
  "revocation_endpoint": "https://planitude.app/api/oauth/revoke",
  "scopes_supported": [
    "planitude:read",
    "planitude:write"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ]
}

错误

Planitude 使用标准 HTTP 状态码。错误始终是相同的 JSON 结构:一个可用于判断的稳定 error 代码,必要时还有包含原因或待修正字段的 details。

状态含义
400invalid_request请求无效:details.fields 列出每个字段及其问题。
401unauthorized密钥缺失、无效、已撤销或已过期。
403forbidden密钥或你的角色不允许此操作(details.reason),例如用只读密钥写入,或执行删除。
404not_found未找到,或你无权查看。
409dependency_cycle与计划冲突,例如会形成循环的依赖(dependency_cycle)。
429rate_limited请求过多:请等待 Retry-After 中的秒数。
500server_error我们这边出错了:请使用指数退避重试。

Error

字段类型说明
error
必填
stringStable error code: invalid_request, unauthorized, forbidden, not_found, conflict, dependency_cycle, limit_exceeded, rate_limited, server_error, ...
detailsobject
响应
{
  "error": "invalid_request",
  "details": {
    "fields": [
      {
        "path": "name",
        "message": "Invalid input: expected string, received undefined"
      },
      {
        "path": "durationMin",
        "message": "Too small: expected number to be >=0"
      }
    ]
  }
}

速率限制

限制按密钥计算,采用一分钟的滑动窗口:240 次读取请求和 60 次写入请求。超出后会收到 429 rate_limited 以及以秒为单位的 Retry-After 请求头。

重试前等待 Retry-After,将批量操作分散进行,并把多项修改合并为一个变更集:一次请求、一次重新计算最多可包含 1,000 项修改。

响应HTTP
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "details": {
    "retryAfterSec": 12
  }
}

分页与搜索

任务列表使用游标分页。传入 limit(1–500,默认 100),获取下一页时将上一次响应的 nextCursor 作为 cursor 传入。当 nextCursor 为 null 时表示没有更多页。

可用 externalId(与你自己的 ID 精确匹配)、q(名称包含)、updatedSince 和 completed 筛选;用 sort=-number(最新优先)或 -updatedAt 排序。项目、成员和依赖等较短的列表会在一次响应中完整返回。

请求
curl "https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks?limit=500" \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"

# next page: pass the nextCursor of the previous response
curl "https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks?limit=500&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"

版本

API 和 Webhook 载荷按日期进行版本管理。当前版本为 2026-10-01:即每个事件的 apiVersion 字段和 OpenAPI 文档的 info.version。

同一版本内我们只做新增:新端点、新的可选字段、新的事件类型。没有新版本时,字段绝不会被删除或更改类型,因此请忽略你不认识的字段。

请求
curl https://planitude.app/api/webhooks/events
响应200 OK
{
  "apiVersion": "2026-10-01",
  "events": [
    "project.created",
    "project.updated",
    "project.deleted",
    "task.created",
    "task.updated",
    "task.deleted",
    "task.completed",
    "task.dates_changed",
    "dependency.created",
    "dependency.deleted",
    "baseline.saved",
    "member.invited",
    "member.joined",
    "comment.created"
  ]
}

API 参考

Account

Who is calling, and their workspaces.

User

属性

字段类型说明
idstring (uuid)
emailstring (email)
namestring可为 null
avatarUrlstring可为 null
localestring
emailVerifiedboolean
对象User
{
  "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
  "email": "anna@example.com",
  "name": "Anna Rossi",
  "avatarUrl": null,
  "locale": "en",
  "emailVerified": true
}

Workspace

属性

字段类型说明
idstring (uuid)
namestring
rolestring

取值之一: owner, admin, member

对象Workspace
{
  "id": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
  "name": "Acme Construction",
  "role": "owner"
}

Current user (connection test)

GET/api/auth/me

具有读取权限的密钥

返回

200 OK The user

字段类型说明
userUser
请求
curl https://planitude.app/api/auth/me \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "user": {
    "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "email": "anna@example.com",
    "name": "Anna Rossi",
    "avatarUrl": null,
    "locale": "en",
    "emailVerified": true
  }
}

Workspaces of the user, with role

GET/api/workspaces

具有读取权限的密钥

返回

200 OK Workspaces

字段类型说明
workspacesarray of Workspace
请求
curl https://planitude.app/api/workspaces \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "workspaces": [
    {
      "id": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
      "name": "Acme Construction",
      "role": "owner"
    }
  ]
}

API 参考

Projects

Projects, templates and baselines.

Project

A project as returned by the write endpoints and project listings.

属性

字段类型说明
idstring (uuid)
workspaceIdstring (uuid)
keystringProject key, e.g. CRON (task keys are CRON-12).
keyLockedboolean
namestring
descriptionstring可为 null
startDatestring (date)
calendarIdstring (uuid)可为 null
currencystring
scheduleFromstring

取值之一: forward, backward

deadlinestring (date)可为 null
colorstring可为 null
settingsobject
archivedAtstring (date-time)可为 null
createdBystring (uuid)可为 null
createdAtstring (date-time)
updatedAtstring (date-time)
对象Project
{
  "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
  "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
  "key": "WHX",
  "keyLocked": false,
  "name": "Warehouse expansion",
  "description": null,
  "startDate": "2026-10-05",
  "calendarId": null,
  "currency": "EUR",
  "scheduleFrom": "forward",
  "deadline": null,
  "color": null,
  "settings": {},
  "archivedAt": null,
  "createdBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
  "createdAt": "2026-10-01T08:30:12.418Z",
  "updatedAt": "2026-10-01T08:30:12.418Z"
}

Template

属性

字段类型说明
idstringbuiltin:<slug> or the id of a template saved by you.
kindstring

取值之一: builtin, user

namestring
descriptionstring可为 null
taskCountinteger
durationDaysintegerWorking days from start to finish.
对象Template
{
  "id": "builtin:website-launch",
  "kind": "builtin",
  "name": "Website launch",
  "description": "From discovery to go-live: design, content, development, testing and launch.",
  "taskCount": 12,
  "durationDays": 43
}

Baseline

属性

字段类型说明
idstring (uuid)
namestring
indexinteger可为 nullNumbered MS Project baseline (1-10); null for the main baseline and the ones you name.
capturedAtstring (date-time)
capturedBystring (uuid)可为 null
taskCountinteger
对象Baseline
{
  "id": "b5d68d05-0640-48f9-8eeb-ed7804f4a116",
  "name": "Plan v1",
  "index": null,
  "capturedAt": "2026-10-01T08:30:12.418Z",
  "capturedBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
  "taskCount": 12
}

List projects

GET/api/projects

具有读取权限的密钥

All projects visible to the user (not paginated). ?archived=1 includes archived ones.

查询参数

字段类型说明
archivedstring

取值之一: 1

返回

200 OK Projects

字段类型说明
projectsarray of Project
请求
curl https://planitude.app/api/projects \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "projects": [
    {
      "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
      "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
      "key": "WHX",
      "keyLocked": false,
      "name": "Warehouse expansion",
      "description": null,
      "startDate": "2026-10-05",
      "calendarId": null,
      "currency": "EUR",
      "scheduleFrom": "forward",
      "deadline": null,
      "color": null,
      "settings": {},
      "archivedAt": null,
      "createdBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "createdAt": "2026-10-01T08:30:12.418Z",
      "updatedAt": "2026-10-01T08:30:12.418Z",
      "workspaceName": "Acme Construction",
      "role": "owner",
      "taskCount": 12,
      "finishAt": "2026-10-07T15:00:00.000Z"
    }
  ]
}

Create a project

POST/api/projects

具有写入权限的密钥

请求体

字段类型说明
name
必填
string
workspaceIdstring (uuid)Defaults to your personal workspace.
keystring2-5 letters/digits, starts with a letter. Derived from the name if omitted.
descriptionstring可为 null
startDatestring (date)
deadlinestring (date)可为 null
currencystring
scheduleFromstring

取值之一: forward, backward

colorstring可为 null

返回

201 Created Created

字段类型说明
projectProject
请求
curl -X POST https://planitude.app/api/projects \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Warehouse expansion","startDate":"2026-10-05","currency":"EUR"}'
响应201 Created
{
  "project": {
    "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "key": "WHX",
    "keyLocked": false,
    "name": "Warehouse expansion",
    "description": null,
    "startDate": "2026-10-05",
    "calendarId": null,
    "currency": "EUR",
    "scheduleFrom": "forward",
    "deadline": null,
    "color": null,
    "settings": {},
    "archivedAt": null,
    "createdBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z"
  }
}

Create a project from a template

POST/api/projects/from-template

具有写入权限的密钥

请求体

字段类型说明
templateId
必填
stringId from GET /api/templates.
startDate
必填
string (date)
namestring
keystring
localestringLanguage of the template texts (en, it, es, fr, de, pt, nl, pl, ja, zh, sv, da, no, fi, cs, ro, uk, tr, ar, he, hi, id, vi, ko).
tzstringIANA time zone of the project calendar.
workspaceIdstring (uuid)

返回

201 Created Created

字段类型说明
projectProject
taskCountinteger
conflictsarray of Conflict
请求
curl -X POST https://planitude.app/api/projects/from-template \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "templateId": "builtin:website-launch",
  "startDate": "2026-10-05",
  "name": "Website relaunch",
  "locale": "en"
}'
响应201 Created
{
  "project": {
    "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "key": "WHX",
    "keyLocked": false,
    "name": "Warehouse expansion",
    "description": null,
    "startDate": "2026-10-05",
    "calendarId": null,
    "currency": "EUR",
    "scheduleFrom": "forward",
    "deadline": null,
    "color": null,
    "settings": {},
    "archivedAt": null,
    "createdBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z"
  },
  "taskCount": 12,
  "conflicts": []
}

List project templates

GET/api/templates

具有读取权限的密钥

查询参数

字段类型说明
localestring

返回

200 OK Templates

字段类型说明
templatesarray of Template
请求
curl https://planitude.app/api/templates \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "templates": [
    {
      "id": "builtin:website-launch",
      "kind": "builtin",
      "name": "Website launch",
      "description": "From discovery to go-live: design, content, development, testing and launch.",
      "taskCount": 12,
      "durationDays": 43
    }
  ]
}

Full project (tasks tree, dependencies, resources, members, baselines)

GET/api/projects/{projectId}

具有读取权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.

返回

200 OK Project

字段类型说明
projectProject
tasksarray of Task
dependenciesarray of Dependency
请求
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8 \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "project": {
    "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "key": "WHX",
    "keyLocked": false,
    "name": "Warehouse expansion",
    "description": null,
    "startDate": "2026-10-05",
    "calendarId": null,
    "currency": "EUR",
    "scheduleFrom": "forward",
    "deadline": null,
    "color": null,
    "settings": {},
    "archivedAt": null,
    "createdBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z"
  },
  "tasks": [
    {
      "id": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "number": 1,
      "key": "WHX-1",
      "parentId": null,
      "sortKey": "i",
      "name": "Foundations",
      "type": "task",
      "durationMin": 1440,
      "workMin": 0,
      "progressPct": 0,
      "constraintKind": "asap",
      "constraintDate": null,
      "deadline": null,
      "calendarId": null,
      "costFixed": 0,
      "notes": null,
      "color": null,
      "wbs": null,
      "externalId": "crm-4711",
      "startAt": "2026-10-05T06:00:00.000Z",
      "finishAt": "2026-10-07T15:00:00.000Z",
      "isCritical": true,
      "totalFloatMin": 0,
      "earlyStartAt": "2026-10-05T06:00:00.000Z",
      "lateFinishAt": "2026-10-07T15:00:00.000Z",
      "actualStartAt": null,
      "actualFinishAt": null,
      "actualDurationMin": null,
      "remainingDurationMin": null,
      "manuallyScheduled": false,
      "levelingDelayMin": 0,
      "taskType": "fixed_units",
      "effortDriven": false,
      "durationOptimisticMin": null,
      "durationPessimisticMin": null
    }
  ],
  "dependencies": [
    {
      "id": "9ba5faf8-923d-4ecc-86f0-f245c5d179db",
      "predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
      "type": "FS",
      "lagMin": 0
    }
  ]
}

Update a project

PATCH/api/projects/{projectId}

具有写入权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.

请求体

字段类型说明
namestring
descriptionstring可为 null
startDatestring (date)
deadlinestring (date)可为 null
currencystring
scheduleFromstring

取值之一: forward, backward

colorstring可为 null
archivedboolean

返回

200 OK Updated

字段类型说明
projectProject
conflictsarray of Conflict
rescheduledbooleanThe schedule was recalculated (start date, calendar or direction changed).
请求
curl -X PATCH https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8 \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deadline":"2026-12-18"}'
响应200 OK
{
  "project": {
    "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "key": "WHX",
    "keyLocked": false,
    "name": "Warehouse expansion",
    "description": null,
    "startDate": "2026-10-05",
    "calendarId": null,
    "currency": "EUR",
    "scheduleFrom": "forward",
    "deadline": null,
    "color": null,
    "settings": {},
    "archivedAt": null,
    "createdBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z"
  },
  "conflicts": [],
  "rescheduled": false
}

Export the plan as a file (Microsoft Project XML, CSV, PNG or PDF)

GET/api/projects/{projectId}/export

具有读取权限的密钥

Returns the file itself (Content-Disposition: attachment), not JSON. Any role with access to the project, read-only included. png and pdf draw the Gantt chart on the server (title, generation date, legend; in the PDF repeated on every page) and accept the image options below; at most 20 image exports per user every 10 minutes. Over the size limits: 413 limit_exceeded with details.reason (tasks, image_too_large, pages, timeline).

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.

查询参数

字段类型说明
formatstringFile format. mspdi = Microsoft Project XML.

取值之一: mspdi, csv, png, pdf

默认值: mspdi

localestringLanguage of headings, legend and dates (e.g. en, it, ar, ja).

默认值: en

scalestringPNG/PDF: time unit of the columns.

取值之一: auto, day, week, month, quarter

默认值: auto

fromstring (date)PNG/PDF: first day to draw (with to). Default: the whole project.
tostring (date)PNG/PDF: last day to draw (with from).
criticalstringPNG/PDF: highlight the critical path.

取值之一: 0, 1

默认值: 1

baselinestringPNG/PDF: draw the main baseline under each bar.

取值之一: 0, 1

默认值: 1

linksstringPNG/PDF: draw dependency arrows.

取值之一: 0, 1

默认值: 1

paperstringPDF: paper size.

取值之一: a4, a3, letter

默认值: a4

orientationstringPDF: page orientation.

取值之一: landscape, portrait

默认值: landscape

返回

200 OK The file: `application/xml`, `text/csv`, `image/png` or `application/pdf`.

请求
curl "https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/export?format=pdf&locale=en&paper=a4" \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -o plan.pdf

List baselines

GET/api/projects/{projectId}/baseline

具有读取权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.

返回

200 OK Baselines

字段类型说明
baselinesarray of Baseline
请求
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/baseline \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "baselines": [
    {
      "id": "b5d68d05-0640-48f9-8eeb-ed7804f4a116",
      "name": "Plan v1",
      "index": null,
      "capturedAt": "2026-10-01T08:30:12.418Z",
      "capturedBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "taskCount": 12
    }
  ]
}

Save a baseline

POST/api/projects/{projectId}/baseline

具有写入权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.

请求体

字段类型说明
namestring

返回

201 Created Saved

字段类型说明
baselineBaseline
请求
curl -X POST https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/baseline \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Plan v1"}'
响应201 Created
{
  "baseline": {
    "id": "b5d68d05-0640-48f9-8eeb-ed7804f4a116",
    "name": "Plan v1",
    "index": null,
    "capturedAt": "2026-10-01T08:30:12.418Z",
    "capturedBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "taskCount": 12
  }
}

API 参考

Tasks

Tasks, search by external id, comments.

Task

Task representation of GET /tasks and webhook payloads: the stored task (without sortKey) plus project, assignees and link.

属性

字段类型说明
idstring (uuid)
numberintegerSequential number in the project, never reused.
keystringHuman key, e.g. CRON-12.
parentIdstring (uuid)可为 null
namestring
typestring

取值之一: summary, task, milestone

durationMinintegerDuration in working minutes (8h day = 480).
workMininteger
progressPctnumber
constraintKindstring

取值之一: asap, alap, start_no_earlier_than, start_no_later_than, finish_no_earlier_than, finish_no_later_than, must_start_on, must_finish_on

constraintDatestring (date-time)可为 null
deadlinestring (date-time)可为 null
calendarIdstring (uuid)可为 null
costFixednumber
notesstring可为 null
colorstring可为 null
wbsstring可为 null
externalIdstring可为 nullYour identifier for this task in another system. Searchable with GET /tasks?externalId=.
startAtstring (date-time)可为 nullComputed start.
finishAtstring (date-time)可为 nullComputed finish.
isCriticalbooleanOn the critical path.
totalFloatMininteger可为 nullTotal float (slack) in working minutes.
earlyStartAtstring (date-time)可为 null
lateFinishAtstring (date-time)可为 null
actualStartAtstring (date-time)可为 null
actualFinishAtstring (date-time)可为 null
actualDurationMininteger可为 null
remainingDurationMininteger可为 null
manuallyScheduledboolean
levelingDelayMininteger
taskTypestring

取值之一: fixed_units, fixed_duration, fixed_work, fixed_duration_and_units

effortDrivenboolean
durationOptimisticMininteger可为 null
durationPessimisticMininteger可为 null
projectIdstring (uuid)
completedbooleanprogressPct = 100.
assigneesarray of Assignee
urlstring (uri)Page of the task in the web app.
对象Task
{
  "id": "4dbd104a-00cd-4035-8955-255f52ea586a",
  "number": 1,
  "key": "WHX-1",
  "parentId": null,
  "name": "Foundations",
  "type": "task",
  "durationMin": 1440,
  "workMin": 0,
  "progressPct": 0,
  "constraintKind": "asap",
  "constraintDate": null,
  "deadline": null,
  "calendarId": null,
  "costFixed": 0,
  "notes": null,
  "color": null,
  "wbs": null,
  "externalId": "crm-4711",
  "startAt": "2026-10-05T06:00:00.000Z",
  "finishAt": "2026-10-07T15:00:00.000Z",
  "isCritical": true,
  "totalFloatMin": 0,
  "earlyStartAt": "2026-10-05T06:00:00.000Z",
  "lateFinishAt": "2026-10-07T15:00:00.000Z",
  "actualStartAt": null,
  "actualFinishAt": null,
  "actualDurationMin": null,
  "remainingDurationMin": null,
  "manuallyScheduled": false,
  "levelingDelayMin": 0,
  "taskType": "fixed_units",
  "effortDriven": false,
  "durationOptimisticMin": null,
  "durationPessimisticMin": null,
  "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
  "completed": false,
  "assignees": [
    {
      "resourceId": "0c6a8f52-3d7e-4b19-9a4e-6f1d2c8b7e30",
      "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi",
      "unitsPct": 100
    }
  ],
  "url": "https://planitude.app/app/t/WHX-1"
}

WriteResult

属性

字段类型说明
tasksarray of TaskCreated/updated tasks plus the ones the recalculation moved.
deletedTaskIdsarray of string
dependenciesarray of Dependency
deletedDependencyIdsarray of string
conflictsarray of Conflict
projectStartAtstring (date-time)
projectFinishAtstring (date-time)
statsobject
显示 stats 的字段
字段类型说明
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
对象WriteResult
{
  "tasks": [
    {
      "id": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "number": 1,
      "key": "WHX-1",
      "parentId": null,
      "sortKey": "i",
      "name": "Foundations",
      "type": "task",
      "durationMin": 1440,
      "workMin": 0,
      "progressPct": 0,
      "constraintKind": "asap",
      "constraintDate": null,
      "deadline": null,
      "calendarId": null,
      "costFixed": 0,
      "notes": null,
      "color": null,
      "wbs": null,
      "externalId": "crm-4711",
      "startAt": "2026-10-05T06:00:00.000Z",
      "finishAt": "2026-10-07T15:00:00.000Z",
      "isCritical": true,
      "totalFloatMin": 0,
      "earlyStartAt": "2026-10-05T06:00:00.000Z",
      "lateFinishAt": "2026-10-07T15:00:00.000Z",
      "actualStartAt": null,
      "actualFinishAt": null,
      "actualDurationMin": null,
      "remainingDurationMin": null,
      "manuallyScheduled": false,
      "levelingDelayMin": 0,
      "taskType": "fixed_units",
      "effortDriven": false,
      "durationOptimisticMin": null,
      "durationPessimisticMin": null
    }
  ],
  "deletedTaskIds": [],
  "dependencies": [
    {
      "id": "9ba5faf8-923d-4ecc-86f0-f245c5d179db",
      "predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
      "type": "FS",
      "lagMin": 0
    }
  ],
  "deletedDependencyIds": [],
  "conflicts": [],
  "projectStartAt": "2026-10-05T06:00:00.000Z",
  "projectFinishAt": "2026-10-07T15:00:00.000Z",
  "stats": {
    "taskCount": 12,
    "recomputedCount": 3,
    "savedCount": 2,
    "durationMs": 39
  }
}

Comment

属性

字段类型说明
idstring (uuid)
taskIdstring (uuid)
userIdstring (uuid)
authorNamestring
authorAvatarUrlstring可为 null
bodystring
mentionsarray of string
createdAtstring (date-time)
editedAtstring (date-time)可为 null
对象Comment
{
  "id": "0fc2dec5-a409-47c9-9c6e-0663e8f8bcf3",
  "taskId": "4dbd104a-00cd-4035-8955-255f52ea586a",
  "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
  "authorName": "Anna Rossi",
  "authorAvatarUrl": null,
  "body": "Concrete delivered, we can start the walls.",
  "mentions": [],
  "createdAt": "2026-10-01T08:30:12.418Z",
  "editedAt": null
}

List or search tasks (paginated)

GET/api/projects/{projectId}/tasks

具有读取权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.

查询参数

字段类型说明
limitinteger1-500.

默认值: 100

cursorstringnextCursor of the previous page.
sortstring-number = newest first (polling triggers). -updatedAt returns the first page only.

取值之一: number, -number, -updatedAt

默认值: number

externalIdstringExact match on externalId.
qstringName contains (case-insensitive).
updatedSincestring (date-time)
completedstring

取值之一: true, false

返回

200 OK A page of tasks

字段类型说明
tasksarray of Task
nextCursorstring可为 null
请求
curl "https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks?externalId=crm-4711" \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "tasks": [
    {
      "id": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "number": 1,
      "key": "WHX-1",
      "parentId": null,
      "name": "Foundations",
      "type": "task",
      "durationMin": 1440,
      "workMin": 0,
      "progressPct": 0,
      "constraintKind": "asap",
      "constraintDate": null,
      "deadline": null,
      "calendarId": null,
      "costFixed": 0,
      "notes": null,
      "color": null,
      "wbs": null,
      "externalId": "crm-4711",
      "startAt": "2026-10-05T06:00:00.000Z",
      "finishAt": "2026-10-07T15:00:00.000Z",
      "isCritical": true,
      "totalFloatMin": 0,
      "earlyStartAt": "2026-10-05T06:00:00.000Z",
      "lateFinishAt": "2026-10-07T15:00:00.000Z",
      "actualStartAt": null,
      "actualFinishAt": null,
      "actualDurationMin": null,
      "remainingDurationMin": null,
      "manuallyScheduled": false,
      "levelingDelayMin": 0,
      "taskType": "fixed_units",
      "effortDriven": false,
      "durationOptimisticMin": null,
      "durationPessimisticMin": null,
      "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
      "completed": false,
      "assignees": [
        {
          "resourceId": "0c6a8f52-3d7e-4b19-9a4e-6f1d2c8b7e30",
          "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
          "name": "Anna Rossi",
          "unitsPct": 100
        }
      ],
      "url": "https://planitude.app/app/t/WHX-1"
    }
  ],
  "nextCursor": null
}

Create a task, or apply a change set

POST/api/projects/{projectId}/tasks

具有写入权限的密钥

Send a TaskCreate to create one task (201), or a ChangeSet to apply several changes in one transaction (200). Dates are recalculated by the scheduling engine.

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.

请求体

TaskCreate

字段类型说明
name
必填
string
parentIdstring (uuid)可为 nullParent (summary) task; null = top level.
afterTaskIdstring (uuid)可为 nullInsert after this sibling.
beforeTaskIdstring (uuid)可为 nullInsert before this sibling.
typestring

取值之一: summary, task, milestone

durationMinintegerDuration in working minutes (8h day = 480).
workMininteger
progressPctnumber
constraintKindstring

取值之一: asap, alap, start_no_earlier_than, start_no_later_than, finish_no_earlier_than, finish_no_later_than, must_start_on, must_finish_on

constraintDatestring (date-time)可为 null
deadlinestring (date-time)可为 null
calendarIdstring (uuid)可为 null
costFixednumber
notesstring可为 null
colorstring可为 null
wbsstring可为 null
externalIdstring可为 nullYour identifier for this task in another system. Searchable with GET /tasks?externalId=.

或 ChangeSet

字段类型说明
createTasksarray of TaskCreate
updateTasksarray of any
createDependenciesarray of DependencyCreate
deleteDependencyIdsarray of string
fullRescheduleboolean

返回

201 Created Task created

字段类型说明
tasksarray of TaskCreated/updated tasks plus the ones the recalculation moved.
deletedTaskIdsarray of string
dependenciesarray of Dependency
deletedDependencyIdsarray of string
conflictsarray of Conflict
projectStartAtstring (date-time)
projectFinishAtstring (date-time)
statsobject
显示 stats 的字段
字段类型说明
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
请求
curl -X POST https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Foundations","durationMin":1440,"externalId":"crm-4711"}'
响应201 Created
{
  "tasks": [
    {
      "id": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "number": 1,
      "key": "WHX-1",
      "parentId": null,
      "sortKey": "i",
      "name": "Foundations",
      "type": "task",
      "durationMin": 1440,
      "workMin": 0,
      "progressPct": 0,
      "constraintKind": "asap",
      "constraintDate": null,
      "deadline": null,
      "calendarId": null,
      "costFixed": 0,
      "notes": null,
      "color": null,
      "wbs": null,
      "externalId": "crm-4711",
      "startAt": "2026-10-05T06:00:00.000Z",
      "finishAt": "2026-10-07T15:00:00.000Z",
      "isCritical": true,
      "totalFloatMin": 0,
      "earlyStartAt": "2026-10-05T06:00:00.000Z",
      "lateFinishAt": "2026-10-07T15:00:00.000Z",
      "actualStartAt": null,
      "actualFinishAt": null,
      "actualDurationMin": null,
      "remainingDurationMin": null,
      "manuallyScheduled": false,
      "levelingDelayMin": 0,
      "taskType": "fixed_units",
      "effortDriven": false,
      "durationOptimisticMin": null,
      "durationPessimisticMin": null
    }
  ],
  "deletedTaskIds": [],
  "dependencies": [
    {
      "id": "9ba5faf8-923d-4ecc-86f0-f245c5d179db",
      "predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
      "type": "FS",
      "lagMin": 0
    }
  ],
  "deletedDependencyIds": [],
  "conflicts": [],
  "projectStartAt": "2026-10-05T06:00:00.000Z",
  "projectFinishAt": "2026-10-07T15:00:00.000Z",
  "stats": {
    "taskCount": 12,
    "recomputedCount": 3,
    "savedCount": 2,
    "durationMs": 39
  }
}

Get a task

GET/api/projects/{projectId}/tasks/{taskId}

具有读取权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.
taskId
必填
string (uuid)Task id.

返回

200 OK The task

字段类型说明
taskTask
请求
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "task": {
    "id": "4dbd104a-00cd-4035-8955-255f52ea586a",
    "number": 1,
    "key": "WHX-1",
    "parentId": null,
    "name": "Foundations",
    "type": "task",
    "durationMin": 1440,
    "workMin": 0,
    "progressPct": 0,
    "constraintKind": "asap",
    "constraintDate": null,
    "deadline": null,
    "calendarId": null,
    "costFixed": 0,
    "notes": null,
    "color": null,
    "wbs": null,
    "externalId": "crm-4711",
    "startAt": "2026-10-05T06:00:00.000Z",
    "finishAt": "2026-10-07T15:00:00.000Z",
    "isCritical": true,
    "totalFloatMin": 0,
    "earlyStartAt": "2026-10-05T06:00:00.000Z",
    "lateFinishAt": "2026-10-07T15:00:00.000Z",
    "actualStartAt": null,
    "actualFinishAt": null,
    "actualDurationMin": null,
    "remainingDurationMin": null,
    "manuallyScheduled": false,
    "levelingDelayMin": 0,
    "taskType": "fixed_units",
    "effortDriven": false,
    "durationOptimisticMin": null,
    "durationPessimisticMin": null,
    "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "completed": false,
    "assignees": [
      {
        "resourceId": "0c6a8f52-3d7e-4b19-9a4e-6f1d2c8b7e30",
        "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
        "name": "Anna Rossi",
        "unitsPct": 100
      }
    ],
    "url": "https://planitude.app/app/t/WHX-1"
  }
}

Update a task

PATCH/api/projects/{projectId}/tasks/{taskId}

具有写入权限的密钥

Only the fields you send change; null clears a field.

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.
taskId
必填
string (uuid)Task id.

请求体

字段类型说明
namestring
typestring

取值之一: summary, task, milestone

durationMinintegerDuration in working minutes (8h day = 480).
workMininteger
progressPctnumber
constraintKindstring

取值之一: asap, alap, start_no_earlier_than, start_no_later_than, finish_no_earlier_than, finish_no_later_than, must_start_on, must_finish_on

constraintDatestring (date-time)可为 null
deadlinestring (date-time)可为 null
calendarIdstring (uuid)可为 null
costFixednumber
notesstring可为 null
colorstring可为 null
wbsstring可为 null
externalIdstring可为 nullYour identifier for this task in another system. Searchable with GET /tasks?externalId=.
placementobject
显示 placement 的字段
字段类型说明
parentIdstring (uuid)可为 nullParent (summary) task; null = top level.
afterTaskIdstring (uuid)可为 nullInsert after this sibling.
beforeTaskIdstring (uuid)可为 nullInsert before this sibling.

返回

200 OK Updated

字段类型说明
tasksarray of TaskCreated/updated tasks plus the ones the recalculation moved.
deletedTaskIdsarray of string
dependenciesarray of Dependency
deletedDependencyIdsarray of string
conflictsarray of Conflict
projectStartAtstring (date-time)
projectFinishAtstring (date-time)
statsobject
显示 stats 的字段
字段类型说明
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
请求
curl -X PATCH https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"progressPct":100}'
响应200 OK
{
  "tasks": [
    {
      "id": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "number": 1,
      "key": "WHX-1",
      "parentId": null,
      "sortKey": "i",
      "name": "Foundations",
      "type": "task",
      "durationMin": 1440,
      "workMin": 0,
      "progressPct": 0,
      "constraintKind": "asap",
      "constraintDate": null,
      "deadline": null,
      "calendarId": null,
      "costFixed": 0,
      "notes": null,
      "color": null,
      "wbs": null,
      "externalId": "crm-4711",
      "startAt": "2026-10-05T06:00:00.000Z",
      "finishAt": "2026-10-07T15:00:00.000Z",
      "isCritical": true,
      "totalFloatMin": 0,
      "earlyStartAt": "2026-10-05T06:00:00.000Z",
      "lateFinishAt": "2026-10-07T15:00:00.000Z",
      "actualStartAt": null,
      "actualFinishAt": null,
      "actualDurationMin": null,
      "remainingDurationMin": null,
      "manuallyScheduled": false,
      "levelingDelayMin": 0,
      "taskType": "fixed_units",
      "effortDriven": false,
      "durationOptimisticMin": null,
      "durationPessimisticMin": null
    }
  ],
  "deletedTaskIds": [],
  "dependencies": [
    {
      "id": "9ba5faf8-923d-4ecc-86f0-f245c5d179db",
      "predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
      "type": "FS",
      "lagMin": 0
    }
  ],
  "deletedDependencyIds": [],
  "conflicts": [],
  "projectStartAt": "2026-10-05T06:00:00.000Z",
  "projectFinishAt": "2026-10-07T15:00:00.000Z",
  "stats": {
    "taskCount": 12,
    "recomputedCount": 3,
    "savedCount": 2,
    "durationMs": 39
  }
}

Comments of a task

GET/api/projects/{projectId}/tasks/{taskId}/comments

具有读取权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.
taskId
必填
string (uuid)Task id.

返回

200 OK Comments

字段类型说明
commentsarray of Comment
请求
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a/comments \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "comments": [
    {
      "id": "0fc2dec5-a409-47c9-9c6e-0663e8f8bcf3",
      "taskId": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "authorName": "Anna Rossi",
      "authorAvatarUrl": null,
      "body": "Concrete delivered, we can start the walls.",
      "mentions": [],
      "createdAt": "2026-10-01T08:30:12.418Z",
      "editedAt": null
    }
  ]
}

Comment on a task

POST/api/projects/{projectId}/tasks/{taskId}/comments

具有写入权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.
taskId
必填
string (uuid)Task id.

请求体

字段类型说明
body
必填
stringPlain text.
mentionsarray of stringUser ids to notify.

返回

201 Created Created

字段类型说明
commentComment
请求
curl -X POST https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a/comments \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Concrete delivered, we can start the walls."}'
响应201 Created
{
  "comment": {
    "id": "0fc2dec5-a409-47c9-9c6e-0663e8f8bcf3",
    "taskId": "4dbd104a-00cd-4035-8955-255f52ea586a",
    "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "authorName": "Anna Rossi",
    "authorAvatarUrl": null,
    "body": "Concrete delivered, we can start the walls.",
    "mentions": [],
    "createdAt": "2026-10-01T08:30:12.418Z",
    "editedAt": null
  }
}

API 参考

Dependencies

Links between tasks (FS, SS, FF, SF, with lag).

Dependency

属性

字段类型说明
idstring (uuid)
predecessorIdstring (uuid)
successorIdstring (uuid)
typestring

取值之一: FS, SS, FF, SF

lagMinintegerWorking minutes; negative = lead.
对象Dependency
{
  "id": "9ba5faf8-923d-4ecc-86f0-f245c5d179db",
  "predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
  "successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
  "type": "FS",
  "lagMin": 0
}

List dependencies

GET/api/projects/{projectId}/dependencies

具有读取权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.

返回

200 OK Dependencies

字段类型说明
dependenciesarray of Dependency
请求
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "dependencies": [
    {
      "id": "9ba5faf8-923d-4ecc-86f0-f245c5d179db",
      "predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
      "type": "FS",
      "lagMin": 0
    }
  ]
}

Create (or update) a dependency

POST/api/projects/{projectId}/dependencies

具有写入权限的密钥

A dependency that would close a cycle is refused with 409 dependency_cycle.

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.

请求体

DependencyCreate

字段类型说明
predecessorId
必填
string (uuid)
successorId
必填
string (uuid)
typestring

取值之一: FS, SS, FF, SF

默认值: FS

lagMininteger

默认值: 0

或 dependencies

字段类型说明
dependencies
必填
array of DependencyCreate

返回

201 Created Created

字段类型说明
tasksarray of TaskCreated/updated tasks plus the ones the recalculation moved.
deletedTaskIdsarray of string
dependenciesarray of Dependency
deletedDependencyIdsarray of string
conflictsarray of Conflict
projectStartAtstring (date-time)
projectFinishAtstring (date-time)
statsobject
显示 stats 的字段
字段类型说明
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
请求
curl -X POST https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
  "successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
  "type": "FS",
  "lagMin": 0
}'
响应201 Created
{
  "tasks": [
    {
      "id": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "number": 1,
      "key": "WHX-1",
      "parentId": null,
      "sortKey": "i",
      "name": "Foundations",
      "type": "task",
      "durationMin": 1440,
      "workMin": 0,
      "progressPct": 0,
      "constraintKind": "asap",
      "constraintDate": null,
      "deadline": null,
      "calendarId": null,
      "costFixed": 0,
      "notes": null,
      "color": null,
      "wbs": null,
      "externalId": "crm-4711",
      "startAt": "2026-10-05T06:00:00.000Z",
      "finishAt": "2026-10-07T15:00:00.000Z",
      "isCritical": true,
      "totalFloatMin": 0,
      "earlyStartAt": "2026-10-05T06:00:00.000Z",
      "lateFinishAt": "2026-10-07T15:00:00.000Z",
      "actualStartAt": null,
      "actualFinishAt": null,
      "actualDurationMin": null,
      "remainingDurationMin": null,
      "manuallyScheduled": false,
      "levelingDelayMin": 0,
      "taskType": "fixed_units",
      "effortDriven": false,
      "durationOptimisticMin": null,
      "durationPessimisticMin": null
    }
  ],
  "deletedTaskIds": [],
  "dependencies": [
    {
      "id": "9ba5faf8-923d-4ecc-86f0-f245c5d179db",
      "predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
      "type": "FS",
      "lagMin": 0
    }
  ],
  "deletedDependencyIds": [],
  "conflicts": [],
  "projectStartAt": "2026-10-05T06:00:00.000Z",
  "projectFinishAt": "2026-10-07T15:00:00.000Z",
  "stats": {
    "taskCount": 12,
    "recomputedCount": 3,
    "savedCount": 2,
    "durationMs": 39
  }
}

Remove a dependency

DEL/api/projects/{projectId}/dependencies/{dependencyId}

具有写入权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.
dependencyId
必填
string (uuid)

返回

200 OK Removed

字段类型说明
tasksarray of TaskCreated/updated tasks plus the ones the recalculation moved.
deletedTaskIdsarray of string
dependenciesarray of Dependency
deletedDependencyIdsarray of string
conflictsarray of Conflict
projectStartAtstring (date-time)
projectFinishAtstring (date-time)
statsobject
显示 stats 的字段
字段类型说明
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
请求
curl -X DELETE https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies/9ba5faf8-923d-4ecc-86f0-f245c5d179db \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "tasks": [
    {
      "id": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "number": 1,
      "key": "WHX-1",
      "parentId": null,
      "sortKey": "i",
      "name": "Foundations",
      "type": "task",
      "durationMin": 1440,
      "workMin": 0,
      "progressPct": 0,
      "constraintKind": "asap",
      "constraintDate": null,
      "deadline": null,
      "calendarId": null,
      "costFixed": 0,
      "notes": null,
      "color": null,
      "wbs": null,
      "externalId": "crm-4711",
      "startAt": "2026-10-05T06:00:00.000Z",
      "finishAt": "2026-10-07T15:00:00.000Z",
      "isCritical": true,
      "totalFloatMin": 0,
      "earlyStartAt": "2026-10-05T06:00:00.000Z",
      "lateFinishAt": "2026-10-07T15:00:00.000Z",
      "actualStartAt": null,
      "actualFinishAt": null,
      "actualDurationMin": null,
      "remainingDurationMin": null,
      "manuallyScheduled": false,
      "levelingDelayMin": 0,
      "taskType": "fixed_units",
      "effortDriven": false,
      "durationOptimisticMin": null,
      "durationPessimisticMin": null
    }
  ],
  "deletedTaskIds": [],
  "dependencies": [
    {
      "id": "9ba5faf8-923d-4ecc-86f0-f245c5d179db",
      "predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
      "type": "FS",
      "lagMin": 0
    }
  ],
  "deletedDependencyIds": [],
  "conflicts": [],
  "projectStartAt": "2026-10-05T06:00:00.000Z",
  "projectFinishAt": "2026-10-07T15:00:00.000Z",
  "stats": {
    "taskCount": 12,
    "recomputedCount": 3,
    "savedCount": 2,
    "durationMs": 39
  }
}

API 参考

People

Project members and task assignees.

Member

属性

字段类型说明
userIdstring (uuid)
namestring
emailstring
rolestringEffective role on the project.

取值之一: owner, editor, viewer

directRolestring可为 nullRole granted on the project itself (null = only through the workspace).

取值之一: owner, editor, viewer

inheritedbooleanAccess comes from the workspace.
resourceIdstring (uuid)可为 nullResource used when the person is assigned to tasks.
addedAtstring (date-time)
avatarUrlstring可为 null
对象Member
{
  "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
  "name": "Anna Rossi",
  "email": "anna@example.com",
  "role": "owner",
  "directRole": null,
  "inherited": false,
  "resourceId": "0c6a8f52-3d7e-4b19-9a4e-6f1d2c8b7e30",
  "addedAt": "2026-10-01T08:30:12.418Z",
  "avatarUrl": null
}

Assignee

属性

字段类型说明
resourceIdstring (uuid)
userIdstring (uuid)可为 null
namestring
unitsPctinteger
对象Assignee
{
  "resourceId": "0c6a8f52-3d7e-4b19-9a4e-6f1d2c8b7e30",
  "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
  "name": "Anna Rossi",
  "unitsPct": 100
}

Replace the people assigned to a task

PUT/api/projects/{projectId}/tasks/{taskId}/assignees

具有写入权限的密钥

userIds must be members of the project (GET /members). An empty list removes everyone. Optional resourceIds replaces the people imported from a file (resources without an account) assigned to the task; omit it to leave them as they are.

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.
taskId
必填
string (uuid)Task id.

请求体

字段类型说明
userIds
必填
array of string
resourceIdsarray of string

返回

200 OK Assignees saved

字段类型说明
taskIdstring (uuid)
assignmentsarray of object
显示 assignments 的字段
字段类型说明
idstring (uuid)
taskIdstring (uuid)
resourceIdstring (uuid)
unitsPctinteger
workMininteger
resourcesarray of object
显示 resources 的字段
字段类型说明
idstring (uuid)
userIdstring (uuid)可为 null
namestring
kindstring

取值之一: work, material, cost

emailstring可为 null
costPerHournumber
costPerUsenumber
capacityPctinteger
calendarIdstring (uuid)可为 null
colorstring可为 null
avatarUrlstring可为 null
needsRescheduleboolean
conflictsarray of Conflict
请求
curl -X PUT https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a/assignees \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userIds":["b1666432-132a-4ea9-b1ae-76ea69e226c5"]}'
响应200 OK
{
  "taskId": "4dbd104a-00cd-4035-8955-255f52ea586a",
  "assignments": [
    {
      "id": "e62ac96b-e68e-40d3-842e-335e27dfd099",
      "taskId": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "resourceId": "0c6a8f52-3d7e-4b19-9a4e-6f1d2c8b7e30",
      "unitsPct": 100,
      "workMin": 0
    }
  ],
  "resources": [
    {
      "id": "0c6a8f52-3d7e-4b19-9a4e-6f1d2c8b7e30",
      "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi",
      "kind": "builtin",
      "email": "anna@example.com",
      "costPerHour": 0,
      "costPerUse": 0,
      "capacityPct": 0,
      "calendarId": null,
      "color": null,
      "avatarUrl": null
    }
  ],
  "needsReschedule": false,
  "conflicts": []
}

People with access to the project (assignable)

GET/api/projects/{projectId}/members

具有读取权限的密钥

路径参数

字段类型说明
projectId
必填
string (uuid)Project id.

返回

200 OK Members

字段类型说明
membersarray of Member
rolestring
请求
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/members \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "members": [
    {
      "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi",
      "email": "anna@example.com",
      "role": "owner",
      "directRole": null,
      "inherited": false,
      "resourceId": "0c6a8f52-3d7e-4b19-9a4e-6f1d2c8b7e30",
      "addedAt": "2026-10-01T08:30:12.418Z",
      "avatarUrl": null
    }
  ],
  "role": "owner"
}

API 参考

Webhooks

Outgoing webhook subscriptions (REST hooks: subscribe/unsubscribe).

Webhook

属性

字段类型说明
idstring (uuid)
workspaceIdstring (uuid)
workspaceNamestring
projectIdstring (uuid)可为 nullnull = every project of the workspace.
projectNamestring可为 null
namestring
urlstring (uri)
eventsarray of string

取值之一: project.created, project.updated, project.deleted, task.created, task.updated, task.deleted, task.completed, task.dates_changed, dependency.created, dependency.deleted, baseline.saved, member.invited, member.joined, comment.created

secretPrefixstringFirst characters of the signing secret (not secret).
activeboolean
disabledReasonstring可为 null

取值之一: failures, gone, project_deleted, user

disabledAtstring (date-time)可为 null
consecutiveFailuresinteger
viaApibooleanCreated with the API (REST hook) rather than from the profile.
createdByobject可为 null
显示 createdBy 的字段
字段类型说明
idstring (uuid)
namestring可为 null
createdAtstring (date-time)
updatedAtstring (date-time)
lastDeliveryAtstring (date-time)可为 null
lastSuccessAtstring (date-time)可为 null
对象Webhook
{
  "id": "1747ee7f-a395-4d3c-94b0-54b513d71d88",
  "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
  "workspaceName": "Acme Construction",
  "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
  "projectName": "Warehouse expansion",
  "name": "Warehouse sync",
  "url": "https://example.com/hooks/planitude",
  "events": [
    "task.created",
    "task.completed"
  ],
  "secretPrefix": "whsec_Fdwl",
  "active": true,
  "disabledReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "viaApi": true,
  "createdBy": {
    "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "name": "Anna Rossi"
  },
  "createdAt": "2026-10-01T08:30:12.418Z",
  "updatedAt": "2026-10-01T08:30:12.418Z",
  "lastDeliveryAt": "2026-10-01T08:30:12.418Z",
  "lastSuccessAt": "2026-10-01T08:30:12.418Z"
}

Delivery

属性

字段类型说明
idstring (uuid)
eventIdstring (uuid)
eventTypestring
statusstring

取值之一: pending, success, failed, cancelled

attemptsinteger
nextAttemptAtstring (date-time)可为 null
lastAttemptAtstring (date-time)可为 null
responseStatusinteger可为 null
responseExcerptstring可为 null
errorstring可为 null
durationMsinteger可为 null
manualboolean
createdAtstring (date-time)
对象Delivery
{
  "id": "4b207161-80f9-40bb-bc3f-d8f70315be00",
  "eventId": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
  "eventType": "task.completed",
  "status": "success",
  "attempts": 1,
  "nextAttemptAt": null,
  "lastAttemptAt": "2026-10-01T08:30:12.418Z",
  "responseStatus": 200,
  "responseExcerpt": "{\"ok\":true}",
  "error": null,
  "durationMs": 39,
  "manual": false,
  "createdAt": "2026-10-01T08:30:12.418Z"
}

Event

属性

字段类型说明
id
必填
string (uuid)Event id, also in the Planitude-Event-Id header: use it to deduplicate.
type
必填
string

取值之一: project.created, project.updated, project.deleted, task.created, task.updated, task.deleted, task.completed, task.dates_changed, dependency.created, dependency.deleted, baseline.saved, member.invited, member.joined, comment.created, webhook.ping

apiVersion
必填
string

取值之一: 2026-10-01

createdAt
必填
string (date-time)
workspaceId
必填
string (uuid)
projectIdstring (uuid)可为 null
actorobject可为 nullWho made the change (null for system changes).
显示 actor 的字段
字段类型说明
idstring (uuid)
namestring可为 null
data
必填
object
对象Event
{
  "id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
  "type": "project.created",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-01T08:30:12.418Z",
  "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
  "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
  "actor": {
    "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "name": "Anna Rossi"
  },
  "data": {}
}

Project (event payload)

Compact project representation used in webhook payloads.

属性

字段类型说明
idstring (uuid)
workspaceIdstring (uuid)
keystring
namestring
descriptionstring可为 null
startDatestring (date)
deadlinestring (date)可为 null
currencystring
scheduleFromstring

取值之一: forward, backward

colorstring可为 null
archivedboolean
createdAtstring (date-time)
updatedAtstring (date-time)
urlstring (uri)
对象Project (event payload)
{
  "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
  "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
  "key": "WHX",
  "name": "Warehouse expansion",
  "description": null,
  "startDate": "2026-10-05",
  "deadline": null,
  "currency": "EUR",
  "scheduleFrom": "forward",
  "color": null,
  "archived": false,
  "createdAt": "2026-10-01T08:30:12.418Z",
  "updatedAt": "2026-10-01T08:30:12.418Z",
  "url": "https://planitude.app/app/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8"
}

List webhook subscriptions

GET/api/webhooks

具有读取权限的密钥

查询参数

字段类型说明
workspaceIdstring (uuid)
projectIdstring (uuid)

返回

200 OK Subscriptions

字段类型说明
webhooksarray of Webhook
请求
curl https://planitude.app/api/webhooks \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "webhooks": [
    {
      "id": "1747ee7f-a395-4d3c-94b0-54b513d71d88",
      "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
      "workspaceName": "Acme Construction",
      "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
      "projectName": "Warehouse expansion",
      "name": "Warehouse sync",
      "url": "https://example.com/hooks/planitude",
      "events": [
        "task.created",
        "task.completed"
      ],
      "secretPrefix": "whsec_Fdwl",
      "active": true,
      "disabledReason": null,
      "disabledAt": null,
      "consecutiveFailures": 0,
      "viaApi": true,
      "createdBy": {
        "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
        "name": "Anna Rossi"
      },
      "createdAt": "2026-10-01T08:30:12.418Z",
      "updatedAt": "2026-10-01T08:30:12.418Z",
      "lastDeliveryAt": "2026-10-01T08:30:12.418Z",
      "lastSuccessAt": "2026-10-01T08:30:12.418Z"
    }
  ]
}

Subscribe (REST hook)

POST/api/webhooks

具有写入权限的密钥

Creates a subscription. The response contains the signing secret: it is shown only once. Aliases accepted for automation platforms: targetUrl for url, event for a single event.

请求体

字段类型说明
url
必填
string (uri)HTTPS endpoint that receives the events. Public addresses only.
events
必填
array of string* = all events.

取值之一: project.created, project.updated, project.deleted, task.created, task.updated, task.deleted, task.completed, task.dates_changed, dependency.created, dependency.deleted, baseline.saved, member.invited, member.joined, comment.created, *

namestring
projectIdstring (uuid)Limit to one project (editor role needed). Omit for the whole workspace (owner/admin).
workspaceIdstring (uuid)

返回

201 Created Created

字段类型说明
webhookWebhook
secretstringwhsec_...
请求
curl -X POST https://planitude.app/api/webhooks \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/planitude",
  "events": [
    "task.created",
    "task.completed"
  ],
  "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8"
}'
响应201 Created
{
  "webhook": {
    "id": "1747ee7f-a395-4d3c-94b0-54b513d71d88",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "workspaceName": "Acme Construction",
    "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "projectName": "Warehouse expansion",
    "name": "Warehouse sync",
    "url": "https://example.com/hooks/planitude",
    "events": [
      "task.created",
      "task.completed"
    ],
    "secretPrefix": "whsec_Fdwl",
    "active": true,
    "disabledReason": null,
    "disabledAt": null,
    "consecutiveFailures": 0,
    "viaApi": true,
    "createdBy": {
      "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi"
    },
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z",
    "lastDeliveryAt": "2026-10-01T08:30:12.418Z",
    "lastSuccessAt": "2026-10-01T08:30:12.418Z"
  },
  "secret": "whsec_3dvU0T1oaYlW4kH6m2Vb8nqXcR9eZpLsYw1QhGk"
}

Event catalog (public)

GET/api/webhooks/events

公开,无需密钥

返回

200 OK Events

字段类型说明
apiVersionstring
eventsarray of string
请求
curl https://planitude.app/api/webhooks/events
响应200 OK
{
  "apiVersion": "2026-10-01",
  "events": [
    "project.created",
    "project.updated",
    "project.deleted",
    "task.created",
    "task.updated",
    "task.deleted",
    "task.completed",
    "task.dates_changed",
    "dependency.created",
    "dependency.deleted",
    "baseline.saved",
    "member.invited",
    "member.joined",
    "comment.created"
  ]
}

Get a subscription

GET/api/webhooks/{webhookId}

具有读取权限的密钥

路径参数

字段类型说明
webhookId
必填
string (uuid)Webhook id.

返回

200 OK Subscription

字段类型说明
webhookWebhook
请求
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88 \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "webhook": {
    "id": "1747ee7f-a395-4d3c-94b0-54b513d71d88",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "workspaceName": "Acme Construction",
    "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "projectName": "Warehouse expansion",
    "name": "Warehouse sync",
    "url": "https://example.com/hooks/planitude",
    "events": [
      "task.created",
      "task.completed"
    ],
    "secretPrefix": "whsec_Fdwl",
    "active": true,
    "disabledReason": null,
    "disabledAt": null,
    "consecutiveFailures": 0,
    "viaApi": true,
    "createdBy": {
      "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi"
    },
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z",
    "lastDeliveryAt": "2026-10-01T08:30:12.418Z",
    "lastSuccessAt": "2026-10-01T08:30:12.418Z"
  }
}

Update, pause or resume a subscription

PATCH/api/webhooks/{webhookId}

具有写入权限的密钥

路径参数

字段类型说明
webhookId
必填
string (uuid)Webhook id.

请求体

字段类型说明
namestring
urlstring (uri)
eventsarray of string
activebooleanfalse = pause; true = resume (also resets the failure counter).

返回

200 OK Updated

字段类型说明
webhookWebhook
请求
curl -X PATCH https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88 \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":false}'
响应200 OK
{
  "webhook": {
    "id": "1747ee7f-a395-4d3c-94b0-54b513d71d88",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "workspaceName": "Acme Construction",
    "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "projectName": "Warehouse expansion",
    "name": "Warehouse sync",
    "url": "https://example.com/hooks/planitude",
    "events": [
      "task.created",
      "task.completed"
    ],
    "secretPrefix": "whsec_Fdwl",
    "active": true,
    "disabledReason": null,
    "disabledAt": null,
    "consecutiveFailures": 0,
    "viaApi": true,
    "createdBy": {
      "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi"
    },
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z",
    "lastDeliveryAt": "2026-10-01T08:30:12.418Z",
    "lastSuccessAt": "2026-10-01T08:30:12.418Z"
  }
}

Unsubscribe (REST hook)

DEL/api/webhooks/{webhookId}

具有写入权限的密钥

路径参数

字段类型说明
webhookId
必填
string (uuid)Webhook id.

返回

204 No Content Deleted

请求
curl -X DELETE https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88 \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"

Delivery log (newest first, kept 30 days)

GET/api/webhooks/{webhookId}/deliveries

具有读取权限的密钥

路径参数

字段类型说明
webhookId
必填
string (uuid)Webhook id.

查询参数

字段类型说明
limitinteger1-100.

默认值: 50

beforestring (date-time)nextCursor of the previous page.

返回

200 OK Deliveries

字段类型说明
deliveriesarray of Delivery
nextCursorstring可为 null
请求
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "deliveries": [
    {
      "id": "4b207161-80f9-40bb-bc3f-d8f70315be00",
      "eventId": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
      "eventType": "task.completed",
      "status": "success",
      "attempts": 1,
      "nextAttemptAt": null,
      "lastAttemptAt": "2026-10-01T08:30:12.418Z",
      "responseStatus": 200,
      "responseExcerpt": "{\"ok\":true}",
      "error": null,
      "durationMs": 39,
      "manual": false,
      "createdAt": "2026-10-01T08:30:12.418Z"
    }
  ],
  "nextCursor": null
}

Body sent with a delivery

GET/api/webhooks/{webhookId}/deliveries/{deliveryId}

具有读取权限的密钥

路径参数

字段类型说明
webhookId
必填
string (uuid)Webhook id.
deliveryId
必填
string (uuid)

返回

200 OK Payload

字段类型说明
payloadEvent
请求
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries/4b207161-80f9-40bb-bc3f-d8f70315be00 \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "payload": {
    "id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
    "type": "project.created",
    "apiVersion": "2026-10-01",
    "createdAt": "2026-10-01T08:30:12.418Z",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "actor": {
      "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi"
    },
    "data": {}
  }
}

Send the same event again

POST/api/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver

具有写入权限的密钥

路径参数

字段类型说明
webhookId
必填
string (uuid)Webhook id.
deliveryId
必填
string (uuid)

返回

202 Accepted Queued

字段类型说明
deliveryDelivery
请求
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries/4b207161-80f9-40bb-bc3f-d8f70315be00/redeliver \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应202 Accepted
{
  "delivery": {
    "id": "4b207161-80f9-40bb-bc3f-d8f70315be00",
    "eventId": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
    "eventType": "task.completed",
    "status": "success",
    "attempts": 1,
    "nextAttemptAt": null,
    "lastAttemptAt": "2026-10-01T08:30:12.418Z",
    "responseStatus": 200,
    "responseExcerpt": "{\"ok\":true}",
    "error": null,
    "durationMs": 39,
    "manual": false,
    "createdAt": "2026-10-01T08:30:12.418Z"
  }
}

Send a webhook.ping test event

POST/api/webhooks/{webhookId}/test

具有写入权限的密钥

路径参数

字段类型说明
webhookId
必填
string (uuid)Webhook id.

返回

202 Accepted Queued

字段类型说明
deliveryDelivery
请求
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应202 Accepted
{
  "delivery": {
    "id": "4b207161-80f9-40bb-bc3f-d8f70315be00",
    "eventId": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
    "eventType": "task.completed",
    "status": "success",
    "attempts": 1,
    "nextAttemptAt": null,
    "lastAttemptAt": "2026-10-01T08:30:12.418Z",
    "responseStatus": 200,
    "responseExcerpt": "{\"ok\":true}",
    "error": null,
    "durationMs": 39,
    "manual": false,
    "createdAt": "2026-10-01T08:30:12.418Z"
  }
}

Generate a new signing secret

POST/api/webhooks/{webhookId}/rotate-secret

具有写入权限的密钥

路径参数

字段类型说明
webhookId
必填
string (uuid)Webhook id.

返回

200 OK New secret (shown once)

字段类型说明
webhookWebhook
secretstring
请求
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/rotate-secret \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应200 OK
{
  "webhook": {
    "id": "1747ee7f-a395-4d3c-94b0-54b513d71d88",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "workspaceName": "Acme Construction",
    "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "projectName": "Warehouse expansion",
    "name": "Warehouse sync",
    "url": "https://example.com/hooks/planitude",
    "events": [
      "task.created",
      "task.completed"
    ],
    "secretPrefix": "whsec_Fdwl",
    "active": true,
    "disabledReason": null,
    "disabledAt": null,
    "consecutiveFailures": 0,
    "viaApi": true,
    "createdBy": {
      "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi"
    },
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z",
    "lastDeliveryAt": "2026-10-01T08:30:12.418Z",
    "lastSuccessAt": "2026-10-01T08:30:12.418Z"
  },
  "secret": "whsec_3dvU0T1oaYlW4kH6m2Vb8nqXcR9eZpLsYw1QhGk"
}

Webhook

Webhook

一旦有变化,Webhook 会立即向你的端点发送带 JSON 请求体的 HTTPS POST,无论变更来自 Web 应用、API、MCP 服务器还是导入。一个 Webhook 覆盖一个项目,或工作区内的所有项目(所有者和管理员)。

可在个人资料 → Webhook中创建,或通过 API 以 REST hook 方式创建:用 POST /api/webhooks 订阅,用 DELETE 取消订阅。签名密钥只显示一次。

每个请求都带有以下请求头:

请求头说明
Planitude-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>: see Verify signatures.
Planitude-EventEvent type, e.g. task.completed.
Planitude-Event-IdEvent id, the same in every retry: use it to deduplicate.
Planitude-DeliveryId of this delivery (changes with a manual resend).
User-AgentPlanitude-Webhooks/1.0 (+https://planitude.app/developers)
Content-Typeapplication/json
请求
curl -X POST https://planitude.app/api/webhooks \
  -H "Authorization: Bearer $PLANITUDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hooks/planitude",
  "events": [
    "task.created",
    "task.completed"
  ],
  "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8"
}'
响应201 Created
{
  "webhook": {
    "id": "1747ee7f-a395-4d3c-94b0-54b513d71d88",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "workspaceName": "Acme Construction",
    "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "projectName": "Warehouse expansion",
    "name": "Warehouse sync",
    "url": "https://example.com/hooks/planitude",
    "events": [
      "task.created",
      "task.completed"
    ],
    "secretPrefix": "whsec_Fdwl",
    "active": true,
    "disabledReason": null,
    "disabledAt": null,
    "consecutiveFailures": 0,
    "viaApi": true,
    "createdBy": {
      "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi"
    },
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z",
    "lastDeliveryAt": "2026-10-01T08:30:12.418Z",
    "lastSuccessAt": "2026-10-01T08:30:12.418Z"
  },
  "secret": "whsec_3dvU0T1oaYlW4kH6m2Vb8nqXcR9eZpLsYw1QhGk"
}

事件类型

可以订阅单个事件,或订阅 * 接收全部事件。所有事件的外层结构相同;data 随类型而变。

事件说明
project.createdA project was created (blank, from a template, duplicated or imported from MS Project).
project.updatedProject fields changed (name, dates, deadline, archive...), or a saved version was restored.
project.deletedA project was deleted.
task.createdA task was created.
task.updatedTask fields or assignees changed. changes lists only the fields that changed.
task.deletedA task was deleted (one event per task of a deleted branch).
task.completedTask progress reached 100%.
task.dates_changedStart or finish moved, because of an edit (cause: edit) or because the schedule was recalculated (cause: reschedule).
dependency.createdA dependency was created or changed.
dependency.deletedA dependency was removed.
baseline.savedA baseline was saved.
member.invitedAn invite link was created for the project.
member.joinedA person joined the project.
comment.createdA comment was added to a task.
示例载荷
{
  "id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
  "type": "project.created",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-01T08:30:12.418Z",
  "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
  "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
  "actor": {
    "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "name": "Anna Rossi"
  },
  "data": {
    "project": {
      "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
      "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
      "key": "WHX",
      "name": "Warehouse expansion",
      "description": null,
      "startDate": "2026-10-05",
      "deadline": null,
      "currency": "EUR",
      "scheduleFrom": "forward",
      "color": null,
      "archived": false,
      "createdAt": "2026-10-01T08:30:12.418Z",
      "updatedAt": "2026-10-01T08:30:12.418Z",
      "url": "https://planitude.app/app/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8"
    },
    "source": "blank"
  }
}

验证签名

每个请求都使用 HMAC-SHA256 和你的 Webhook 密钥签名。Planitude-Signature 请求头包含时间戳 t 和签名 v1,签名基于 t、一个点号和原始请求体计算。

  1. 使用解析 JSON 之前的原始请求体:重新序列化后的请求体签名不同。
  2. 计算 HMAC 并以恒定时间进行比较。
  3. 拒绝时间戳与你的时钟相差超过 5 分钟的请求:被截获的请求无法重放。
  4. 可随时轮换密钥:旧密钥立即失效。
Verify
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body as a string, before JSON.parse
export function verifyPlanitude(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // replay
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

// Express: app.post("/hooks/planitude", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyPlanitude(req.body.toString("utf8"), req.get("Planitude-Signature"), process.env.PLANITUDE_WEBHOOK_SECRET)) return res.sendStatus(400);
//   res.sendStatus(200); // then process the event in a queue
// });

重试与投递

请在 10 秒内返回任意 2xx,实际处理放在之后的队列中进行。不会跟随重定向。遇到错误或超时,Planitude 最多共尝试 6 次:立即一次,之后间隔 1 min, 5 min, 30 min, 2 h, 12 h。

投递至少一次且不保证顺序。保存事件 ID(Planitude-Event-Id,也是请求体中的 id)并跳过已处理的事件;按 createdAt 排序。

连续 5 个事件在所有尝试中均失败后,Webhook 会被停用,其所有者会收到邮件。返回 410 Gone 会立即停用。可在个人资料中重新启用,或使用 PATCH 并设置 active: true。

投递日志(状态、HTTP 状态码、响应摘录、载荷、手动重发)保留 30 天。目标地址只接受公网地址。

重试计划6 × POST
尝试 1   立即
尝试 2   + 1 min
尝试 3   + 5 min
尝试 4   + 30 min
尝试 5   + 2 h
尝试 6   + 12 h

测试你的端点

  1. 使用测试端点或个人资料中的测试按钮发送 webhook.ping 事件。
  2. 要在自己的电脑上接收事件,请用隧道(例如 ngrok 或 Cloudflare Tunnel)暴露本地服务器,并订阅其公开的 HTTPS 地址。
  3. 打开投递日志查看状态、HTTP 状态码和响应,修复端点后重新发送投递。
请求
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
响应202 Accepted
{
  "delivery": {
    "id": "4b207161-80f9-40bb-bc3f-d8f70315be00",
    "eventId": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
    "eventType": "task.completed",
    "status": "success",
    "attempts": 1,
    "nextAttemptAt": null,
    "lastAttemptAt": "2026-10-01T08:30:12.418Z",
    "responseStatus": 200,
    "responseExcerpt": "{\"ok\":true}",
    "error": null,
    "durationMs": 39,
    "manual": false,
    "createdAt": "2026-10-01T08:30:12.418Z"
  }
}

AI 与 MCP

MCP 服务器

Planitude 是一个 MCP(Model Context Protocol)服务器:AI 助手和代码编辑器以你的权限读取项目、分析关键路径和工作负载,并创建或修改任务。Web 应用通过 OAuth 连接(登录并允许访问);命令行工具和编辑器使用 API 密钥。

服务器 URL

https://planitude.app/mcp

  • ChatGPTOAuth

    在 ChatGPT 中打开 设置 › 安全与登录 并开启开发者模式。用服务器 URL 和 OAuth 身份验证创建一个应用,然后登录 Planitude 并允许访问。

    官方文档 ↗
  • ClaudeOAuth

    打开 自定义 › 连接器 › 添加自定义连接器,粘贴服务器 URL 并选择 连接:Planitude 会打开,你登录并允许访问。适用于 claude.ai、Claude Desktop 和移动应用。

    官方文档 ↗
  • GeminiOAuth

    在 gemini.google.com 打开 设置 › 已连接的应用,选择 添加自定义应用 并粘贴服务器 URL;然后登录 Planitude 并允许访问。

    官方文档 ↗
  • Claude CodeAPI 密钥

    将密钥放入环境变量后运行命令。加上 --scope user 可在所有项目中使用,并用 claude mcp list 检查。

    官方文档 ↗
  • CodexAPI 密钥

    将密钥放入 PLANITUDE_API_KEY,并把配置块添加到 ~/.codex/config.toml:适用于 CLI、应用和 IDE 扩展。

    官方文档 ↗
  • CursorAPI 密钥

    将配置块添加到 ~/.cursor/mcp.json(所有项目)或 .cursor/mcp.json(单个项目);Cursor 从环境中读取密钥。

    官方文档 ↗
  • 在工作区中添加 .vscode/mcp.json:VS Code 只询问一次密钥,并安全地保存在文件之外。

    官方文档 ↗
  • Gemini CLIAPI 密钥

    将密钥放入环境变量后运行命令,或将配置块添加到 ~/.gemini/settings.json。

    官方文档 ↗

工具

服务器提供 29 个工具,从读取和分析到安全的修改。没有任何工具会删除项目或任务。

read

  • planitude_list_projects
  • planitude_portfolio_overview
  • planitude_get_project
  • planitude_critical_path
  • planitude_delay_impact
  • planitude_monte_carlo
  • planitude_workload
  • planitude_list_baselines
  • planitude_list_versions
  • planitude_list_templates
  • planitude_list_comments
  • planitude_preview_import

write

  • planitude_create_project
  • planitude_create_project_from_template
  • planitude_create_project_from_plan
  • planitude_import_file
  • planitude_edit_project
  • planitude_add_task
  • planitude_update_task
  • planitude_set_progress
  • planitude_indent_task
  • planitude_outdent_task
  • planitude_link_tasks
  • planitude_unlink_tasks
  • planitude_reschedule
  • planitude_configure_simulation
  • planitude_add_comment
  • planitude_save_baseline
  • planitude_save_version
MCP

Server URL

https://planitude.app/mcp

AI 智能体

将最多 5 个外部 AI 智能体作为成员添加到工作区:Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 或任何 MCP 客户端。给它们分配任务,在评论中提及它们,并审核它们的更改。

所有者和管理员在 智能体 的“连接”选项卡中创建智能体密钥。密钥以 pln_ 开头,只显示一次,且仅以哈希形式保存;每个智能体最多 2 个密钥,撤销立即生效。

智能体密钥仅适用于 MCP 服务器,此时服务器提供智能体工具而非常规工具。在 REST API 上会得到 403 agent_credential。

每个密钥要么只读并可评论,要么可以编辑。领取、完成任务和提议更改都需要可编辑的密钥,否则返回 403 agent_key_read_only。

智能体只能看到它被添加到的项目,身份为 viewer(阅读并评论)或 editor(还可修改任务),绝不会是所有者。项目还需开启“允许此项目使用智能体”:默认关闭,由所有者开启。

智能体可以修改任务的名称、备注、工期、进度和截止日期,或创建任务。没有任何工具会删除、邀请成员或更改角色。

每个智能体的默认上限:每分钟 60 次请求,每天 200 次写入,最多可调到 240 和 2,000。每个项目最多 200 项更改可等待审核。

读取工具会把人写的文本(名称、备注、评论)以 JSON 字符串放入带随机 nonce 的 planitude-data 块中,并给自动检查标记的行加上 SUSPICIOUS:这些是数据,绝不是指令。用个人密钥读取的评论也放在同样的块中。

AI 智能体在 Planitude 中如何工作
MCPClaude Code
claude mcp add --transport http planitude https://planitude.app/mcp \
  --header "Authorization: Bearer $PLANITUDE_AGENT_KEY"

智能体工具

使用智能体密钥时,MCP 服务器提供以下 16 个工具:

read

  • planitude_list_my_projects
  • planitude_list_tasks
  • planitude_read_comments
  • planitude_list_my_proposals

propose

  • planitude_add_comment
  • planitude_propose_task_update
  • planitude_propose_status
  • planitude_propose_task_create

events

  • planitude_poll_events
  • planitude_ack_events

runs

  • planitude_list_my_runs
  • planitude_claim_task
  • planitude_extend_lease
  • planitude_complete_task
  • planitude_fail_task
  • planitude_release_task

在 自主 模式的执行中,智能体对自己任务的更改会立即生效并保留在历史记录中,可随时恢复。其他情况以及 需审批 模式下,更改会在“待审核”中等待,直到项目中有人应用它们。

没有 Webhook 时,智能体用 planitude_poll_events 读取事件(每次最多 50 个),并用 planitude_ack_events 确认。

请求tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "planitude_claim_task",
    "arguments": {
      "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
      "task": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "leaseMinutes": 30
    }
  }
}

执行 Webhook

要让智能体自动启动,请在 智能体 的“执行”选项卡中开启执行,并填写 runner 的 Webhook:当智能体有任务要执行时,Planitude 会发送签名的 POST。密钥以 whsec_ 开头,只显示一次。URL 必须是公开的 HTTPS 地址:私有和本地地址会被拒绝。

签名、请求头、10 秒超时和重试(1 min, 5 min, 30 min, 2 h, 12 h)与其他 Webhook 相同。连续 5 次投递失败后 Webhook 会关闭:重新保存 URL 即可再次开启。

通知只包含 ID,绝不包含任务文本:智能体通过 MCP 读取任务。

事件说明
task.assignedOnly with the “on assignment” trigger: a person assigned the task to the agent. Once per assignment.
task.start_dueDefault trigger: the task’s start date has come (a working day of its calendar).
task.due_todayThe task is due today (deadline or planned finish). Opens a run only if the task never had one.
task.overdueThe task is past its due date, once per due date. Opens a run only if the task never had one.
run.retryThe lease expired without completion, or a person chose Rerun: a new attempt is queued.
run.cancelA run in progress was cancelled (by a person, an emergency stop or the rules): stop working on it.
webhook.pingSent by “Send test event” in the agent’s Execution tab.

带有 newRun: true 的通知会开启一次执行。智能体用 planitude_claim_task 领取,并持有 30 分钟的 lease(5 到 240),用 planitude_extend_lease 续期。lease 过期后会开始新的尝试,最多 3 次(上限 10 次)。无人领取的执行在 24 小时后过期。

planitude_complete_task 将任务设为 100% 并把报告作为评论发布;若有未完成的子任务,返回 409 subtasks_open。planitude_fail_task 记录原因并通知团队,团队可重新执行;planitude_release_task 交还任务且不重试。

每次执行允许 50 次编辑(最多 500,超出返回 429),每个智能体允许 5 个未结束的执行(超出返回 409 too_many_open_runs)。默认模式 自主 会立即应用更改并可恢复;需审批 会把更改送去审核。按项目或整个工作区的紧急停止会取消未结束的执行并阻止写入。

示例载荷task.start_due
{
  "id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
  "type": "task.start_due",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-14T07:00:00.000Z",
  "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
  "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
  "actor": null,
  "data": {
    "agentId": "b4d17e2c-93a8-4c6f-8e15-6a0f2d9c7b31",
    "taskId": "4dbd104a-00cd-4035-8955-255f52ea586a",
    "runId": "7c3e2a91-5d4b-4f08-b6e1-2f9a0c8d4e57",
    "newRun": true,
    "attempt": 1,
    "leaseMinutes": 30,
    "writeMode": "autonomous",
    "day": "2026-10-14",
    "links": {
      "mcp": "https://planitude.app/mcp",
      "app": "https://planitude.app/app/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8?task=4dbd104a-00cd-4035-8955-255f52ea586a"
    }
  }
}

编写 runner

runner 是你的一个小服务,负责接收通知并启动智能体。任何语言都可以;在 Node 20+ 中无需任何依赖。

  1. 在原始请求体上验证签名并立即返回 200:Planitude 最多等待 10 秒。
  2. 跳过已经处理过的事件(Planitude-Event-Id):重试会再次发送同一事件。
  3. 收到 newRun: true 时,领取任务并启动智能体,例如使用 Planitude MCP 服务器和智能体密钥运行 claude -p。
  4. 智能体工作期间续期 lease;收到 run.cancel 时停止它。
  5. 要求智能体只在整个任务完成时以 PLANITUDE: DONE 结尾,然后用它的报告完成任务。否则(PLANITUDE: NOT DONE - … 或没有最后一行)标记为失败并注明剩余工作。

把任务文本当作数据:告诉智能体绝不执行其中的指令,并只允许它使用所需的 Planitude 工具。

Runner
// after verifyPlanitude(rawBody, signature, secret) and dedupe on Planitude-Event-Id
res.sendStatus(200); // answer at once, work afterwards
const { type, projectId, data } = event;
if (type === "run.cancel") return stopAgent(data.runId);
if (!data.newRun) return;

await callTool("planitude_claim_task", { projectId, task: data.taskId, leaseMinutes: data.leaseMinutes });
const out = await runAgent(data); // renew with planitude_extend_lease while it works
if (out.lastLine === "PLANITUDE: DONE") {
  await callTool("planitude_complete_task", { runId: data.runId, report: out.report }); // task -> 100%
} else {
  await callTool("planitude_fail_task", { runId: data.runId, reason: out.whatIsLeft });
}

// callTool = JSON-RPC tools/call to the MCP URL
// with Authorization: Bearer <agent key>

OData 源(Power BI、Excel)

面向 Power BI、Excel 及任何 OData 客户端的只读 OData v4 源,提供两个地址:单个项目,或密钥所有者在某个工作区中可见的所有项目。

  • https://planitude.app/api/odata/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8
  • https://planitude.app/api/odata/workspaces/824650d2-d0b3-4cac-8df8-5743ae9ff65a

使用具有读取权限的个人 API 密钥进行身份验证:Authorization: Bearer,或以密钥作为密码(用户名任意)的 HTTP Basic,这也是 Power BI 和 Excel 提供的方式。不接受 OAuth 令牌和会话 Cookie。仅限某个工作区的密钥无法读取其他工作区。

表:Projects, Tasks, Milestones, Dependencies, Resources, Assignments。架构位于 $metadata(CSDL XML),服务文档位于根地址。

支持的选项:$select、$filter(比较运算、and/or/not、in、contains、startswith、endswith、tolower、toupper)、$orderby、$top、$skip、$count 和 /$count。每页默认 2,000 行,使用 Prefer: odata.maxpagesize 最多可达 5,000 行;请跟随 @odata.nextLink 获取后续页。响应带有 ETag:发送 If-None-Match 可获得 304。不支持 $expand、$apply 和 $search(400)。

单个数据源最多涵盖 500 个项目和 25,000 个任务(超出则返回 413)。请求计入密钥的读取限额,每分钟 240 次。

Power BI 与 Excel 分步指南
请求cURL
curl "https://planitude.app/api/odata/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/Tasks?$select=Key,Name,Start,Finish,ProgressPct,IsCritical&$filter=IsCritical&$orderby=Start&$top=2&$count=true" \
  -u "powerbi:$PLANITUDE_API_KEY"

# schema (CSDL XML), for Power BI, Excel and any OData client
curl "https://planitude.app/api/odata/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/$metadata" -u "powerbi:$PLANITUDE_API_KEY"
响应200 OK
{
  "@odata.context": "https://planitude.app/api/odata/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/$metadata#Tasks(Key,Name,Start,Finish,ProgressPct,IsCritical)",
  "@odata.count": 3,
  "value": [
    {
      "Key": "WHX-2",
      "Name": "Foundations",
      "Start": "2026-10-05T07:00:00Z",
      "Finish": "2026-10-06T15:00:00Z",
      "ProgressPct": 100,
      "IsCritical": true
    },
    {
      "Key": "WHX-3",
      "Name": "Walls",
      "Start": "2026-10-07T07:00:00Z",
      "Finish": "2026-10-09T15:00:00Z",
      "ProgressPct": 50,
      "IsCritical": true
    }
  ]
}

更新日志

  1. 新增只读 OData v4 源,地址为 /api/odata/projects/:projectId 和 /api/odata/workspaces/:workspaceId,适用于 Power BI、Excel 及其他 OData 客户端:六个表、$metadata、$select、$filter、$orderby、$top、$skip、$count、服务器驱动分页和 ETag。

  2. 新增端点 GET /api/projects/:projectId/export:以 Microsoft Project XML、CSV、PNG 图片或 PDF 导出计划,可设置时间刻度、日期范围、关键路径、基线、依赖关系、纸张大小和方向。

  3. 所有 API 密钥现在都以 pln_ 开头。以 gnt_ 开头的密钥已不再可用:请创建新密钥。

  4. 智能体执行任务:签名的执行 Webhook(task.assigned、task.start_due、task.due_today、task.overdue、run.retry、run.cancel)、6 个带 lease 的执行工具,以及 runner 编写指南。

  5. MCP 读取工具会把人写的文本包裹在带 nonce 的 planitude-data 块中,作为带 SUSPICIOUS 标记的 JSON 字符串,适用于所有类型的密钥。

  6. AI 智能体作为工作区成员:仅适用于 MCP 服务器的智能体密钥、10 个用于阅读、评论和提议更改的工具,以及事件队列。

  7. 全新的开发者文档,由 OpenAPI 文档生成。OpenAPI 文档现在描述了成员、评论、基准、模板和分配返回的所有字段。

  8. API 版本 2026-10-01:签名的出站 Webhook、有文档的公开 REST API(OpenAPI 3.1)、游标分页以及按 externalId 搜索。

  9. MCP 服务器和 API 支持 OAuth 2.1:ChatGPT、Claude 和 Gemini 无需复制密钥即可连接。

  10. MCP 服务器以及具有只读或读写权限的个人 API 密钥。

广告让 Planitude 保持免费