Factories
Create, read, update, pause, resume and archive factories: a team's workflows, repositories and guardrails, through the Duun API.
On this page
A factory is one team’s pipeline from issue to merged pull request: its workflows, the repositories it opens pull requests in, and the guardrails its agents work under. Runs always belong to a factory. See Factories for the concepts.
Factories created through the API start paused, exactly like the ones you create in the app, so nothing happens until you resume them or start a first run.
The factory object
| Field | Type | Description |
|---|---|---|
id | string | Unique id, prefixed fac_. |
object | string | Always "factory". |
name | string | Display name, shown on the factory’s card. |
description | string | One-line description. |
project_id | string | null | The project its runs belong to by default. |
status | enum | active, paused or archived. Paused factories don’t start runs from triggers. |
default_workflow_id | string | The workflow runs use when none is named. |
workflow_ids | string[] | Every workflow in the factory. |
repos | object[] | Repositories it works in. Each has name (owner/repo) and sandbox: size (standard or large), platform (linux, macos or windows) and status (none, waiting, building, ready, failed or cancelled). |
guardrails | object | permission_mode (ask_everything, ask_writes or autonomous_sandbox), plan_approval (whether plans always wait for a person) and budget with day_usd and month_usd (each null when unset). |
created_at | string | When the factory was created. |
updated_at | string | When it last changed. |
permission_mode maps to the modes in the app: Ask for everything, Ask for writes and Autonomous in sandbox. Factory guardrails can only tighten the workspace’s action approvals, never loosen them.
{
"id": "fac_platform",
"object": "factory",
"name": "Platform",
"description": "Runs the Platform team's work through to reviewed PRs.",
"project_id": "prj_payments",
"status": "active",
"default_workflow_id": "wf_base9c1d",
"workflow_ids": ["wf_base9c1d", "wf_small4e7a", "wf_hotfix21b"],
"repos": [
{
"name": "acme/platform",
"sandbox": { "size": "large", "platform": "linux", "status": "ready" }
},
{
"name": "acme/ledger-sdk",
"sandbox": { "size": "standard", "platform": "linux", "status": "ready" }
}
],
"guardrails": {
"permission_mode": "ask_writes",
"plan_approval": true,
"budget": { "day_usd": 120, "month_usd": 2000 }
},
"created_at": "2026-09-02T14:11:40Z",
"updated_at": "2026-11-14T16:25:03Z"
}Endpoints
List factories
https://api.duun.ai/v1/factories Returns the factories the key can see, most recently updated first. Archived factories are left out unless you ask for them. Needs factories:read.
Query parameters
-
statusenum Optional -
Only factories in this status. Without it, active and paused factories are returned.
-
project_idstring Optional -
Only factories whose runs belong to this project.
-
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom the previous page.
curl https://api.duun.ai/v1/factories \
-H "Authorization: Bearer $DUUN_API_KEY"import Duun from "@duun/sdk";
const duun = new Duun({ apiKey: process.env.DUUN_API_KEY });
for await (const factory of duun.factories.list()) {
console.log(factory.id, factory.name, factory.status);
}from duun import Duun
client = Duun()
for factory in client.factories.list():
print(factory.id, factory.name, factory.status){
"object": "list",
"data": [
{
"id": "fac_platform",
"object": "factory",
"name": "Platform",
"status": "active",
"default_workflow_id": "wf_base9c1d",
"updated_at": "2026-11-14T16:25:03Z"
},
{
"id": "fac_growth",
"object": "factory",
"name": "Growth",
"status": "paused",
"default_workflow_id": "wf_growth3a0e",
"updated_at": "2026-11-10T08:02:19Z"
}
],
"has_more": false,
"next_cursor": null
}List items are full factory objects; the example is trimmed.
Create a factory
https://api.duun.ai/v1/factories Creates a factory from a template, with its first workflow at version 1. The factory starts paused. Needs factories:write.
Body parameters
-
namestring Required -
Display name. Max 80 characters.
-
descriptionstring Optional -
One line shown on its card. Defaults to "Runs the <name> team's work through to reviewed PRs."
-
project_idstring Optional -
The project its runs belong to by default.
-
templateenum Optional -
Which starting workflow to create: Ship features, Fix bugs from Sentry, Dependency upgrades, Docs & changelog, or Blank (one implement step and a PR).
-
reposstring[] Optional -
Repositories to add, as
owner/repo. They must be reachable through a connected GitHub, Bitbucket or Azure DevOps account.
curl https://api.duun.ai/v1/factories \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Bug fixes",
"project_id": "prj_payments",
"template": "sentry-bugs",
"repos": ["acme/platform"]
}'const factory = await duun.factories.create({
name: "Bug fixes",
project_id: "prj_payments",
template: "sentry-bugs",
repos: ["acme/platform"],
});
console.log(factory.id, factory.status); // fac_bugfix8d2 pausedfactory = client.factories.create(
name="Bug fixes",
project_id="prj_payments",
template="sentry-bugs",
repos=["acme/platform"],
)
print(factory.id, factory.status) # fac_bugfix8d2 paused{
"id": "fac_bugfix8d2",
"object": "factory",
"name": "Bug fixes",
"description": "Runs the Bug fixes team's work through to reviewed PRs.",
"project_id": "prj_payments",
"status": "paused",
"default_workflow_id": "wf_bugfix0c4",
"workflow_ids": ["wf_bugfix0c4"],
"repos": [
{
"name": "acme/platform",
"sandbox": { "size": "standard", "platform": "linux", "status": "waiting" }
}
],
"guardrails": {
"permission_mode": "ask_writes",
"plan_approval": true,
"budget": { "day_usd": null, "month_usd": null }
},
"created_at": "2026-11-15T10:12:00Z",
"updated_at": "2026-11-15T10:12:00Z"
}Errors worth handling:
400 invalid_requestwith coderepo_not_foundandparam: "repos"when a repository isn’t reachable through a connected repo host.403 permission_deniedwith codeplan_limitwhen your plan’s factory limit is reached.
Retrieve a factory
https://api.duun.ai/v1/factories/{factory_id} Returns one factory, including archived ones. Needs factories:read.
Path parameters
-
factory_idstring Required -
The factory's id, e.g.
fac_platform.
curl https://api.duun.ai/v1/factories/fac_platform \
-H "Authorization: Bearer $DUUN_API_KEY"const factory = await duun.factories.retrieve("fac_platform");factory = client.factories.retrieve("fac_platform")The response is a factory object.
Update a factory
https://api.duun.ai/v1/factories/{factory_id} Changes a factory’s details, default workflow, repositories or guardrails. Send only the fields you want to change. Nested objects are merged, so sending guardrails.budget.day_usd leaves month_usd alone. Needs factories:write.
Path parameters
-
factory_idstring Required -
The factory's id.
Body parameters
-
namestring Optional -
Display name.
-
descriptionstring Optional -
One-line description.
-
project_idstring | null Optional -
Default project for its runs.
nullclears it. -
default_workflow_idstring Optional -
Must be one of
workflow_ids. -
reposobject[] Optional -
The full list of repositories:
{ name, sandbox: { size, platform } }. Repos you leave out are removed from the factory; their sandboxes stay in the workspace. -
guardrailsobject Optional -
permission_mode,plan_approval,budget.day_usd,budget.month_usd. A guardrail can't be looser than the workspace's action approvals.
curl -X PATCH https://api.duun.ai/v1/factories/fac_platform \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"default_workflow_id": "wf_small4e7a",
"guardrails": { "budget": { "day_usd": 150 } }
}'const factory = await duun.factories.update("fac_platform", {
default_workflow_id: "wf_small4e7a",
guardrails: { budget: { day_usd: 150 } },
});factory = client.factories.update(
"fac_platform",
default_workflow_id="wf_small4e7a",
guardrails={"budget": {"day_usd": 150}},
){
"id": "fac_platform",
"object": "factory",
"name": "Platform",
"status": "active",
"default_workflow_id": "wf_small4e7a",
"guardrails": {
"permission_mode": "ask_writes",
"plan_approval": true,
"budget": { "day_usd": 150, "month_usd": 2000 }
},
"updated_at": "2026-11-15T10:15:42Z"
}The response is the full factory object; the example is trimmed. Setting permission_mode looser than the workspace allows returns 422 validation_error with param: "guardrails.permission_mode".
Pause a factory
https://api.duun.ai/v1/factories/{factory_id}/pause Stops every workflow in the factory from starting runs on its own. Runs in progress continue; manual and API runs are refused until you resume. Needs factories:write.
Path parameters
-
factory_idstring Required -
The factory's id.
curl -X POST https://api.duun.ai/v1/factories/fac_platform/pause \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"await duun.factories.pause("fac_platform");client.factories.pause("fac_platform"){ "id": "fac_platform", "object": "factory", "status": "paused", "updated_at": "2026-11-15T18:00:00Z" }Resume a factory
https://api.duun.ai/v1/factories/{factory_id}/resume Lets the factory’s workflows start runs again from their triggers. Needs factories:write.
Path parameters
-
factory_idstring Required -
The factory's id.
curl -X POST https://api.duun.ai/v1/factories/fac_platform/resume \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"await duun.factories.resume("fac_platform");client.factories.resume("fac_platform"){ "id": "fac_platform", "object": "factory", "status": "active", "updated_at": "2026-11-16T08:00:00Z" }Resuming an archived factory returns 409 conflict with code factory_archived.
Archive a factory
https://api.duun.ai/v1/factories/{factory_id}/archive Removes the factory from your factories. It can’t be restored yet. Its workflows, repos and sandboxes stay in the workspace, and its past runs stay readable. Needs factories:write.
Path parameters
-
factory_idstring Required -
The factory's id.
curl -X POST https://api.duun.ai/v1/factories/fac_growth/archive \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"await duun.factories.archive("fac_growth");client.factories.archive("fac_growth"){ "id": "fac_growth", "object": "factory", "status": "archived", "updated_at": "2026-11-15T10:20:00Z" }Errors worth handling:
409 conflictwith codedefault_factory: the workspace’s default factory can’t be archived.409 conflictwith coderuns_active: cancel or finish its running runs first.
Related
- Factories and Build your first factory
- Workflows API for the steps inside a factory
- Use a template from Explore in the help center