PI Planning for integrators and assistants
What this page is — Every way software, rather than a person in the session, reaches PI Planning: the read-only Orbit Public API and the matching MCP tools, the questions the Orbit Assistant answers, the two e-mails and the webhook a session sends, and the live connection the page itself uses. What it is for — Showing PI objectives, risks and cross-team dependencies in a portfolio tool or a status page, letting people ask "how is PI 2026.4 going?" in plain language, and knowing which messages a session sends and to whom. The problem it solves — The outcome of a planning event is needed far beyond the room — by portfolio managers, finance, other programmes. Without an interface someone copies objectives and risks into slides by hand. These interfaces read the same session the room sees, while every decision that changes the plan stays with people in the session.
Base path: /api/v1/ext/task/pi-planning · Credentials: an API key from Developers → API keys with the scope task:pi_planning:read · Assistant: needs Open PI Planning sessions read-only
Module: PI Planning · Entry points: the developers portal (tag PI Planning) · Developers → API keys · the Orbit Assistant · the communication templates PI Planning Broadcast and PI Planning Session Committed
1. What is available, and to whom
| Interface | Direction | Who uses it | Reads | Writes |
|---|---|---|---|---|
| Public API | Your system → Orbit | Integrations with an API key | Planning teams, sessions with their teams and objectives, ROAM risks, cross-team dependencies | Nothing |
| MCP tools | An AI agent → Orbit | Agents connected with an API key | Same as the API | Nothing |
| Orbit Assistant | A person → Orbit | Anyone with the read-only PI Planning permission | Summary, sessions, one session, its risks | Nothing |
| E-mails | Orbit → people | Participants, facilitator, team leads | — | — |
Webhook planning.committed | Orbit → your system | Integrations subscribed on Developers → Webhooks | — | — (sent once when a PI plan is committed) |
What is deliberately not exposed. A PI session is run live by people: the clock, moving cards on team boards, allocations, answering dependencies, the vote, the merge and the commit are decisions taken in the room. No API, MCP tool or assistant question can change a session. Discussion posts and individual votes are not exposed either — only the session's teams, objectives, risks and dependencies.
2. Why you would use it
- Portfolio reporting without slides. A portfolio tool reads each PI's objectives and business value, and after the PI the delivered value — predictability across programmes, updated automatically.
- A risk register that stays current. Pull the open and owned ROAM risks of every running session into your enterprise risk register every night.
- Dependency visibility across programmes. Read accepted and pending cross-team links to see which teams are waiting on which.
- Answers in seconds. The assistant tells a stakeholder how many sessions are open, which risks are still open and what a PI's objectives are, for free, without opening the session.
3. Step by step — connect an integration
- Developers → API keys — create a key and tick task:pi_planning:read ("Read PI Planning: planning teams, PI sessions with their teams and objectives, ROAM risks and cross-team dependencies"). Existing keys do not gain the scope automatically; edit the key to add it. Bind the key to one project if the integration should only see that project.
- Send the key on every call —
X-Orbit-API-Key: <key>orAuthorization: Bearer <key>. GET /sessionsto list the project's sessions; pick one bynameorstatus.GET /sessions/{id}for its teams and objectives;/sessions/{id}/risksand/sessions/{id}/dependenciesfor the rest.- For planning teams across the organisation,
GET /teams.
The organisation always comes from the key. An org-wide key passes project_id as a query parameter on the session calls; a project-bound key uses its own project and needs none. A session of another project is simply not found.
4. Field reference
Endpoints
| Method and path | Query parameters | Returns |
|---|---|---|
GET /teams | project_id (only teams linked to it), include_inactive (true/false, default false) | data: teams |
GET /sessions | project_id, status (comma-separated: draft, briefing, planning, review, adjusting, committed, closed), include_closed (default false; asking for closed in status includes them) | data: sessions, newest first |
GET /sessions/{id} | project_id | One session with its teams and objectives |
GET /sessions/{id}/risks | project_id, roam (comma-separated open, owned, mitigated, accepted, resolved), view (all, team, program) | data: risks |
GET /sessions/{id}/dependencies | project_id, status (comma-separated proposed, accepted, declined) | data: cross-team dependencies |
An unknown query parameter or a value outside the lists is refused with 400 and a code such as invalid_view or invalid_status; an unknown session is 404 session_not_found.
Team
| Field | Type | Notes |
|---|---|---|
id, name, code, description, colour | text | code up to 12 characters; colour like #1E88E5 |
lead_user_id, lead_name | id, text | May be empty |
is_active | boolean | |
members[] | user_id, name, role, allocation | role is member, lead, scrum_master or po; allocation is the share of time, 0–1. No contact details |
projects[] | project_id, name | A project-bound key sees only its own project here |
updated_at | timestamp |
Session
| Field | Type | Notes |
|---|---|---|
id, project_id, project_name, name | ||
pi_milestone_id, pi_title, pi_start, pi_end | The PI phase | |
iteration_ids[] | ids | The PI's sprints, fixed when the session was published |
status, round | text, number | round is 2 or more after an adjustment round |
facilitator_user_id, facilitator_name | ||
started_at, ended_at, closed_at | timestamps | When planning started, when it ended, when the session closed |
commit_id | id | The Planning commit, once committed |
teams[] | team_id, name, code, colour, status, item_count, members, demoed_at, merged_at | Team status is planning, demoed or committed; item_count = tasks on its board |
objectives[] (single session only) | id, team_id, title, description, business_value, actual_value, committed, sort_order, updated_at | team_id empty = the project objective; committed: false = stretch; actual_value is set after the PI |
Risk
id, team_id (empty = programme risk), title, description, roam, owner_user_id, owner_name, impact and likelihood (low, medium, high or empty), linked_task_ids[], synthesised (a combined programme risk), merged_into (set on a team risk that was combined into a programme risk), created_by, created_by_name, created_at, updated_at.
Cross-team dependency
id, from_team_id (owns the work needed), to_team_id (waits), predecessor_task_id, task_id, dependency_type (finish-to-start, start-to-start, finish-to-finish, start-to-finish), lag_days, needed_by_iteration_id, note, status (proposed, accepted, declined), created_by, created_by_name, created_at, accepted_by, accepted_at.
MCP tools
The same five reads are MCP tools for AI agents connected to Orbit's MCP server with an API key carrying the scope: list_pi_planning_teams, list_pi_sessions, get_pi_session, list_pi_risks, list_pi_dependencies. Their parameters are the query parameters above.
Orbit Assistant
| Tool | Answers | Example question |
|---|---|---|
| PI Planning at a glance | Open sessions, open ROAM risks, teams not yet merged, sessions committed in the last 30 days, the next or running session | "How is PI planning going?" |
| PI sessions | Recent sessions with status, round, PI, teams and facilitator; can keep only the ones still being planned | "Which PI sessions are running?" |
| One PI session | Status, round, PI, facilitator, clock, each team's status and items, objectives with business value, risks by ROAM state, links by status, the current round's vote average | "How is PI 2026.4 going?" "What are the objectives of PI 2026.4?" |
| PI risks | A session's risks, open first, with team, owner, impact and likelihood (team risks already combined are left out) | "What are the open risks in PI 2026.4?" |
The assistant answers only for projects the person is a member of, needs Open PI Planning sessions read-only, costs no credits and never changes anything.
E-mails and notifications
| When | Bell | E-mail (template) | To |
|---|---|---|---|
| The facilitator broadcasts with Bell / E-mail ticked | Yes | PI Planning Broadcast — subject "session name: message from facilitator" | Every participant except the sender |
| Someone is @mentioned in a post | Yes | — | The person mentioned |
| A cross-team link is proposed | Yes | — | The owning team's leads and scrum masters |
| A PI plan is committed | Yes, PI plan committed | PI Planning Session Committed — subject "PI plan committed: session in project" | Bell: every participant except the committer. E-mail: the facilitator and the team leads |
| A PI plan is committed | — | Planning's own plan-committed e-mail | The project's managers, as for any Planning commit |
Template variables you can use when editing the templates: recipient_name, session_name, project_name, facilitator_name, body_html, body_text, session_url, organization_name (broadcast); and committed_by_name, committed_at, summary_html, summary_text besides the session and project names (committed). Links open the session on the right tab.
Webhook
No PI-specific webhook event exists. Committing a PI plan is a Planning commit, so the planning.committed event (group Orbit Ops – Planning on Developers → Webhooks) fires once per committed PI plan, with Planning's usual payload — see Planning for integrators.
The live connection
The PI Planning page keeps a live connection per open session so that the clock, posts, board moves and votes appear on every screen at once. It runs as the signed-in person over a WebSocket at /api/v1/projects/<project>/pi-planning/sessions/<session>/ws on your Orbit API address. It is part of the app, not an integration interface: an API key cannot open it. If a proxy or firewall blocks WebSocket upgrades, the page still works and catches up every few seconds; allow WebSocket traffic to the API address for instant updates.
5. Worked example
A portfolio office wants a weekly PI report across programmes. The administrator creates the key Portfolio report with task:pi_planning:read, org-wide. Each Monday the report job calls:
GET /api/v1/ext/task/pi-planning/sessions?project_id=6869…&status=committed,closed
X-Orbit-API-Key: ok_live_…
It finds PI 2026.4 (status: committed, round: 1, three teams) and calls GET /sessions/{id}?project_id=6869…. The objectives array holds the project objective (team_id empty) and five team objectives; four are committed: true with business_value 8, 9, 6 and 7, one is a stretch with 4. After the PI the facilitator scores the delivered value, and the next Monday's call returns actual_value 8, 7, 3 and 7 — the report computes 25 of 30, 83% predictability.
The same job calls /sessions/{id}/risks?roam=open,owned and gets two rows: Payment gateway vendor is on the critical path (synthesised: true, owned) and Event bus spike may need a second iteration (open, Platform). Meanwhile a stakeholder asks the assistant "What are the open risks in PI 2026.4?" and gets the same two, without a key.
6. The admin contract
- Scopes are explicit. Add
task:pi_planning:readto a key; nothing else grants it. Project-bound keys see one project. - The assistant follows the person's permissions, not a key: without Open PI Planning sessions read-only it declines PI questions, and it sees only the person's projects.
- Templates PI Planning Broadcast and PI Planning Session Committed are editable like any communication template; if one is switched off, the bell still goes out but no e-mail.
- Webhook subscriptions for
planning.committedare managed on Developers → Webhooks; there is nothing PI-specific to subscribe to. - WebSocket traffic to the API address should be allowed for live updates.
7. Don't confuse this with…
- Planning for integrators — the Planning API reads committed plans per time box, burndown and scenarios, and can prepare draft scenarios and planned hires. The committed result of a PI session is readable there too, as an ordinary Planning commit.
- The Tasks API — reads and changes tasks. A PI plan's placements, assignees and dependencies are on the tasks after the commit and readable there.
- Notifications settings — who receives bells and e-mails in general; the table above says which PI Planning events create them.
8. Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
403 on every PI call | The key lacks task:pi_planning:read | Edit the key and add the scope |
400 project_id required or not allowed | An org-wide key without project_id, or a project-bound key asking for another project | Pass the project on org-wide keys; use a key for that project |
404 session_not_found | The session belongs to another project, or the id is wrong | Check project_id; list the sessions first |
400 invalid_status / invalid_roam / invalid_view | A value outside the documented lists | Use the values in the endpoint table |
| Closed sessions are missing | They are hidden by default | include_closed=true or status=closed |
| A team risk is missing from the assistant's answer | It was combined into a programme risk | Read the programme risk; the API still returns the original with merged_into |
objectives has no actual_value | The PI has not been scored | The facilitator scores after the commit |
| The assistant declines PI questions | The person lacks the read-only PI Planning permission, or is not a member of the project | Grant the permission; add them to the project |
| No e-mail after a broadcast | E-mail was not ticked, or the template is off | Tick E-mail; check the template |