开发者
使用 Planitude 构建
REST API、签名 Webhook 和 MCP 服务器:让你的系统与计划保持同步,响应每一次变更,并让 AI 助手处理你的项目。
与大多数 API 文档一样,代码、字段名和技术参考均为英文。
- 与你的系统同步任务从 CRM、ERP 或脚本创建项目和任务,通过
externalId用你自己的 ID 找回它们,并让排程引擎计算日期。 - 响应每一次变更任务被创建、完成或移动时,你会收到一个签名的 HTTPS 请求,无论变更来自应用、API、导入还是 AI 助手。
- 连接 AI 助手ChatGPT、Claude、Gemini、Cursor 和 VS Code 通过 MCP 服务器读取你的计划并提出修改,权限与你相同,仅此而已。
基础 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"const res = await fetch("https://planitude.app/api/auth/me", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/auth/me",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"user": {
"id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
"email": "anna@example.com",
"name": "Anna Rossi",
"avatarUrl": null,
"locale": "en",
"emailVerified": true
}
}快速开始
三步完成第一个 Webhook,只需要一个终端。
创建 API 密钥
打开个人资料 → API 密钥,选择读写并复制密钥:它以
pln_开头,只显示一次。请将它保存在环境变量中。发起第一次调用
列出你能看到的项目。密钥以你的身份操作:相同的项目,相同的角色。
接收 Webhook
为公开的 HTTPS 端点订阅所需事件,立即发送一个测试事件并验证其签名。
export PLANITUDE_API_KEY="pln_…"curl https://planitude.app/api/projects \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/projects", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/projects",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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"
}
]
}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"
}'const res = await fetch("https://planitude.app/api/webhooks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://example.com/hooks/planitude",
events: ["task.created", "task.completed"],
projectId: "40be00e0-7e34-4f7a-864b-5cc986f575b8",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/webhooks",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"url": "https://example.com/hooks/planitude",
"events": ["task.created", "task.completed"],
"projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
},
)
res.raise_for_status()
print(res.json()){
"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-serverhttps://planitude.app/.well-known/oauth-protected-resource
最佳实践
- 将密钥保存在环境变量或密钥管理器中,切勿放在代码或代码仓库里。密钥以
pln_开头,便于密钥扫描工具识别。 - 只读取时使用只读密钥,每个集成使用单独的密钥:撤销一个不会影响其他。
- 为脚本使用的密钥设置有效期并定期轮换。
- 从你的服务器调用 API,而不是从浏览器:前端代码中的密钥就是公开的密钥。
curl https://planitude.app/api/projects \
-H "Authorization: Bearer $PLANITUDE_API_KEY"{
"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 必填 | string | Stable error code: invalid_request, unauthorized, forbidden, not_found, conflict, dependency_cycle, limit_exceeded, rate_limited, server_error, ... |
| details | object |
{
"error": "invalid_request",
"details": {
"fields": [
{
"path": "name",
"message": "Invalid input: expected string, received undefined"
},
{
"path": "durationMin",
"message": "Too small: expected number to be >=0"
}
]
}
}{
"error": "forbidden",
"details": {
"reason": "destructive"
}
}{
"error": "dependency_cycle",
"details": {
"cycles": [
{
"path": "Foundations -> Walls -> Foundations",
"taskIds": [
"4dbd104a-00cd-4035-8955-255f52ea586a",
"a22fd799-c4dc-4869-a466-0dd6e96f71ce"
],
"taskNames": [
"Foundations",
"Walls"
]
}
]
}
}速率限制
限制按密钥计算,采用一分钟的滑动窗口:240 次读取请求和 60 次写入请求。超出后会收到 429 rate_limited 以及以秒为单位的 Retry-After 请求头。
重试前等待 Retry-After,将批量操作分散进行,并把多项修改合并为一个变更集:一次请求、一次重新计算最多可包含 1,000 项修改。
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"const tasks = [];
let cursor = null;
do {
const url = new URL("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks");
url.searchParams.set("limit", "500");
if (cursor) url.searchParams.set("cursor", cursor);
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const page = await res.json();
tasks.push(...page.tasks);
cursor = page.nextCursor;
} while (cursor);
console.log(tasks.length);import os
import requests
tasks, cursor = [], None
while True:
res = requests.get(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
params={"limit": 500, **({"cursor": cursor} if cursor else {})},
)
res.raise_for_status()
page = res.json()
tasks += page["tasks"]
cursor = page["nextCursor"]
if not cursor:
break
print(len(tasks))版本
API 和 Webhook 载荷按日期进行版本管理。当前版本为 2026-10-01:即每个事件的 apiVersion 字段和 OpenAPI 文档的 info.version。
同一版本内我们只做新增:新端点、新的可选字段、新的事件类型。没有新版本时,字段绝不会被删除或更改类型,因此请忽略你不认识的字段。
curl https://planitude.app/api/webhooks/eventsconst res = await fetch("https://planitude.app/api/webhooks/events");
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import requests
res = requests.get("https://planitude.app/api/webhooks/events")
res.raise_for_status()
print(res.json()){
"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
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string (uuid) | |
| string (email) | ||
| name | string可为 null | |
| avatarUrl | string可为 null | |
| locale | string | |
| emailVerified | boolean |
{
"id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
"email": "anna@example.com",
"name": "Anna Rossi",
"avatarUrl": null,
"locale": "en",
"emailVerified": true
}Workspace
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string (uuid) | |
| name | string | |
| role | string | 取值之一: |
{
"id": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
"name": "Acme Construction",
"role": "owner"
}curl https://planitude.app/api/auth/me \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/auth/me", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/auth/me",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| workspaces | array of Workspace |
curl https://planitude.app/api/workspaces \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/workspaces", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/workspaces",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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.
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string (uuid) | |
| workspaceId | string (uuid) | |
| key | string | Project key, e.g. CRON (task keys are CRON-12). |
| keyLocked | boolean | |
| name | string | |
| description | string可为 null | |
| startDate | string (date) | |
| calendarId | string (uuid)可为 null | |
| currency | string | |
| scheduleFrom | string | 取值之一: |
| deadline | string (date)可为 null | |
| color | string可为 null | |
| settings | object | |
| archivedAt | string (date-time)可为 null | |
| createdBy | string (uuid)可为 null | |
| createdAt | string (date-time) | |
| updatedAt | string (date-time) |
{
"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
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | builtin:<slug> or the id of a template saved by you. |
| kind | string | 取值之一: |
| name | string | |
| description | string可为 null | |
| taskCount | integer | |
| durationDays | integer | Working days from start to finish. |
{
"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
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string (uuid) | |
| name | string | |
| index | integer可为 null | Numbered MS Project baseline (1-10); null for the main baseline and the ones you name. |
| capturedAt | string (date-time) | |
| capturedBy | string (uuid)可为 null | |
| taskCount | integer |
{
"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.
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| archived | string | 取值之一: |
返回
200 OK Projects
| 字段 | 类型 | 说明 |
|---|---|---|
| projects | array of Project |
curl https://planitude.app/api/projects \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/projects", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/projects",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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 | |
| workspaceId | string (uuid) | Defaults to your personal workspace. |
| key | string | 2-5 letters/digits, starts with a letter. Derived from the name if omitted. |
| description | string可为 null | |
| startDate | string (date) | |
| deadline | string (date)可为 null | |
| currency | string | |
| scheduleFrom | string | 取值之一: |
| color | string可为 null |
返回
201 Created Created
| 字段 | 类型 | 说明 |
|---|---|---|
| project | Project |
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"}'const res = await fetch("https://planitude.app/api/projects", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Warehouse expansion",
startDate: "2026-10-05",
currency: "EUR",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/projects",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"name": "Warehouse expansion",
"startDate": "2026-10-05",
"currency": "EUR",
},
)
res.raise_for_status()
print(res.json()){
"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 必填 | string | Id from GET /api/templates. |
| startDate 必填 | string (date) | |
| name | string | |
| key | string | |
| locale | string | Language 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). |
| tz | string | IANA time zone of the project calendar. |
| workspaceId | string (uuid) |
返回
201 Created Created
| 字段 | 类型 | 说明 |
|---|---|---|
| project | Project | |
| taskCount | integer | |
| conflicts | array 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"
}'const res = await fetch("https://planitude.app/api/projects/from-template", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
templateId: "builtin:website-launch",
startDate: "2026-10-05",
name: "Website relaunch",
locale: "en",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/projects/from-template",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"templateId": "builtin:website-launch",
"startDate": "2026-10-05",
"name": "Website relaunch",
"locale": "en",
},
)
res.raise_for_status()
print(res.json()){
"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
具有读取权限的密钥
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| locale | string |
返回
200 OK Templates
| 字段 | 类型 | 说明 |
|---|---|---|
| templates | array of Template |
curl https://planitude.app/api/templates \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/templates", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/templates",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| project | Project | |
| tasks | array of Task | |
| dependencies | array of Dependency |
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8 \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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. |
请求体
| 字段 | 类型 | 说明 |
|---|---|---|
| name | string | |
| description | string可为 null | |
| startDate | string (date) | |
| deadline | string (date)可为 null | |
| currency | string | |
| scheduleFrom | string | 取值之一: |
| color | string可为 null | |
| archived | boolean |
返回
200 OK Updated
| 字段 | 类型 | 说明 |
|---|---|---|
| project | Project | |
| conflicts | array of Conflict | |
| rescheduled | boolean | The 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"}'const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
deadline: "2026-12-18",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.patch(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"deadline": "2026-12-18",
},
)
res.raise_for_status()
print(res.json()){
"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. |
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| format | string | File format. mspdi = Microsoft Project XML.取值之一: 默认值: |
| locale | string | Language of headings, legend and dates (e.g. en, it, ar, ja).默认值: |
| scale | string | PNG/PDF: time unit of the columns. 取值之一: 默认值: |
| from | string (date) | PNG/PDF: first day to draw (with to). Default: the whole project. |
| to | string (date) | PNG/PDF: last day to draw (with from). |
| critical | string | PNG/PDF: highlight the critical path. 取值之一: 默认值: |
| baseline | string | PNG/PDF: draw the main baseline under each bar. 取值之一: 默认值: |
| links | string | PNG/PDF: draw dependency arrows. 取值之一: 默认值: |
| paper | string | PDF: paper size. 取值之一: 默认值: |
| orientation | string | PDF: page orientation. 取值之一: 默认值: |
返回
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.pdfconst res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/export?format=pdf&locale=en&paper=a4", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
await (await import("node:fs/promises")).writeFile("plan.pdf", Buffer.from(await res.arrayBuffer()));import os
import requests
res = requests.get(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/export",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
params={
"format": "pdf",
"locale": "en",
"paper": "a4",
},
)
res.raise_for_status()
with open("plan.pdf", "wb") as out:
out.write(res.content)List baselines
GET/api/projects/{projectId}/baseline
具有读取权限的密钥
路径参数
| 字段 | 类型 | 说明 |
|---|---|---|
| projectId 必填 | string (uuid) | Project id. |
返回
200 OK Baselines
| 字段 | 类型 | 说明 |
|---|---|---|
| baselines | array of Baseline |
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/baseline \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/baseline", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/baseline",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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. |
请求体
| 字段 | 类型 | 说明 |
|---|---|---|
| name | string |
返回
201 Created Saved
| 字段 | 类型 | 说明 |
|---|---|---|
| baseline | Baseline |
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"}'const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/baseline", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Plan v1",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/baseline",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"name": "Plan v1",
},
)
res.raise_for_status()
print(res.json()){
"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.
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string (uuid) | |
| number | integer | Sequential number in the project, never reused. |
| key | string | Human key, e.g. CRON-12. |
| parentId | string (uuid)可为 null | |
| name | string | |
| type | string | 取值之一: |
| durationMin | integer | Duration in working minutes (8h day = 480). |
| workMin | integer | |
| progressPct | number | |
| constraintKind | string | 取值之一: |
| constraintDate | string (date-time)可为 null | |
| deadline | string (date-time)可为 null | |
| calendarId | string (uuid)可为 null | |
| costFixed | number | |
| notes | string可为 null | |
| color | string可为 null | |
| wbs | string可为 null | |
| externalId | string可为 null | Your identifier for this task in another system. Searchable with GET /tasks?externalId=. |
| startAt | string (date-time)可为 null | Computed start. |
| finishAt | string (date-time)可为 null | Computed finish. |
| isCritical | boolean | On the critical path. |
| totalFloatMin | integer可为 null | Total float (slack) in working minutes. |
| earlyStartAt | string (date-time)可为 null | |
| lateFinishAt | string (date-time)可为 null | |
| actualStartAt | string (date-time)可为 null | |
| actualFinishAt | string (date-time)可为 null | |
| actualDurationMin | integer可为 null | |
| remainingDurationMin | integer可为 null | |
| manuallyScheduled | boolean | |
| levelingDelayMin | integer | |
| taskType | string | 取值之一: |
| effortDriven | boolean | |
| durationOptimisticMin | integer可为 null | |
| durationPessimisticMin | integer可为 null | |
| projectId | string (uuid) | |
| completed | boolean | progressPct = 100. |
| assignees | array of Assignee | |
| url | string (uri) | Page of the task in the web app. |
{
"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
属性
| 字段 | 类型 | 说明 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| tasks | array of Task | Created/updated tasks plus the ones the recalculation moved. | |||||||||||||||
| deletedTaskIds | array of string | ||||||||||||||||
| dependencies | array of Dependency | ||||||||||||||||
| deletedDependencyIds | array of string | ||||||||||||||||
| conflicts | array of Conflict | ||||||||||||||||
| projectStartAt | string (date-time) | ||||||||||||||||
| projectFinishAt | string (date-time) | ||||||||||||||||
| stats | object | 显示 stats 的字段
|
{
"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
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string (uuid) | |
| taskId | string (uuid) | |
| userId | string (uuid) | |
| authorName | string | |
| authorAvatarUrl | string可为 null | |
| body | string | |
| mentions | array of string | |
| createdAt | string (date-time) | |
| editedAt | string (date-time)可为 null |
{
"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. |
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| limit | integer | 1-500. 默认值: |
| cursor | string | nextCursor of the previous page. |
| sort | string | -number = newest first (polling triggers). -updatedAt returns the first page only.取值之一: 默认值: |
| externalId | string | Exact match on externalId. |
| q | string | Name contains (case-insensitive). |
| updatedSince | string (date-time) | |
| completed | string | 取值之一: |
返回
200 OK A page of tasks
| 字段 | 类型 | 说明 |
|---|---|---|
| tasks | array of Task | |
| nextCursor | string可为 null |
curl "https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks?externalId=crm-4711" \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks?externalId=crm-4711", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
params={
"externalId": "crm-4711",
},
)
res.raise_for_status()
print(res.json()){
"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 | |
| parentId | string (uuid)可为 null | Parent (summary) task; null = top level. |
| afterTaskId | string (uuid)可为 null | Insert after this sibling. |
| beforeTaskId | string (uuid)可为 null | Insert before this sibling. |
| type | string | 取值之一: |
| durationMin | integer | Duration in working minutes (8h day = 480). |
| workMin | integer | |
| progressPct | number | |
| constraintKind | string | 取值之一: |
| constraintDate | string (date-time)可为 null | |
| deadline | string (date-time)可为 null | |
| calendarId | string (uuid)可为 null | |
| costFixed | number | |
| notes | string可为 null | |
| color | string可为 null | |
| wbs | string可为 null | |
| externalId | string可为 null | Your identifier for this task in another system. Searchable with GET /tasks?externalId=. |
或 ChangeSet
| 字段 | 类型 | 说明 |
|---|---|---|
| createTasks | array of TaskCreate | |
| updateTasks | array of any | |
| createDependencies | array of DependencyCreate | |
| deleteDependencyIds | array of string | |
| fullReschedule | boolean |
返回
201 Created Task created
| 字段 | 类型 | 说明 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| tasks | array of Task | Created/updated tasks plus the ones the recalculation moved. | |||||||||||||||
| deletedTaskIds | array of string | ||||||||||||||||
| dependencies | array of Dependency | ||||||||||||||||
| deletedDependencyIds | array of string | ||||||||||||||||
| conflicts | array of Conflict | ||||||||||||||||
| projectStartAt | string (date-time) | ||||||||||||||||
| projectFinishAt | string (date-time) | ||||||||||||||||
| stats | object | 显示 stats 的字段
|
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"}'const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Foundations",
durationMin: 1440,
externalId: "crm-4711",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"name": "Foundations",
"durationMin": 1440,
"externalId": "crm-4711",
},
)
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| task | Task |
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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. |
请求体
| 字段 | 类型 | 说明 | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | |||||||||||||
| type | string | 取值之一: | ||||||||||||
| durationMin | integer | Duration in working minutes (8h day = 480). | ||||||||||||
| workMin | integer | |||||||||||||
| progressPct | number | |||||||||||||
| constraintKind | string | 取值之一: | ||||||||||||
| constraintDate | string (date-time)可为 null | |||||||||||||
| deadline | string (date-time)可为 null | |||||||||||||
| calendarId | string (uuid)可为 null | |||||||||||||
| costFixed | number | |||||||||||||
| notes | string可为 null | |||||||||||||
| color | string可为 null | |||||||||||||
| wbs | string可为 null | |||||||||||||
| externalId | string可为 null | Your identifier for this task in another system. Searchable with GET /tasks?externalId=. | ||||||||||||
| placement | object | 显示 placement 的字段
|
返回
200 OK Updated
| 字段 | 类型 | 说明 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| tasks | array of Task | Created/updated tasks plus the ones the recalculation moved. | |||||||||||||||
| deletedTaskIds | array of string | ||||||||||||||||
| dependencies | array of Dependency | ||||||||||||||||
| deletedDependencyIds | array of string | ||||||||||||||||
| conflicts | array of Conflict | ||||||||||||||||
| projectStartAt | string (date-time) | ||||||||||||||||
| projectFinishAt | string (date-time) | ||||||||||||||||
| stats | object | 显示 stats 的字段
|
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}'const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
progressPct: 100,
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.patch(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"progressPct": 100,
},
)
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| comments | array 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"const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a/comments", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a/comments",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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 必填 | string | Plain text. |
| mentions | array of string | User ids to notify. |
返回
201 Created Created
| 字段 | 类型 | 说明 |
|---|---|---|
| comment | Comment |
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."}'const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a/comments", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
body: "Concrete delivered, we can start the walls.",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a/comments",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"body": "Concrete delivered, we can start the walls.",
},
)
res.raise_for_status()
print(res.json()){
"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
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string (uuid) | |
| predecessorId | string (uuid) | |
| successorId | string (uuid) | |
| type | string | 取值之一: |
| lagMin | integer | Working minutes; negative = lead. |
{
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| dependencies | array of Dependency |
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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) | |
| type | string | 取值之一: 默认值: |
| lagMin | integer | 默认值: |
或 dependencies
| 字段 | 类型 | 说明 |
|---|---|---|
| dependencies 必填 | array of DependencyCreate |
返回
201 Created Created
| 字段 | 类型 | 说明 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| tasks | array of Task | Created/updated tasks plus the ones the recalculation moved. | |||||||||||||||
| deletedTaskIds | array of string | ||||||||||||||||
| dependencies | array of Dependency | ||||||||||||||||
| deletedDependencyIds | array of string | ||||||||||||||||
| conflicts | array of Conflict | ||||||||||||||||
| projectStartAt | string (date-time) | ||||||||||||||||
| projectFinishAt | string (date-time) | ||||||||||||||||
| stats | object | 显示 stats 的字段
|
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
}'const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
predecessorId: "4dbd104a-00cd-4035-8955-255f52ea586a",
successorId: "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
type: "FS",
lagMin: 0,
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
"successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
"type": "FS",
"lagMin": 0,
},
)
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| tasks | array of Task | Created/updated tasks plus the ones the recalculation moved. | |||||||||||||||
| deletedTaskIds | array of string | ||||||||||||||||
| dependencies | array of Dependency | ||||||||||||||||
| deletedDependencyIds | array of string | ||||||||||||||||
| conflicts | array of Conflict | ||||||||||||||||
| projectStartAt | string (date-time) | ||||||||||||||||
| projectFinishAt | string (date-time) | ||||||||||||||||
| stats | object | 显示 stats 的字段
|
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"const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies/9ba5faf8-923d-4ecc-86f0-f245c5d179db", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(res.status); // 204import os
import requests
res = requests.delete(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies/9ba5faf8-923d-4ecc-86f0-f245c5d179db",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.status_code) # 204{
"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
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| userId | string (uuid) | |
| name | string | |
| string | ||
| role | string | Effective role on the project. 取值之一: |
| directRole | string可为 null | Role granted on the project itself (null = only through the workspace). 取值之一: |
| inherited | boolean | Access comes from the workspace. |
| resourceId | string (uuid)可为 null | Resource used when the person is assigned to tasks. |
| addedAt | string (date-time) | |
| avatarUrl | string可为 null |
{
"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
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| resourceId | string (uuid) | |
| userId | string (uuid)可为 null | |
| name | string | |
| unitsPct | integer |
{
"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 | |
| resourceIds | array of string |
返回
200 OK Assignees saved
| 字段 | 类型 | 说明 | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| taskId | string (uuid) | |||||||||||||||||||||||||||||||||||||
| assignments | array of object | 显示 assignments 的字段
| ||||||||||||||||||||||||||||||||||||
| resources | array of object | 显示 resources 的字段
| ||||||||||||||||||||||||||||||||||||
| needsReschedule | boolean | |||||||||||||||||||||||||||||||||||||
| conflicts | array 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"]}'const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a/assignees", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
userIds: ["b1666432-132a-4ea9-b1ae-76ea69e226c5"],
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.put(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a/assignees",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"userIds": ["b1666432-132a-4ea9-b1ae-76ea69e226c5"],
},
)
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| members | array of Member | |
| role | string |
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/members \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/members", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/members",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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).
- GET/api/webhooks
- POST/api/webhooks
- GET/api/webhooks/events
- GET/api/webhooks/{webhookId}
- PATCH/api/webhooks/{webhookId}
- DELETE/api/webhooks/{webhookId}
- GET/api/webhooks/{webhookId}/deliveries
- GET/api/webhooks/{webhookId}/deliveries/{deliveryId}
- POST/api/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver
- POST/api/webhooks/{webhookId}/test
- POST/api/webhooks/{webhookId}/rotate-secret
Webhook
属性
| 字段 | 类型 | 说明 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| id | string (uuid) | ||||||||||
| workspaceId | string (uuid) | ||||||||||
| workspaceName | string | ||||||||||
| projectId | string (uuid)可为 null | null = every project of the workspace. | |||||||||
| projectName | string可为 null | ||||||||||
| name | string | ||||||||||
| url | string (uri) | ||||||||||
| events | array of string | 取值之一: | |||||||||
| secretPrefix | string | First characters of the signing secret (not secret). | |||||||||
| active | boolean | ||||||||||
| disabledReason | string可为 null | 取值之一: | |||||||||
| disabledAt | string (date-time)可为 null | ||||||||||
| consecutiveFailures | integer | ||||||||||
| viaApi | boolean | Created with the API (REST hook) rather than from the profile. | |||||||||
| createdBy | object可为 null | 显示 createdBy 的字段
| |||||||||
| createdAt | string (date-time) | ||||||||||
| updatedAt | string (date-time) | ||||||||||
| lastDeliveryAt | string (date-time)可为 null | ||||||||||
| lastSuccessAt | string (date-time)可为 null |
{
"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
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string (uuid) | |
| eventId | string (uuid) | |
| eventType | string | |
| status | string | 取值之一: |
| attempts | integer | |
| nextAttemptAt | string (date-time)可为 null | |
| lastAttemptAt | string (date-time)可为 null | |
| responseStatus | integer可为 null | |
| responseExcerpt | string可为 null | |
| error | string可为 null | |
| durationMs | integer可为 null | |
| manual | boolean | |
| createdAt | string (date-time) |
{
"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 | 取值之一: | |||||||||
| apiVersion 必填 | string | 取值之一: | |||||||||
| createdAt 必填 | string (date-time) | ||||||||||
| workspaceId 必填 | string (uuid) | ||||||||||
| projectId | string (uuid)可为 null | ||||||||||
| actor | object可为 null | Who made the change (null for system changes).显示 actor 的字段
| |||||||||
| data 必填 | object |
{
"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.
属性
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string (uuid) | |
| workspaceId | string (uuid) | |
| key | string | |
| name | string | |
| description | string可为 null | |
| startDate | string (date) | |
| deadline | string (date)可为 null | |
| currency | string | |
| scheduleFrom | string | 取值之一: |
| color | string可为 null | |
| archived | boolean | |
| createdAt | string (date-time) | |
| updatedAt | string (date-time) | |
| url | string (uri) |
{
"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
具有读取权限的密钥
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| workspaceId | string (uuid) | |
| projectId | string (uuid) |
返回
200 OK Subscriptions
| 字段 | 类型 | 说明 |
|---|---|---|
| webhooks | array of Webhook |
curl https://planitude.app/api/webhooks \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/webhooks", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/webhooks",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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.取值之一: |
| name | string | |
| projectId | string (uuid) | Limit to one project (editor role needed). Omit for the whole workspace (owner/admin). |
| workspaceId | string (uuid) |
返回
201 Created Created
| 字段 | 类型 | 说明 |
|---|---|---|
| webhook | Webhook | |
| secret | string | whsec_... |
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"
}'const res = await fetch("https://planitude.app/api/webhooks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://example.com/hooks/planitude",
events: ["task.created", "task.completed"],
projectId: "40be00e0-7e34-4f7a-864b-5cc986f575b8",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/webhooks",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"url": "https://example.com/hooks/planitude",
"events": ["task.created", "task.completed"],
"projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
},
)
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| apiVersion | string | |
| events | array of string |
curl https://planitude.app/api/webhooks/eventsconst res = await fetch("https://planitude.app/api/webhooks/events");
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import requests
res = requests.get("https://planitude.app/api/webhooks/events")
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| webhook | Webhook |
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88 \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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. |
请求体
| 字段 | 类型 | 说明 |
|---|---|---|
| name | string | |
| url | string (uri) | |
| events | array of string | |
| active | boolean | false = pause; true = resume (also resets the failure counter). |
返回
200 OK Updated
| 字段 | 类型 | 说明 |
|---|---|---|
| webhook | Webhook |
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}'const res = await fetch("https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
active: false,
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.patch(
"https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"active": False,
},
)
res.raise_for_status()
print(res.json()){
"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"const res = await fetch("https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(res.status); // 204import os
import requests
res = requests.delete(
"https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.status_code) # 204Delivery log (newest first, kept 30 days)
GET/api/webhooks/{webhookId}/deliveries
具有读取权限的密钥
路径参数
| 字段 | 类型 | 说明 |
|---|---|---|
| webhookId 必填 | string (uuid) | Webhook id. |
查询参数
| 字段 | 类型 | 说明 |
|---|---|---|
| limit | integer | 1-100. 默认值: |
| before | string (date-time) | nextCursor of the previous page. |
返回
200 OK Deliveries
| 字段 | 类型 | 说明 |
|---|---|---|
| deliveries | array of Delivery | |
| nextCursor | string可为 null |
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| payload | Event |
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries/4b207161-80f9-40bb-bc3f-d8f70315be00 \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries/4b207161-80f9-40bb-bc3f-d8f70315be00", {
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.get(
"https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries/4b207161-80f9-40bb-bc3f-d8f70315be00",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| delivery | Delivery |
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"const res = await fetch("https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries/4b207161-80f9-40bb-bc3f-d8f70315be00/redeliver", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries/4b207161-80f9-40bb-bc3f-d8f70315be00/redeliver",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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
| 字段 | 类型 | 说明 |
|---|---|---|
| delivery | Delivery |
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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)
| 字段 | 类型 | 说明 |
|---|---|---|
| webhook | Webhook | |
| secret | string |
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/rotate-secret \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/rotate-secret", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/rotate-secret",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256>: see Verify signatures. |
| Planitude-Event | Event type, e.g. task.completed. |
| Planitude-Event-Id | Event id, the same in every retry: use it to deduplicate. |
| Planitude-Delivery | Id of this delivery (changes with a manual resend). |
| User-Agent | Planitude-Webhooks/1.0 (+https://planitude.app/developers) |
| Content-Type | application/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"
}'const res = await fetch("https://planitude.app/api/webhooks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://example.com/hooks/planitude",
events: ["task.created", "task.completed"],
projectId: "40be00e0-7e34-4f7a-864b-5cc986f575b8",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/webhooks",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
json={
"url": "https://example.com/hooks/planitude",
"events": ["task.created", "task.completed"],
"projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
},
)
res.raise_for_status()
print(res.json()){
"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.created | A project was created (blank, from a template, duplicated or imported from MS Project). |
| project.updated | Project fields changed (name, dates, deadline, archive...), or a saved version was restored. |
| project.deleted | A project was deleted. |
| task.created | A task was created. |
| task.updated | Task fields or assignees changed. changes lists only the fields that changed. |
| task.deleted | A task was deleted (one event per task of a deleted branch). |
| task.completed | Task progress reached 100%. |
| task.dates_changed | Start or finish moved, because of an edit (cause: edit) or because the schedule was recalculated (cause: reschedule). |
| dependency.created | A dependency was created or changed. |
| dependency.deleted | A dependency was removed. |
| baseline.saved | A baseline was saved. |
| member.invited | An invite link was created for the project. |
| member.joined | A person joined the project. |
| comment.created | A 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"
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "project.updated",
"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"
},
"changes": {
"deadline": {
"from": null,
"to": "2026-12-18"
}
},
"reason": "version_restored"
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "project.deleted",
"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"
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "task.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": {
"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"
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "task.updated",
"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": {
"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"
},
"changes": {
"progressPct": {
"from": 40,
"to": 60
}
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "task.deleted",
"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": {
"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"
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "task.completed",
"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": {
"task": {
"id": "4dbd104a-00cd-4035-8955-255f52ea586a",
"number": 1,
"key": "WHX-1",
"parentId": null,
"name": "Foundations",
"type": "task",
"durationMin": 1440,
"workMin": 0,
"progressPct": 100,
"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": true,
"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"
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "task.dates_changed",
"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": {
"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"
},
"cause": "reschedule",
"changes": {
"startAt": {
"from": "2026-10-02T06:00:00.000Z",
"to": "2026-10-05T06:00:00.000Z"
},
"finishAt": {
"from": "2026-10-06T15:00:00.000Z",
"to": "2026-10-07T15:00:00.000Z"
}
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "dependency.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": {
"dependency": {
"id": "9ba5faf8-923d-4ecc-86f0-f245c5d179db",
"predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
"successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
"type": "FS",
"lagMin": 0
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "dependency.deleted",
"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": {
"dependency": {
"id": "9ba5faf8-923d-4ecc-86f0-f245c5d179db",
"predecessorId": "4dbd104a-00cd-4035-8955-255f52ea586a",
"successorId": "a22fd799-c4dc-4869-a466-0dd6e96f71ce",
"type": "FS",
"lagMin": 0
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "baseline.saved",
"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": {
"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
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "member.invited",
"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": {
"invite": {
"id": "5d0b7c11-8e2a-4f63-a1d4-93c7e2b6f804",
"role": "editor",
"expiresAt": "2026-10-31T08:30:12.418Z",
"maxUses": null
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "member.joined",
"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": {
"member": {
"userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
"name": "Anna Rossi",
"role": "editor"
}
}
}{
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"type": "comment.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": {
"comment": {
"id": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
"taskId": "4dbd104a-00cd-4035-8955-255f52ea586a",
"body": "Concrete delivered, we can start the walls.",
"author": {
"id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
"name": "Anna Rossi"
},
"createdAt": "2026-10-01T08:30:12.418Z"
},
"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"
}
}
}验证签名
每个请求都使用 HMAC-SHA256 和你的 Webhook 密钥签名。Planitude-Signature 请求头包含时间戳 t 和签名 v1,签名基于 t、一个点号和原始请求体计算。
- 使用解析 JSON 之前的原始请求体:重新序列化后的请求体签名不同。
- 计算 HMAC 并以恒定时间进行比较。
- 拒绝时间戳与你的时钟相差超过 5 分钟的请求:被截获的请求无法重放。
- 可随时轮换密钥:旧密钥立即失效。
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
// });import hashlib
import hmac
import time
def verify_planitude(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t = int(parts.get("t", "0"))
if abs(time.time() - t) > tolerance:
return False # replay
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
# Flask: verify_planitude(request.get_data(), request.headers["Planitude-Signature"], os.environ["PLANITUDE_WEBHOOK_SECRET"])重试与投递
请在 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 天。目标地址只接受公网地址。
尝试 1 立即
尝试 2 + 1 min
尝试 3 + 5 min
尝试 4 + 30 min
尝试 5 + 2 h
尝试 6 + 12 h测试你的端点
- 使用测试端点或个人资料中的测试按钮发送
webhook.ping事件。 - 要在自己的电脑上接收事件,请用隧道(例如 ngrok 或 Cloudflare Tunnel)暴露本地服务器,并订阅其公开的 HTTPS 地址。
- 打开投递日志查看状态、HTTP 状态码和响应,修复端点后重新发送投递。
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test \
-H "Authorization: Bearer $PLANITUDE_API_KEY"const res = await fetch("https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLANITUDE_API_KEY}`,
},
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());import os
import requests
res = requests.post(
"https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test",
headers={"Authorization": f"Bearer {os.environ['PLANITUDE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()){
"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 从环境中读取密钥。 - Visual Studio CodeAPI 密钥
在工作区中添加
官方文档 ↗.vscode/mcp.json:VS Code 只询问一次密钥,并安全地保存在文件之外。 - Gemini CLIAPI 密钥
将密钥放入环境变量后运行命令,或将配置块添加到
官方文档 ↗~/.gemini/settings.json。
工具
服务器提供 29 个工具,从读取和分析到安全的修改。没有任何工具会删除项目或任务。
read
planitude_list_projectsplanitude_portfolio_overviewplanitude_get_projectplanitude_critical_pathplanitude_delay_impactplanitude_monte_carloplanitude_workloadplanitude_list_baselinesplanitude_list_versionsplanitude_list_templatesplanitude_list_commentsplanitude_preview_import
write
planitude_create_projectplanitude_create_project_from_templateplanitude_create_project_from_planplanitude_import_fileplanitude_edit_projectplanitude_add_taskplanitude_update_taskplanitude_set_progressplanitude_indent_taskplanitude_outdent_taskplanitude_link_tasksplanitude_unlink_tasksplanitude_rescheduleplanitude_configure_simulationplanitude_add_commentplanitude_save_baselineplanitude_save_version
Server URL
https://planitude.app/mcpServer URL
https://planitude.app/mcpServer URL
https://planitude.app/mcpTerminal
claude mcp add --transport http planitude https://planitude.app/mcp \
--header "Authorization: Bearer $PLANITUDE_API_KEY"~/.codex/config.toml
[mcp_servers.planitude]
url = "https://planitude.app/mcp"
bearer_token_env_var = "PLANITUDE_API_KEY"~/.cursor/mcp.json
{
"mcpServers": {
"planitude": {
"url": "https://planitude.app/mcp",
"headers": {
"Authorization": "Bearer ${env:PLANITUDE_API_KEY}"
}
}
}
}.vscode/mcp.json
{
"servers": {
"planitude": {
"type": "http",
"url": "https://planitude.app/mcp",
"headers": {
"Authorization": "Bearer ${input:planitude-key}"
}
}
},
"inputs": [
{
"id": "planitude-key",
"type": "promptString",
"description": "Planitude API key",
"password": true
}
]
}Terminal
gemini mcp add --transport http \
--header "Authorization: Bearer $PLANITUDE_API_KEY" planitude https://planitude.app/mcp~/.gemini/settings.json
{
"mcpServers": {
"planitude": {
"httpUrl": "https://planitude.app/mcp",
"headers": {
"Authorization": "Bearer $PLANITUDE_API_KEY"
}
}
}
}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:这些是数据,绝不是指令。用个人密钥读取的评论也放在同样的块中。
claude mcp add --transport http planitude https://planitude.app/mcp \
--header "Authorization: Bearer $PLANITUDE_AGENT_KEY"智能体工具
使用智能体密钥时,MCP 服务器提供以下 16 个工具:
read
planitude_list_my_projectsplanitude_list_tasksplanitude_read_commentsplanitude_list_my_proposals
propose
planitude_add_commentplanitude_propose_task_updateplanitude_propose_statusplanitude_propose_task_create
events
planitude_poll_eventsplanitude_ack_events
runs
planitude_list_my_runsplanitude_claim_taskplanitude_extend_leaseplanitude_complete_taskplanitude_fail_taskplanitude_release_task
在 自主 模式的执行中,智能体对自己任务的更改会立即生效并保留在历史记录中,可随时恢复。其他情况以及 需审批 模式下,更改会在“待审核”中等待,直到项目中有人应用它们。
没有 Webhook 时,智能体用 planitude_poll_events 读取事件(每次最多 50 个),并用 planitude_ack_events 确认。
{
"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.assigned | Only with the “on assignment” trigger: a person assigned the task to the agent. Once per assignment. |
| task.start_due | Default trigger: the task’s start date has come (a working day of its calendar). |
| task.due_today | The task is due today (deadline or planned finish). Opens a run only if the task never had one. |
| task.overdue | The task is past its due date, once per due date. Opens a run only if the task never had one. |
| run.retry | The lease expired without completion, or a person chose Rerun: a new attempt is queued. |
| run.cancel | A run in progress was cancelled (by a person, an emergency stop or the rules): stop working on it. |
| webhook.ping | Sent 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)。默认模式 自主 会立即应用更改并可恢复;需审批 会把更改送去审核。按项目或整个工作区的紧急停止会取消未结束的执行并阻止写入。
{
"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+ 中无需任何依赖。
- 在原始请求体上验证签名并立即返回 200:Planitude 最多等待 10 秒。
- 跳过已经处理过的事件(
Planitude-Event-Id):重试会再次发送同一事件。 - 收到
newRun: true时,领取任务并启动智能体,例如使用 Planitude MCP 服务器和智能体密钥运行claude -p。 - 智能体工作期间续期 lease;收到
run.cancel时停止它。 - 要求智能体只在整个任务完成时以
PLANITUDE: DONE结尾,然后用它的报告完成任务。否则(PLANITUDE: NOT DONE - …或没有最后一行)标记为失败并注明剩余工作。
把任务文本当作数据:告诉智能体绝不执行其中的指令,并只允许它使用所需的 Planitude 工具。
// 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># mcp.json: {"mcpServers":{"planitude":{"type":"http","url":"https://planitude.app/mcp",
# "headers":{"Authorization":"Bearer pln_..."}}}}
claude -p --output-format text \
--mcp-config mcp.json --allowedTools mcp__planitude < prompt.txtOData 源(Power BI、Excel)
面向 Power BI、Excel 及任何 OData 客户端的只读 OData v4 源,提供两个地址:单个项目,或密钥所有者在某个工作区中可见的所有项目。
https://planitude.app/api/odata/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8https://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 次。
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"{
"@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
}
]
}现成的集成
无需编写代码:这些集成使用相同的 API 和 Webhook,几次点击即可设置。
- Jira可用任务、日期和依赖与 Jira 事务双向同步。
- Azure DevOps可用与 Azure DevOps Boards 工作项双向同步。
- Slack可用在你的频道中接收项目更新、每日摘要并使用斜杠命令。
- Microsoft Teams可用Microsoft Teams 中的更新、摘要和 Planitude 选项卡。
- Power BI, Excel可用只读 OData 源,提供项目、任务、里程碑和分配数据,用于报表和仪表板。
- Zapier, Make, n8n即将推出为无代码自动化提供针对任务和项目的即时触发器和操作。
更新日志
新增只读 OData v4 源,地址为 /api/odata/projects/:projectId 和 /api/odata/workspaces/:workspaceId,适用于 Power BI、Excel 及其他 OData 客户端:六个表、$metadata、$select、$filter、$orderby、$top、$skip、$count、服务器驱动分页和 ETag。
新增端点 GET /api/projects/:projectId/export:以 Microsoft Project XML、CSV、PNG 图片或 PDF 导出计划,可设置时间刻度、日期范围、关键路径、基线、依赖关系、纸张大小和方向。
所有 API 密钥现在都以 pln_ 开头。以 gnt_ 开头的密钥已不再可用:请创建新密钥。
智能体执行任务:签名的执行 Webhook(task.assigned、task.start_due、task.due_today、task.overdue、run.retry、run.cancel)、6 个带 lease 的执行工具,以及 runner 编写指南。
MCP 读取工具会把人写的文本包裹在带 nonce 的 planitude-data 块中,作为带 SUSPICIOUS 标记的 JSON 字符串,适用于所有类型的密钥。
AI 智能体作为工作区成员:仅适用于 MCP 服务器的智能体密钥、10 个用于阅读、评论和提议更改的工具,以及事件队列。
全新的开发者文档,由 OpenAPI 文档生成。OpenAPI 文档现在描述了成员、评论、基准、模板和分配返回的所有字段。
API 版本 2026-10-01:签名的出站 Webhook、有文档的公开 REST API(OpenAPI 3.1)、游标分页以及按 externalId 搜索。
MCP 服务器和 API 支持 OAuth 2.1:ChatGPT、Claude 和 Gemini 无需复制密钥即可连接。
MCP 服务器以及具有只读或读写权限的个人 API 密钥。