Sviluppatori

Costruisci con Planitude

Un’API REST, webhook firmati e un server MCP: tieni i tuoi sistemi allineati al piano, reagisci a ogni modifica e fai lavorare un assistente AI sui tuoi progetti.

Codice, nomi dei campi e riferimento tecnico sono in inglese, come nella maggior parte delle documentazioni API.

URL di base: https://planitude.app

Richieste e risposte sono JSON su HTTPS. Durate e ritardi sono in minuti lavorativi (una giornata di 8 ore vale 480), gli istanti sono ISO 8601 in UTC, le date senza ora sono YYYY-MM-DD.

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

Avvio rapido

Da zero al primo webhook in tre passi. Basta un terminale.

  1. Crea una chiave API

    Apri Profilo → Chiavi API, scegli Lettura e scrittura e copia la chiave: inizia con pln_ e viene mostrata una sola volta. Tienila in una variabile d’ambiente.

  2. Fai la prima chiamata

    Elenca i progetti che vedi. La chiave agisce come te: stessi progetti, stessi ruoli.

  3. Ricevi un webhook

    Iscrivi un endpoint HTTPS pubblico agli eventi che ti servono, poi invia subito un evento di prova e verificane la firma.

1Terminal
export PLANITUDE_API_KEY="pln_…"
2
curl https://planitude.app/api/projects \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risultato atteso200 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’esempiowebhook.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"
      ]
    }
  }
}

Autenticazione

Autentica ogni richiesta con una chiave API personale nell’intestazione Authorization, come bearer token. Le chiavi sono personali: agiscono come te, con il tuo ruolo in ogni progetto, mai di più. Puoi limitare una chiave a un workspace, darle una scadenza e revocarla quando vuoi; ogni chiamata è registrata accanto alla chiave.

Scope

ScopeConsente
readplanitude:readLeggere progetti, attività, dipendenze, membri, commenti, baseline e webhook.
writeplanitude:writeTutto ciò che consente la lettura, più creare e modificare progetti, attività, dipendenze, commenti, baseline e webhook.

Chiavi e app OAuth non possono eliminare progetti o attività: l’eliminazione resta nell’app web, dove una persona la conferma. Uno script che punta all’id sbagliato non può cancellare un piano.

OAuth 2.1 per le app di terze parti

Le app che agiscono per conto di altre persone usano OAuth 2.1: authorization code con PKCE (S256), refresh token ruotati a ogni uso, registrazione dinamica dei client (RFC 7591). Chiedi la risorsa https://planitude.app/api e lo scope planitude:read o planitude:write.

Gli endpoint sono pubblicati nei documenti di discovery standard, così le librerie OAuth si configurano da sole.

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

Buone pratiche

  • Tieni le chiavi in variabili d’ambiente o in un gestore di segreti, mai nel codice o in un repository. Le chiavi iniziano con pln_, così gli scanner di segreti le riconoscono.
  • Usa una chiave in sola lettura quando leggi soltanto, e una chiave per ogni integrazione: puoi revocarne una senza fermare le altre.
  • Dai una scadenza alle chiavi usate dagli script e ruotale.
  • Chiama l’API dal tuo server, non dal browser: una chiave nel codice front-end è una chiave pubblica.
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"
  ]
}

Errori

Planitude usa i codici di stato HTTP standard. Gli errori hanno sempre la stessa forma JSON: un codice error stabile su cui decidere e, quando serve, details con il motivo o i campi da correggere.

StatoSignificato
400invalid_requestLa richiesta non è valida: details.fields elenca ogni campo con il problema.
401unauthorizedLa chiave manca, non è valida, è revocata o scaduta.
403forbiddenLa chiave o il tuo ruolo non lo consentono (details.reason), per esempio una scrittura con una chiave in sola lettura, o un’eliminazione.
404not_foundNon trovato, o non visibile per te.
409dependency_cycleConflitto con il piano, per esempio una dipendenza che chiuderebbe un ciclo (dependency_cycle).
429rate_limitedTroppe richieste: attendi i secondi indicati in Retry-After.
500server_errorErrore da parte nostra: riprova con un’attesa esponenziale.

Error

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

Limiti di frequenza

I limiti valgono per chiave, in una finestra mobile di un minuto: 240 richieste di lettura e 60 di scrittura. Oltre il limite ricevi 429 rate_limited con l’intestazione Retry-After, in secondi.

Attendi Retry-After prima di riprovare, distribuisci nel tempo i lavori massivi e raggruppa molte modifiche in un change set: fino a 1000 modifiche in una richiesta e un solo ricalcolo.

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

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

Paginazione e ricerca

Gli elenchi di attività sono paginati con un cursore. Passa limit (1–500, predefinito 100) e, per la pagina successiva, il nextCursor della risposta precedente come cursor. Quando nextCursor è null non ci sono altre pagine.

Filtra con externalId (corrispondenza esatta con il tuo identificativo), q (il nome contiene), updatedSince e completed; ordina con sort=-number (prima le più recenti) o -updatedAt. Gli elenchi più brevi, come progetti, membri e dipendenze, arrivano interi in una sola risposta.

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

Versioni

L’API e i payload dei webhook hanno versioni datate. La versione attuale è 2026-10-01: è il campo apiVersion di ogni evento e l’info.version del documento OpenAPI.

All’interno di una versione aggiungiamo soltanto: nuovi endpoint, nuovi campi facoltativi, nuovi tipi di evento. Nessun campo viene tolto o cambia tipo senza una nuova versione, quindi ignora i campi che non conosci.

Richiesta
curl https://planitude.app/api/webhooks/events
Risposta200 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"
  ]
}

Riferimento API

Account

Who is calling, and their workspaces.

User

Attributi

CampoTipoDescrizione
idstring (uuid)
emailstring (email)
namestringpuò essere null
avatarUrlstringpuò essere null
localestring
emailVerifiedboolean
OggettiUser
{
  "id": "b1666432-132a-4ea9-b1ae-76ea69e226c5",
  "email": "anna@example.com",
  "name": "Anna Rossi",
  "avatarUrl": null,
  "locale": "en",
  "emailVerified": true
}

Workspace

Attributi

CampoTipoDescrizione
idstring (uuid)
namestring
rolestring

Uno tra: owner, admin, member

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

Current user (connection test)

GET/api/auth/me

Chiave con accesso in lettura

Restituisce

200 OK The user

CampoTipoDescrizione
userUser
Richiesta
curl https://planitude.app/api/auth/me \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta200 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

Chiave con accesso in lettura

Restituisce

200 OK Workspaces

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

Riferimento API

Projects

Projects, templates and baselines.

Project

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

Attributi

CampoTipoDescrizione
idstring (uuid)
workspaceIdstring (uuid)
keystringProject key, e.g. CRON (task keys are CRON-12).
keyLockedboolean
namestring
descriptionstringpuò essere null
startDatestring (date)
calendarIdstring (uuid)può essere null
currencystring
scheduleFromstring

Uno tra: forward, backward

deadlinestring (date)può essere null
colorstringpuò essere null
settingsobject
archivedAtstring (date-time)può essere null
createdBystring (uuid)può essere null
createdAtstring (date-time)
updatedAtstring (date-time)
OggettiProject
{
  "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

Attributi

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

Uno tra: builtin, user

namestring
descriptionstringpuò essere null
taskCountinteger
durationDaysintegerWorking days from start to finish.
OggettiTemplate
{
  "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

Attributi

CampoTipoDescrizione
idstring (uuid)
namestring
indexintegerpuò essere nullNumbered MS Project baseline (1-10); null for the main baseline and the ones you name.
capturedAtstring (date-time)
capturedBystring (uuid)può essere null
taskCountinteger
OggettiBaseline
{
  "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

Chiave con accesso in lettura

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

Parametri di query

CampoTipoDescrizione
archivedstring

Uno tra: 1

Restituisce

200 OK Projects

CampoTipoDescrizione
projectsarray of Project
Richiesta
curl https://planitude.app/api/projects \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta200 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

Chiave con accesso in scrittura

Corpo della richiesta

CampoTipoDescrizione
name
obbligatorio
string
workspaceIdstring (uuid)Defaults to your personal workspace.
keystring2-5 letters/digits, starts with a letter. Derived from the name if omitted.
descriptionstringpuò essere null
startDatestring (date)
deadlinestring (date)può essere null
currencystring
scheduleFromstring

Uno tra: forward, backward

colorstringpuò essere null

Restituisce

201 Created Created

CampoTipoDescrizione
projectProject
Richiesta
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"}'
Risposta201 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

Chiave con accesso in scrittura

Corpo della richiesta

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

Restituisce

201 Created Created

CampoTipoDescrizione
projectProject
taskCountinteger
conflictsarray of Conflict
Richiesta
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"
}'
Risposta201 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

Chiave con accesso in lettura

Parametri di query

CampoTipoDescrizione
localestring

Restituisce

200 OK Templates

CampoTipoDescrizione
templatesarray of Template
Richiesta
curl https://planitude.app/api/templates \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta200 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}

Chiave con accesso in lettura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.

Restituisce

200 OK Project

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

Chiave con accesso in scrittura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.

Corpo della richiesta

CampoTipoDescrizione
namestring
descriptionstringpuò essere null
startDatestring (date)
deadlinestring (date)può essere null
currencystring
scheduleFromstring

Uno tra: forward, backward

colorstringpuò essere null
archivedboolean

Restituisce

200 OK Updated

CampoTipoDescrizione
projectProject
conflictsarray of Conflict
rescheduledbooleanThe schedule was recalculated (start date, calendar or direction changed).
Richiesta
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"}'
Risposta200 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

Chiave con accesso in lettura

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

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.

Parametri di query

CampoTipoDescrizione
formatstringFile format. mspdi = Microsoft Project XML.

Uno tra: mspdi, csv, png, pdf

Predefinito: mspdi

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

Predefinito: en

scalestringPNG/PDF: time unit of the columns.

Uno tra: auto, day, week, month, quarter

Predefinito: 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.

Uno tra: 0, 1

Predefinito: 1

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

Uno tra: 0, 1

Predefinito: 1

linksstringPNG/PDF: draw dependency arrows.

Uno tra: 0, 1

Predefinito: 1

paperstringPDF: paper size.

Uno tra: a4, a3, letter

Predefinito: a4

orientationstringPDF: page orientation.

Uno tra: landscape, portrait

Predefinito: landscape

Restituisce

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

Richiesta
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

Chiave con accesso in lettura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.

Restituisce

200 OK Baselines

CampoTipoDescrizione
baselinesarray of Baseline
Richiesta
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/baseline \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta200 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

Chiave con accesso in scrittura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.

Corpo della richiesta

CampoTipoDescrizione
namestring

Restituisce

201 Created Saved

CampoTipoDescrizione
baselineBaseline
Richiesta
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"}'
Risposta201 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
  }
}

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

Attributi

CampoTipoDescrizione
idstring (uuid)
numberintegerSequential number in the project, never reused.
keystringHuman key, e.g. CRON-12.
parentIdstring (uuid)può essere null
namestring
typestring

Uno tra: summary, task, milestone

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

Uno tra: 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)può essere null
deadlinestring (date-time)può essere null
calendarIdstring (uuid)può essere null
costFixednumber
notesstringpuò essere null
colorstringpuò essere null
wbsstringpuò essere null
externalIdstringpuò essere nullYour identifier for this task in another system. Searchable with GET /tasks?externalId=.
startAtstring (date-time)può essere nullComputed start.
finishAtstring (date-time)può essere nullComputed finish.
isCriticalbooleanOn the critical path.
totalFloatMinintegerpuò essere nullTotal float (slack) in working minutes.
earlyStartAtstring (date-time)può essere null
lateFinishAtstring (date-time)può essere null
actualStartAtstring (date-time)può essere null
actualFinishAtstring (date-time)può essere null
actualDurationMinintegerpuò essere null
remainingDurationMinintegerpuò essere null
manuallyScheduledboolean
levelingDelayMininteger
taskTypestring

Uno tra: fixed_units, fixed_duration, fixed_work, fixed_duration_and_units

effortDrivenboolean
durationOptimisticMinintegerpuò essere null
durationPessimisticMinintegerpuò essere null
projectIdstring (uuid)
completedbooleanprogressPct = 100.
assigneesarray of Assignee
urlstring (uri)Page of the task in the web app.
OggettiTask
{
  "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

Attributi

CampoTipoDescrizione
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
Mostra i campi di stats
CampoTipoDescrizione
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
OggettiWriteResult
{
  "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

Attributi

CampoTipoDescrizione
idstring (uuid)
taskIdstring (uuid)
userIdstring (uuid)
authorNamestring
authorAvatarUrlstringpuò essere null
bodystring
mentionsarray of string
createdAtstring (date-time)
editedAtstring (date-time)può essere null
OggettiComment
{
  "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

Chiave con accesso in lettura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.

Parametri di query

CampoTipoDescrizione
limitinteger1-500.

Predefinito: 100

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

Uno tra: number, -number, -updatedAt

Predefinito: number

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

Uno tra: true, false

Restituisce

200 OK A page of tasks

CampoTipoDescrizione
tasksarray of Task
nextCursorstringpuò essere null
Richiesta
curl "https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/tasks?externalId=crm-4711" \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta200 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

Chiave con accesso in scrittura

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.

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.

Corpo della richiesta

TaskCreate

CampoTipoDescrizione
name
obbligatorio
string
parentIdstring (uuid)può essere nullParent (summary) task; null = top level.
afterTaskIdstring (uuid)può essere nullInsert after this sibling.
beforeTaskIdstring (uuid)può essere nullInsert before this sibling.
typestring

Uno tra: summary, task, milestone

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

Uno tra: 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)può essere null
deadlinestring (date-time)può essere null
calendarIdstring (uuid)può essere null
costFixednumber
notesstringpuò essere null
colorstringpuò essere null
wbsstringpuò essere null
externalIdstringpuò essere nullYour identifier for this task in another system. Searchable with GET /tasks?externalId=.

oppure ChangeSet

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

Restituisce

201 Created Task created

CampoTipoDescrizione
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
Mostra i campi di stats
CampoTipoDescrizione
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
Richiesta
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"}'
Risposta201 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}

Chiave con accesso in lettura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.
taskId
obbligatorio
string (uuid)Task id.

Restituisce

200 OK The task

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

Chiave con accesso in scrittura

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

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.
taskId
obbligatorio
string (uuid)Task id.

Corpo della richiesta

CampoTipoDescrizione
namestring
typestring

Uno tra: summary, task, milestone

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

Uno tra: 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)può essere null
deadlinestring (date-time)può essere null
calendarIdstring (uuid)può essere null
costFixednumber
notesstringpuò essere null
colorstringpuò essere null
wbsstringpuò essere null
externalIdstringpuò essere nullYour identifier for this task in another system. Searchable with GET /tasks?externalId=.
placementobject
Mostra i campi di placement
CampoTipoDescrizione
parentIdstring (uuid)può essere nullParent (summary) task; null = top level.
afterTaskIdstring (uuid)può essere nullInsert after this sibling.
beforeTaskIdstring (uuid)può essere nullInsert before this sibling.

Restituisce

200 OK Updated

CampoTipoDescrizione
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
Mostra i campi di stats
CampoTipoDescrizione
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
Richiesta
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}'
Risposta200 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

Chiave con accesso in lettura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.
taskId
obbligatorio
string (uuid)Task id.

Restituisce

200 OK Comments

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

Chiave con accesso in scrittura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.
taskId
obbligatorio
string (uuid)Task id.

Corpo della richiesta

CampoTipoDescrizione
body
obbligatorio
stringPlain text.
mentionsarray of stringUser ids to notify.

Restituisce

201 Created Created

CampoTipoDescrizione
commentComment
Richiesta
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."}'
Risposta201 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
  }
}

Riferimento API

Dependencies

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

Dependency

Attributi

CampoTipoDescrizione
idstring (uuid)
predecessorIdstring (uuid)
successorIdstring (uuid)
typestring

Uno tra: FS, SS, FF, SF

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

Chiave con accesso in lettura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.

Restituisce

200 OK Dependencies

CampoTipoDescrizione
dependenciesarray of Dependency
Richiesta
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/dependencies \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta200 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

Chiave con accesso in scrittura

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

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.

Corpo della richiesta

DependencyCreate

CampoTipoDescrizione
predecessorId
obbligatorio
string (uuid)
successorId
obbligatorio
string (uuid)
typestring

Uno tra: FS, SS, FF, SF

Predefinito: FS

lagMininteger

Predefinito: 0

oppure dependencies

CampoTipoDescrizione
dependencies
obbligatorio
array of DependencyCreate

Restituisce

201 Created Created

CampoTipoDescrizione
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
Mostra i campi di stats
CampoTipoDescrizione
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
Richiesta
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
}'
Risposta201 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}

Chiave con accesso in scrittura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.
dependencyId
obbligatorio
string (uuid)

Restituisce

200 OK Removed

CampoTipoDescrizione
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
Mostra i campi di stats
CampoTipoDescrizione
taskCountinteger
recomputedCountintegerTasks the scheduling engine recalculated.
savedCountintegerTasks whose stored values changed.
durationMsinteger
Richiesta
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"
Risposta200 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
  }
}

Riferimento API

People

Project members and task assignees.

Member

Attributi

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

Uno tra: owner, editor, viewer

directRolestringpuò essere nullRole granted on the project itself (null = only through the workspace).

Uno tra: owner, editor, viewer

inheritedbooleanAccess comes from the workspace.
resourceIdstring (uuid)può essere nullResource used when the person is assigned to tasks.
addedAtstring (date-time)
avatarUrlstringpuò essere null
OggettiMember
{
  "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

Attributi

CampoTipoDescrizione
resourceIdstring (uuid)
userIdstring (uuid)può essere null
namestring
unitsPctinteger
OggettiAssignee
{
  "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

Chiave con accesso in scrittura

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.

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.
taskId
obbligatorio
string (uuid)Task id.

Corpo della richiesta

CampoTipoDescrizione
userIds
obbligatorio
array of string
resourceIdsarray of string

Restituisce

200 OK Assignees saved

CampoTipoDescrizione
taskIdstring (uuid)
assignmentsarray of object
Mostra i campi di assignments
CampoTipoDescrizione
idstring (uuid)
taskIdstring (uuid)
resourceIdstring (uuid)
unitsPctinteger
workMininteger
resourcesarray of object
Mostra i campi di resources
CampoTipoDescrizione
idstring (uuid)
userIdstring (uuid)può essere null
namestring
kindstring

Uno tra: work, material, cost

emailstringpuò essere null
costPerHournumber
costPerUsenumber
capacityPctinteger
calendarIdstring (uuid)può essere null
colorstringpuò essere null
avatarUrlstringpuò essere null
needsRescheduleboolean
conflictsarray of Conflict
Richiesta
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"]}'
Risposta200 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

Chiave con accesso in lettura

Parametri di percorso

CampoTipoDescrizione
projectId
obbligatorio
string (uuid)Project id.

Restituisce

200 OK Members

CampoTipoDescrizione
membersarray of Member
rolestring
Richiesta
curl https://planitude.app/api/projects/40be00e0-7e34-4f7a-864b-5cc986f575b8/members \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta200 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"
}

Riferimento API

Webhooks

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

Webhook

Attributi

CampoTipoDescrizione
idstring (uuid)
workspaceIdstring (uuid)
workspaceNamestring
projectIdstring (uuid)può essere nullnull = every project of the workspace.
projectNamestringpuò essere null
namestring
urlstring (uri)
eventsarray of string

Uno tra: 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
disabledReasonstringpuò essere null

Uno tra: failures, gone, project_deleted, user

disabledAtstring (date-time)può essere null
consecutiveFailuresinteger
viaApibooleanCreated with the API (REST hook) rather than from the profile.
createdByobjectpuò essere null
Mostra i campi di createdBy
CampoTipoDescrizione
idstring (uuid)
namestringpuò essere null
createdAtstring (date-time)
updatedAtstring (date-time)
lastDeliveryAtstring (date-time)può essere null
lastSuccessAtstring (date-time)può essere null
OggettiWebhook
{
  "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

Attributi

CampoTipoDescrizione
idstring (uuid)
eventIdstring (uuid)
eventTypestring
statusstring

Uno tra: pending, success, failed, cancelled

attemptsinteger
nextAttemptAtstring (date-time)può essere null
lastAttemptAtstring (date-time)può essere null
responseStatusintegerpuò essere null
responseExcerptstringpuò essere null
errorstringpuò essere null
durationMsintegerpuò essere null
manualboolean
createdAtstring (date-time)
OggettiDelivery
{
  "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

Attributi

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

Uno tra: 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
obbligatorio
string

Uno tra: 2026-10-01

createdAt
obbligatorio
string (date-time)
workspaceId
obbligatorio
string (uuid)
projectIdstring (uuid)può essere null
actorobjectpuò essere nullWho made the change (null for system changes).
Mostra i campi di actor
CampoTipoDescrizione
idstring (uuid)
namestringpuò essere null
data
obbligatorio
object
OggettiEvent
{
  "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.

Attributi

CampoTipoDescrizione
idstring (uuid)
workspaceIdstring (uuid)
keystring
namestring
descriptionstringpuò essere null
startDatestring (date)
deadlinestring (date)può essere null
currencystring
scheduleFromstring

Uno tra: forward, backward

colorstringpuò essere null
archivedboolean
createdAtstring (date-time)
updatedAtstring (date-time)
urlstring (uri)
OggettiProject (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

Chiave con accesso in lettura

Parametri di query

CampoTipoDescrizione
workspaceIdstring (uuid)
projectIdstring (uuid)

Restituisce

200 OK Subscriptions

CampoTipoDescrizione
webhooksarray of Webhook
Richiesta
curl https://planitude.app/api/webhooks \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta200 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

Chiave con accesso in scrittura

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.

Corpo della richiesta

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

Uno tra: 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)

Restituisce

201 Created Created

CampoTipoDescrizione
webhookWebhook
secretstringwhsec_...
Richiesta
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"
}'
Risposta201 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

Pubblico, senza chiave

Restituisce

200 OK Events

CampoTipoDescrizione
apiVersionstring
eventsarray of string
Richiesta
curl https://planitude.app/api/webhooks/events
Risposta200 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}

Chiave con accesso in lettura

Parametri di percorso

CampoTipoDescrizione
webhookId
obbligatorio
string (uuid)Webhook id.

Restituisce

200 OK Subscription

CampoTipoDescrizione
webhookWebhook
Richiesta
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88 \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta200 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}

Chiave con accesso in scrittura

Parametri di percorso

CampoTipoDescrizione
webhookId
obbligatorio
string (uuid)Webhook id.

Corpo della richiesta

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

Restituisce

200 OK Updated

CampoTipoDescrizione
webhookWebhook
Richiesta
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}'
Risposta200 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}

Chiave con accesso in scrittura

Parametri di percorso

CampoTipoDescrizione
webhookId
obbligatorio
string (uuid)Webhook id.

Restituisce

204 No Content Deleted

Richiesta
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

Chiave con accesso in lettura

Parametri di percorso

CampoTipoDescrizione
webhookId
obbligatorio
string (uuid)Webhook id.

Parametri di query

CampoTipoDescrizione
limitinteger1-100.

Predefinito: 50

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

Restituisce

200 OK Deliveries

CampoTipoDescrizione
deliveriesarray of Delivery
nextCursorstringpuò essere null
Richiesta
curl https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/deliveries \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta200 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}

Chiave con accesso in lettura

Parametri di percorso

CampoTipoDescrizione
webhookId
obbligatorio
string (uuid)Webhook id.
deliveryId
obbligatorio
string (uuid)

Restituisce

200 OK Payload

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

Chiave con accesso in scrittura

Parametri di percorso

CampoTipoDescrizione
webhookId
obbligatorio
string (uuid)Webhook id.
deliveryId
obbligatorio
string (uuid)

Restituisce

202 Accepted Queued

CampoTipoDescrizione
deliveryDelivery
Richiesta
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"
Risposta202 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

Chiave con accesso in scrittura

Parametri di percorso

CampoTipoDescrizione
webhookId
obbligatorio
string (uuid)Webhook id.

Restituisce

202 Accepted Queued

CampoTipoDescrizione
deliveryDelivery
Richiesta
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta202 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

Chiave con accesso in scrittura

Parametri di percorso

CampoTipoDescrizione
webhookId
obbligatorio
string (uuid)Webhook id.

Restituisce

200 OK New secret (shown once)

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

Webhook

Webhook

I webhook inviano un POST HTTPS con un corpo JSON al tuo endpoint appena qualcosa cambia, che la modifica arrivi dall’app web, dall’API, dal server MCP o da un import. Un webhook copre un progetto, oppure tutti i progetti di un workspace (proprietari e amministratori).

Creali in Profilo → Webhook o con l’API, come REST hook: iscrizione con POST /api/webhooks, disiscrizione con DELETE. Il segreto di firma viene mostrato una sola volta.

Ogni richiesta porta queste intestazioni:

IntestazioneDescrizione
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
Richiesta
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"
}'
Risposta201 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"
}

Tipi di evento

Iscriviti a singoli eventi, oppure a * per riceverli tutti. Ogni evento ha la stessa busta; data cambia con il tipo.

EventoDescrizione
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’esempio
{
  "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"
  }
}

Verifica delle firme

Ogni richiesta è firmata con HMAC-SHA256 e il segreto del tuo webhook. L’intestazione Planitude-Signature contiene un timestamp t e la firma v1, calcolata su t, un punto e il corpo grezzo.

  1. Usa il corpo grezzo, prima di qualunque parsing JSON: un corpo riserializzato ha una firma diversa.
  2. Calcola l’HMAC e confrontalo in tempo costante.
  3. Rifiuta le richieste con un timestamp lontano più di 5 minuti dal tuo orologio: una richiesta intercettata non si può riprodurre.
  4. Ruota il segreto quando vuoi: quello vecchio smette subito di funzionare.
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
// });

Tentativi e consegna

Rispondi con un qualunque 2xx entro 10 secondi e fai il lavoro vero dopo, in una coda. I redirect non vengono seguiti. Su errori e timeout Planitude prova fino a 6 volte in tutto: subito, poi dopo 1 min, 5 min, 30 min, 2 h, 12 h.

La consegna è almeno una volta e senza ordine garantito. Salva l’id dell’evento (Planitude-Event-Id, anche id nel corpo) e salta quelli già elaborati; ordina per createdAt.

Dopo 5 eventi di fila falliti a ogni tentativo, il webhook si disattiva e il proprietario riceve un’email. Una risposta 410 Gone lo disattiva subito. Riattivalo dal profilo, oppure con PATCH e active: true.

Il registro delle consegne (stato, codice HTTP, estratto della risposta, payload, nuovo invio manuale) si conserva per 30 giorni. Come destinazione sono accettati solo indirizzi pubblici.

Calendario dei tentativi6 × POST
Tentativo 1   subito
Tentativo 2   + 1 min
Tentativo 3   + 5 min
Tentativo 4   + 30 min
Tentativo 5   + 2 h
Tentativo 6   + 12 h

Prova il tuo endpoint

  1. Invia un evento webhook.ping con l’endpoint di prova, oppure con il pulsante Prova nel profilo.
  2. Per ricevere eventi sul tuo computer, esponi il server locale con un tunnel (per esempio ngrok o Cloudflare Tunnel) e iscrivi il suo indirizzo HTTPS pubblico.
  3. Apri il registro delle consegne per vedere stato, codice HTTP e risposta, e invia di nuovo una consegna dopo aver corretto l’endpoint.
Richiesta
curl -X POST https://planitude.app/api/webhooks/1747ee7f-a395-4d3c-94b0-54b513d71d88/test \
  -H "Authorization: Bearer $PLANITUDE_API_KEY"
Risposta202 Accepted
{
  "delivery": {
    "id": "4b207161-80f9-40bb-bc3f-d8f70315be00",
    "eventId": "6f1c1d1e-2f4b-4d0a-9a77-2a3c5b1e9f10",
    "eventType": "task.completed",
    "status": "success",
    "attempts": 1,
    "nextAttemptAt": null,
    "lastAttemptAt": "2026-10-01T08:30:12.418Z",
    "responseStatus": 200,
    "responseExcerpt": "{\"ok\":true}",
    "error": null,
    "durationMs": 39,
    "manual": false,
    "createdAt": "2026-10-01T08:30:12.418Z"
  }
}

AI e MCP

Server MCP

Planitude è un server MCP (Model Context Protocol): assistenti AI ed editor di codice leggono i progetti, analizzano percorso critico e carichi di lavoro, creano e modificano attività, con i tuoi permessi. Le app web si collegano con OAuth (accedi e consenti l’accesso); gli strumenti a riga di comando e gli editor usano una chiave API.

URL del server

https://planitude.app/mcp

  • ChatGPTOAuth

    In ChatGPT apri Impostazioni › Sicurezza e accesso e attiva la Modalità sviluppatore. Crea un’app con l’URL del server e l’autenticazione OAuth, poi accedi a Planitude e consenti l’accesso.

    Documentazione ufficiale ↗
  • ClaudeOAuth

    Apri Personalizza › Connettori › Aggiungi connettore personalizzato, incolla l’URL del server e scegli Connetti: si apre Planitude, accedi e consenti l’accesso. Funziona su claude.ai, Claude Desktop e nell’app mobile.

    Documentazione ufficiale ↗
  • GeminiOAuth

    Su gemini.google.com apri Impostazioni › App collegate, scegli Aggiungi un’app personalizzata e incolla l’URL del server; poi accedi a Planitude e consenti l’accesso.

    Documentazione ufficiale ↗
  • Claude CodeChiave API

    Esegui il comando con la chiave in una variabile d’ambiente. Aggiungi --scope user per usarlo in tutti i progetti e verifica con claude mcp list.

    Documentazione ufficiale ↗
  • CodexChiave API

    Metti la chiave in PLANITUDE_API_KEY e aggiungi il blocco a ~/.codex/config.toml: vale per la CLI, l’app e l’estensione per IDE.

    Documentazione ufficiale ↗
  • CursorChiave API

    Aggiungi il blocco a ~/.cursor/mcp.json (tutti i progetti) o .cursor/mcp.json (un progetto); Cursor legge la chiave dall’ambiente.

    Documentazione ufficiale ↗
  • Aggiungi .vscode/mcp.json al workspace: VS Code chiede la chiave una volta e la conserva in modo sicuro, fuori dal file.

    Documentazione ufficiale ↗
  • Gemini CLIChiave API

    Esegui il comando con la chiave in una variabile d’ambiente, oppure aggiungi il blocco a ~/.gemini/settings.json.

    Documentazione ufficiale ↗

Strumenti

Il server espone 29 strumenti, dalla lettura e analisi alle modifiche sicure. Nessuno elimina progetti o attività.

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

Agenti AI

Aggiungi fino a 5 agenti AI esterni al workspace come membri: Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot o qualsiasi client MCP. Assegna loro task, menzionali nei commenti e rivedi le loro modifiche.

Owner e admin creano le chiavi degli agenti in Agenti, scheda Collegamento. La chiave inizia con pln_, si vede una volta sola e si salva solo come hash; ogni agente ha al massimo 2 chiavi e la revoca vale subito.

Le chiavi degli agenti funzionano solo con il server MCP, che mostra gli strumenti per agenti al posto di quelli normali. Sull’API REST ricevono 403 agent_credential.

Ogni chiave legge e commenta oppure può modificare. Prendere in carico, completare e proporre modifiche richiede una chiave che può modificare; altrimenti la risposta è 403 agent_key_read_only.

Un agente vede solo i progetti in cui è stato aggiunto, come viewer (legge e commenta) o editor (modifica anche i task), mai come owner. Nel progetto deve essere attivo anche “Consenti agenti in questo progetto”: è spento di default e lo accende l’owner.

Gli agenti possono cambiare nome, note, durata, avanzamento e scadenza di un task, oppure creare task. Nessuno strumento elimina, invita persone o cambia ruoli.

Limiti di default per agente: 60 richieste al minuto e 200 scritture al giorno, regolabili fino a 240 e 2000. Al massimo 200 modifiche per progetto in attesa di revisione.

Gli strumenti di lettura mettono il testo scritto dalle persone (nomi, note, commenti) in blocchi planitude-data con un nonce casuale, come stringhe JSON, e marcano SUSPICIOUS le righe segnalate da un controllo automatico: sono dati, mai istruzioni. I commenti letti con una chiave personale arrivano negli stessi blocchi.

Come funzionano gli agenti AI in Planitude
MCPClaude Code
claude mcp add --transport http planitude https://planitude.app/mcp \
  --header "Authorization: Bearer $PLANITUDE_AGENT_KEY"

Strumenti per agenti

Con una chiave d’agente il server MCP espone questi 16 strumenti:

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

Durante un’esecuzione Autonomo le modifiche dell’agente ai propri task valgono subito e restano nella cronologia, pronte da ripristinare. Negli altri casi, e in modalità Con approvazione, aspettano in “Da approvare” finché qualcuno del progetto le applica.

Senza webhook l’agente legge i suoi eventi con planitude_poll_events (fino a 50 per volta) e li conferma con planitude_ack_events.

Richiestatools/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 di esecuzione

Per far partire un agente da solo, attiva l’esecuzione in Agenti, scheda Esecuzione, e inserisci il webhook del tuo runner: Planitude manda una POST firmata quando l’agente ha un task da eseguire. Il segreto inizia con whsec_ e si vede una volta sola. L’URL deve essere un indirizzo HTTPS pubblico: quelli privati e locali sono rifiutati.

Firma, intestazioni, timeout di 10 secondi e nuovi tentativi (1 min, 5 min, 30 min, 2 h, 12 h) funzionano come per gli altri webhook. Dopo 5 consegne fallite di fila il webhook si spegne: salva di nuovo l’URL per riattivarlo.

L’avviso porta solo id, mai il testo del task: l’agente legge il task via MCP.

EventoDescrizione
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 avviso con newRun: true apre un’esecuzione. L’agente la prende con planitude_claim_task e tiene un lease di 30 minuti (da 5 a 240), rinnovato con planitude_extend_lease. Se il lease scade parte un nuovo tentativo, fino a 3 (al massimo 10). Un’esecuzione che nessuno prende scade dopo 24 ore.

planitude_complete_task porta il task al 100% e pubblica il report come commento; con sottotask aperti risponde 409 subtasks_open. planitude_fail_task registra il motivo e avvisa il team, che può rilanciarla; planitude_release_task restituisce il task senza nuovi tentativi.

Ogni esecuzione consente 50 modifiche (fino a 500, poi 429) e ogni agente 5 esecuzioni aperte (poi 409 too_many_open_runs). Autonomo, la modalità di default, applica subito le modifiche e permette di ripristinarle; Con approvazione le manda in revisione. Un fermo d’emergenza, per progetto o per tutto il workspace, annulla le esecuzioni aperte e blocca le scritture.

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

Scrivere un runner

Il runner è il tuo piccolo servizio che riceve gli avvisi e avvia l’agente. Va bene qualsiasi linguaggio; con Node 20+ non servono dipendenze.

  1. Verifica la firma sul corpo grezzo e rispondi subito 200: Planitude aspetta al massimo 10 secondi.
  2. Salta gli eventi già visti (Planitude-Event-Id): i nuovi tentativi rimandano lo stesso evento.
  3. Con newRun: true prendi il task e avvia l’agente, per esempio claude -p con il server MCP di Planitude e la chiave dell’agente.
  4. Rinnova il lease mentre l’agente lavora; con run.cancel fermalo.
  5. Chiedi all’agente di chiudere con PLANITUDE: DONE solo se tutto il task è finito, poi completa con il suo report. Altrimenti (PLANITUDE: NOT DONE - … o nessuna riga finale) chiudi come fallita con ciò che resta da fare.

Tratta il testo del task come dati: chiedi all’agente di non seguire mai istruzioni trovate lì e consentigli solo gli strumenti di Planitude che gli servono.

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>

Feed OData (Power BI, Excel)

Un feed OData v4 in sola lettura per Power BI, Excel e qualunque client OData, a due indirizzi: un progetto, oppure tutti i progetti che il titolare della chiave vede in un workspace.

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

Autenticazione con una chiave API personale con accesso in lettura: Authorization: Bearer, oppure HTTP Basic con la chiave come password (nome utente qualsiasi), che è il metodo offerto da Power BI ed Excel. Token OAuth e cookie di sessione non sono accettati. Una chiave limitata a un workspace non legge gli altri.

Tabelle: Projects, Tasks, Milestones, Dependencies, Resources, Assignments. Lo schema è in $metadata (CSDL XML) e il documento di servizio all’indirizzo radice.

Opzioni supportate: $select, $filter (confronti, and/or/not, in, contains, startswith, endswith, tolower, toupper), $orderby, $top, $skip, $count e /$count. Le pagine contengono 2000 righe di default, fino a 5000 con Prefer: odata.maxpagesize; segui @odata.nextLink. Le risposte hanno un ETag: invia If-None-Match per ricevere 304. $expand, $apply e $search non sono supportati (400).

Un feed copre al massimo 500 progetti e 25.000 attività (oltre, 413). Le richieste contano nel limite di lettura della chiave, 240 al minuto.

Guida passo passo per Power BI ed Excel
RichiestacURL
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"
Risposta200 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
    }
  ]
}

Novità

  1. Nuovo feed OData v4 in sola lettura su /api/odata/projects/:projectId e /api/odata/workspaces/:workspaceId per Power BI, Excel e altri client OData: sei tabelle, $metadata, $select, $filter, $orderby, $top, $skip, $count, paginazione lato server ed ETag.

  2. Nuovo endpoint GET /api/projects/:projectId/export: il piano in XML di Microsoft Project, CSV, immagine PNG o PDF, con opzioni per scala, intervallo di date, percorso critico, baseline, dipendenze, formato carta e orientamento.

  3. Tutte le chiavi API ora iniziano con pln_. Le chiavi che iniziano con gnt_ non funzionano più: creane una nuova.

  4. Gli agenti eseguono i task: webhook di esecuzione firmato (task.assigned, task.start_due, task.due_today, task.overdue, run.retry, run.cancel), 6 strumenti di esecuzione con lease e una guida per scrivere un runner.

  5. Gli strumenti MCP di lettura racchiudono il testo scritto dalle persone in blocchi planitude-data con un nonce, come stringhe JSON con la marca SUSPICIOUS, per ogni tipo di chiave.

  6. Agenti AI come membri del workspace: chiavi d’agente valide solo con il server MCP, 10 strumenti per leggere, commentare e proporre modifiche, e una coda di eventi.

  7. Nuova documentazione per sviluppatori, generata dal documento OpenAPI. Il documento OpenAPI ora descrive tutti i campi restituiti per membri, commenti, baseline, modelli e assegnatari.

  8. Versione API 2026-10-01: webhook in uscita firmati, API REST pubblica documentata (OpenAPI 3.1), paginazione con cursore e ricerca per externalId.

  9. OAuth 2.1 per il server MCP e l’API: ChatGPT, Claude e Gemini si collegano senza copiare una chiave.

  10. Server MCP e chiavi API personali con accesso in lettura o in lettura e scrittura.

La pubblicità mantiene Planitude gratuito