Resource shape
Every factory read returns only factories your key or External App may read: it must holdfactories: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, andupdatedAt. Optional fields are omitted when unset.FactoryListItem— aFactoryplus the bounded countsteamMemberCount,activeTaskCount, andactiveRunCount(active assignments).FactoryWorker—id,_creationTime,factoryId,personId,workerId,workerType,factoryRole,permissions,agentDefinitionId,status,joinedAt,leftAt, andworkerName.FactoryDetail— aFactoryplusteam,teamPartial, andrecentTasks.FactorySpend—factoryId,taskId,window,coveredFrom,totals,bySource,byModel,byAgentWorker,humanWorkers, andbyTask. Every total carriestotalTokens,inputTokens,outputTokens,thinkingTokens,costCents, andeventCount. 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(nullwhen unset),tags([]when unset),assignee({ type: "agent", workerId },{ type: "person" }, ornull;workerIdisnullunless the agent is an active member of the factory’s team),assigneeName(nullwhen Forge does not know the name),createdBy,github(pullRequest,issueandcommitSha, eachnullwhen unset;nullwhen the task has no GitHub link),createdAt, andupdatedAt.FactoryTaskDetail— aFactoryTaskplusdescription(nullwhen unset).FactoryBlueprint—id,name,description,factoryTypeId,version,status,defaultTeam,additionalChannels,budgetDefaults,createdAt, andupdatedAt. Factory configuration, manager prompt text, the creator, a channel’s external link, and repository settings are not returned.FactoryAssignment—id,factoryId,assignmentType(project,workflow, ortask),projectId,workflowId,taskId(exactly one is set),status(ACTIVE,COMPLETED, orCANCELLED),assignedAt, andcompletedAt.FactoryRelease—id,name,quarter,targetDate,releaseVersion,status, andupdatedAt.FactoryEntitySpend—entity(kindtask,project, orworker, andid),window,coveredFrom,totals,bySource, andbyModel, summed across every factory.FactoryType—typeId,name,description,version,category,status, the manager template (managerRoleId,managerSkillKeys,managerTrustLevel,managerSandbox),workerRoleTemplates,defaultChannels,requiredIntegrations,createdAt, andupdatedAt. The manager’s system prompt and every tools profile are not returned.CodebaseFile—pathandchunks.CodebaseSearchHit—path,chunk,chunkIndex, andlanguage.
Operations
Reads:GET /api/v3/factories— listFactories — one page of the factories you may read, newest firstGET /api/v3/factories/{factoryId}— getFactory — fetch a single factory by IDGET /api/v3/factories/{factoryId}/workers— listFactoryWorkers — one page of a factory’s active membersGET /api/v3/factories/{factoryId}/spend— getFactorySpend — a factory’s token spend over a window of at most 30 daysGET /api/v3/factory-tasks/{taskId}/spend— getFactoryTaskSpend — one task’s factory token spend over a windowGET /api/v3/projects/{projectId}/spend— getProjectFactorySpend — one project’s factory token spend over a windowGET /api/v3/factory-workers/{workerId}/spend— getWorkerFactorySpend — one worker’s factory token spend over a windowGET /api/v3/factory-tasks— listFactoryTasks — one page of a factory’s tasks, or of one task kind across factories, optionally onestatus, in index orderGET /api/v3/factory-tasks/{taskId}— getFactoryTask — fetch a single task with its descriptionGET /api/v3/factories/{factoryId}/assignments— listFactoryAssignments — one page of a factory’s assignments,ACTIVEby defaultGET /api/v3/factories/{factoryId}/releases— listFactoryReleases — a factory’s release milestones, most recently updated firstGET /api/v3/factory-blueprints— listFactoryBlueprints — one page of the deployment’s blueprint catalogGET /api/v3/factory-blueprints/{blueprintId}— getFactoryBlueprint — fetch a single blueprint by IDGET /api/v3/factory-types/{typeId}— getFactoryType — fetch a single factory type by its type IDGET /api/v3/factory-codebase-files— listCodebaseFiles — the indexed codebase’s files and chunk countsGET /api/v3/factory-codebase-search— searchCodebase — text search over the indexed codebase’s chunks
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)
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)
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 needfactories: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 needsfactories: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 needsfactories: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, sogetType, 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:Related
- Factories overview — conceptual background on production units, managers, and budgets
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token

