> ## 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-15 — People administration and position assignments through the API and MCP

> Administer people, seats, budgets and position assignments through /api/v2/workforce and MCP, at Console parity.

**2026-10-15**

People administration.

## Added

* `POST /api/v2/workforce/createPerson`, `PATCH updatePerson`, `POST mergePersons`, `POST offboardPerson` and `POST reactivatePerson` under `workforce:write:pods` (`workforce:manage` at the platform scope, plus the `workforce:read` scope), and `POST previewPersonMerge`, which writes nothing and needs the same two scopes because it names both people. A merge cannot be undone and an offboard is only partly reversible; preview first and send an `Idempotency-Key`. See [People](https://docs.gloo.com/forge/reference/http-api/workforce#people).
* `GET /api/v2/workforce/getPerson` and `GET /api/v2/workforce/listWorkers` under `workforce:read` at the platform scope. A person never carries its avatar URL; the worker list never returns email, metadata, agent configuration, budget or spend.
* `POST /api/v2/workforce/updateWorkerSeat` under `workforce:write:org` sets a human seat's monthly budget.
* MCP: `forge_create_person`, `forge_update_person`, `forge_preview_person_merge`, `forge_merge_persons`, `forge_offboard_person`, `forge_reactivate_person`, `forge_get_person`, `forge_list_workers` and `forge_update_worker_seat` in the `workforce` group.

## Changed

* A person with any seat in a customer organization or under one is not found by the people routes and tools, exactly as an unknown person.
* Changing a worker seat's name, status or budget in Forge Console is now audited, on the person's history for an employee or contractor seat.

**2026-10-15**

Workflow library through the API and MCP.

## Added

* `POST /api/v2/workflows/createFiscalCalendar`, `PATCH updateFiscalCalendar` and `POST deleteFiscalCalendar`, and `POST createStep`, `PATCH updateStep` and `POST deleteStep`, under `workflows:manage` at the platform scope (the elevated `workflows:manage` scope, plus `workflows:read`). See [Fiscal calendars](https://docs.gloo.com/forge/reference/http-api/workflows#fiscal-calendars) and [Step library](https://docs.gloo.com/forge/reference/http-api/workflows#step-library).
* `GET /api/v2/workflows/listSteps` (`workflows:read` at the platform scope) and `GET /api/v2/workflows/listIngressInvocations` (an ingress trigger's recent requests, under the trigger read rule).
* MCP: `forge_create_fiscal_calendar`, `forge_update_fiscal_calendar`, `forge_delete_fiscal_calendar`, `forge_list_workflow_steps`, `forge_create_workflow_step`, `forge_update_workflow_step`, `forge_delete_workflow_step` and `forge_list_ingress_invocations` in the `workflows` group.

## Changed

* A step library entry's author is always the person or credential that created it; a `createdBy` value sent by the caller is ignored. Creating, changing and deleting a step is now audited, in Forge Console and the API.

**2026-10-15**

Person identity administration.

## Added

* `GET /api/v2/workforce/listPersonIdentities`, `POST linkPersonIdentity` and `POST unlinkPersonIdentity`; `GET listPersonEmailClaims`, `POST upsertPersonEmailClaim` and `POST revokePersonEmailClaim`; `GET getPersonCommunicationProfile`, `POST savePersonCommunicationProfile` and `GET listPersonCommunicationProfileHistory`, under `workforce:write:pods` (`workforce:manage` at the platform scope; changes also need the `workforce:read` scope). WorkOS sign-in bindings stay in the Console and Freshservice links are not accepted. See [Identities, email claims and profiles](https://docs.gloo.com/forge/reference/http-api/workforce#identities-email-claims-and-profiles).
* `GET /api/v2/workforce/listPersonAuditEvents` under `compliance:read` and `workforce:read` (`audit:read` and `workforce:read` at the platform scope).
* MCP: `forge_list_person_identities`, `forge_link_person_identity`, `forge_unlink_person_identity`, `forge_list_person_email_claims`, `forge_upsert_person_email_claim`, `forge_revoke_person_email_claim`, `forge_get_person_communication_profile`, `forge_save_person_communication_profile`, `forge_list_person_communication_profile_history` and `forge_list_person_audit_events` in the `workforce` group.

## Changed

* Reading the audit events of one resource now requires `audit:read` for every resource type except a project (which keeps `projects:read` and its visibility); before, any signed-in member could read them for most types.
* Adding or revoking a person's email claim, in Forge Console or the API, is now recorded on the person's history, and revoking a claim that is already revoked keeps its original revocation time and reason.

**2026-10-15**

Workforce: position assignment commands and the worker role list.

## Added

* `POST /api/v2/workforce/createPositionAssignment`, `PATCH /api/v2/workforce/updatePositionAssignment`, `POST /api/v2/workforce/endPositionAssignment` and `POST /api/v2/workforce/reassignPrimaryPosition` run the Console people page's assignment commands. They need `org:manage` (scope `workforce:write:org`) and `workforce:read` at the platform scope, take an audited `reason`, and answer assignment history rows. Workers, positions and assignments in or under a customer organization are `404`. See [Position assignment commands](https://docs.gloo.com/forge/reference/http-api/workforce#position-assignment-commands).
* `GET /api/v2/workforce/listWorkerRoles` lists every worker role (Job) without its agent configuration, under `workforce:read` at the platform scope.
* MCP tools `forge_create_position_assignment`, `forge_update_position_assignment`, `forge_end_position_assignment`, `forge_reassign_primary_position` and `forge_list_worker_roles` in the `workforce` group.

**2026-10-15**

Security: inference file confirm accepts only that file's own upload.

## Fixed

`POST /api/inference/v1/files/confirm` used to accept any `storage_id` whose bytes existed, so an app that knew another upload's storage id could add that file to its own knowledge. The `upload_url` that `POST /api/inference/v1/files` returns now points at Forge. Forge stores the bytes you upload there and records their storage id against the pending file. Confirm then accepts only that storage id. Any other answers `400` `storage_id_mismatch` with a sentence ending `Reference: <id>.` and a `decision_id`, and the refusal is recorded.

## Changed (integrators)

* Keep using the flow as before: upload the raw bytes with `POST` to `upload_url`, read `storageId` from its answer, and pass it as `storage_id` to confirm. The request and response shapes are unchanged.
* `upload_url` takes one upload of at most 20,971,520 bytes (20 MiB), within an hour of the `POST /files` call, and needs no `Authorization` header. A second upload to the same URL answers `409` `upload_already_received`, and a late one `403` `upload_url_expired`.
* A file started before this change and not yet confirmed cannot be confirmed, even if its bytes were uploaded. Start it again with `POST /api/inference/v1/files`.

See [Uploading a file for knowledge](https://docs.gloo.com/forge/reference/inference.md#uploading-a-file-for-knowledge).

**2026-10-15**

Trust Fabric: adding a file to knowledge, or importing an org chart, records who read the file.

## Changed

* Adding a file to knowledge from chat or a factory dispatch, an External App's confirmed upload, and the Rippling org-chart import now write one `file_read` audit event before the file is read. The event (category `file_access`, event `file_read`) names the person or app that asked, with `mode: "ingest"`.
* When that event cannot be written, the ingest refuses and reads nothing:
  * in chat, the conversation shows `"<file name>" was not added to knowledge, because Forge could not record reading it. Attach the file again to retry.`;
  * an External App's file ends in status `error` (`GET /api/inference/v1/files/get`);
  * the org-chart import answers `FILE_READ_NOT_RECORDED` with "The file read could not be recorded, so it was refused. Try again."

See [Audit events](https://docs.gloo.com/forge/run/audit.md).

**2026-10-15**

Webhooks are sent only for events in the event log.

## Changed

* Forge now writes an event to the event log before it sends any webhook for it, trying the write up to three times. Every webhook's `id` is the event's row in `GET /api/v2/events`, and one event has the same `id` on every subscription.
* If the write still fails, no webhook is sent for that event and operators see a `notification.event_log_write_failed` audit event naming it. In-app, Slack and email notifications still go out.
* An operator-only (`admin`) event is never in the event log, by design. Its webhook `id` is now the same for every subscription.

See [Webhooks](https://docs.gloo.com/forge/run/webhooks.md#ordering-gaps-and-reconciliation).

**2026-10-15**

Security: Console uploads are bound to the person who uploaded them.

## Fixed

Forge Console functions that take an uploaded file's storage id used to accept any storage id whose bytes existed. That covers chat and knowledge attachments, workflow run inputs, files returned on a human task, workflow documents, avatars, trace snapshots and the Rippling org-chart import. A person who learned another file's storage id could adopt that file as their own. Now the Console hashes the file before asking for an upload URL, and Forge issues that person a one-hour upload ticket for exactly those bytes. A storage id is accepted only with a ticket of the same person, issued before the file existed. Any other storage id is refused with "This file was not uploaded through Forge by you, so it cannot be used here. Upload it again."

A storage id belongs to the first person who uses it. A workflow launch accepts a raw storage id as a file input only from the person who uploaded it; Slack attachments now reach a run as platform files. Uploads still go straight to storage, so the upload size limit is unchanged. A Console tab opened before this release needs a reload before its next upload.

**2026-10-15**

The workforce directory needs workforce:read.

## Changed

* `orgWorkers.listWorkers`, `orgWorkers.listWorkersPage` and `orgWorkers.workerFacets` now require `workforce:read` at the platform scope; before, any signed-in member could read them.
* My Work → Reassign now searches people by name, and needs `approvals:approve`.
* The planning assignee, analytics worker, and environment and vault member pickers list people only for a person with `workforce:read`, and otherwise say so.

**2026-10-15**

The remaining worker directory reads need workforce:read.

## Changed

* `workers.list` now requires `workforce:read` instead of `workflows:read`, and `chatDM.listWorkersForDM` requires `workforce:read` instead of `chat:read`. Both return the whole worker directory.
* The workflow builder canvas names a node's specific person by reading that one worker, so building a workflow no longer needs the worker directory.

**2026-10-15**

Human tasks, Increment 3a: workflow and factory agents pause for a person's answer and resume.

## Changed

* A workflow agent node's `human_ask` now returns `status: "pending"` at once, as a chat agent's does. When the agent ends its turn, its node pauses: it holds no agent slot and no timer reaps it. When every question it asked has closed (answered, canceled at its due date, or declined), the node resumes on the same conversation, and each answer arrives as a Forge notice that names the person and the `requestId` and quotes the answer as fenced text.
* A factory worker's `human_ask` pauses its dispatch the same way, and the worker resumes on its own thread. A dispatch that needed an approval resumes on that approval: the same approval is never spent twice.
* For these agents, `human_check` and `human_withdraw` report a question's status without its answer. The answer arrives only as the Forge notice. Chat agents and agent nodes placed detached keep today's results.
* An agent node placed detached (in a sandbox) still waits up to 2 minutes for an answer in its turn, then withdraws the question.
* Rerunning a workflow from a step cancels the questions its earlier attempt left open, as `superseded`.
* A question answered through the API with a Personal key resumes the agent exactly as an answer in Forge Console does.
* A workflow node paused on a person shows a card in the run view with a link to each question in My Work.


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