projects:read. Each project is decided at its home org unit; unhomed and unreadable projects are omitted or answer 404.
The Project allowlist includes identifiers, names, status, ownership references, dates, purpose, and timestamps. Planning internals and the home ID are not returned.
- List projects
- Get project
- List project objectives
- List projects for planning: each readable project with its customer and task counts; with
customerId, a customer’s project portfolio.
Lifecycle commands
Project writes requireprojects:manage (mutating, never given to the built-in apps), and the credential’s scopes must reach it. Each write decides its authority inside the write, at the project’s home: a project the caller cannot read (projects:read) is 404, and one it can read but not change (projects:manage) is 403. Every success returns the post-write Project, so the credential’s scopes must reach projects:read as well as projects:manage; otherwise 403 permission_denied naming projects:read, and nothing is written.
- Create project: an External App owned by an org unit creates a
PLANNINGproject owned by that unit or one below it, and a Personal key one owned by the unit it names. A create may name an active customer; the project homes at its owner, or at the customer’s org unit when the customer has one, and the caller needsprojects:manageandprojects:readat each. - Update project: name, description, start and target dates, purpose statement.
- Transition project: the status machine, including archive and revive.
Retries
Send anIdempotency-Key to make a retry safe. A same-key retry within 24 hours returns the recorded result only while the caller’s scopes still include projects:read, it still holds projects:manage, and it may read and change the project at its current home; otherwise 409 idempotency_result_unavailable, and the write never runs twice. Without a key a repeated create creates a second project and a repeated transition answers 409 invalid_state; reconcile with Get project.
Relationship changes
A relationship change touches two resources and authorizes both inside the write, withprojects:manage and nothing written on any refusal. The project side is the lifecycle commands’ rule: 404 unless the caller may read the project at its home, 403 without projects:manage there.
- Link project objective: link a project to an objective, or re-weight the link. The caller must also read objectives (
objectives:read, decided at the deployment root), and the objective must exist. - Unlink project objective: remove a link. The primary objective is never removed.
- Transfer project ownership: hand a project to a team or department where the caller also holds
projects:manage. The project’s home does not move. - Change project customer: set or clear the customer a project is for; the customer must exist and be active. The project’s home does not move.
ProjectObjectiveLinkSet, in the order List project objectives pages it after the change, so their credential’s scopes must include projects:read and objectives:read; a transfer or customer change returns the Project and needs projects:read. A same-key retry within 24 hours returns the recorded result only while all of this still holds; otherwise 409 idempotency_result_unavailable. The primary objective, factory and budget links, person or factory owners and task milestones are not changed through the Platform API.
Tasks
A project’s ordinary tasks are read withprojects:read and changed with projects:manage, decided at the project’s home exactly as the lifecycle commands are: 404 unless the caller may read the project, 403 without projects:manage there. A task write, like a lifecycle command, also needs the projects:read scope alongside projects:manage (otherwise 403 naming projects:read), and a same-key retry returns the recorded task only while the scopes still include it. Factory tasks are read and changed through the factory task operations, and a task with no project is never returned. Assigning a task is done by a person in Console.
- List project tasks
- Get project task
- Create project task: starts in
BACKLOGwith kindgenericand no assignee. - Update project task: title, description, priority and tags.
- Transition project task: the task status machine, including cancel and reopen.
ProjectTaskDetail. A same-key retry within 24 hours returns the recorded result only while the caller may still read and change the task at its project’s home; otherwise 409 idempotency_result_unavailable.
Staffing
A project is staffed directly, one worker at a time, or through a pod, which staffs the pod’s members together and is later reconciled with the pod’s roster or released. These operations have the Console’s authority: the two views needworkforce:read, and every preview and change needs workforce:manage, both held at the platform scope, so a grant that covers only some org units receives 403. Each also needs projects:read at the project’s home: a project that is missing, has no home, or that the caller cannot read answers 404. Because every answer is a staffing read, the credential’s scopes must include projects:read, and for a preview or change workforce:read, as well; otherwise 403 naming the missing one, and nothing changes.
- Get project staffing: the direct assignments overlapping a window, each with its worker and project access grant coverage.
- Preview staffing assignment: capacity, the worker’s other commitments (named only on projects you can read; the rest are counted), and the blockers confirm would refuse on.
- Confirm staffing assignment: staff one worker; going over 100% needs
overAllocationReason. - Amend staffing assignment: change the delivery role, allocation or dates at the assignment’s
revision. - Release staffing assignment: end an assignment with a reason.
- Get project pod staffing: the pod assignments overlapping a window, each with its pod.
- Preview pod staffing, then Confirm pod staffing at the roster revision you previewed.
- Preview pod staffing reconciliation, then Reconcile pod staffing: confirm, amend and release members against the pod’s current roster.
- Preview pod staffing release, then Release pod staffing.
404 exactly as for a missing pod, and on the pod staffing view its assignment stays with pod: null. The commands are the Console’s own, so their date, revision, capacity, over-allocation and audit rules are unchanged; a refusal is 400, 404, 409 or 413 and its message ends with the Console’s code in parentheses, such as (STAFFING_ASSIGNMENT_CHANGED). Results never name who created, confirmed, amended, approved or released an assignment; the reasons the caller supplied are kept.
Send an Idempotency-Key with a change to make a retry safe: see Project staffing replay. Previews change nothing and take no key.
Intake requests
These admin routes run the Console’s own intake request reads for an API key. Each needsfactories:read. An External App is refused with 403, even when it holds the permission.
- Intake requests: list them, or read one by its
_id. With astatus, the list is most recently updated first; without one, it is ordered by status (descending), then most recently updated first. An unknown id answersnull, as the Console does. - Plans: list the plans made for one request, ordered by status (descending).
GET /api/v3/projects/{projectId}/tasks lists one project’s tasks.
