Skip to content

Project status updates

A status update is the project manager’s report on a project at a point in time: a RAG call (green, amber or red), a narrative of up to 600 characters, and a snapshot of the plan that the server takes at the moment of posting. The snapshot is stored and never recomputed. Reading an update later shows what the plan said when it was posted, and separately what has changed since.

ActionWho
Post a status updateProject Manager or above, signed in. An API token cannot post, an agent’s included, even one acting for the project manager.
Read the historyEvery project member, Viewer and above. An mcp:read token (an agent) can read the history and one update, as the person it acts for, unless the project has turned agent access off.
Create or revoke a share link for an updateProject Manager or above.
Open a share linkAnyone holding the link, with no sign-in.

A posted update cannot be edited or deleted. To correct one, post a new update. Updates on an archived project cannot be posted.

An agent can read status updates and cannot post one. A post sent with any API token, an mcp:read token or a full-access personal access token alike, is refused with 403, even when the token belongs to the project manager. Posting needs the person signed in.

Posting is rate limited per account and per project: every project manager on a project shares the project’s limit.

Each figure carries its value, the time it was true (as_of) and its one-sentence definition from the metric vocabulary. A figure that cannot be computed is returned as null with a reason, such as no_forecast or no_baseline, rather than left out.

  • Forecast: the P50 and P80 finish from the latest Monte Carlo result, the CPM finish, and the CPM finish’s variance against the active baseline.
  • Milestones: each milestone’s CPM finish, baseline finish and variance, up to 50 rows, earliest first. milestones_truncated is true when the project has more.
  • Since the previous update: tasks completed and milestones slipped. On the first update both are null with the reason no_previous_update.
    • Completed counts tasks whose actual finish falls on or after the day the previous update was posted, in the server’s time zone. It is day-granular, so two updates posted on the same day both count that day’s completions.
    • Slipped counts milestones whose CPM finish moved later between the two snapshots. Only the milestones inside each snapshot’s 50-row cap are compared, so a slip on a milestone past the cap is not counted.
  • Top risks: the three open or mitigating risks with the highest probability times impact.
  • Open decisions: awaiting program decisions linked to a task or risk of this project.
  • Computed health: the health band the counts give at post time, stored beside the project manager’s RAG call so a reader can see where the two disagreed.

The snapshot holds no cost figures.

Every update is numbered within its project (seq), and two posts made at the same moment take consecutive numbers. The server records a SHA-256 digest at post time over everything a reader is served (the number, the RAG call, the narrative, the author, the posting time, the computed health and the snapshot) and checks it on every read; snapshot_verified is false if any of them was changed outside TruePPM, and a share link for such an update stops resolving. Deleting the author’s account is not a change of that kind: TruePPM re-records the digest without the author as the account is removed, so the update still verifies and shows no author.

When you read an update, live_diff lists each snapshot figure whose current value differs from the frozen one, keyed by its place in the snapshot (for example forecast.p80 or milestones.<task id>.cpm_finish). Figures that have not moved are left out. A milestone that has left the plan reads {"value": null, "reason": "removed"}.

A share link for a status update is created with the same POST /api/v1/projects/{id}/share-links/ call as board and schedule links, with content_kind: "status_update" and the status_update id. The link is bound to that one update. It never moves to a newer one, and it never shows data newer than that update’s snapshot.

The shared view is the frozen snapshot only. It never carries the “what has moved since” values, and it carries no ids or links into the workspace. Its contents are filtered on the server:

SettingDefaultControls
show_milestone_datesonThe milestone rows.
show_risksoffThe top risks. Risk titles are internal, so they are opt-in.
show_decisionsoffThe open decisions. Decision titles are internal, so they are opt-in.
show_assigneesoffPeople’s names: the author, and risk and decision owners.

Hiding milestones removes their rows, but the CPM finish and the counts are still shown. Those can bound a withheld date. The setting withholds the dates and does not guarantee they cannot be inferred.

The narrative is part of the shared view. Write it knowing that anyone holding the link reads it.

A status-update link that is unknown, revoked, expired, for a project in Trash, or blocked by the sharing policy returns the same 404. Revocation, expiry and the sharing policy otherwise work as they do for board and schedule links.

  • GET /api/v1/projects/{id}/status-updates/: the history, newest first, paginated.
  • POST /api/v1/projects/{id}/status-updates/: post {rag, narrative}.
  • GET /api/v1/projects/{id}/status-updates/{update_id}/: one update.
  • GET /api/v1/share/status-update/{token}/: the public, read-only shared view.

The full schema is in the API reference.