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

FieldTypeDescription
idstringUnique id, prefixed fac_.
objectstringAlways "factory".
namestringDisplay name, shown on the factory’s card.
descriptionstringOne-line description.
project_idstring | nullThe project its runs belong to by default.
statusenumactive, paused or archived. Paused factories don’t start runs from triggers.
default_workflow_idstringThe workflow runs use when none is named.
workflow_idsstring[]Every workflow in the factory.
reposobject[]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).
guardrailsobjectpermission_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_atstringWhen the factory was created.
updated_atstringWhen 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.

Factory
{
  "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

GET 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

status enum Optional

Only factories in this status. Without it, active and paused factories are returned.

One of active paused archived

project_id string Optional

Only factories whose runs belong to this project.

limit integer Optional

1–100.

Default 20

cursor string Optional

next_cursor from 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)
Response
{
  "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

POST 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

name string Required

Display name. Max 80 characters.

description string Optional

One line shown on its card. Defaults to "Runs the <name> team's work through to reviewed PRs."

project_id string Optional

The project its runs belong to by default.

template enum Optional

Which starting workflow to create: Ship features, Fix bugs from Sentry, Dependency upgrades, Docs & changelog, or Blank (one implement step and a PR).

Default blank

One of ship-features sentry-bugs dependency-upgrades docs-changelog blank

repos string[] 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 paused
factory = client.factories.create(
    name="Bug fixes",
    project_id="prj_payments",
    template="sentry-bugs",
    repos=["acme/platform"],
)
print(factory.id, factory.status)  # fac_bugfix8d2 paused
Response
{
  "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_request with code repo_not_found and param: "repos" when a repository isn’t reachable through a connected repo host.
  • 403 permission_denied with code plan_limit when your plan’s factory limit is reached.

Retrieve a factory

GET https://api.duun.ai/v1/factories/{factory_id}

Returns one factory, including archived ones. Needs factories:read.

Path parameters

factory_id string 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

PATCH 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_id string Required

The factory's id.

Body parameters

name string Optional

Display name.

description string Optional

One-line description.

project_id string | null Optional

Default project for its runs. null clears it.

default_workflow_id string Optional

Must be one of workflow_ids.

repos object[] 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.

guardrails object 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}},
)
Response
{
  "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

POST 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_id string 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")
Response
{ "id": "fac_platform", "object": "factory", "status": "paused", "updated_at": "2026-11-15T18:00:00Z" }

Resume a factory

POST 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_id string 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")
Response
{ "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

POST 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_id string 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")
Response
{ "id": "fac_growth", "object": "factory", "status": "archived", "updated_at": "2026-11-15T10:20:00Z" }

Errors worth handling:

  • 409 conflict with code default_factory: the workspace’s default factory can’t be archived.
  • 409 conflict with code runs_active: cancel or finish its running runs first.

    Type to search the docs, help center and blog.