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

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

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

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

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

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

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

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.
External Apps and platform API keys can validate workflow drafts.
GET /api/v2/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.
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.

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

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.
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.
Assignment history reads for machines.
GET /api/v2/workforce/listAssignmentHistory 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.
Pod membership writes for machines.
Six workforce pod membership routes 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.
Pod directory reads for machines.
Three workforce pod GET routes (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.
Pod membership allocation previews for machines.
POST /api/v2/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.