Developers

Build with Planitude

A REST API, signed webhooks and an MCP server: keep your systems in sync with the plan, react to every change and let an AI assistant work on your projects.

Code, field names and the technical reference are in English, like most API documentation.

Base URL: https://planitude.app

Requests and responses are JSON over HTTPS. Durations and lags are in working minutes (an 8-hour day is 480), instants are ISO 8601 in UTC, dates without a time are YYYY-MM-DD.

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

Quickstart

From zero to your first webhook in three steps. All you need is a terminal.

  1. Create an API key

    Open Profile → API keys, choose Read and write and copy the key: it starts with pln_ and is shown only once. Keep it in an environment variable.

  2. Make your first call

    List the projects you can see. The key acts as you: same projects, same roles.

  3. Receive a webhook

    Subscribe a public HTTPS endpoint to the events you need, then send a test event right away and verify its signature.

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

Authentication

Authenticate every request with a personal API key in the Authorization header, as a bearer token. Keys are personal: they act as you, with your role on each project, never more. You can limit a key to one workspace, give it an expiry and revoke it at any time; every call is logged next to the key.

Scopes

ScopeAllows
readplanitude:readRead projects, tasks, dependencies, members, comments, baselines and webhooks.
writeplanitude:writeEverything in read, plus create and change projects, tasks, dependencies, comments, baselines and webhooks.

Keys and OAuth apps cannot delete projects or tasks: deleting stays in the web app, where a person confirms it. A script that targets the wrong id cannot wipe a plan.

OAuth 2.1 for third-party apps

Apps that act on behalf of other people use OAuth 2.1: authorization code with PKCE (S256), refresh tokens rotated on every use, dynamic client registration (RFC 7591). Ask for the resource https://planitude.app/api and the scope planitude:read or planitude:write.

The endpoints are published in the standard discovery documents, so OAuth libraries configure themselves.

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

Good practices

  • Keep keys in environment variables or a secret manager, never in code or in a repository. Keys start with pln_, so secret scanners can spot them.
  • Use a read-only key when you only read, and one key per integration: you can revoke one without stopping the others.
  • Give keys used by scripts an expiry and rotate them.
  • Call the API from your server, not from a browser: a key in front-end code is a public key.
Bearercurl
curl https://planitude.app/api/projects \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
OAuth 2.1/.well-known/oauth-authorization-server
{
  "issuer": "https://planitude.app",
  "authorization_endpoint": "https://planitude.app/oauth/authorize",
  "token_endpoint": "https://planitude.app/api/oauth/token",
  "registration_endpoint": "https://planitude.app/api/oauth/register",
  "revocation_endpoint": "https://planitude.app/api/oauth/revoke",
  "scopes_supported": [
    "planitude:read",
    "planitude:write"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ]
}

Errors

Planitude uses standard HTTP status codes. Errors always have the same JSON shape: a stable error code to branch on and, when useful, details with the reason or the fields to fix.

StatusMeaning
400invalid_requestThe request is not valid: details.fields lists each field and the problem.
401unauthorizedThe key is missing, invalid, revoked or expired.
403forbiddenThe key or your role does not allow it (details.reason), for example a write with a read-only key, or a delete.
404not_foundNot found, or not visible to you.
409dependency_cycleConflict with the plan, for example a dependency that would close a cycle (dependency_cycle).
429rate_limitedToo many requests: wait for the seconds in Retry-After.
500server_errorSomething went wrong on our side: retry with exponential backoff.

Error

FieldTypeDescription
error
required
stringStable error code: invalid_request, unauthorized, forbidden, not_found, conflict, dependency_cycle, limit_exceeded, rate_limited, server_error, ...
detailsobject
Response
{
  "error": "invalid_request",
  "details": {
    "fields": [
      {
        "path": "name",
        "message": "Invalid input: expected string, received undefined"
      },
      {
        "path": "durationMin",
        "message": "Too small: expected number to be >=0"
      }
    ]
  }
}

Rate limits

Limits apply per key, in a sliding window of one minute: 240 read requests and 60 write requests. Over the limit you get 429 rate_limited with a Retry-After header, in seconds.

Wait for Retry-After before retrying, spread bulk work over time and group many changes in one change set: up to 1,000 changes in one request and one recalculation.

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

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

Pagination and search

Task lists are paginated with a cursor. Pass limit (1–500, default 100) and, for the next page, the nextCursor of the previous response as cursor. When nextCursor is null there are no more pages.

Filter with externalId (exact match on your own id), q (name contains), updatedSince and completed; sort with sort=-number (newest first) or -updatedAt. Shorter lists, such as projects, members and dependencies, come back whole in one response.

Request
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"

Versioning

The API and the webhook payloads are versioned by date. The current version is 2026-10-01: it is the apiVersion field of every event and the info.version of the OpenAPI document.

Within a version we only add: new endpoints, new optional fields, new event types. Fields are never removed or retyped without a new version, so ignore the fields you do not know.

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

API reference

Account

Who is calling, and their workspaces.

User

Attributes

FieldTypeDescription
idstring (uuid)
emailstring (email)
namestringnullable
avatarUrlstringnullable
localestring
emailVerifiedboolean
ObjectsUser
{
  "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
  "email": "anna@example.com",
  "name": "Anna Rossi",
  "avatarUrl": null,
  "locale": "en",
  "emailVerified": true
}

Workspace

Attributes

FieldTypeDescription
idstring (uuid)
namestring
rolestring

One of: owner, admin, member

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

Current user (connection test)

GET/api/auth/me

Key with read access

Returns

200 OK The user

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

Workspaces of the user, with role

GET/api/workspaces

Key with read access

Returns

200 OK Workspaces

FieldTypeDescription
workspacesarray of Workspace
Request
curl https://planitude.app/api/workspaces \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Response200 OK
{
  "workspaces": [
    {
      "id": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
      "name": "Acme Construction",
      "role": "owner"
    }
  ]
}

API reference

Projects

Projects, templates and baselines.

Project

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

Attributes

FieldTypeDescription
idstring (uuid)
workspaceIdstring (uuid)
keystringProject key, e.g. CRON (task keys are CRON-12).
keyLockedboolean
namestring
descriptionstringnullable
startDatestring (date)
calendarIdstring (uuid)nullable
currencystring
scheduleFromstring

One of: forward, backward

deadlinestring (date)nullable
colorstringnullable
settingsobject
archivedAtstring (date-time)nullable
createdBystring (uuid)nullable
createdAtstring (date-time)
updatedAtstring (date-time)
ObjectsProject
{
  "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

Attributes

FieldTypeDescription
idstringbuiltin:<slug> or the id of a template saved by you.
kindstring

One of: builtin, user

namestring
descriptionstringnullable
taskCountinteger
durationDaysintegerWorking days from start to finish.
ObjectsTemplate
{
  "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

Attributes

FieldTypeDescription
idstring (uuid)
namestring
indexintegernullableNumbered MS Project baseline (1-10); null for the main baseline and the ones you name.
capturedAtstring (date-time)
capturedBystring (uuid)nullable
taskCountinteger
ObjectsBaseline
{
  "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

Key with read access

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

Query parameters

FieldTypeDescription
archivedstring

One of: 1

Returns

200 OK Projects

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

Create a project

POST/api/projects

Key with write access

Request body

FieldTypeDescription
name
required
string
workspaceIdstring (uuid)Defaults to your personal workspace.
keystring2-5 letters/digits, starts with a letter. Derived from the name if omitted.
descriptionstringnullable
startDatestring (date)
deadlinestring (date)nullable
currencystring
scheduleFromstring

One of: forward, backward

colorstringnullable

Returns

201 Created Created

FieldTypeDescription
projectProject
Request
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"}'
Response201 Created
{
  "project": {
    "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "key": "WHX",
    "keyLocked": false,
    "name": "Warehouse expansion",
    "description": null,
    "startDate": "2026-10-05",
    "calendarId": null,
    "currency": "EUR",
    "scheduleFrom": "forward",
    "deadline": null,
    "color": null,
    "settings": {},
    "archivedAt": null,
    "createdBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z"
  }
}

Create a project from a template

POST/api/projects/from-template

Key with write access

Request body

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

Returns

201 Created Created

FieldTypeDescription
projectProject
taskCountinteger
conflictsarray of Conflict
Request
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"
}'
Response201 Created
{
  "project": {
    "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "key": "WHX",
    "keyLocked": false,
    "name": "Warehouse expansion",
    "description": null,
    "startDate": "2026-10-05",
    "calendarId": null,
    "currency": "EUR",
    "scheduleFrom": "forward",
    "deadline": null,
    "color": null,
    "settings": {},
    "archivedAt": null,
    "createdBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z"
  },
  "taskCount": 12,
  "conflicts": []
}

List project templates

GET/api/templates

Key with read access

Query parameters

FieldTypeDescription
localestring

Returns

200 OK Templates

FieldTypeDescription
templatesarray of Template
Request
curl https://planitude.app/api/templates \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Response200 OK
{
  "templates": [
    {
      "id": "builtin:website-launch",
      "kind": "builtin",
      "name": "Website launch",
      "description": "From discovery to go-live: design, content, development, testing and launch.",
      "taskCount": 12,
      "durationDays": 43
    }
  ]
}

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

GET/api/projects/{projectId}

Key with read access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.

Returns

200 OK Project

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

Update a project

PATCH/api/projects/{projectId}

Key with write access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.

Request body

FieldTypeDescription
namestring
descriptionstringnullable
startDatestring (date)
deadlinestring (date)nullable
currencystring
scheduleFromstring

One of: forward, backward

colorstringnullable
archivedboolean

Returns

200 OK Updated

FieldTypeDescription
projectProject
conflictsarray of Conflict
rescheduledbooleanThe schedule was recalculated (start date, calendar or direction changed).
Request
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"}'
Response200 OK
{
  "project": {
    "id": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "key": "WHX",
    "keyLocked": false,
    "name": "Warehouse expansion",
    "description": null,
    "startDate": "2026-10-05",
    "calendarId": null,
    "currency": "EUR",
    "scheduleFrom": "forward",
    "deadline": null,
    "color": null,
    "settings": {},
    "archivedAt": null,
    "createdBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z"
  },
  "conflicts": [],
  "rescheduled": false
}

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

GET/api/projects/{projectId}/export

Key with read access

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).

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.

Query parameters

FieldTypeDescription
formatstringFile format. mspdi = Microsoft Project XML.

One of: mspdi, csv, png, pdf

Default: mspdi

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

Default: en

scalestringPNG/PDF: time unit of the columns.

One of: auto, day, week, month, quarter

Default: auto

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

One of: 0, 1

Default: 1

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

One of: 0, 1

Default: 1

linksstringPNG/PDF: draw dependency arrows.

One of: 0, 1

Default: 1

paperstringPDF: paper size.

One of: a4, a3, letter

Default: a4

orientationstringPDF: page orientation.

One of: landscape, portrait

Default: landscape

Returns

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

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

List baselines

GET/api/projects/{projectId}/baseline

Key with read access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.

Returns

200 OK Baselines

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

Save a baseline

POST/api/projects/{projectId}/baseline

Key with write access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.

Request body

FieldTypeDescription
namestring

Returns

201 Created Saved

FieldTypeDescription
baselineBaseline
Request
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"}'
Response201 Created
{
  "baseline": {
    "id": "b5d68d05-0640-48f9-8eeb-ed7804f4a116",
    "name": "Plan v1",
    "index": null,
    "capturedAt": "2026-10-01T08:30:12.418Z",
    "capturedBy": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "taskCount": 12
  }
}

API reference

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.

Attributes

FieldTypeDescription
idstring (uuid)
numberintegerSequential number in the project, never reused.
keystringHuman key, e.g. CRON-12.
parentIdstring (uuid)nullable
namestring
typestring

One of: summary, task, milestone

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

One of: asap, alap, start_no_earlier_than, start_no_later_than, finish_no_earlier_than, finish_no_later_than, must_start_on, must_finish_on

constraintDatestring (date-time)nullable
deadlinestring (date-time)nullable
calendarIdstring (uuid)nullable
costFixednumber
notesstringnullable
colorstringnullable
wbsstringnullable
externalIdstringnullableYour identifier for this task in another system. Searchable with GET /tasks?externalId=.
startAtstring (date-time)nullableComputed start.
finishAtstring (date-time)nullableComputed finish.
isCriticalbooleanOn the critical path.
totalFloatMinintegernullableTotal float (slack) in working minutes.
earlyStartAtstring (date-time)nullable
lateFinishAtstring (date-time)nullable
actualStartAtstring (date-time)nullable
actualFinishAtstring (date-time)nullable
actualDurationMinintegernullable
remainingDurationMinintegernullable
manuallyScheduledboolean
levelingDelayMininteger
taskTypestring

One of: fixed_units, fixed_duration, fixed_work, fixed_duration_and_units

effortDrivenboolean
durationOptimisticMinintegernullable
durationPessimisticMinintegernullable
projectIdstring (uuid)
completedbooleanprogressPct = 100.
assigneesarray of Assignee
urlstring (uri)Page of the task in the web app.
ObjectsTask
{
  "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

Attributes

FieldTypeDescription
tasksarray of TaskCreated/updated tasks plus the ones the recalculation moved.
deletedTaskIdsarray of string
dependenciesarray of Dependency
deletedDependencyIdsarray of string
conflictsarray of Conflict
projectStartAtstring (date-time)
projectFinishAtstring (date-time)
statsobject
Show the fields of stats
FieldTypeDescription
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
ObjectsWriteResult
{
  "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

Attributes

FieldTypeDescription
idstring (uuid)
taskIdstring (uuid)
userIdstring (uuid)
authorNamestring
authorAvatarUrlstringnullable
bodystring
mentionsarray of string
createdAtstring (date-time)
editedAtstring (date-time)nullable
ObjectsComment
{
  "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

Key with read access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.

Query parameters

FieldTypeDescription
limitinteger1-500.

Default: 100

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

One of: number, -number, -updatedAt

Default: number

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

One of: true, false

Returns

200 OK A page of tasks

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

Create a task, or apply a change set

POST/api/projects/{projectId}/tasks

Key with write access

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.

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.

Request body

TaskCreate

FieldTypeDescription
name
required
string
parentIdstring (uuid)nullableParent (summary) task; null = top level.
afterTaskIdstring (uuid)nullableInsert after this sibling.
beforeTaskIdstring (uuid)nullableInsert before this sibling.
typestring

One of: summary, task, milestone

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

One of: asap, alap, start_no_earlier_than, start_no_later_than, finish_no_earlier_than, finish_no_later_than, must_start_on, must_finish_on

constraintDatestring (date-time)nullable
deadlinestring (date-time)nullable
calendarIdstring (uuid)nullable
costFixednumber
notesstringnullable
colorstringnullable
wbsstringnullable
externalIdstringnullableYour identifier for this task in another system. Searchable with GET /tasks?externalId=.

or ChangeSet

FieldTypeDescription
createTasksarray of TaskCreate
updateTasksarray of any
createDependenciesarray of DependencyCreate
deleteDependencyIdsarray of string
fullRescheduleboolean

Returns

201 Created Task created

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

Get a task

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

Key with read access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.
taskId
required
string (uuid)Task id.

Returns

200 OK The task

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

Update a task

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

Key with write access

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

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.
taskId
required
string (uuid)Task id.

Request body

FieldTypeDescription
namestring
typestring

One of: summary, task, milestone

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

One of: asap, alap, start_no_earlier_than, start_no_later_than, finish_no_earlier_than, finish_no_later_than, must_start_on, must_finish_on

constraintDatestring (date-time)nullable
deadlinestring (date-time)nullable
calendarIdstring (uuid)nullable
costFixednumber
notesstringnullable
colorstringnullable
wbsstringnullable
externalIdstringnullableYour identifier for this task in another system. Searchable with GET /tasks?externalId=.
placementobject
Show the fields of placement
FieldTypeDescription
parentIdstring (uuid)nullableParent (summary) task; null = top level.
afterTaskIdstring (uuid)nullableInsert after this sibling.
beforeTaskIdstring (uuid)nullableInsert before this sibling.

Returns

200 OK Updated

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

Comments of a task

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

Key with read access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.
taskId
required
string (uuid)Task id.

Returns

200 OK Comments

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

Comment on a task

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

Key with write access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.
taskId
required
string (uuid)Task id.

Request body

FieldTypeDescription
body
required
stringPlain text.
mentionsarray of stringUser ids to notify.

Returns

201 Created Created

FieldTypeDescription
commentComment
Request
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."}'
Response201 Created
{
  "comment": {
    "id": "0fc2dec5-a409-47c9-9c6e-0663e8f8bcf3",
    "taskId": "4dbd104a-00cd-4035-8955-255f52ea586a",
    "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
    "authorName": "Anna Rossi",
    "authorAvatarUrl": null,
    "body": "Concrete delivered, we can start the walls.",
    "mentions": [],
    "createdAt": "2026-10-01T08:30:12.418Z",
    "editedAt": null
  }
}

API reference

Dependencies

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

Dependency

Attributes

FieldTypeDescription
idstring (uuid)
predecessorIdstring (uuid)
successorIdstring (uuid)
typestring

One of: FS, SS, FF, SF

lagMinintegerWorking minutes; negative = lead.
ObjectsDependency
{
  "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

Key with read access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.

Returns

200 OK Dependencies

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

Create (or update) a dependency

POST/api/projects/{projectId}/dependencies

Key with write access

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

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.

Request body

DependencyCreate

FieldTypeDescription
predecessorId
required
string (uuid)
successorId
required
string (uuid)
typestring

One of: FS, SS, FF, SF

Default: FS

lagMininteger

Default: 0

or dependencies

FieldTypeDescription
dependencies
required
array of DependencyCreate

Returns

201 Created Created

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

Remove a dependency

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

Key with write access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.
dependencyId
required
string (uuid)

Returns

200 OK Removed

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

API reference

People

Project members and task assignees.

Member

Attributes

FieldTypeDescription
userIdstring (uuid)
namestring
emailstring
rolestringEffective role on the project.

One of: owner, editor, viewer

directRolestringnullableRole granted on the project itself (null = only through the workspace).

One of: owner, editor, viewer

inheritedbooleanAccess comes from the workspace.
resourceIdstring (uuid)nullableResource used when the person is assigned to tasks.
addedAtstring (date-time)
avatarUrlstringnullable
ObjectsMember
{
  "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

Attributes

FieldTypeDescription
resourceIdstring (uuid)
userIdstring (uuid)nullable
namestring
unitsPctinteger
ObjectsAssignee
{
  "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

Key with write access

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.

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.
taskId
required
string (uuid)Task id.

Request body

FieldTypeDescription
userIds
required
array of string
resourceIdsarray of string

Returns

200 OK Assignees saved

FieldTypeDescription
taskIdstring (uuid)
assignmentsarray of object
Show the fields of assignments
FieldTypeDescription
idstring (uuid)
taskIdstring (uuid)
resourceIdstring (uuid)
unitsPctinteger
workMininteger
resourcesarray of object
Show the fields of resources
FieldTypeDescription
idstring (uuid)
userIdstring (uuid)nullable
namestring
kindstring

One of: work, material, cost

emailstringnullable
costPerHournumber
costPerUsenumber
capacityPctinteger
calendarIdstring (uuid)nullable
colorstringnullable
avatarUrlstringnullable
needsRescheduleboolean
conflictsarray of Conflict
Request
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"]}'
Response200 OK
{
  "taskId": "4dbd104a-00cd-4035-8955-255f52ea586a",
  "assignments": [
    {
      "id": "e62ac96b-e68e-40d3-842e-335e27dfd099",
      "taskId": "4dbd104a-00cd-4035-8955-255f52ea586a",
      "resourceId": "0c6a8f52-3d7e-4b19-9a4e-6f1d2c8b7e30",
      "unitsPct": 100,
      "workMin": 0
    }
  ],
  "resources": [
    {
      "id": "0c6a8f52-3d7e-4b19-9a4e-6f1d2c8b7e30",
      "userId": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi",
      "kind": "builtin",
      "email": "anna@example.com",
      "costPerHour": 0,
      "costPerUse": 0,
      "capacityPct": 0,
      "calendarId": null,
      "color": null,
      "avatarUrl": null
    }
  ],
  "needsReschedule": false,
  "conflicts": []
}

People with access to the project (assignable)

GET/api/projects/{projectId}/members

Key with read access

Path parameters

FieldTypeDescription
projectId
required
string (uuid)Project id.

Returns

200 OK Members

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

API reference

Webhooks

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

Webhook

Attributes

FieldTypeDescription
idstring (uuid)
workspaceIdstring (uuid)
workspaceNamestring
projectIdstring (uuid)nullablenull = every project of the workspace.
projectNamestringnullable
namestring
urlstring (uri)
eventsarray of string

One of: project.created, project.updated, project.deleted, task.created, task.updated, task.deleted, task.completed, task.dates_changed, dependency.created, dependency.deleted, baseline.saved, member.invited, member.joined, comment.created

secretPrefixstringFirst characters of the signing secret (not secret).
activeboolean
disabledReasonstringnullable

One of: failures, gone, project_deleted, user

disabledAtstring (date-time)nullable
consecutiveFailuresinteger
viaApibooleanCreated with the API (REST hook) rather than from the profile.
createdByobjectnullable
Show the fields of createdBy
FieldTypeDescription
idstring (uuid)
namestringnullable
createdAtstring (date-time)
updatedAtstring (date-time)
lastDeliveryAtstring (date-time)nullable
lastSuccessAtstring (date-time)nullable
ObjectsWebhook
{
  "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

Attributes

FieldTypeDescription
idstring (uuid)
eventIdstring (uuid)
eventTypestring
statusstring

One of: pending, success, failed, cancelled

attemptsinteger
nextAttemptAtstring (date-time)nullable
lastAttemptAtstring (date-time)nullable
responseStatusintegernullable
responseExcerptstringnullable
errorstringnullable
durationMsintegernullable
manualboolean
createdAtstring (date-time)
ObjectsDelivery
{
  "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

Attributes

FieldTypeDescription
id
required
string (uuid)Event id, also in the Planitude-Event-Id header: use it to deduplicate.
type
required
string

One of: project.created, project.updated, project.deleted, task.created, task.updated, task.deleted, task.completed, task.dates_changed, dependency.created, dependency.deleted, baseline.saved, member.invited, member.joined, comment.created, webhook.ping

apiVersion
required
string

One of: 2026-10-01

createdAt
required
string (date-time)
workspaceId
required
string (uuid)
projectIdstring (uuid)nullable
actorobjectnullableWho made the change (null for system changes).
Show the fields of actor
FieldTypeDescription
idstring (uuid)
namestringnullable
data
required
object
ObjectsEvent
{
  "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.

Attributes

FieldTypeDescription
idstring (uuid)
workspaceIdstring (uuid)
keystring
namestring
descriptionstringnullable
startDatestring (date)
deadlinestring (date)nullable
currencystring
scheduleFromstring

One of: forward, backward

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

List webhook subscriptions

GET/api/webhooks

Key with read access

Query parameters

FieldTypeDescription
workspaceIdstring (uuid)
projectIdstring (uuid)

Returns

200 OK Subscriptions

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

Subscribe (REST hook)

POST/api/webhooks

Key with write access

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.

Request body

FieldTypeDescription
url
required
string (uri)HTTPS endpoint that receives the events. Public addresses only.
events
required
array of string* = all events.

One of: project.created, project.updated, project.deleted, task.created, task.updated, task.deleted, task.completed, task.dates_changed, dependency.created, dependency.deleted, baseline.saved, member.invited, member.joined, comment.created, *

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

Returns

201 Created Created

FieldTypeDescription
webhookWebhook
secretstringwhsec_...
Request
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"
}'
Response201 Created
{
  "webhook": {
    "id": "1747ee7f-a395-4d3c-94b0-54b513d71d88",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "workspaceName": "Acme Construction",
    "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "projectName": "Warehouse expansion",
    "name": "Warehouse sync",
    "url": "https://example.com/hooks/planitude",
    "events": [
      "task.created",
      "task.completed"
    ],
    "secretPrefix": "whsec_Fdwl",
    "active": true,
    "disabledReason": null,
    "disabledAt": null,
    "consecutiveFailures": 0,
    "viaApi": true,
    "createdBy": {
      "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi"
    },
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z",
    "lastDeliveryAt": "2026-10-01T08:30:12.418Z",
    "lastSuccessAt": "2026-10-01T08:30:12.418Z"
  },
  "secret": "whsec_3dvU0T1oaYlW4kH6m2Vb8nqXcR9eZpLsYw1QhGk"
}

Event catalog (public)

GET/api/webhooks/events

Public, no key

Returns

200 OK Events

FieldTypeDescription
apiVersionstring
eventsarray of string
Request
curl https://planitude.app/api/webhooks/events
Response200 OK
{
  "apiVersion": "2026-10-01",
  "events": [
    "project.created",
    "project.updated",
    "project.deleted",
    "task.created",
    "task.updated",
    "task.deleted",
    "task.completed",
    "task.dates_changed",
    "dependency.created",
    "dependency.deleted",
    "baseline.saved",
    "member.invited",
    "member.joined",
    "comment.created"
  ]
}

Get a subscription

GET/api/webhooks/{webhookId}

Key with read access

Path parameters

FieldTypeDescription
webhookId
required
string (uuid)Webhook id.

Returns

200 OK Subscription

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

Update, pause or resume a subscription

PATCH/api/webhooks/{webhookId}

Key with write access

Path parameters

FieldTypeDescription
webhookId
required
string (uuid)Webhook id.

Request body

FieldTypeDescription
namestring
urlstring (uri)
eventsarray of string
activebooleanfalse = pause; true = resume (also resets the failure counter).

Returns

200 OK Updated

FieldTypeDescription
webhookWebhook
Request
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}'
Response200 OK
{
  "webhook": {
    "id": "1747ee7f-a395-4d3c-94b0-54b513d71d88",
    "workspaceId": "824650d2-d0b3-4cac-8df8-5743ae9ff65a",
    "workspaceName": "Acme Construction",
    "projectId": "40be00e0-7e34-4f7a-864b-5cc986f575b8",
    "projectName": "Warehouse expansion",
    "name": "Warehouse sync",
    "url": "https://example.com/hooks/planitude",
    "events": [
      "task.created",
      "task.completed"
    ],
    "secretPrefix": "whsec_Fdwl",
    "active": true,
    "disabledReason": null,
    "disabledAt": null,
    "consecutiveFailures": 0,
    "viaApi": true,
    "createdBy": {
      "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
      "name": "Anna Rossi"
    },
    "createdAt": "2026-10-01T08:30:12.418Z",
    "updatedAt": "2026-10-01T08:30:12.418Z",
    "lastDeliveryAt": "2026-10-01T08:30:12.418Z",
    "lastSuccessAt": "2026-10-01T08:30:12.418Z"
  }
}

Unsubscribe (REST hook)

DEL/api/webhooks/{webhookId}

Key with write access

Path parameters

FieldTypeDescription
webhookId
required
string (uuid)Webhook id.

Returns

204 No Content Deleted

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

Delivery log (newest first, kept 30 days)

GET/api/webhooks/{webhookId}/deliveries

Key with read access

Path parameters

FieldTypeDescription
webhookId
required
string (uuid)Webhook id.

Query parameters

FieldTypeDescription
limitinteger1-100.

Default: 50

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

Returns

200 OK Deliveries

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

Body sent with a delivery

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

Key with read access

Path parameters

FieldTypeDescription
webhookId
required
string (uuid)Webhook id.
deliveryId
required
string (uuid)

Returns

200 OK Payload

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

Send the same event again

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

Key with write access

Path parameters

FieldTypeDescription
webhookId
required
string (uuid)Webhook id.
deliveryId
required
string (uuid)

Returns

202 Accepted Queued

FieldTypeDescription
deliveryDelivery
Request
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"
Response202 Accepted
{
  "delivery": {
    "id": "4b207161-80f9-40bb-bc3f-d8f70315be00",
    "eventId": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
    "eventType": "task.completed",
    "status": "success",
    "attempts": 1,
    "nextAttemptAt": null,
    "lastAttemptAt": "2026-10-01T08:30:12.418Z",
    "responseStatus": 200,
    "responseExcerpt": "{\"ok\":true}",
    "error": null,
    "durationMs": 39,
    "manual": false,
    "createdAt": "2026-10-01T08:30:12.418Z"
  }
}

Send a webhook.ping test event

POST/api/webhooks/{webhookId}/test

Key with write access

Path parameters

FieldTypeDescription
webhookId
required
string (uuid)Webhook id.

Returns

202 Accepted Queued

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

Generate a new signing secret

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

Key with write access

Path parameters

FieldTypeDescription
webhookId
required
string (uuid)Webhook id.

Returns

200 OK New secret (shown once)

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

Webhooks

Webhooks

Webhooks send an HTTPS POST with a JSON body to your endpoint as soon as something changes, whether the change comes from the web app, the API, the MCP server or an import. A webhook covers one project, or every project of a workspace (owners and admins).

Create them in Profile → Webhooks or with the API, as REST hooks: subscribe with POST /api/webhooks, unsubscribe with DELETE. The signing secret is shown only once.

Every request carries these headers:

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

Event types

Subscribe to single events, or to * for all of them. Every event has the same envelope; data changes with the type.

EventDescription
project.createdA project was created (blank, from a template, duplicated or imported from MS Project).
project.updatedProject fields changed (name, dates, deadline, archive...), or a saved version was restored.
project.deletedA project was deleted.
task.createdA task was created.
task.updatedTask fields or assignees changed. changes lists only the fields that changed.
task.deletedA task was deleted (one event per task of a deleted branch).
task.completedTask progress reached 100%.
task.dates_changedStart or finish moved, because of an edit (cause: edit) or because the schedule was recalculated (cause: reschedule).
dependency.createdA dependency was created or changed.
dependency.deletedA dependency was removed.
baseline.savedA baseline was saved.
member.invitedAn invite link was created for the project.
member.joinedA person joined the project.
comment.createdA comment was added to a task.
Example 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": {
    "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"
  }
}

Verify signatures

Every request is signed with HMAC-SHA256 and your webhook’s secret. The Planitude-Signature header holds a timestamp t and the signature v1, computed on t, a dot and the raw body.

  1. Use the raw body, before any JSON parsing: a re-serialized body has a different signature.
  2. Compute the HMAC and compare it in constant time.
  3. Reject requests whose timestamp is more than 5 minutes from your clock: a captured request cannot be replayed.
  4. Rotate the secret whenever you want: the old one stops working at once.
Verify
import { createHmac, timingSafeEqual } from "node:crypto";

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

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

Retries and delivery

Answer with any 2xx within 10 seconds and do the real work afterwards, in a queue. Redirects are not followed. On errors and timeouts Planitude tries up to 6 times in total: immediately, then after 1 min, 5 min, 30 min, 2 h, 12 h.

Delivery is at least once and not ordered. Store the event id (Planitude-Event-Id, also id in the body) and skip the ones you have already processed; order by createdAt.

After 5 events in a row fail every attempt, the webhook is disabled and its owner receives an email. A 410 Gone answer disables it at once. Turn it back on from the profile, or with PATCH and active: true.

The delivery log (status, HTTP code, response excerpt, payload, manual resend) is kept for 30 days. Only public addresses are accepted as destinations.

Retry schedule6 × POST
Attempt 1   immediately
Attempt 2   + 1 min
Attempt 3   + 5 min
Attempt 4   + 30 min
Attempt 5   + 2 h
Attempt 6   + 12 h

Test your endpoint

  1. Send a webhook.ping event with the test endpoint, or with the Test button in the profile.
  2. To receive events on your computer, expose your local server with a tunnel (for example ngrok or Cloudflare Tunnel) and subscribe its public HTTPS address.
  3. Open the delivery log to see status, HTTP code and response, and resend a delivery once your endpoint is fixed.
Request
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Response202 Accepted
{
  "delivery": {
    "id": "4b207161-80f9-40bb-bc3f-d8f70315be00",
    "eventId": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
    "eventType": "task.completed",
    "status": "success",
    "attempts": 1,
    "nextAttemptAt": null,
    "lastAttemptAt": "2026-10-01T08:30:12.418Z",
    "responseStatus": 200,
    "responseExcerpt": "{\"ok\":true}",
    "error": null,
    "durationMs": 39,
    "manual": false,
    "createdAt": "2026-10-01T08:30:12.418Z"
  }
}

AI and MCP

MCP server

Planitude is an MCP (Model Context Protocol) server: AI assistants and code editors read projects, analyze the critical path and the workload, and create or change tasks, with your permissions. Web apps connect with OAuth (you sign in and allow access); command-line tools and editors use an API key.

Server URL

https://planitude.app/mcp

  • ChatGPTOAuth

    In ChatGPT open Settings › Security and login and turn on Developer mode. Create an app with the server URL and OAuth authentication, then sign in to Planitude and allow access.

    Official documentation ↗
  • ClaudeOAuth

    Open Customize › Connectors › Add custom connector, paste the server URL and choose Connect: Planitude opens, you sign in and allow access. It works in claude.ai, Claude Desktop and the mobile app.

    Official documentation ↗
  • GeminiOAuth

    On gemini.google.com open Settings › Connected Apps, choose Add a custom app and paste the server URL; then sign in to Planitude and allow access.

    Official documentation ↗
  • Run the command with your key in an environment variable. Add --scope user to use it in every project and check with claude mcp list.

    Official documentation ↗
  • CodexAPI key

    Put the key in PLANITUDE_API_KEY and add the block to ~/.codex/config.toml: it applies to the CLI, the app and the IDE extension.

    Official documentation ↗
  • CursorAPI key

    Add the block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project); Cursor reads the key from the environment.

    Official documentation ↗
  • Add .vscode/mcp.json to the workspace: VS Code asks for the key once and stores it securely, outside the file.

    Official documentation ↗
  • Gemini CLIAPI key

    Run the command with your key in an environment variable, or add the block to ~/.gemini/settings.json.

    Official documentation ↗

Tools

The server exposes 29 tools, from reading and analysis to safe changes. None of them deletes projects or tasks.

read

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

write

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

Server URL

https://planitude.app/mcp

AI agents

Add up to 5 external AI agents to the workspace as members: Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot or any MCP client. Assign them tasks, mention them in comments and review their changes.

Owners and admins create agent keys in Agents, Connection tab. A key starts with pln_, is shown once and stored as a hash; each agent can have up to 2 keys, and revoking one takes effect at once.

Agent keys work only with the MCP server, which then exposes the agent tools instead of the usual ones. On the REST API they get 403 agent_credential.

Each key either reads and comments or can edit. Claiming, completing and proposing changes need a key that can edit; otherwise the answer is 403 agent_key_read_only.

An agent sees only the projects it was added to, as viewer (reads and comments) or editor (also changes tasks), never as owner. The project also needs “Allow agents in this project”: it is off by default and the owner turns it on.

Agents can change a task’s name, notes, duration, progress and deadline, or create tasks. No tool deletes, invites people or changes roles.

Default limits per agent: 60 requests a minute and 200 writes a day, adjustable up to 240 and 2,000. At most 200 changes per project can wait for review.

Read tools put text written by people (names, notes, comments) inside planitude-data blocks with a random nonce, as JSON strings, and mark rows flagged by an automatic check as SUSPICIOUS: it is data, never instructions. Comments read with a personal key get the same blocks.

How AI agents work in Planitude
MCPClaude Code
claude mcp add --transport http planitude https://planitude.app/mcp \
  --header "Authorization: Bearer $PLANITUDE_AGENT_KEY"

Agent tools

With an agent key, the MCP server exposes these 16 tools:

read

  • planitude_list_my_projects
  • planitude_list_tasks
  • planitude_read_comments
  • planitude_list_my_proposals

propose

  • planitude_add_comment
  • planitude_propose_task_update
  • planitude_propose_status
  • planitude_propose_task_create

events

  • planitude_poll_events
  • planitude_ack_events

runs

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

During an Autonomous run, the agent’s changes to its own tasks apply right away and stay in the history, ready to restore. Otherwise, and in With approval mode, they wait in “Needs review” until someone on the project applies them.

Without a webhook, the agent reads its events with planitude_poll_events (up to 50 at a time) and confirms them with planitude_ack_events.

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

Run webhook

To start an agent on its own, turn on execution in Agents, Execution tab, and enter your runner’s webhook: Planitude sends a signed POST when the agent has a task to run. The secret starts with whsec_ and is shown once. The URL must be a public HTTPS address: private and local ones are refused.

Signature, headers, the 10-second timeout and retries (1 min, 5 min, 30 min, 2 h, 12 h) work as for the other webhooks. After 5 failed deliveries in a row the webhook turns off: save the URL again to turn it back on.

The notice carries only ids, never task text: the agent reads the task over MCP.

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

A notice with newRun: true opens a run. The agent claims it with planitude_claim_task and holds a lease of 30 minutes (from 5 to 240), renewed with planitude_extend_lease. If the lease expires, a new attempt starts, up to 3 (at most 10). A run nobody claims expires after 24 hours.

planitude_complete_task sets the task to 100% and posts the report as a comment; with open subtasks it answers 409 subtasks_open. planitude_fail_task records why and notifies the team, who can rerun it; planitude_release_task gives the task back with no retry.

Each run allows 50 edits (up to 500, then 429) and each agent 5 open runs (then 409 too_many_open_runs). Autonomous, the default mode, applies changes at once and lets you restore them; With approval sends them to review. An emergency stop, per project or for the whole workspace, cancels open runs and blocks writes.

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

Write a runner

The runner is your small service that receives the notices and starts the agent. Any language works; in Node 20+ it needs no dependencies.

  1. Verify the signature on the raw body and answer 200 at once: Planitude waits 10 seconds at most.
  2. Skip events you have already seen (Planitude-Event-Id): retries resend the same event.
  3. On newRun: true, claim the task and start the agent, for example claude -p with the Planitude MCP server and the agent key.
  4. Renew the lease while the agent works; on run.cancel, stop it.
  5. Ask the agent to end with PLANITUDE: DONE only when the whole task is done, then complete with its report. Otherwise (PLANITUDE: NOT DONE - … or no last line) fail with what is left.

Treat task text as data: tell the agent never to follow instructions found in it, and allow it only the Planitude tools it needs.

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

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

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

OData feed (Power BI, Excel)

A read-only OData v4 feed for Power BI, Excel and any OData client, at two addresses: one project, or every project the key owner can see in a workspace.

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

Authenticate with a personal API key with read access: Authorization: Bearer, or HTTP Basic with the key as password (any user name), which is the method Power BI and Excel offer. OAuth tokens and session cookies are not accepted. A key limited to one workspace cannot read the others.

Tables: Projects, Tasks, Milestones, Dependencies, Resources, Assignments. The schema is at $metadata (CSDL XML) and the service document at the root address.

Supported options: $select, $filter (comparisons, and/or/not, in, contains, startswith, endswith, tolower, toupper), $orderby, $top, $skip, $count and /$count. Pages hold 2,000 rows by default, up to 5,000 with Prefer: odata.maxpagesize; follow @odata.nextLink. Responses carry an ETag: send If-None-Match to get 304. $expand, $apply and $search are not supported (400).

A feed covers at most 500 projects and 25,000 tasks (beyond that, 413). Requests count toward the read limit of the key, 240 per minute.

Step-by-step guide for Power BI and Excel
RequestcURL
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"
Response200 OK
{
  "@odata.context": "https://planitude.app/api/odata/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/$metadata#Tasks(Key,Name,Start,Finish,ProgressPct,IsCritical)",
  "@odata.count": 3,
  "value": [
    {
      "Key": "WHX-2",
      "Name": "Foundations",
      "Start": "2026-10-05T07:00:00Z",
      "Finish": "2026-10-06T15:00:00Z",
      "ProgressPct": 100,
      "IsCritical": true
    },
    {
      "Key": "WHX-3",
      "Name": "Walls",
      "Start": "2026-10-07T07:00:00Z",
      "Finish": "2026-10-09T15:00:00Z",
      "ProgressPct": 50,
      "IsCritical": true
    }
  ]
}

Changelog

  1. New read-only OData v4 feed at /api/odata/projects/:projectId and /api/odata/workspaces/:workspaceId for Power BI, Excel and other OData clients: six tables, $metadata, $select, $filter, $orderby, $top, $skip, $count, server-driven paging and ETag.

  2. New endpoint GET /api/projects/:projectId/export: the plan as Microsoft Project XML, CSV, PNG image or PDF, with options for scale, date range, critical path, baseline, dependencies, paper size and orientation.

  3. All API keys now start with pln_. Keys that start with gnt_ no longer work: create a new one.

  4. Agents run tasks: signed run webhook (task.assigned, task.start_due, task.due_today, task.overdue, run.retry, run.cancel), 6 run tools with a lease and a guide to writing a runner.

  5. MCP read tools wrap text written by people in planitude-data blocks with a nonce, as JSON strings with a SUSPICIOUS mark, for every kind of key.

  6. AI agents as workspace members: agent keys that work only with the MCP server, 10 agent tools to read, comment and propose changes, and an event queue.

  7. New developer documentation, generated from the OpenAPI document. The OpenAPI document now describes every field returned for members, comments, baselines, templates and assignees.

  8. API version 2026-10-01: signed outgoing webhooks, documented public REST API (OpenAPI 3.1), cursor pagination and search by externalId.

  9. OAuth 2.1 for the MCP server and the API: ChatGPT, Claude and Gemini connect without copying a key.

  10. MCP server and personal API keys with read or read + write access.

Advertising keeps Planitude free