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 (
404unless readable,403withoutprojects:manage), and eitherobjectives:readat the deployment root with an existing objective (link, unlink) orprojects:manageat 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/listObjectivesdoes, so the credential’s scopes must includeprojects:readandobjectives:read; a transfer returns theProjectand needsprojects: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.
Fixed
GET /api/v2/workforce/getOrgUnit,getPosition,listOrgUnits,listPositions,listAssignmentHistory,listPods,getPod,listPodMembershipHistoryandPOST /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 answer404as for a missing ID; lists omit the rows, and cursors, counts, parent, head and reporting fields never name them. Before this fixgetOrgUnitandgetPositionreturned 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.
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/updateTaskandPOST /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 includeprojects:read. A credential withprojects:writebut notprojects:readreceives403 forbiddennamingprojects:read, and nothing is written; a same-key retry by such a credential is409 idempotency_result_unavailable. Before this fix such a credential received the written project or task. See Projects.
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.completedmeans finalized:testCasesCompletedbelowtestCasesTotalmeans 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:writeat 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. EvalRungainsstartedByCaller,trueonly on a run the calling credential started. A run started through the API readstriggeredBy: "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
cancelledwhile recording the totals of the cases that ran.
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
Outcomecarries 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. getForRunkeeps every state explicit:not_declared,running,pending,invalidwith its diagnostic,readyandnot_applicable.- Rating an outcome stays with a person in Console.
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:
404unless the caller may read the project,403withoutprojects:managethere. 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
BACKLOGwith kindgenericand no assignee; a disallowed transition is409 conflictand changes nothing. - A same-key retry within 24 hours returns the recorded result only while the caller may still read and change the task.
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(otherwise404) andprojects:manage(otherwise403) at the project’s home. Transition follows the canonical status machine, including archive and revive; a disallowed move is409 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.
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:readandobjectives:writescopes andobjectives:readandobjectives:manageat the deployment root, the same permission and home the Console uses; otherwise403 forbiddennaming the missing permission. - A machine names only a
companyororgUnitowner. Archive setsCANCELLED; 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.
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 conflicton assign and unassign, and assigning anything an operator denied for the agent is409 conflicttoo. 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.
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.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:manageandworkforce:readat 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 with400or409and 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.
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:writeat the version’s home, the procedure author permission;procedures:readandworkflows:readnever 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 one404.
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.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.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.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.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.
