Skip to main content
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 — one page of the factories you may read, newest first
  • GET /api/v3/factories/{factoryId} — getFactory — fetch a single factory by ID
  • GET /api/v3/factories/{factoryId}/workers — listFactoryWorkers — one page of a factory’s active members
  • GET /api/v3/factories/{factoryId}/spend — getFactorySpend — a factory’s token spend over a window of at most 30 days
  • GET /api/v3/factory-tasks/{taskId}/spend — getFactoryTaskSpend — one task’s factory token spend over a window
  • GET /api/v3/projects/{projectId}/spend — getProjectFactorySpend — one project’s factory token spend over a window
  • GET /api/v3/factory-workers/{workerId}/spend — getWorkerFactorySpend — one worker’s factory token spend over a window
  • GET /api/v3/factory-tasks — listFactoryTasks — 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 — fetch a single task with its description
  • GET /api/v3/factories/{factoryId}/assignments — listFactoryAssignments — one page of a factory’s assignments, ACTIVE by default
  • GET /api/v3/factories/{factoryId}/releases — listFactoryReleases — a factory’s release milestones, most recently updated first
  • GET /api/v3/factory-blueprints — listFactoryBlueprints — one page of the deployment’s blueprint catalog
  • GET /api/v3/factory-blueprints/{blueprintId} — getFactoryBlueprint — fetch a single blueprint by ID
  • GET /api/v3/factory-types/{typeId} — getFactoryType — fetch a single factory type by its type ID
  • GET /api/v3/factory-codebase-files — listCodebaseFiles — the indexed codebase’s files and chunk counts
  • GET /api/v3/factory-codebase-search — searchCodebase — text search over the indexed codebase’s chunks
Task writes:
  • POST /api/v3/factories/{factoryId}/tasks — createFactoryTask — create a task on a factory (factories:manage)
  • PATCH /api/v3/factory-tasks/{taskId} — updateFactoryTask — edit a task’s title, description, priority or tags (projects:manage)
  • POST /api/v3/factory-tasks/{taskId}/assign — assignFactoryTask — assign a task to an agent of its factory, or unassign it (projects:manage)
  • POST /api/v3/factory-tasks/{taskId}/transition — transitionFactoryTask — move a task to another status (factories:manage)
Operating a factory:
  • POST /api/v3/factories/{factoryId}/send-message — sendFactoryMessage — 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 — block new work through the factory (switches:use)
  • POST /api/v3/factories/{factoryId}/resume — resumeFactory — restore a paused factory (switches:use)
  • DELETE /api/v3/factories/{factoryId} — archiveFactory — 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: