> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects

> Read, create, update, transition and transfer projects, change their objective links, manage their ordinary tasks, and staff them directly or through pods through the Platform API.

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.

* [List projects](https://docs.gloo.com/forge/reference/http-api/projects/list.md)
* [Get project](https://docs.gloo.com/forge/reference/http-api/projects/get.md)
* [List project objectives](https://docs.gloo.com/forge/reference/http-api/projects/listObjectives.md)
* [List projects for planning](https://docs.gloo.com/forge/reference/http-api/projects/listForPlanning.md): each readable project with its customer and task counts; with `customerId`, a customer's project portfolio.

## 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](https://docs.gloo.com/forge/reference/http-api/projects/create.md): 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](https://docs.gloo.com/forge/reference/http-api/projects/update.md): name, description, start and target dates, purpose statement.
* [Transition project](https://docs.gloo.com/forge/reference/http-api/projects/transition.md): 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](https://docs.gloo.com/forge/reference/http-api/projects/get.md).

## 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](https://docs.gloo.com/forge/reference/http-api/projects/linkObjective.md): 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](https://docs.gloo.com/forge/reference/http-api/projects/unlinkObjective.md): remove a link. The primary objective is never removed.
* [Transfer project ownership](https://docs.gloo.com/forge/reference/http-api/projects/transferOwnership.md): 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](https://docs.gloo.com/forge/reference/http-api/projects/changeCustomer.md): 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](https://docs.gloo.com/forge/reference/http-api/projects/listObjectives.md) 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](https://docs.gloo.com/forge/reference/http-api/factories), and a task with no project is never returned. Assigning a task is done by a person in Console.

* [List project tasks](https://docs.gloo.com/forge/reference/http-api/projects/listTasks.md)
* [Get project task](https://docs.gloo.com/forge/reference/http-api/projects/getTask.md)
* [Create project task](https://docs.gloo.com/forge/reference/http-api/projects/createTask.md): starts in `BACKLOG` with kind `generic` and no assignee.
* [Update project task](https://docs.gloo.com/forge/reference/http-api/projects/updateTask.md): title, description, priority and tags.
* [Transition project task](https://docs.gloo.com/forge/reference/http-api/projects/transitionTask.md): the task status machine, including cancel and reopen.

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.

* [Get project staffing](https://docs.gloo.com/forge/reference/http-api/projects/getStaffing.md): the direct assignments overlapping a window, each with its worker and project access grant coverage.
* [Preview staffing assignment](https://docs.gloo.com/forge/reference/http-api/projects/previewStaffingAssignment.md): 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](https://docs.gloo.com/forge/reference/http-api/projects/confirmStaffingAssignment.md): staff one worker; going over 100% needs `overAllocationReason`.
* [Amend staffing assignment](https://docs.gloo.com/forge/reference/http-api/projects/amendStaffingAssignment.md): change the delivery role, allocation or dates at the assignment's `revision`.
* [Release staffing assignment](https://docs.gloo.com/forge/reference/http-api/projects/releaseStaffingAssignment.md): end an assignment with a reason.
* [Get project pod staffing](https://docs.gloo.com/forge/reference/http-api/projects/getPodStaffing.md): the pod assignments overlapping a window, each with its pod.
* [Preview pod staffing](https://docs.gloo.com/forge/reference/http-api/projects/previewPodStaffing.md), then [Confirm pod staffing](https://docs.gloo.com/forge/reference/http-api/projects/confirmPodStaffing.md) at the roster revision you previewed.
* [Preview pod staffing reconciliation](https://docs.gloo.com/forge/reference/http-api/projects/previewPodStaffingReconciliation.md), then [Reconcile pod staffing](https://docs.gloo.com/forge/reference/http-api/projects/reconcilePodStaffing.md): confirm, amend and release members against the pod's current roster.
* [Preview pod staffing release](https://docs.gloo.com/forge/reference/http-api/projects/previewPodStaffingRelease.md), then [Release pod staffing](https://docs.gloo.com/forge/reference/http-api/projects/releasePodStaffing.md).

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](https://docs.gloo.com/forge/reference/idempotency.md#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.