Skip to main content
Project reads require 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.

Lifecycle commands

Project writes require projects: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 PLANNING project 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 needs projects:manage and projects:read at each.
  • Update project: name, description, start and target dates, purpose statement.
  • Transition project: the status machine, including archive and revive.
Factory, objective and budget relationships and ownership are not changed by these commands; objective links, ownership and the customer change through the relationship commands below.

Retries

Send an Idempotency-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, with projects: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.
Link and unlink return the project’s whole 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 with projects: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. Task writes return the post-write 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 need workforce: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. A pod managed by a customer organization, or by a unit under one, is never shown: its routes answer 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 needs factories: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 a status, the list is most recently updated first; without one, it is ordered by status (descending), then most recently updated first. An unknown id answers null, as the Console does.
  • Plans: list the plans made for one request, ordered by status (descending).
Each answer is the request or plan’s own fields. Who created or approved it, the approval task, and the ids of the project, factory, tasks, workflow runs and requirements document it links to are left out. Listing project tasks across projects is not on these routes yet; GET /api/v3/projects/{projectId}/tasks lists one project’s tasks.