> ## 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.

# 2026-10-02 — Machine credentials can create, update and transition projects

> The project create, update and transition routes and MCP tools run the project lifecycle under the new projects:write scope, with authority decided at each project's home.

**2026-10-02**

Machine credentials can link projects to objectives and transfer project ownership.

## Summary

`POST /api/v2/projects/linkObjective`, `unlinkObjective` and `transferOwnership` (scope `projects:write`, `projects:manage`), with matching MCP tools in the `projects` group, change a project's objective links and its owning team or department. See [Projects](https://docs.gloo.com/forge/reference/http-api/projects#relationship-changes).

## New

* Each change authorizes both affected resources inside the write: the project at its home (`404` unless readable, `403` without `projects:manage`), and either `objectives:read` at the deployment root with an existing objective (link, unlink) or `projects:manage` at an existing new owner org unit (transfer). Nothing is written on any refusal.
* Link and unlink return the project's links exactly as `GET /api/v2/projects/listObjectives` does, so the credential's scopes must include `projects:read` and `objectives:read`; a transfer returns the `Project` and needs `projects:read`. A transfer never moves the project's home.
* A same-key retry within 24 hours returns the recorded result only while the caller still holds all of this; otherwise `409 idempotency_result_unavailable`.

**2026-10-02**

Workforce reads never return customer organizations or anything under them.

## Fixed

* `GET /api/v2/workforce/getOrgUnit`, `getPosition`, `listOrgUnits`, `listPositions`, `listAssignmentHistory`, `listPods`, `getPod`, `listPodMembershipHistory` and `POST /api/v2/workforce/previewPodMembership`, and their MCP tools, never return a customer organization, an org unit under one, a position homed in either, an assignment naming one, or a pod managed by one. Single reads answer `404` as for a missing ID; lists omit the rows, and cursors, counts, parent, head and reporting fields never name them. Before this fix `getOrgUnit` and `getPosition` returned a customer organization and its positions with their assigned workers, the position lists included them, and the assignment and pod reads hid only the customer organization itself, not the org units under it. See [Workforce](https://docs.gloo.com/forge/reference/http-api/workforce).

**2026-10-02**

Project and project-task writes need the projects:read scope.

## Fixed

* `POST /api/v2/projects/create`, `PATCH /api/v2/projects/update`, `POST /api/v2/projects/transition`, `POST /api/v2/projects/createTask`, `PATCH /api/v2/projects/updateTask` and `POST /api/v2/projects/transitionTask`, and their MCP tools, return the project or task they wrote, so they now also require the credential's scopes to include `projects:read`. A credential with `projects:write` but not `projects:read` receives `403 forbidden` naming `projects:read`, and nothing is written; a same-key retry by such a credential is `409 idempotency_result_unavailable`. Before this fix such a credential received the written project or task. See [Projects](https://docs.gloo.com/forge/reference/http-api/projects#lifecycle-commands).

**2026-10-02**

Machine credentials can start and cancel metered evaluation runs.

## Summary

`POST /api/v2/evals/startRun` and `POST /api/v2/evals/cancelRun`, with MCP `forge_start_eval_run` and `forge_cancel_eval_run` in the `agents` group, start and cancel evaluation runs under the new mutating published scope `evals:write:run`, which narrows to both `agents:write` and `inference:use`. The built-in apps do not receive it. See [Evals](https://docs.gloo.com/forge/reference/http-api/evals#running-evaluations).

## New

* Starting a run queues it. Each test case makes two metered model calls (the chosen model and the fixed judge model); cost accrues as cases run and is reported in `totalCost` (target plus judge) when the run finalizes. `completed` means finalized: `testCasesCompleted` below `testCasesTotal` means some cases never finished. Cancelling stops cases that have not started; cost already incurred is not refunded and recorded results remain. Eval spend is recorded under the platform's eval runner, not your organization's budget.
* Machine-started runs are limited to 200 test cases and 2 in-progress runs per credential, and are refused while the platform's eval-runner, eval-judge or global budget is frozen or exhausted.
* The run's set is decided as for authoring: `agents:write` at the set's agent home, or the deployment root for an unbound set. A same-key retry within 24 hours returns the recorded run only while the run stays visible and its set writable.
* `EvalRun` gains `startedByCaller`, `true` only on a run the calling credential started. A run started through the API reads `triggeredBy: "machine"` in every read, the Console's included: no credential's id is returned.

## Fixed

* A cancelled run, including one started in the Console or by the weekly regression evals, starts no further test case, and finalization keeps it `cancelled` while recording the totals of the cases that ran.

**2026-10-02**

Machine credentials can read the governed outcome a run produced.

## Summary

`GET /api/v2/outcomes/get`, `GET /api/v2/outcomes/getForRun` and `GET /api/v2/outcomes/list`, with MCP `forge_get_outcome`, `forge_get_run_outcome` and `forge_list_outcomes` in the `runs` group, read workflow outcomes under `runs:read` on the run that produced them. See [Outcomes](https://docs.gloo.com/forge/reference/http-api/outcomes).

## New

* An `Outcome` carries the claim, its metrics and exceptions with evidence references exactly as stored, the human-review, evaluation and cost state, and the latest rating value. The origin, decisions, trust receipt, project and objective names, the rater and rating notes are never returned.
* `getForRun` keeps every state explicit: `not_declared`, `running`, `pending`, `invalid` with its diagnostic, `ready` and `not_applicable`.
* Rating an outcome stays with a person in Console.

**2026-10-02**

Machine credentials can read, create, update and transition a project's tasks.

## Summary

`GET /api/v2/projects/listTasks` and `getTask` (scope `projects:read`) and `POST /api/v2/projects/createTask`, `PATCH /api/v2/projects/updateTask` and `POST /api/v2/projects/transitionTask` (scope `projects:write`, `projects:manage`) cover a project's ordinary tasks, with matching MCP tools in the `projects` group. See [Projects](https://docs.gloo.com/forge/reference/http-api/projects#tasks).

## New

* Authority is decided at the task's project home: `404` unless the caller may read the project, `403` without `projects:manage` there. Factory tasks stay with the factory task operations, a task with no project is never returned, and assigning a task stays with a person in Console.
* A new task starts in `BACKLOG` with kind `generic` and no assignee; a disallowed transition is `409 conflict` and changes nothing.
* A same-key retry within 24 hours returns the recorded result only while the caller may still read and change the task.

**2026-10-02**

Machine credentials can create, update and transition projects.

## Summary

`POST /api/v2/projects/create`, `PATCH /api/v2/projects/update` and `POST /api/v2/projects/transition`, with MCP `forge_create_project`, `forge_update_project` and `forge_transition_project`, run the project lifecycle under the new mutating published scope `projects:write` (`projects:manage`). The built-in apps do not receive it. Every success returns the post-write `Project`. See [Projects](https://docs.gloo.com/forge/reference/http-api/projects#lifecycle-commands).

## New

* Update and transition need `projects:read` (otherwise `404`) and `projects:manage` (otherwise `403`) at the project's home. Transition follows the canonical status machine, including archive and revive; a disallowed move is `409 conflict`.
* Only an External App owned by an org unit creates. The owner is that unit or one below it, never a person, and the project homes there. Customer, factory, objective and budget links are not accepted.
* A same-key retry within 24 hours returns the recorded result only while the caller may still read and change the project. Without a key, a repeated create creates a second project.

**2026-10-02**

Machine credentials can create, update and archive objectives and manage their key results.

## Summary

`POST /api/v2/objectives/create`, `PATCH /api/v2/objectives/update`, `POST /api/v2/objectives/archive`, `POST /api/v2/objectives/addKeyResult`, `PATCH /api/v2/objectives/updateKeyResult` and `POST /api/v2/objectives/removeKeyResult`, with the matching Forge MCP tools in the `factories` group, run the Console's objective and key-result writes under the new mutating published scope `objectives:write` (`objectives:manage`). The built-in apps do not receive it. See [Objectives](https://docs.gloo.com/forge/reference/http-api/objectives).

## New

* Every write needs the `objectives:read` and `objectives:write` scopes and `objectives:read` and `objectives:manage` at the deployment root, the same permission and home the Console uses; otherwise `403 forbidden` naming the missing permission.
* A machine names only a `company` or `orgUnit` owner. Archive sets `CANCELLED`; key-result removal is a permanent delete, as in the Console.
* A same-key retry within 24 hours returns a recorded success only while the caller still holds both permissions at the deployment root; a recorded refusal or failure is never replayed.

**2026-10-02**

External Apps can grant and revoke workspace tool sets and skills on the agents they own.

## Summary

`POST /api/v2/agents/assignToolSet`, `unassignToolSet`, `assignSkill` and `unassignSkill` let an External App give an agent it owns one workspace tool set or one skill at a time, and take back what it gave. Each needs the opt-in `agents:manage` scope, which the built-in Apps never carry, and `agents:manage` at the agent's home. MCP adds `forge_assign_agent_tool_set`, `forge_unassign_agent_tool_set`, `forge_assign_agent_skill` and `forge_unassign_agent_skill` in the `agents` group. See [Tools and skills](https://docs.gloo.com/forge/reference/http-api/agents#tools-and-skills).

## New

* Only workspace tool sets and workspace skills: a system tool set and a builtin or Anthropic skill are `409 conflict` on assign and unassign, and assigning anything an operator denied for the agent is `409 conflict` too. The API never lifts or removes an operator deny, and an App takes back only the grants it placed.
* Each result names the agent definition (`id`) and says whether anything changed (`changed`); a repeat of a state that already holds writes nothing.
* A change takes effect on the agent's next dispatch and is audited with the App as the actor. Tools in an assigned set are still governed when the agent calls them.
* A same-key retry returns the recorded result only while the App still owns the same agent definition.

## Fixed

* Deleting a workspace tool set in the Console now removes every agent's assignment of it and refreshes the dispatch configuration of each agent that held it. Before, the assignments were left in place.

**2026-10-02**

External Apps and platform API keys can validate workflow drafts.

[`GET /api/v2/workflows/validateDraft`](https://docs.gloo.com/forge/reference/http-api/workflows/validateDraft) and MCP `forge_validate_workflow_draft` return the Forge Console validator's findings for a draft (code, severity, layer, node or edge, in order) and its publishability (`publishable`, `gated` or `broken`), under `workflows:read` at the workflow's home. Nothing is written. A message that would name a Console-only setting or platform resource is withheld, and publishing stays in the Console.

**2026-10-02**

Machine credentials can create and restructure org units and positions.

## Summary

`POST /api/v2/workforce/createOrgUnit`, `moveOrgUnit`, `createPosition`, `setPositionReporting` and `PATCH /api/v2/workforce/updatePosition`, with the matching Forge MCP tools, run the Console's org-structure commands under the new mutating published scope `workforce:write:org` (`org:manage`). The built-in apps do not receive it. Each success returns the written org unit or position. See [Workforce](https://docs.gloo.com/forge/reference/http-api/workforce#org-unit-and-position-commands).

## New

* Authority matches the Console: `org:manage` and `workforce:read` at the platform scope, or at the target org unit when creating a position.
* Customer organizations and the org units under them are never confirmed to a machine (`404`). Every refusal the org structure's integrity rules would raise answers first with `400` or `409` and writes nothing, including reporting cycles, inactive org units and capital-partner codes.
* Reporting-edge changes record the reason and the calling key or app in the audit log. Assigning people or agents to positions stays in the Console.

**2026-10-02**

Machine credentials can read a procedure version's source under a separate, sensitive scope.

## Summary

`GET /api/v2/procedures/getSource` and MCP `forge_get_procedure_source` (`workflows` group) return one procedure version's bundled files exactly as stored, with UTF-8 byte counts, under the new sensitive published scope `procedures:read:source` (`procedures:write`). The built-in apps do not receive it. See [Procedure source](https://docs.gloo.com/forge/reference/http-api/procedures#procedure-source).

## New

* Source needs `procedures:write` at the version's home, the procedure author permission; `procedures:read` and `workflows:read` never reach source.
* Source is not scanned for secrets. More than 900 KiB of source is `413 payload_too_large`; a missing procedure and unreadable source are one `404`.

**2026-10-02**

External Apps and platform API keys can read and edit workflow draft graphs.

`GET /api/v2/workflows/getDraftGraph` returns a draft's nodes and edges, at most 200 and 400 with `meta.partial`. `POST /api/v2/workflows/createDraftNode`, `PATCH /updateDraftNode`, `DELETE /deleteDraftNode`, `POST /createDraftEdge`, `PATCH /updateDraftEdge` and `DELETE /deleteDraftEdge` edit it through the Console builder's checks, under `workflows:write:draft` with read and write grants at the workflow's home. MCP adds `forge_get_workflow_draft_graph` and six edit tools. Nodes take structure and content only: agent, worker, person, recipient, channel, credential, vault, tool, procedure, model and sandbox settings stay in the Console. Keyed retries replay while the workflow stays readable.

**2026-10-02**

Assignment history reads for machines.

[`GET /api/v2/workforce/listAssignmentHistory`](https://docs.gloo.com/forge/reference/http-api/workforce#assignment-history) and MCP `forge_list_assignment_history` return one worker's or one position's complete assignment history, newest start first, under `workforce:read` at the platform scope, as the Console does. Rows in a customer organization's org unit, or in no org unit, are omitted, and who made an assignment is never returned. Assignment writes stay Console-only.

**2026-10-02**

Pod membership writes for machines.

Six [workforce pod membership routes](https://docs.gloo.com/forge/reference/http-api/workforce#pod-membership-writes) and their MCP tools add, re-date, edit (future), end, delete (future) and confirm pod memberships under the opt-in scope `workforce:write:pods` (`workforce:manage` at the platform scope, as the Console), together with the `workforce:read` scope because each returns the written membership (otherwise `403` naming `workforce:read`). They run the Console's own commands, so dates, revisions, person capacity and audit records are unchanged; a pod whose managing org unit is a customer organization or sits under one answers `404`; refusals carry the Console's code. Built-in apps do not receive the scope. Pod create, update and archive and pod-to-Customer assignments stay Console-only.

**2026-10-02**

Pod directory reads for machines.

Three [workforce pod GET routes](https://docs.gloo.com/forge/reference/http-api/workforce#pods) (`listPods`, `getPod`, `listPodMembershipHistory`) and MCP `forge_list_pods`, `forge_get_pod` and `forge_list_pod_membership_history` read pods, effective rosters and membership history under `workforce:read` at the platform scope, as the Console does. Pods managed by a customer organization are never returned, and outputs omit creator, updater, archiver and verifier identities, archive reasons and manager resolution.

**2026-10-02**

Pod membership allocation previews for machines.

[`POST /api/v2/workforce/previewPodMembership`](https://docs.gloo.com/forge/reference/http-api/workforce/previewPodMembership) and MCP `forge_preview_pod_membership` preview one pod membership change (add, change-effective, update-future or end) exactly as the Console does, and change nothing. They need the new opt-in scope `workforce:write:pods`, which narrows to `workforce:manage` at the platform scope and is never given to the built-in Apps. Validation refusals come back as `status: "blocked"` with the Console's code and message; unknown pods and pods managed by a customer organization are both `404`. Results carry no person ID or actor identities, and overlapping memberships never name a pod the caller cannot see.


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