Développeurs

Développer avec Planitude

Une API REST, des webhooks signés et un serveur MCP : gardez vos systèmes alignés sur le planning, réagissez à chaque changement et laissez un assistant d’IA travailler sur vos projets.

Le code, les noms de champs et la référence technique sont en anglais, comme dans la plupart des documentations d’API.

URL de base: https://planitude.app

Requêtes et réponses sont en JSON sur HTTPS. Durées et décalages sont en minutes ouvrées (une journée de 8 heures vaut 480), les instants en ISO 8601 UTC, les dates sans heure en YYYY-MM-DD.

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

Démarrage rapide

De zéro à votre premier webhook en trois étapes. Un terminal suffit.

  1. Créer une clé API

    Ouvrez Profil → Clés API, choisissez Lecture et écriture et copiez la clé : elle commence par pln_ et ne s’affiche qu’une fois. Gardez-la dans une variable d’environnement.

  2. Faire le premier appel

    Listez les projets que vous voyez. La clé agit en votre nom : mêmes projets, mêmes rôles.

  3. Recevoir un webhook

    Abonnez un endpoint HTTPS public aux événements dont vous avez besoin, envoyez aussitôt un événement de test et vérifiez sa signature.

1Terminal
export PLANITUDE_API_KEY="pln_…"
2
curl https://planitude.app/api/projects \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Résultat attendu200 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"
}'
Payload d’exemplewebhook.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"
      ]
    }
  }
}

Authentification

Authentifiez chaque requête avec une clé API personnelle dans l’en-tête Authorization, comme bearer token. Les clés sont personnelles : elles agissent en votre nom, avec votre rôle dans chaque projet, jamais plus. Vous pouvez limiter une clé à un workspace, lui donner une expiration et la révoquer à tout moment ; chaque appel est consigné à côté de la clé.

Scopes

ScopeAutorise
readplanitude:readLire projets, tâches, dépendances, membres, commentaires, références et webhooks.
writeplanitude:writeTout ce que permet la lecture, plus créer et modifier projets, tâches, dépendances, commentaires, références et webhooks.

Les clés et les apps OAuth ne peuvent pas supprimer de projets ni de tâches : la suppression reste dans l’app web, où une personne la confirme. Un script qui vise le mauvais id ne peut pas effacer un planning.

OAuth 2.1 pour les apps tierces

Les apps qui agissent au nom d’autres personnes utilisent OAuth 2.1 : authorization code avec PKCE (S256), refresh tokens renouvelés à chaque usage, enregistrement dynamique des clients (RFC 7591). Demandez la ressource https://planitude.app/api et le scope planitude:read ou planitude:write.

Les endpoints sont publiés dans les documents de discovery standard, les bibliothèques OAuth se configurent donc seules.

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

Bonnes pratiques

  • Gardez les clés dans des variables d’environnement ou un gestionnaire de secrets, jamais dans le code ni dans un dépôt. Les clés commencent par pln_ pour que les scanners de secrets les repèrent.
  • Utilisez une clé en lecture seule quand vous ne faites que lire, et une clé par intégration : vous pouvez en révoquer une sans arrêter les autres.
  • Donnez une expiration aux clés des scripts et renouvelez-les.
  • Appelez l’API depuis votre serveur, pas depuis un navigateur : une clé dans du code front-end est une clé publique.
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"
  ]
}

Erreurs

Planitude utilise les codes de statut HTTP standard. Les erreurs ont toujours la même forme JSON : un code error stable sur lequel décider et, si utile, details avec la raison ou les champs à corriger.

StatutSignification
400invalid_requestLa requête n’est pas valide : details.fields liste chaque champ et le problème.
401unauthorizedLa clé est absente, invalide, révoquée ou expirée.
403forbiddenLa clé ou votre rôle ne le permet pas (details.reason), par exemple une écriture avec une clé en lecture seule, ou une suppression.
404not_foundIntrouvable, ou non visible pour vous.
409dependency_cycleConflit avec le planning, par exemple une dépendance qui fermerait un cycle (dependency_cycle).
429rate_limitedTrop de requêtes : attendez les secondes indiquées dans Retry-After.
500server_errorErreur de notre côté : réessayez avec un délai exponentiel.

Error

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

Limites de débit

Les limites s’appliquent par clé, sur une fenêtre glissante d’une minute : 240 requêtes de lecture et 60 requêtes d’écriture. Au-delà, vous recevez 429 rate_limited avec l’en-tête Retry-After, en secondes.

Attendez Retry-After avant de réessayer, étalez les traitements en masse et regroupez de nombreux changements dans un change set : jusqu’à 1 000 changements en une requête et un seul recalcul.

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

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

Pagination et recherche

Les listes de tâches sont paginées avec un curseur. Passez limit (1–500, par défaut 100) et, pour la page suivante, le nextCursor de la réponse précédente comme cursor. Quand nextCursor vaut null, il n’y a plus de pages.

Filtrez avec externalId (correspondance exacte avec votre identifiant), q (le nom contient), updatedSince et completed ; triez avec sort=-number (les plus récentes d’abord) ou -updatedAt. Les listes plus courtes, comme projets, membres et dépendances, arrivent entières en une réponse.

Requête
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"

Versions

L’API et les payloads des webhooks sont versionnés par date. La version actuelle est 2026-10-01 : c’est le champ apiVersion de chaque événement et l’info.version du document OpenAPI.

Au sein d’une version, nous ne faisons qu’ajouter : nouveaux endpoints, nouveaux champs facultatifs, nouveaux types d’événements. Aucun champ n’est retiré ni ne change de type sans nouvelle version : ignorez donc les champs inconnus.

Requête
curl https://planitude.app/api/webhooks/events
Réponse200 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"
  ]
}

Référence de l’API

Account

Who is calling, and their workspaces.

User

Attributs

ChampTypeDescription
idstring (uuid)
emailstring (email)
namestringpeut être null
avatarUrlstringpeut être null
localestring
emailVerifiedboolean
ObjetsUser
{
  "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
  "email": "anna@example.com",
  "name": "Anna Rossi",
  "avatarUrl": null,
  "locale": "en",
  "emailVerified": true
}

Workspace

Attributs

ChampTypeDescription
idstring (uuid)
namestring
rolestring

Parmi: owner, admin, member

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

Current user (connection test)

GET/api/auth/me

Clé avec accès en lecture

Renvoie

200 OK The user

ChampTypeDescription
userUser
Requête
curl https://planitude.app/api/auth/me \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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

Clé avec accès en lecture

Renvoie

200 OK Workspaces

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

Référence de l’API

Projects

Projects, templates and baselines.

Project

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

Attributs

ChampTypeDescription
idstring (uuid)
workspaceIdstring (uuid)
keystringProject key, e.g. CRON (task keys are CRON-12).
keyLockedboolean
namestring
descriptionstringpeut être null
startDatestring (date)
calendarIdstring (uuid)peut être null
currencystring
scheduleFromstring

Parmi: forward, backward

deadlinestring (date)peut être null
colorstringpeut être null
settingsobject
archivedAtstring (date-time)peut être null
createdBystring (uuid)peut être null
createdAtstring (date-time)
updatedAtstring (date-time)
ObjetsProject
{
  "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

Attributs

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

Parmi: builtin, user

namestring
descriptionstringpeut être null
taskCountinteger
durationDaysintegerWorking days from start to finish.
ObjetsTemplate
{
  "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

Attributs

ChampTypeDescription
idstring (uuid)
namestring
indexintegerpeut être nullNumbered MS Project baseline (1-10); null for the main baseline and the ones you name.
capturedAtstring (date-time)
capturedBystring (uuid)peut être null
taskCountinteger
ObjetsBaseline
{
  "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

Clé avec accès en lecture

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

Paramètres de requête

ChampTypeDescription
archivedstring

Parmi: 1

Renvoie

200 OK Projects

ChampTypeDescription
projectsarray of Project
Requête
curl https://planitude.app/api/projects \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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

Clé avec accès en écriture

Corps de la requête

ChampTypeDescription
name
obligatoire
string
workspaceIdstring (uuid)Defaults to your personal workspace.
keystring2-5 letters/digits, starts with a letter. Derived from the name if omitted.
descriptionstringpeut être null
startDatestring (date)
deadlinestring (date)peut être null
currencystring
scheduleFromstring

Parmi: forward, backward

colorstringpeut être null

Renvoie

201 Created Created

ChampTypeDescription
projectProject
Requête
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"}'
Réponse201 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

Clé avec accès en écriture

Corps de la requête

ChampTypeDescription
templateId
obligatoire
stringId from GET /api/templates.
startDate
obligatoire
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)

Renvoie

201 Created Created

ChampTypeDescription
projectProject
taskCountinteger
conflictsarray of Conflict
Requête
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"
}'
Réponse201 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

Clé avec accès en lecture

Paramètres de requête

ChampTypeDescription
localestring

Renvoie

200 OK Templates

ChampTypeDescription
templatesarray of Template
Requête
curl https://planitude.app/api/templates \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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}

Clé avec accès en lecture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.

Renvoie

200 OK Project

ChampTypeDescription
projectProject
tasksarray of Task
dependenciesarray of Dependency
Requête
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8 \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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}

Clé avec accès en écriture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.

Corps de la requête

ChampTypeDescription
namestring
descriptionstringpeut être null
startDatestring (date)
deadlinestring (date)peut être null
currencystring
scheduleFromstring

Parmi: forward, backward

colorstringpeut être null
archivedboolean

Renvoie

200 OK Updated

ChampTypeDescription
projectProject
conflictsarray of Conflict
rescheduledbooleanThe schedule was recalculated (start date, calendar or direction changed).
Requête
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"}'
Réponse200 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

Clé avec accès en lecture

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

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.

Paramètres de requête

ChampTypeDescription
formatstringFile format. mspdi = Microsoft Project XML.

Parmi: mspdi, csv, png, pdf

Par défaut: mspdi

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

Par défaut: en

scalestringPNG/PDF: time unit of the columns.

Parmi: auto, day, week, month, quarter

Par défaut: 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.

Parmi: 0, 1

Par défaut: 1

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

Parmi: 0, 1

Par défaut: 1

linksstringPNG/PDF: draw dependency arrows.

Parmi: 0, 1

Par défaut: 1

paperstringPDF: paper size.

Parmi: a4, a3, letter

Par défaut: a4

orientationstringPDF: page orientation.

Parmi: landscape, portrait

Par défaut: landscape

Renvoie

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

Requête
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

Clé avec accès en lecture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.

Renvoie

200 OK Baselines

ChampTypeDescription
baselinesarray of Baseline
Requête
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/baseline \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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

Clé avec accès en écriture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.

Corps de la requête

ChampTypeDescription
namestring

Renvoie

201 Created Saved

ChampTypeDescription
baselineBaseline
Requête
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"}'
Réponse201 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
  }
}

Référence de l’API

Tasks

Tasks, search by external id, comments.

Task

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

Attributs

ChampTypeDescription
idstring (uuid)
numberintegerSequential number in the project, never reused.
keystringHuman key, e.g. CRON-12.
parentIdstring (uuid)peut être null
namestring
typestring

Parmi: summary, task, milestone

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

Parmi: 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)peut être null
deadlinestring (date-time)peut être null
calendarIdstring (uuid)peut être null
costFixednumber
notesstringpeut être null
colorstringpeut être null
wbsstringpeut être null
externalIdstringpeut être nullYour identifier for this task in another system. Searchable with GET /tasks?externalId=.
startAtstring (date-time)peut être nullComputed start.
finishAtstring (date-time)peut être nullComputed finish.
isCriticalbooleanOn the critical path.
totalFloatMinintegerpeut être nullTotal float (slack) in working minutes.
earlyStartAtstring (date-time)peut être null
lateFinishAtstring (date-time)peut être null
actualStartAtstring (date-time)peut être null
actualFinishAtstring (date-time)peut être null
actualDurationMinintegerpeut être null
remainingDurationMinintegerpeut être null
manuallyScheduledboolean
levelingDelayMininteger
taskTypestring

Parmi: fixed_units, fixed_duration, fixed_work, fixed_duration_and_units

effortDrivenboolean
durationOptimisticMinintegerpeut être null
durationPessimisticMinintegerpeut être null
projectIdstring (uuid)
completedbooleanprogressPct = 100.
assigneesarray of Assignee
urlstring (uri)Page of the task in the web app.
ObjetsTask
{
  "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

Attributs

ChampTypeDescription
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
Afficher les champs de stats
ChampTypeDescription
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
ObjetsWriteResult
{
  "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

Attributs

ChampTypeDescription
idstring (uuid)
taskIdstring (uuid)
userIdstring (uuid)
authorNamestring
authorAvatarUrlstringpeut être null
bodystring
mentionsarray of string
createdAtstring (date-time)
editedAtstring (date-time)peut être null
ObjetsComment
{
  "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

Clé avec accès en lecture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.

Paramètres de requête

ChampTypeDescription
limitinteger1-500.

Par défaut: 100

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

Parmi: number, -number, -updatedAt

Par défaut: number

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

Parmi: true, false

Renvoie

200 OK A page of tasks

ChampTypeDescription
tasksarray of Task
nextCursorstringpeut être null
Requête
curl "https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks?externalId=crm-4711" \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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

Clé avec accès en écriture

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.

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.

Corps de la requête

TaskCreate

ChampTypeDescription
name
obligatoire
string
parentIdstring (uuid)peut être nullParent (summary) task; null = top level.
afterTaskIdstring (uuid)peut être nullInsert after this sibling.
beforeTaskIdstring (uuid)peut être nullInsert before this sibling.
typestring

Parmi: summary, task, milestone

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

Parmi: 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)peut être null
deadlinestring (date-time)peut être null
calendarIdstring (uuid)peut être null
costFixednumber
notesstringpeut être null
colorstringpeut être null
wbsstringpeut être null
externalIdstringpeut être nullYour identifier for this task in another system. Searchable with GET /tasks?externalId=.

ou ChangeSet

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

Renvoie

201 Created Task created

ChampTypeDescription
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
Afficher les champs de stats
ChampTypeDescription
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
Requête
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"}'
Réponse201 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}

Clé avec accès en lecture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.
taskId
obligatoire
string (uuid)Task id.

Renvoie

200 OK The task

ChampTypeDescription
taskTask
Requête
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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}

Clé avec accès en écriture

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

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.
taskId
obligatoire
string (uuid)Task id.

Corps de la requête

ChampTypeDescription
namestring
typestring

Parmi: summary, task, milestone

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

Parmi: 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)peut être null
deadlinestring (date-time)peut être null
calendarIdstring (uuid)peut être null
costFixednumber
notesstringpeut être null
colorstringpeut être null
wbsstringpeut être null
externalIdstringpeut être nullYour identifier for this task in another system. Searchable with GET /tasks?externalId=.
placementobject
Afficher les champs de placement
ChampTypeDescription
parentIdstring (uuid)peut être nullParent (summary) task; null = top level.
afterTaskIdstring (uuid)peut être nullInsert after this sibling.
beforeTaskIdstring (uuid)peut être nullInsert before this sibling.

Renvoie

200 OK Updated

ChampTypeDescription
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
Afficher les champs de stats
ChampTypeDescription
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
Requête
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}'
Réponse200 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

Clé avec accès en lecture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.
taskId
obligatoire
string (uuid)Task id.

Renvoie

200 OK Comments

ChampTypeDescription
commentsarray of Comment
Requête
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks/4dbd104a-00cd-4035-8955-255f52ea586a/comments \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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

Clé avec accès en écriture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.
taskId
obligatoire
string (uuid)Task id.

Corps de la requête

ChampTypeDescription
body
obligatoire
stringPlain text.
mentionsarray of stringUser ids to notify.

Renvoie

201 Created Created

ChampTypeDescription
commentComment
Requête
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."}'
Réponse201 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
  }
}

Référence de l’API

Dependencies

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

Dependency

Attributs

ChampTypeDescription
idstring (uuid)
predecessorIdstring (uuid)
successorIdstring (uuid)
typestring

Parmi: FS, SS, FF, SF

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

Clé avec accès en lecture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.

Renvoie

200 OK Dependencies

ChampTypeDescription
dependenciesarray of Dependency
Requête
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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

Clé avec accès en écriture

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

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.

Corps de la requête

DependencyCreate

ChampTypeDescription
predecessorId
obligatoire
string (uuid)
successorId
obligatoire
string (uuid)
typestring

Parmi: FS, SS, FF, SF

Par défaut: FS

lagMininteger

Par défaut: 0

ou dependencies

ChampTypeDescription
dependencies
obligatoire
array of DependencyCreate

Renvoie

201 Created Created

ChampTypeDescription
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
Afficher les champs de stats
ChampTypeDescription
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
Requête
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
}'
Réponse201 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}

Clé avec accès en écriture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.
dependencyId
obligatoire
string (uuid)

Renvoie

200 OK Removed

ChampTypeDescription
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
Afficher les champs de stats
ChampTypeDescription
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
Requête
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"
Réponse200 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
  }
}

Référence de l’API

People

Project members and task assignees.

Member

Attributs

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

Parmi: owner, editor, viewer

directRolestringpeut être nullRole granted on the project itself (null = only through the workspace).

Parmi: owner, editor, viewer

inheritedbooleanAccess comes from the workspace.
resourceIdstring (uuid)peut être nullResource used when the person is assigned to tasks.
addedAtstring (date-time)
avatarUrlstringpeut être null
ObjetsMember
{
  "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

Attributs

ChampTypeDescription
resourceIdstring (uuid)
userIdstring (uuid)peut être null
namestring
unitsPctinteger
ObjetsAssignee
{
  "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

Clé avec accès en écriture

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.

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.
taskId
obligatoire
string (uuid)Task id.

Corps de la requête

ChampTypeDescription
userIds
obligatoire
array of string
resourceIdsarray of string

Renvoie

200 OK Assignees saved

ChampTypeDescription
taskIdstring (uuid)
assignmentsarray of object
Afficher les champs de assignments
ChampTypeDescription
idstring (uuid)
taskIdstring (uuid)
resourceIdstring (uuid)
unitsPctinteger
workMininteger
resourcesarray of object
Afficher les champs de resources
ChampTypeDescription
idstring (uuid)
userIdstring (uuid)peut être null
namestring
kindstring

Parmi: work, material, cost

emailstringpeut être null
costPerHournumber
costPerUsenumber
capacityPctinteger
calendarIdstring (uuid)peut être null
colorstringpeut être null
avatarUrlstringpeut être null
needsRescheduleboolean
conflictsarray of Conflict
Requête
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"]}'
Réponse200 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

Clé avec accès en lecture

Paramètres de chemin

ChampTypeDescription
projectId
obligatoire
string (uuid)Project id.

Renvoie

200 OK Members

ChampTypeDescription
membersarray of Member
rolestring
Requête
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/members \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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"
}

Référence de l’API

Webhooks

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

Webhook

Attributs

ChampTypeDescription
idstring (uuid)
workspaceIdstring (uuid)
workspaceNamestring
projectIdstring (uuid)peut être nullnull = every project of the workspace.
projectNamestringpeut être null
namestring
urlstring (uri)
eventsarray of string

Parmi: 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
disabledReasonstringpeut être null

Parmi: failures, gone, project_deleted, user

disabledAtstring (date-time)peut être null
consecutiveFailuresinteger
viaApibooleanCreated with the API (REST hook) rather than from the profile.
createdByobjectpeut être null
Afficher les champs de createdBy
ChampTypeDescription
idstring (uuid)
namestringpeut être null
createdAtstring (date-time)
updatedAtstring (date-time)
lastDeliveryAtstring (date-time)peut être null
lastSuccessAtstring (date-time)peut être null
ObjetsWebhook
{
  "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

Attributs

ChampTypeDescription
idstring (uuid)
eventIdstring (uuid)
eventTypestring
statusstring

Parmi: pending, success, failed, cancelled

attemptsinteger
nextAttemptAtstring (date-time)peut être null
lastAttemptAtstring (date-time)peut être null
responseStatusintegerpeut être null
responseExcerptstringpeut être null
errorstringpeut être null
durationMsintegerpeut être null
manualboolean
createdAtstring (date-time)
ObjetsDelivery
{
  "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

Attributs

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

Parmi: 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
obligatoire
string

Parmi: 2026-10-01

createdAt
obligatoire
string (date-time)
workspaceId
obligatoire
string (uuid)
projectIdstring (uuid)peut être null
actorobjectpeut être nullWho made the change (null for system changes).
Afficher les champs de actor
ChampTypeDescription
idstring (uuid)
namestringpeut être null
data
obligatoire
object
ObjetsEvent
{
  "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.

Attributs

ChampTypeDescription
idstring (uuid)
workspaceIdstring (uuid)
keystring
namestring
descriptionstringpeut être null
startDatestring (date)
deadlinestring (date)peut être null
currencystring
scheduleFromstring

Parmi: forward, backward

colorstringpeut être null
archivedboolean
createdAtstring (date-time)
updatedAtstring (date-time)
urlstring (uri)
ObjetsProject (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

Clé avec accès en lecture

Paramètres de requête

ChampTypeDescription
workspaceIdstring (uuid)
projectIdstring (uuid)

Renvoie

200 OK Subscriptions

ChampTypeDescription
webhooksarray of Webhook
Requête
curl https://planitude.app/api/webhooks \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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

Clé avec accès en écriture

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.

Corps de la requête

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

Parmi: 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)

Renvoie

201 Created Created

ChampTypeDescription
webhookWebhook
secretstringwhsec_...
Requête
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"
}'
Réponse201 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, sans clé

Renvoie

200 OK Events

ChampTypeDescription
apiVersionstring
eventsarray of string
Requête
curl https://planitude.app/api/webhooks/events
Réponse200 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}

Clé avec accès en lecture

Paramètres de chemin

ChampTypeDescription
webhookId
obligatoire
string (uuid)Webhook id.

Renvoie

200 OK Subscription

ChampTypeDescription
webhookWebhook
Requête
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88 \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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}

Clé avec accès en écriture

Paramètres de chemin

ChampTypeDescription
webhookId
obligatoire
string (uuid)Webhook id.

Corps de la requête

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

Renvoie

200 OK Updated

ChampTypeDescription
webhookWebhook
Requête
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}'
Réponse200 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}

Clé avec accès en écriture

Paramètres de chemin

ChampTypeDescription
webhookId
obligatoire
string (uuid)Webhook id.

Renvoie

204 No Content Deleted

Requête
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

Clé avec accès en lecture

Paramètres de chemin

ChampTypeDescription
webhookId
obligatoire
string (uuid)Webhook id.

Paramètres de requête

ChampTypeDescription
limitinteger1-100.

Par défaut: 50

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

Renvoie

200 OK Deliveries

ChampTypeDescription
deliveriesarray of Delivery
nextCursorstringpeut être null
Requête
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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}

Clé avec accès en lecture

Paramètres de chemin

ChampTypeDescription
webhookId
obligatoire
string (uuid)Webhook id.
deliveryId
obligatoire
string (uuid)

Renvoie

200 OK Payload

ChampTypeDescription
payloadEvent
Requête
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries/4b207161-80f9-40bb-bc3f-d8f70315be00 \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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

Clé avec accès en écriture

Paramètres de chemin

ChampTypeDescription
webhookId
obligatoire
string (uuid)Webhook id.
deliveryId
obligatoire
string (uuid)

Renvoie

202 Accepted Queued

ChampTypeDescription
deliveryDelivery
Requête
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"
Réponse202 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

Clé avec accès en écriture

Paramètres de chemin

ChampTypeDescription
webhookId
obligatoire
string (uuid)Webhook id.

Renvoie

202 Accepted Queued

ChampTypeDescription
deliveryDelivery
Requête
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse202 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

Clé avec accès en écriture

Paramètres de chemin

ChampTypeDescription
webhookId
obligatoire
string (uuid)Webhook id.

Renvoie

200 OK New secret (shown once)

ChampTypeDescription
webhookWebhook
secretstring
Requête
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/rotate-secret \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse200 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

Les webhooks envoient un POST HTTPS avec un corps JSON à votre endpoint dès que quelque chose change, que le changement vienne de l’app web, de l’API, du serveur MCP ou d’un import. Un webhook couvre un projet, ou tous les projets d’un workspace (propriétaires et administrateurs).

Créez-les dans Profil → Webhooks ou avec l’API, en REST hooks : abonnement avec POST /api/webhooks, désabonnement avec DELETE. Le secret de signature ne s’affiche qu’une fois.

Chaque requête porte ces en-têtes :

En-têteDescription
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
Requête
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"
}'
Réponse201 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"
}

Types d’événements

Abonnez-vous à des événements précis, ou à * pour tous les recevoir. Chaque événement a la même enveloppe ; data change selon le type.

ÉvénementDescription
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.
Payload d’exemple
{
  "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"
  }
}

Vérifier les signatures

Chaque requête est signée avec HMAC-SHA256 et le secret de votre webhook. L’en-tête Planitude-Signature contient un horodatage t et la signature v1, calculée sur t, un point et le corps brut.

  1. Utilisez le corps brut, avant tout parsing JSON : un corps resérialisé a une autre signature.
  2. Calculez le HMAC et comparez-le en temps constant.
  3. Refusez les requêtes dont l’horodatage s’écarte de plus de 5 minutes de votre horloge : une requête interceptée ne peut pas être rejouée.
  4. Renouvelez le secret quand vous voulez : l’ancien cesse aussitôt de fonctionner.
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
// });

Nouvelles tentatives et livraison

Répondez par n’importe quel 2xx en moins de 10 secondes et faites le vrai travail ensuite, dans une file. Les redirections ne sont pas suivies. En cas d’erreur ou de délai dépassé, Planitude essaie jusqu’à 6 fois au total : immédiatement, puis après 1 min, 5 min, 30 min, 2 h, 12 h.

La livraison est au moins une fois et sans ordre garanti. Conservez l’id de l’événement (Planitude-Event-Id, aussi id dans le corps) et ignorez ceux déjà traités ; triez par createdAt.

Après 5 événements d’affilée en échec à chaque tentative, le webhook est désactivé et son propriétaire reçoit un e-mail. Une réponse 410 Gone le désactive aussitôt. Réactivez-le depuis le profil, ou avec PATCH et active: true.

Le journal des livraisons (statut, code HTTP, extrait de réponse, payload, renvoi manuel) est conservé 30 jours. Seules les adresses publiques sont acceptées comme destination.

Calendrier des tentatives6 × POST
Tentative 1   immédiatement
Tentative 2   + 1 min
Tentative 3   + 5 min
Tentative 4   + 30 min
Tentative 5   + 2 h
Tentative 6   + 12 h

Tester votre endpoint

  1. Envoyez un événement webhook.ping avec l’endpoint de test, ou avec le bouton Tester du profil.
  2. Pour recevoir des événements sur votre ordinateur, exposez votre serveur local avec un tunnel (par exemple ngrok ou Cloudflare Tunnel) et abonnez son adresse HTTPS publique.
  3. Ouvrez le journal des livraisons pour voir statut, code HTTP et réponse, et renvoyez une livraison une fois l’endpoint corrigé.
Requête
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Réponse202 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"
  }
}

IA et MCP

Serveur MCP

Planitude est un serveur MCP (Model Context Protocol) : assistants d’IA et éditeurs de code lisent les projets, analysent le chemin critique et la charge, créent et modifient des tâches, avec vos droits. Les apps web se connectent en OAuth (vous vous connectez et autorisez l’accès) ; les outils en ligne de commande et les éditeurs utilisent une clé API.

URL du serveur

https://planitude.app/mcp

  • ChatGPTOAuth

    Dans ChatGPT, ouvrez Paramètres › Sécurité et connexion et activez le mode développeur. Créez une app avec l’URL du serveur et l’authentification OAuth, puis connectez-vous à Planitude et autorisez l’accès.

    Documentation officielle ↗
  • ClaudeOAuth

    Ouvrez Personnaliser › Connecteurs › Ajouter un connecteur personnalisé, collez l’URL du serveur et choisissez Connecter : Planitude s’ouvre, vous vous connectez et autorisez l’accès. Fonctionne sur claude.ai, Claude Desktop et l’app mobile.

    Documentation officielle ↗
  • GeminiOAuth

    Sur gemini.google.com, ouvrez Paramètres › Applications connectées, choisissez Ajouter une application personnalisée et collez l’URL du serveur ; connectez-vous ensuite à Planitude et autorisez l’accès.

    Documentation officielle ↗
  • Claude CodeClé API

    Lancez la commande avec la clé dans une variable d’environnement. Ajoutez --scope user pour l’utiliser dans tous les projets et vérifiez avec claude mcp list.

    Documentation officielle ↗
  • CodexClé API

    Placez la clé dans PLANITUDE_API_KEY et ajoutez le bloc à ~/.codex/config.toml : il vaut pour la CLI, l’app et l’extension d’IDE.

    Documentation officielle ↗
  • CursorClé API

    Ajoutez le bloc à ~/.cursor/mcp.json (tous les projets) ou .cursor/mcp.json (un projet) ; Cursor lit la clé dans l’environnement.

    Documentation officielle ↗
  • Ajoutez .vscode/mcp.json au workspace : VS Code demande la clé une fois et la conserve en sécurité, hors du fichier.

    Documentation officielle ↗
  • Gemini CLIClé API

    Lancez la commande avec la clé dans une variable d’environnement, ou ajoutez le bloc à ~/.gemini/settings.json.

    Documentation officielle ↗

Outils

Le serveur propose 29 outils, de la lecture et de l’analyse aux modifications sûres. Aucun ne supprime de projets ni de tâches.

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

Agents IA

Ajoutez jusqu’à 5 agents IA externes à l’espace de travail comme membres : Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot ou tout client MCP. Assignez-leur des tâches, mentionnez-les en commentaire et validez leurs modifications.

Les owners et admins créent les clés d’agent dans Agents, onglet Connexion. Une clé commence par pln_, n’est affichée qu’une fois et n’est stockée que sous forme de hash ; chaque agent a au plus 2 clés et la révocation est immédiate.

Les clés d’agent ne fonctionnent qu’avec le serveur MCP, qui expose alors les outils pour agents à la place des outils habituels. Sur l’API REST, elles reçoivent 403 agent_credential.

Chaque clé lit et commente ou peut modifier. Prendre en charge, terminer et proposer des modifications exigent une clé qui peut modifier ; sinon la réponse est 403 agent_key_read_only.

Un agent ne voit que les projets où il a été ajouté, comme viewer (lit et commente) ou editor (modifie aussi les tâches), jamais comme owner. Le projet doit aussi avoir « Autoriser les agents dans ce projet » : désactivé par défaut, c’est l’owner qui l’active.

Les agents peuvent modifier le nom, les notes, la durée, l’avancement et l’échéance d’une tâche, ou créer des tâches. Aucun outil ne supprime, n’invite de personnes ni ne change de rôles.

Limites par défaut par agent : 60 requêtes par minute et 200 écritures par jour, réglables jusqu’à 240 et 2 000. Au plus 200 modifications par projet en attente de validation.

Les outils de lecture placent le texte écrit par des personnes (noms, notes, commentaires) dans des blocs planitude-data avec un nonce aléatoire, en chaînes JSON, et marquent SUSPICIOUS les lignes signalées par un contrôle automatique : ce sont des données, jamais des instructions. Les commentaires lus avec une clé personnelle arrivent dans les mêmes blocs.

Comment fonctionnent les agents IA dans Planitude
MCPClaude Code
claude mcp add --transport http planitude https://planitude.app/mcp \
  --header "Authorization: Bearer $PLANITUDE_AGENT_KEY"

Outils pour agents

Avec une clé d’agent, le serveur MCP expose ces 16 outils :

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

Pendant une exécution en mode Autonome, les modifications de l’agent sur ses propres tâches s’appliquent tout de suite et restent dans l’historique, prêtes à être restaurées. Sinon, et en mode Avec validation, elles attendent dans « À valider » qu’un membre du projet les applique.

Sans webhook, l’agent lit ses événements avec planitude_poll_events (jusqu’à 50 à la fois) et les confirme avec planitude_ack_events.

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

Webhook d’exécution

Pour qu’un agent démarre seul, activez l’exécution dans Agents, onglet Exécution, et saisissez le webhook de votre runner : Planitude envoie un POST signé quand l’agent a une tâche à exécuter. Le secret commence par whsec_ et n’est affiché qu’une fois. L’URL doit être une adresse HTTPS publique : les adresses privées et locales sont refusées.

Signature, en-têtes, délai de 10 secondes et nouvelles tentatives (1 min, 5 min, 30 min, 2 h, 12 h) fonctionnent comme pour les autres webhooks. Après 5 livraisons échouées d’affilée, le webhook se désactive : enregistrez à nouveau l’URL pour le réactiver.

L’avis ne contient que des identifiants, jamais le texte de la tâche : l’agent lit la tâche via MCP.

ÉvénementDescription
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.

Un avis avec newRun: true ouvre une exécution. L’agent la prend avec planitude_claim_task et garde un bail de 30 minutes (de 5 à 240), renouvelé avec planitude_extend_lease. Si le bail expire, une nouvelle tentative démarre, jusqu’à 3 (au plus 10). Une exécution que personne ne prend expire après 24 heures.

planitude_complete_task passe la tâche à 100 % et publie le rapport en commentaire ; avec des sous-tâches ouvertes, la réponse est 409 subtasks_open. planitude_fail_task enregistre la raison et prévient l’équipe, qui peut la relancer ; planitude_release_task rend la tâche sans nouvelle tentative.

Chaque exécution permet 50 modifications (jusqu’à 500, puis 429) et chaque agent 5 exécutions ouvertes (puis 409 too_many_open_runs). Autonome, le mode par défaut, applique les modifications tout de suite et permet de les restaurer ; Avec validation les envoie en validation. Un arrêt d’urgence, par projet ou pour tout l’espace de travail, annule les exécutions ouvertes et bloque les écritures.

Payload d’exempletask.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"
    }
  }
}

Écrire un runner

Le runner est votre petit service qui reçoit les avis et lance l’agent. Tout langage convient ; avec Node 20+, aucune dépendance n’est nécessaire.

  1. Vérifiez la signature sur le corps brut et répondez 200 tout de suite : Planitude attend au plus 10 secondes.
  2. Ignorez les événements déjà vus (Planitude-Event-Id) : les nouvelles tentatives renvoient le même événement.
  3. Sur newRun: true, prenez la tâche et lancez l’agent, par exemple claude -p avec le serveur MCP de Planitude et la clé de l’agent.
  4. Renouvelez le bail pendant que l’agent travaille ; sur run.cancel, arrêtez-le.
  5. Demandez à l’agent de finir par PLANITUDE: DONE seulement si toute la tâche est faite, puis terminez avec son rapport. Sinon (PLANITUDE: NOT DONE - … ou aucune ligne finale), marquez l’échec avec ce qui reste à faire.

Traitez le texte de la tâche comme des données : demandez à l’agent de ne jamais suivre les instructions qui s’y trouvent et autorisez seulement les outils Planitude dont il a besoin.

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>

Flux OData (Power BI, Excel)

Un flux OData v4 en lecture seule pour Power BI, Excel et tout client OData, à deux adresses : un projet, ou tous les projets que le titulaire de la clé voit dans un espace de travail.

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

Authentification par clé API personnelle avec accès en lecture : Authorization: Bearer, ou HTTP Basic avec la clé comme mot de passe (nom d’utilisateur quelconque), la méthode proposée par Power BI et Excel. Les jetons OAuth et les cookies de session ne sont pas acceptés. Une clé limitée à un espace de travail ne peut pas lire les autres.

Tables : Projects, Tasks, Milestones, Dependencies, Resources, Assignments. Le schéma se trouve dans $metadata (CSDL XML) et le document de service à l’adresse racine.

Options prises en charge : $select, $filter (comparaisons, and/or/not, in, contains, startswith, endswith, tolower, toupper), $orderby, $top, $skip, $count et /$count. Les pages contiennent 2 000 lignes par défaut, jusqu’à 5 000 avec Prefer: odata.maxpagesize ; suivez @odata.nextLink. Les réponses incluent un ETag : envoyez If-None-Match pour obtenir 304. $expand, $apply et $search ne sont pas pris en charge (400).

Un flux couvre au maximum 500 projets et 25 000 tâches (au-delà, 413). Les requêtes sont décomptées de la limite de lecture de la clé, 240 par minute.

Guide pas à pas pour Power BI et Excel
RequêtecURL
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"
Réponse200 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
    }
  ]
}

Nouveautés

  1. Nouveau flux OData v4 en lecture seule sur /api/odata/projects/:projectId et /api/odata/workspaces/:workspaceId pour Power BI, Excel et autres clients OData : six tables, $metadata, $select, $filter, $orderby, $top, $skip, $count, pagination côté serveur et ETag.

  2. Nouveau point de terminaison GET /api/projects/:projectId/export : le planning en XML Microsoft Project, CSV, image PNG ou PDF, avec des options d’échelle, de période, de chemin critique, de référence, de dépendances, de format de papier et d’orientation.

  3. Toutes les clés API commencent désormais par pln_. Les clés qui commencent par gnt_ ne fonctionnent plus : créez-en une nouvelle.

  4. Les agents exécutent les tâches : webhook d’exécution signé (task.assigned, task.start_due, task.due_today, task.overdue, run.retry, run.cancel), 6 outils d’exécution avec bail et un guide pour écrire un runner.

  5. Les outils MCP de lecture enveloppent le texte écrit par des personnes dans des blocs planitude-data avec un nonce, en chaînes JSON avec la marque SUSPICIOUS, pour tous les types de clé.

  6. Agents IA comme membres de l’espace de travail : clés d’agent valables uniquement avec le serveur MCP, 10 outils pour lire, commenter et proposer des modifications, et une file d’événements.

  7. Nouvelle documentation développeurs, générée à partir du document OpenAPI. Le document OpenAPI décrit désormais tous les champs renvoyés pour les membres, commentaires, références, modèles et affectations.

  8. Version d’API 2026-10-01 : webhooks sortants signés, API REST publique documentée (OpenAPI 3.1), pagination par curseur et recherche par externalId.

  9. OAuth 2.1 pour le serveur MCP et l’API : ChatGPT, Claude et Gemini se connectent sans copier de clé.

  10. Serveur MCP et clés API personnelles en lecture ou en lecture et écriture.

La publicité permet à Planitude de rester gratuit