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

# Workforce

> Read org units, positions, pods, people and workers; manage pods, people and identity links, and, at the platform scope, position assignments.

Workforce reads require `workforce:read`. A platform grant reads every homed row; an org-unit grant reads that unit and its descendants. An unhomed position is invisible. Missing and invisible get IDs both return `404`.

* [List org units](https://docs.gloo.com/forge/reference/http-api/workforce/listOrgUnits.md)
* [Get org unit](https://docs.gloo.com/forge/reference/http-api/workforce/getOrgUnit.md)
* [List positions](https://docs.gloo.com/forge/reference/http-api/workforce/listPositions.md)
* [Get position](https://docs.gloo.com/forge/reference/http-api/workforce/getPosition.md)

IDs stay in legacy space. Position assignments include assignment and worker IDs, nullable canonical `personId`, worker name and worker type. Position outputs exclude instructions, skills, tool permissions, governance overrides and billing data. These operations do not expose the raw worker/person directory; [Get worker](#worker-detail) reads one worker seat, and [People](#people) lists workers and reads and manages people at the platform scope.

Lists default to 50 rows and take a `limit` of at most 100; a larger one is `400` `too_big`. Lists scan legacy IDs past rows the caller cannot see until a page holds `limit` visible rows or the source ends, so a page is short or empty only when it is the last page. Continue using `meta.nextCursor` while `meta.hasMore` is true. Cursors and non-empty IDs are opaque strings, and a cursor never names a row the caller cannot see. Customer organizations, the org units under them and positions homed in either are never returned: lists omit them, single reads answer `404` like a missing ID, and joins and counts never name them.

Duplicate query keys, empty values, invalid limits and unknown status enums return `400`. Component or enrichment faults remain server failures; successful absence alone becomes `404` or nullable enrichment.

## Org-unit and position commands

Five commands change the org structure and require `org:manage`, which the credential's scopes must reach. Because each answers a workforce read projection, the credential's scopes must also reach `workforce:read`. Each needs `org:manage` and `workforce:read` at the home the Console checks: the platform scope for creating and moving org units, setting a position's agent-assignable flag and its reporting edge, and the target org unit for creating a position. A grant below that home is `403`. Each success answers the `WorkforceOrgUnit` or `WorkforcePosition` above.

* [Create org unit](https://docs.gloo.com/forge/reference/http-api/workforce/createOrgUnit.md)
* [Move org unit](https://docs.gloo.com/forge/reference/http-api/workforce/moveOrgUnit.md)
* [Create position](https://docs.gloo.com/forge/reference/http-api/workforce/createPosition.md)
* [Update position](https://docs.gloo.com/forge/reference/http-api/workforce/updatePosition.md)
* [Set position reporting](https://docs.gloo.com/forge/reference/http-api/workforce/setPositionReporting.md)

Customer organizations, the org units under them, positions homed in either and positions without an org unit are `404`, like a missing ID. Every refusal the org structure's own integrity rules would raise is decided first, as a `400` or `409`, and writes nothing. Bodies are strict: head-of-unit, role and instructions are not machine inputs. Seating a person or agent in a position is a [position assignment command](#position-assignment-commands). With an `Idempotency-Key`, a same-key retry within 24 hours returns the recorded result only while the caller still holds the same authority and can see the row; otherwise `409 idempotency_result_unavailable`. If an outcome is unknown, repeat with the same key or read the row; never retry under a new key.

Moving an org unit into another company also moves its seated agents' `agent_worker` role: each agent seated in the moved unit or a unit under it gets the role at the new company root, and loses a role a seat gave at the old one that no other seat or its home company needs. A move inside one company changes no role.

## Pods

Pod reads require `workforce:read` at the **platform scope**, as in the Console: a key or app whose grant covers only some org units receives `403`. Pods managed by a customer organization or by an org unit under one are never returned; single reads answer `404`, exactly as for a missing pod.

* [List pods](https://docs.gloo.com/forge/reference/http-api/workforce/listPods.md)
* [Get pod](https://docs.gloo.com/forge/reference/http-api/workforce/getPod.md)
* [List pod membership history](https://docs.gloo.com/forge/reference/http-api/workforce/listPodMembershipHistory.md)
* [Preview pod membership](https://docs.gloo.com/forge/reference/http-api/workforce/previewPodMembership.md)

Pod IDs are the IDs the Console uses; `managingOrgUnitId` and membership `workerId` are legacy IDs. Optional `at` (epoch milliseconds, default the request time) chooses which memberships count as effective. Roster workers carry worker and person IDs, name and type only. Outputs never include who created, updated, archived or verified a pod or membership, the archive reason, or manager resolution.

`listPods` defaults `limit` to 25, its maximum (a larger one is `400` `too_big`), filters by `status` (`active` by default) and optional `managingOrgUnitId`, and continues by an opaque cursor that never names a pod the caller cannot see. `listPodMembershipHistory` defaults to 50 rows, clamps at 100, and continues by the decimal sequence in `meta.nextCursor`; any other cursor is `400`.

`POST previewPodMembership` previews one membership change as the Console does and changes nothing. It requires `workforce:manage` at the platform scope (mutating, never given to the built-in Apps), and the credential's scopes must reach it. Validation refusals are `200` results with `status: "blocked"`; unknown pods and pods managed by or under a customer organization are `404`. The result carries the worker's ID, name and type but no person ID, and its overlapping memberships never name a pod you cannot see.

## Assignment history

Assignment history requires `workforce:read` at the **platform scope**, as in the Console; a key or app whose grant covers only some org units receives `403`.

* [List assignment history](https://docs.gloo.com/forge/reference/http-api/workforce/listAssignmentHistory.md)

Pass `workerId`, `positionId` or both. Rows are the Console's rows in the Console's order, newest start first: assignment, worker and position IDs (legacy space), `assignmentKind`, `startDate`, optional `endDate` and `supersededByAssignmentId`, and the worker name, position title and org unit name. Who made an assignment, and why, is never returned. The whole history (at most 500 rows) arrives in one response without `limit`, or in pages of `limit` with `cursor`. Rows in a customer organization's org unit or an org unit under one, or in no org unit, are omitted; a `positionId` the caller cannot see returns `404`, and an unknown `workerId` returns an empty list. The [position assignment commands](#position-assignment-commands) create, change, end and reassign these rows. Seating an agent also gives it the `agent_worker` role (`workflows:use`, `tools:read`) at the company root of the position's org unit, or at the platform scope for a system agent; ending the seat removes a role the seat gave, unless another of the agent's seats or its home company still needs it. A seat whose end is dated in the future keeps the role until that end.

## Position assignment commands

Four commands change position assignments as the Console's people page does, and require `org:manage`, which the credential's scopes must reach. Each needs `org:manage` and `workforce:read` at the **platform scope** (the Console's home for these commands); a grant below it is `403`. Because each answers assignment rows, the credential's scopes must also reach `workforce:read`. Each takes a non-blank `reason`, recorded in the audit log with the calling key or app, and dates in epoch milliseconds.

* [Create position assignment](https://docs.gloo.com/forge/reference/http-api/workforce/createPositionAssignment.md)
* [Update position assignment](https://docs.gloo.com/forge/reference/http-api/workforce/updatePositionAssignment.md)
* [End position assignment](https://docs.gloo.com/forge/reference/http-api/workforce/endPositionAssignment.md)
* [Reassign primary position](https://docs.gloo.com/forge/reference/http-api/workforce/reassignPrimaryPosition.md)

A success is the assignment history row (create and update), `{assignment, outcome}` (end; `ALREADY_ENDED` changes nothing) or `{assignment, endedAssignment}` (reassign; `endedAssignment` is `null` when no primary ended). Rows never name who made an assignment. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are `404` (`Worker not found`, `Position not found`, `Assignment not found`). Refusals end with the Console's code in parentheses and write nothing: `400` (`ASSIGNMENT_REASON_REQUIRED`, `INVALID_ASSIGNMENT_INTERVAL`), `404` (`MISSING_ASSIGNMENT_TARGET`), `409 invalid_state` (`INACTIVE_ASSIGNMENT_TARGET`), `409 conflict` (`AGENT_ASSIGNMENT_INCOMPATIBLE`, `PRIMARY_ASSIGNMENT_OVERLAP`, `PRIMARY_ASSIGNMENT_AMBIGUOUS`, `INVALID_ASSIGNMENT_SUPERSESSION`) and `413` (`INTEGRITY_ASSIGNMENT_LIMIT`, past 500 assignments). The Console's rule that an agent cannot manage a human worker is refused as `500`, with nothing written. Seating and unseating agents moves their `agent_worker` role exactly as described under [Assignment history](#assignment-history).

With an `Idempotency-Key`, a same-key retry within 24 hours returns the recorded result only while the caller still holds the same authority and can see every assignment the result names; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. Without one, a repeated create records a second assignment (or is refused as an overlapping primary), an update writes and audits again, an end answers `ALREADY_ENDED`, and a reassignment reassigns again.

## Worker roles

* [List worker roles](https://docs.gloo.com/forge/reference/http-api/workforce/listWorkerRoles.md)

The worker roles (Jobs) a position can carry, oldest first, in one response without `limit`, or in pages of `limit` with `cursor`, as the Console's Jobs picker lists them: ID, `roleId`, name, description and the system and template flags. A role's agent configuration and its author are never returned. Requires `workforce:read` at the platform scope; more than 500 roles is `413`.

## Pod membership writes

Membership writes require `workforce:manage`, reached by the credential's scopes and held at the **platform scope** as in the Console; a key or app whose grant covers only some org units receives `403`. Because every success returns the membership, the credential's scopes must also include `workforce:read`; otherwise `403` naming `workforce:read`, and nothing is written. Built-in apps never receive `workforce:manage`. Each write runs the Console's own command, so its UTC-day dates, person-capacity check, verification window and audit record are unchanged.

* [Add pod membership](https://docs.gloo.com/forge/reference/http-api/workforce/addPodMembership.md)
* [Change pod membership effective](https://docs.gloo.com/forge/reference/http-api/workforce/changePodMembershipEffective.md)
* [Update future pod membership](https://docs.gloo.com/forge/reference/http-api/workforce/updateFuturePodMembership.md)
* [End pod membership](https://docs.gloo.com/forge/reference/http-api/workforce/endPodMembership.md)
* [Delete future pod membership](https://docs.gloo.com/forge/reference/http-api/workforce/deleteFuturePodMembership.md)
* [Confirm pod membership accuracy](https://docs.gloo.com/forge/reference/http-api/workforce/confirmPodMembershipAccuracy.md)

Every body is exactly the command's arguments; unknown fields return `400`. `expectedMembershipRevision` is the pod's current `membershipRevision`. A pod whose managing org unit is a customer organization or sits under one returns `404`, exactly as a missing pod (the same rule as the org-unit and position commands). A refusal returns `400` (invalid allocation or dates, a missing correction reason), `404` (membership or worker seat not found) or `409` (overlap, capacity, stale revision, archived pod, ineligible seat, future-only or ended membership); its message ends with the Console's code in parentheses, such as `(POD_MEMBERSHIP_CAPACITY_EXCEEDED)`. Results never name who created, updated or verified a membership. With an `Idempotency-Key`, a same-key retry within 24 hours returns the recorded result while the caller's scopes still include `workforce:read`, it still holds `workforce:manage` and the pod's managing org unit is still outside every customer organization; otherwise `409 idempotency_result_unavailable`. Pod-to-Customer assignments are below.

## Pod lifecycle, ownership and internal profiles

Pod create, update and archive, and pod owner and internal delivery profile writes, use the same key `workforce:manage` (held at the **platform scope**) and the same rules as the membership writes: the credential's scopes must also include `workforce:read`, each write runs the Console's own command, and a refusal ends with the Console's code in parentheses. A pod whose managing org unit is a customer organization or sits under one returns `404` exactly as a missing pod, and so does an owner assignment or internal profile of such a pod, or an ID that does not resolve. Creating a pod, or moving one, under a managing org unit that does not exist, is a customer organization or sits under one returns `404` ending `(MANAGING_ORG_UNIT_NOT_FOUND)`.

* [Create pod](https://docs.gloo.com/forge/reference/http-api/workforce/createPod.md), [Update pod](https://docs.gloo.com/forge/reference/http-api/workforce/updatePod.md), [Archive pod](https://docs.gloo.com/forge/reference/http-api/workforce/archivePod.md)
* [Assign pod owner](https://docs.gloo.com/forge/reference/http-api/workforce/assignPodOwner.md), [Change pod owner effective](https://docs.gloo.com/forge/reference/http-api/workforce/changePodOwnerEffective.md), [End pod owner](https://docs.gloo.com/forge/reference/http-api/workforce/endPodOwner.md), [List pod owners](https://docs.gloo.com/forge/reference/http-api/workforce/listPodOwners.md)
* [Set pod internal profile](https://docs.gloo.com/forge/reference/http-api/workforce/setPodInternalProfile.md), [End pod internal profile](https://docs.gloo.com/forge/reference/http-api/workforce/endPodInternalProfile.md), [List pod internal profiles](https://docs.gloo.com/forge/reference/http-api/workforce/listPodInternalProfiles.md)

`updatePod` and `archivePod` take the pod's `updatedAt` from [Get pod](https://docs.gloo.com/forge/reference/http-api/workforce/getPod.md) as `expectedUpdatedAt`; a stale value returns `409` ending `(POD_ROSTER_CHANGED)`. A move to another managing org unit needs a `reason`, and `reason` without a move returns `400 (POD_REASON_REQUIRED)`. Archiving ends the pod's open memberships and records the reason in the audit; results never carry it. Owner and profile rows carry a `revision`; send it as `expectedRevision`. A pod's owner intervals never overlap, and an internal profile cannot overlap another profile or any Customer assignment of the pod. Dates are UTC day boundaries; a change dated before today needs `correctionReason`. Results never name who created or updated a row.

`listPodOwners` and `listPodInternalProfiles` require `workforce:read` at the platform scope and take `podId`, `startsAt` and `endsAt` (UTC day boundaries, at most 366 days apart) They return every row that overlaps the window, oldest first, paged with `limit` and `cursor`; more than 100 overlapping rows return `413` with `error.code: "payload_too_large"`, never a truncated list. Owner rows carry the owner's display name and whether the person is `current`, `inactive` or `unresolved`.

With an `Idempotency-Key`, a same-key retry of any of these writes within 24 hours returns the recorded result under the same rule as the membership writes. Without a key, a repeat is refused by the command's own name, revision or overlap check.

## Pod Customer assignments

Pod-to-Customer assignment writes use the same key `workforce:manage` (held at the **platform scope**) and the same rules as the other pod writes: the credential's scopes must also include `workforce:read`, each write runs the Console's own command, and a refusal ends with the Console's code in parentheses. The reads require `workforce:read` at the platform scope. No route needs `customers:read`: as in the Console, each Customer's name, type and status are part of the Workforce answer. A pod whose managing org unit is a customer organization or sits under one returns `404` exactly as a missing pod, and so does any assignment of such a pod, or an assignment ID that does not resolve.

* [Assign pod customer](https://docs.gloo.com/forge/reference/http-api/workforce/assignPodCustomer.md), [Change pod customer assignment effective](https://docs.gloo.com/forge/reference/http-api/workforce/changePodCustomerAssignmentEffective.md), [Update future pod customer assignment](https://docs.gloo.com/forge/reference/http-api/workforce/updateFuturePodCustomerAssignment.md), [Delete future pod customer assignment](https://docs.gloo.com/forge/reference/http-api/workforce/deleteFuturePodCustomerAssignment.md), [End pod customer assignment](https://docs.gloo.com/forge/reference/http-api/workforce/endPodCustomerAssignment.md), [Confirm pod customer assignment accuracy](https://docs.gloo.com/forge/reference/http-api/workforce/confirmPodCustomerAssignmentAccuracy.md)
* [Preview pod customer assignment](https://docs.gloo.com/forge/reference/http-api/workforce/previewPodCustomerAssignment.md)
* [List pod customer assignments](https://docs.gloo.com/forge/reference/http-api/workforce/listPodCustomerAssignments.md), [List customer pod assignments](https://docs.gloo.com/forge/reference/http-api/workforce/listCustomerPodAssignments.md), [List pod customer assignment history](https://docs.gloo.com/forge/reference/http-api/workforce/listPodCustomerAssignmentHistory.md)

An assignment gives an active Organization Customer `allocationPercent` (1–100) of a pod's capacity from a UTC day, optionally split into delivery slices by delivery type, reporting category and stage. A Customer has at most one assignment to a pod at a time, a pod's assignments never exceed 100% at any moment, and an assignment cannot overlap the pod's internal profile. Rows carry a `revision`; send it as `expectedRevision`. A change dated before today needs `correctionReason`; only an assignment that has not started can be edited with `updateFuturePodCustomerAssignment` or deleted. Confirming accuracy moves the verification due date forward; reads report each row's verification as `current` or `stale`. Results never name who created, updated or verified a row.

`POST previewPodCustomerAssignment` previews one `assign`, `change-effective`, `update-future` or `end` operation as the Console does and changes nothing; refusals are `200` results with `status: "blocked"`. It takes no `Idempotency-Key`.

`listPodCustomerAssignments` (by `podId`) and `listCustomerPodAssignments` (by `customerId`) take `startsAt` and `endsAt` (UTC day boundaries, `endsAt` exclusive) and return the rows that overlap the window a page at a time, oldest effective end first: `limit` is 1–100 (default 100; a larger value is `400` `too_big`), and while `meta.hasMore` is `true`, `meta.nextCursor` passed as `cursor` with the same other parameters reads the next page. A Customer's list omits assignments of pods managed by or under a customer organization without naming them. A row that starts after the window ends, or of such a pod, is left out after the read, so a page may hold fewer rows than `limit`, or none, while more remain. Neither answers `413` for a large window. `listPodCustomerAssignmentHistory` pages a pod's assignments, latest effective end first: `limit` defaults to 20 and clamps at 50, and `meta.nextCursor` continues it; an unreadable cursor returns `400`.

With an `Idempotency-Key`, a same-key retry of any of these writes within 24 hours returns the recorded result under the same rule as the membership writes. Without a key, a repeat is refused by the command's own revision or overlap check.

## Worker detail

[Get worker](https://docs.gloo.com/forge/reference/http-api/workforce/getWorker.md) reads one worker seat by `id`: name, type, status, person ID, current position and its team and department. It requires `workforce:read` at the **platform scope**. It never returns the owner's email, metadata, agent configuration, budget or spend. A worker with any current or upcoming assignment in a customer organization or an org unit under one returns `404`, exactly as a missing worker.

## People

People are not homed in an org unit, so every people operation is decided at the **platform scope** (Console parity): a grant that covers only some org units receives `403`. A person reaches a machine caller only when none of their seats sits in a customer organization or an org unit under one; any other person, an unknown ID, or an ID merged into such a person returns `404` with the same message. Results never carry a person's avatar URL, and audit rows name the calling credential.

* [Create person](https://docs.gloo.com/forge/reference/http-api/workforce/createPerson.md), [Update person](https://docs.gloo.com/forge/reference/http-api/workforce/updatePerson.md), [Reactivate person](https://docs.gloo.com/forge/reference/http-api/workforce/reactivatePerson.md)
* [Preview person merge](https://docs.gloo.com/forge/reference/http-api/workforce/previewPersonMerge.md), [Merge persons](https://docs.gloo.com/forge/reference/http-api/workforce/mergePersons.md), [Offboard person](https://docs.gloo.com/forge/reference/http-api/workforce/offboardPerson.md)
* [Get person](https://docs.gloo.com/forge/reference/http-api/workforce/getPerson.md), [List workers](https://docs.gloo.com/forge/reference/http-api/workforce/listWorkers.md)
* [Update worker seat](https://docs.gloo.com/forge/reference/http-api/workforce/updateWorkerSeat.md)

The person changes use the key `workforce:manage` (held at the platform scope) and, because each returns the person or its counts, the credential's scopes must include `workforce:read` as well (otherwise `403` naming `workforce:read`, and nothing changes). Each runs the Console's own command and ends a refusal with the Console's code in parentheses, e.g. `(PERSON_SEAT_TYPE_CONFLICT)`. A duplicate or email conflict names the other person (`conflicting person <id>`) only when that person is in reach. `reason` is required; for merge, offboard and reactivate it is 1–500 characters.

**Merge and offboard change people for good.** A merge cannot be undone: there is no unmerge, the loser becomes an inactive redirect, and a role grant both people hold is kept once (the loser's copy is deleted). Call [Preview person merge](https://docs.gloo.com/forge/reference/http-api/workforce/previewPersonMerge.md) first; it writes nothing and shows exactly what would move. An offboard is only partly reversible: reactivating restores the person and one seat, never claims, role grants, Personal keys or personal agents. Send an `Idempotency-Key` with both.

[Get person](https://docs.gloo.com/forge/reference/http-api/workforce/getPerson.md) and [List workers](https://docs.gloo.com/forge/reference/http-api/workforce/listWorkers.md) require `workforce:read` at the platform scope. A person includes every human seat with its monthly budget and spend; the worker list never returns email, metadata, agent configuration, budget or spend, and leaves out workers seated in a customer organization and every seat of a person with any such seat. [Update worker seat](https://docs.gloo.com/forge/reference/http-api/workforce/updateWorkerSeat.md) sets a human seat's monthly budget under `org:manage` (with `workforce:read`, both at the platform scope) and records it on the person's history.

With an `Idempotency-Key`, a same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read`, you still hold the route's authority at the platform scope, and every person the result names is still in reach; otherwise `409 idempotency_result_unavailable` (see [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md#people-replay)). Without a key, a create with no email makes a second person, an update writes again, a merge or reactivate returns `409`, and an offboard returns `alreadyInactive: true`.

## Identities, email claims and profiles

A person's identity links, email claims and communication profile follow the [People](#people) rules: each operation is decided at the **platform scope**, needs `workforce:manage`, and answers `404 Person not found` for a person out of reach.

* [List person identities](https://docs.gloo.com/forge/reference/http-api/workforce/listPersonIdentities.md), [Link person identity](https://docs.gloo.com/forge/reference/http-api/workforce/linkPersonIdentity.md), [Unlink person identity](https://docs.gloo.com/forge/reference/http-api/workforce/unlinkPersonIdentity.md)
* [List person email claims](https://docs.gloo.com/forge/reference/http-api/workforce/listPersonEmailClaims.md), [Add person email claim](https://docs.gloo.com/forge/reference/http-api/workforce/upsertPersonEmailClaim.md), [Revoke person email claim](https://docs.gloo.com/forge/reference/http-api/workforce/revokePersonEmailClaim.md)
* [Get person communication profile](https://docs.gloo.com/forge/reference/http-api/workforce/getPersonCommunicationProfile.md), [Save person communication profile](https://docs.gloo.com/forge/reference/http-api/workforce/savePersonCommunicationProfile.md), [List person communication profile history](https://docs.gloo.com/forge/reference/http-api/workforce/listPersonCommunicationProfileHistory.md)

Each change runs the Console's own command and, because it returns the person's record, the credential's scopes must include `workforce:read` as well. **WorkOS sign-in bindings are managed in the Console**: linking or unlinking provider `workos` decides who signs in as the person, so these routes refuse it with `400`. A Freshservice link names the synchronized Freshservice Knowledge source, the org unit it is homed at and the technician, and needs `knowledge:read` at that org unit as well, as in the Console. An identity never carries its email, a profile revision never names its editor, and an email claim's origin shows as `providerName` (`api` or `console`).

An email claim is sign-in relevant: the first verified sign-in with a claimed address binds an unbound person. Adding and revoking claims is recorded on the person's history (the claim ID and the reason, never the address), and revoking a claim that is already revoked keeps its original revocation. With an `Idempotency-Key`, the five changes replay under the [people rule](https://docs.gloo.com/forge/reference/idempotency.md#people-replay).

## Person history

[List person audit events](https://docs.gloo.com/forge/reference/http-api/workforce/listPersonAuditEvents.md) pages the audit events on a person's history, newest first. A person's record is a read about the person, so it requires `audit:read` and `workforce:read` at the platform scope, and the credential's scopes must include both. It returns the event, its category, whether a person or a credential acted and when, and only the detail the Console's person history shows (counts and the reason); never who acted, run or resource IDs, or before and after values. Every other single-resource audit read in Forge also requires `audit:read`.

## Resourcing settings

The settings behind the resourcing views are platform rows with no per-record home, so each operation is decided at the **platform scope** (Console parity): a grant that covers only some org units receives `403`. Reads need `workforce:read`; changes need `workforce:manage`, which built-in apps never receive. Because each change returns the written row, its credential's scopes must include `workforce:read` as well (otherwise `403` naming `workforce:read`, and nothing changes). Dates are UTC midnight epoch milliseconds.

* [Get person allocation](https://docs.gloo.com/forge/reference/http-api/workforce/getPersonAllocation.md): one person's pod memberships, derived customer allocations and availability over a window, by `personId` or `workerId`. The person is projected as `listEngineers` projects one; a person in a pod managed by, or under, a customer organization answers `404`.
* [Get engineering scope](https://docs.gloo.com/forge/reference/http-api/workforce/getEngineeringScope.md) and [Set engineering scope](https://docs.gloo.com/forge/reference/http-api/workforce/setEngineeringScope.md): the effective-dated org units that form the engineering pool.
* [List reporting categories](https://docs.gloo.com/forge/reference/http-api/workforce/listReportingCategories.md), [Create reporting category](https://docs.gloo.com/forge/reference/http-api/workforce/createReportingCategory.md) and [Update reporting category](https://docs.gloo.com/forge/reference/http-api/workforce/updateReportingCategory.md): the delivery classification categories (at most 100).
* [List bandwidth feedback](https://docs.gloo.com/forge/reference/http-api/workforce/listBandwidthFeedback.md): one worker's newest bandwidth reports.

The changes run the Console's own commands and end every refusal with the Console's code in parentheses. Results never name who created or updated a row, or who answered a bandwidth report. A same-key retry within 24 hours returns the recorded result only while your scopes still include `workforce:read` and you still hold `workforce:manage` at the platform scope; otherwise `409 idempotency_result_unavailable` (see [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md#resourcing-settings-replay)).

## Engineering resourcing snapshots

Three GET operations provide the Engineers, Pods and Customers planning perspectives and require `workforce:read`. The credential's scopes must reach it, and its grants must hold it at **platform scope**; an org-unit-only grant receives `403`.

| Operation | Result |
| - | - |
| `GET /api/v3/engineers` | One employee-derived Engineering pool summary, future capacity boundaries and one Engineer detail page |
| `GET /api/v3/pod-planning` | Visible Pod headcount, allocated FTE, assignment percentages and typed delivery context |
| `GET /api/v3/customer-planning` | Minimal canonical Customer summaries and staffing FTE joined only to visible Pods |

Each request requires `startsAt`, exclusive `endsAt`, and `at`, all UTC midnight epoch milliseconds. `at` must lie inside a window of at most 366 days. `numItems` defaults to 20 and must be an integer from 1 through 20. Continue with the opaque `cursor` from `meta.nextCursor`; it belongs to that exact window, evaluation date, filters and page size. Invalid or stale cursors, duplicate or unknown keys, empty values and invalid filters return `400`. Bounded-source limits return `413` with `error.code: "payload_too_large"` and message `ENGINEERING_PLANNING_LIMIT_EXCEEDED`, never partial totals.

The success envelope is `{data, meta: {requestId, hasMore, nextCursor}}`. `data` retains the planning page and its `scope`, `isDone` and `continueCursor`; Engineers also include `summary`, `boundaries` and `matchingRows`. Those values come from one authorized query snapshot. Engineer row `query`, `mode` and pagination do not change the pool summary. `engineeringGroupId` refines the pool; `mode` is `all`, `available` (default), `opening`, `full`, `over` or `review`, and `minAvailable` is 0–100 (default 0, positive capacity in available mode). Search matches names, never email.

Pod and Customer requests accept `query`, `podId`, `customerId`, `staffingOrgUnitId`, `deliveryType`, `categoryKey`, and `stage`. Delivery types are `msp`, `project`, `platform`, and `forward_deployed`; stages are `pre_deal` and `engaged`. Filters multiply matching classification percentage points by membership percentages; they never convert a matching slice into the whole parent allocation. Partners remain distinct from the Gloo employee denominator. Available Engineer capacity is 100% minus all Pod commitments; Customer-unattributed capacity can include internal work. Over-allocation stays negative, and missing legacy percentages remain conservative 100% commitments.

Customer-housed org units, their subtrees and their Pods are hidden before results, totals and cursors. An Engineer with any hidden Pod commitment anywhere in the reporting window is omitted rather than displayed as falsely available. Engineer `scope.visibility` is `visible_employee_pool_all_commitments_visible`; delivery scope is `visible_pods`. No global omitted or hidden count is returned. Customer pages cover Customers related to visible workforce assignments, not an unrestricted CRM directory. A restricted or unresolved owner display is null; ownership never increases Pod staffing. Historical source gaps remain coverage gaps, not verified bench. Outputs omit primary email, audit identities, unrestricted CRM fields, SOW, signatures, contracts and revenue evidence. Editing remains in Forge Console.

Engineer rows emit optional `capacityTimeline` segments covering the selected window contiguously:
`{startsAt, endsAt, eligible, allocatedPercent, availablePercent}`. Ends are exclusive. These values
use authoritative eligibility and Pod commitments; negative availability indicates overallocation.
Proven outside-scope time has `eligible: false` and zero availability. Historical time without
employment evidence has null eligibility and availability. Current group labels describe `at`, while
future transfers still affect the timeline. `engineeringGroupId` must select an effective configured
Engineering unit or its known active descendant; invalid selections return `400` with
`ENGINEERING_PLANNING_INPUT_INVALID`.

Pod and Customer `resourcing` context emits optional `staffingAffiliationCoverage` with `status`
(`proven`, `incomplete`, or `historical_unproven`) and `unprovenFte`. The latter is the portion of
counted, filtered staffing whose worker identity or employer is unproven, bounded by the existing total staffing FTE.
The existing Gloo/partner-and-other split keeps its arithmetic; unknown employer evidence never
proves partner affiliation. Historical reports carry the qualifier even at zero FTE. Older responses
may omit the field; clients should treat omission as unavailable evidence.

Staffing-organization filters follow dated Position changes at each timeline boundary. Historical windows whose employment/organization context cannot be proven are refused with `400 bad_request` and message `ENGINEERING_STAFFING_HISTORY_UNPROVEN`; they never return an attributed zero as proven coverage. Hidden or unknown staffing-organization selectors yield no matches, and hidden organization names/IDs are omitted from member affiliation.


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