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

# Factories

> Inspect factories, their workers, tasks, milestones, spend and catalogs; maintain tasks; message the manager agent; pause, resume or archive a factory.

Factories are autonomous production units: a Factory Type plus a Factory Manager agent, a team of workers, dedicated channels, dev environments, and a budget. Over the API, external dashboards and integrations can list factories, their worker rosters, tasks, assignments and release milestones; read token spend by factory, task, project or worker; and read the blueprint and factory-type catalogs and the indexed codebase. They can also create, edit, assign and move a factory's tasks, message a factory's manager agent, and pause, resume or archive a factory.

## Resource shape

Every factory read returns only factories your key or External App may read: it must hold `factories:read` at the factory's home org unit, or at an org unit above it. A factory with no home org unit is never returned.

* `Factory` — `id`, `_creationTime`, `name`, `description`, `factoryType`, `status`, `managerAgentId`, `channelIds`, `budgetHierarchyId`, `blueprintId`, `blueprintVersion`, `ownerType`, `ownerId`, `createdBy`, `createdAt`, and `updatedAt`. Optional fields are omitted when unset.
* `FactoryListItem` — a `Factory` plus the bounded counts `teamMemberCount`, `activeTaskCount`, and `activeRunCount` (active assignments).
* `FactoryWorker` — `id`, `_creationTime`, `factoryId`, `personId`, `workerId`, `workerType`, `factoryRole`, `permissions`, `agentDefinitionId`, `status`, `joinedAt`, `leftAt`, and `workerName`.
* `FactoryDetail` — a `Factory` plus `team`, `teamPartial`, and `recentTasks`.
* `FactorySpend` — `factoryId`, `taskId`, `window`, `coveredFrom`, `totals`, `bySource`, `byModel`, `byAgentWorker`, `humanWorkers`, and `byTask`. Every total carries `totalTokens`, `inputTokens`, `outputTokens`, `thinkingTokens`, `costCents`, and `eventCount`. The provider, project, workflow run, org-unit columns, micro-dollar cost, and any human worker's ID are not returned.
* `FactoryTask` — `id`, `_creationTime`, `factoryId`, `title`, `status`, `priority`, `taskKind` (`null` when unset), `tags` (`[]` when unset), `assignee` (`{ type: "agent", workerId }`, `{ type: "person" }`, or `null`; `workerId` is `null` unless the agent is an active member of the factory's team), `assigneeName` (`null` when Forge does not know the name), `createdBy`, `github` (`pullRequest`, `issue` and `commitSha`, each `null` when unset; `null` when the task has no GitHub link), `createdAt`, and `updatedAt`.
* `FactoryTaskDetail` — a `FactoryTask` plus `description` (`null` when unset).
* `FactoryBlueprint` — `id`, `name`, `description`, `factoryTypeId`, `version`, `status`, `defaultTeam`, `additionalChannels`, `budgetDefaults`, `createdAt`, and `updatedAt`. Factory configuration, manager prompt text, the creator, a channel's external link, and repository settings are not returned.
* `FactoryAssignment` — `id`, `factoryId`, `assignmentType` (`project`, `workflow`, or `task`), `projectId`, `workflowId`, `taskId` (exactly one is set), `status` (`ACTIVE`, `COMPLETED`, or `CANCELLED`), `assignedAt`, and `completedAt`.
* `FactoryRelease` — `id`, `name`, `quarter`, `targetDate`, `releaseVersion`, `status`, and `updatedAt`.
* `FactoryEntitySpend` — `entity` (`kind` `task`, `project`, or `worker`, and `id`), `window`, `coveredFrom`, `totals`, `bySource`, and `byModel`, summed across every factory.
* `FactoryType` — `typeId`, `name`, `description`, `version`, `category`, `status`, the manager template (`managerRoleId`, `managerSkillKeys`, `managerTrustLevel`, `managerSandbox`), `workerRoleTemplates`, `defaultChannels`, `requiredIntegrations`, `createdAt`, and `updatedAt`. The manager's system prompt and every tools profile are not returned.
* `CodebaseFile` — `path` and `chunks`. `CodebaseSearchHit` — `path`, `chunk`, `chunkIndex`, and `language`.

Each schema is an explicit allowlist and rejects other fields. Factory configuration, the manager thread, the home org unit, a worker's dev-environment user, whole task rows, and owner objectives are not returned. A task never carries a person assignee's ID, its project, or other task links.

A task is visible only through its factory: it must belong to a factory you may read. A task with no factory is never returned.

## Operations

Reads:

* `GET /api/v3/factories` — [listFactories](https://docs.gloo.com/forge/reference/http-api/factories/list.md) — one page of the factories you may read, newest first
* `GET /api/v3/factories/{factoryId}` — [getFactory](https://docs.gloo.com/forge/reference/http-api/factories/get.md) — fetch a single factory by ID
* `GET /api/v3/factories/{factoryId}/workers` — [listFactoryWorkers](https://docs.gloo.com/forge/reference/http-api/factories/listWorkers.md) — one page of a factory's active members
* `GET /api/v3/factories/{factoryId}/spend` — [getFactorySpend](https://docs.gloo.com/forge/reference/http-api/factories/getSpend.md) — a factory's token spend over a window of at most 30 days
* `GET /api/v3/factory-tasks/{taskId}/spend` — [getFactoryTaskSpend](https://docs.gloo.com/forge/reference/http-api/factories/getTaskSpend.md) — one task's factory token spend over a window
* `GET /api/v3/projects/{projectId}/spend` — [getProjectFactorySpend](https://docs.gloo.com/forge/reference/http-api/factories/getProjectSpend.md) — one project's factory token spend over a window
* `GET /api/v3/factory-workers/{workerId}/spend` — [getWorkerFactorySpend](https://docs.gloo.com/forge/reference/http-api/factories/getWorkerSpend.md) — one worker's factory token spend over a window
* `GET /api/v3/factory-tasks` — [listFactoryTasks](https://docs.gloo.com/forge/reference/http-api/factories/listTasks.md) — one page of a factory's tasks, or of one task kind across factories, optionally one `status`, in index order
* `GET /api/v3/factory-tasks/{taskId}` — [getFactoryTask](https://docs.gloo.com/forge/reference/http-api/factories/getTask.md) — fetch a single task with its description
* `GET /api/v3/factories/{factoryId}/assignments` — [listFactoryAssignments](https://docs.gloo.com/forge/reference/http-api/factories/listAssignments.md) — one page of a factory's assignments, `ACTIVE` by default
* `GET /api/v3/factories/{factoryId}/releases` — [listFactoryReleases](https://docs.gloo.com/forge/reference/http-api/factories/listReleases.md) — a factory's release milestones, most recently updated first
* `GET /api/v3/factory-blueprints` — [listFactoryBlueprints](https://docs.gloo.com/forge/reference/http-api/factories/listBlueprints.md) — one page of the deployment's blueprint catalog
* `GET /api/v3/factory-blueprints/{blueprintId}` — [getFactoryBlueprint](https://docs.gloo.com/forge/reference/http-api/factories/getBlueprint.md) — fetch a single blueprint by ID
* `GET /api/v3/factory-types/{typeId}` — [getFactoryType](https://docs.gloo.com/forge/reference/http-api/factories/getType.md) — fetch a single factory type by its type ID
* `GET /api/v3/factory-codebase-files` — [listCodebaseFiles](https://docs.gloo.com/forge/reference/http-api/factories/listCodebaseFiles.md) — the indexed codebase's files and chunk counts
* `GET /api/v3/factory-codebase-search` — [searchCodebase](https://docs.gloo.com/forge/reference/http-api/factories/searchCodebase.md) — text search over the indexed codebase's chunks

Task writes:

* `POST /api/v3/factories/{factoryId}/tasks` — [createFactoryTask](https://docs.gloo.com/forge/reference/http-api/factories/createTask.md) — create a task on a factory (`factories:manage`)
* `PATCH /api/v3/factory-tasks/{taskId}` — [updateFactoryTask](https://docs.gloo.com/forge/reference/http-api/factories/updateTask.md) — edit a task's title, description, priority or tags (`projects:manage`)
* `POST /api/v3/factory-tasks/{taskId}/assign` — [assignFactoryTask](https://docs.gloo.com/forge/reference/http-api/factories/assignTask.md) — assign a task to an agent of its factory, or unassign it (`projects:manage`)
* `POST /api/v3/factory-tasks/{taskId}/transition` — [transitionFactoryTask](https://docs.gloo.com/forge/reference/http-api/factories/transitionTask.md) — move a task to another status (`factories:manage`)

Operating a factory:

* `POST /api/v3/factories/{factoryId}/send-message` — [sendFactoryMessage](https://docs.gloo.com/forge/reference/http-api/factories/sendMessage.md) — message the factory's manager agent in one of its chat sessions; a billable model turn (`factories:manage`)
* `POST /api/v3/factories/{factoryId}/pause` — [pauseFactory](https://docs.gloo.com/forge/reference/http-api/factories/pause.md) — block new work through the factory (`switches:use`)
* `POST /api/v3/factories/{factoryId}/resume` — [resumeFactory](https://docs.gloo.com/forge/reference/http-api/factories/resume.md) — restore a paused factory (`switches:use`)
* `DELETE /api/v3/factories/{factoryId}` — [archiveFactory](https://docs.gloo.com/forge/reference/http-api/factories/archive.md) — archive the factory permanently (`switches:use`)

The paged reads (`list`, `listWorkers`, `listTasks`, `listAssignments` and `listBlueprints`) take `limit` (1–50, default 50) and `cursor`. Follow `meta.nextCursor` while `meta.hasMore` is `true`. A page can be short or empty before the last page. A factory or task you may not read answers `404 resource_missing`, the same as a missing one.

## Task writes

Each task write needs the key Console checks for the same operation. Creating and moving a task need `factories:manage`. Editing and assigning one need `projects:manage`. Neither key is given to the built-in apps. Your credential's scopes must reach the key, your role grants must hold it at the task's home, which is its factory's org unit, and the check is made again inside the write.

Console files a task created without a project under the legacy software project, and so does `createTask`. It therefore also needs `factories:manage` at that project's home, the deployment root. You must be able to read the factory or task (`factories:read`); otherwise the answer is `404`.

Machines never set a project, a GitHub link, a beneficiary or a person assignee. An agent assignee must be an active agent member of the task's own factory. Pass `expectedUpdatedAt` or `expectedStatus` to turn a stale write into `409 conflict`.

A task write changes the task only: nothing is scheduled, and assigning an agent does not start it. Send an `Idempotency-Key`: a repeat within 24 hours replays the recorded response only while you may still write the task. Otherwise it answers `409`, and the write never runs twice.

## Operating a factory

Messaging a factory's manager agent needs `factories:manage` at the factory's home and at the session's home, and the credential's scopes must reach `factories:manage`. The message goes into an open session in one of the factory's channels (`channelIds`), and the manager answers later in that session: read the reply with `GET /api/v3/chat-sessions/{sessionId}/messages`. Messages are text only, and a factory that is not active (paused, archived or still provisioning) refuses them with `409`.

Pausing, resuming and archiving need `switches:use` at the factory's home. It is an approve-and-administer key: no built-in app is given it, a Forge agent never holds it, and a Personal key that carries it expires sooner. An archived factory is never paused or resumed, a factory still provisioning is never paused, and repeating a control that already holds changes nothing (`changed: false`, no audit event). Each change writes one audit event with your `reason`, naming your External App or key, or a Personal key's owner.

Send an `Idempotency-Key` with each write: a repeat within 24 hours replays the recorded response only while you may still perform the operation on that factory (and, for a message, the session is still in the factory). Otherwise it answers `409`, and the write never runs twice.

## Spend

Spend is factory token-event attribution; it is not the deployment cost rollup (`GET /api/v3/cost-summary`). Reading a factory's spend needs both `factories:read` and `cost:read`: your credential's scopes must reach both (`factories:read` and `cost:read`), and your role grants must hold both at the factory's home org unit. A factory you may read without `cost:read` there answers `403` with `requiredPermission: "cost:read"`. The read sums at most 10,000 events, newest first, and `meta.partial` says when more existed. Agent workers are listed one by one; every human worker's spend is one `humanWorkers` row.

`getTaskSpend`, `getProjectSpend` and `getWorkerSpend` sum one task's, project's or worker's spend across every factory, with the same window rules and 10,000-event bound. Each needs `factories:read` and `cost:read` in your credential's scopes, then in your role grants: at the home of the task's factory, at the project's home, or, for a worker, at the deployment root. Worker spend names one worker, a person's or an agent's; the single `humanWorkers` row applies only to `getSpend`.

## Blueprints

Factory blueprints are the deployment's catalog of reusable factory templates. They have no home org unit, so reading them needs `factories:read` at the deployment root (every migrated API key's root compatibility grant holds it). A key or External App that holds `factories:read` only below the root, or at a partner organization's root, is refused with `403` and `requiredPermission: "factories:read"`. `listBlueprints` lists ACTIVE blueprints newest first; pass `includeDeprecated=true` for all of them and `factoryTypeId` for one type (with both, DEPRECATED blueprints come first, each status newest first).

## Factory types and the codebase

Factory types and the deployment's indexed codebase also have no home org unit, so `getType`, `listCodebaseFiles` and `searchCodebase` are decided at the deployment root the same way. A factory type never carries the manager's system prompt or a tools profile. `listCodebaseFiles` scans at most 500 index entries and sets `meta.partial` when it stops there; `searchCodebase` is a text match over chunk text, with a `query` of 1 to 500 characters and a `limit` of 1 to 50 (default 20).

## Common workflows

Walk a factory and its team:

```bash theme={null}
curl "$FORGE_BASE/api/v3/factories?limit=50" \
  -H "Authorization: Bearer $FORGE_TOKEN"

# Repeat with the previous page's meta.nextCursor while meta.hasMore is true
curl "$FORGE_BASE/api/v3/factories?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $FORGE_TOKEN"

curl "$FORGE_BASE/api/v3/factories/factory_abc/workers" \
  -H "Authorization: Bearer $FORGE_TOKEN"

curl "$FORGE_BASE/api/v3/factory-tasks?factoryId=factory_abc&status=BLOCKED" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## Related

* [Factories overview](https://docs.gloo.com/forge/run/factories.md) — conceptual background on production units, managers, and budgets
* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token


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