ForjioHuudisIdentityPlugipayPaymentsCatentioAgentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
Catentio Docs
⌘K

Workflows

A workflow is the reusable phase graph a project expands from: phases (tasks), each phase's steps (agent / action / gate subtasks), their dependency edges, per-step tool/skill bindings, and per-step output schemas.

Workflows are database-backed and versioned. Versions are immutable — projects pin (workflow_slug, workflow_version) at expansion and keep that pin forever — so "editing" a spec always mints a new version. Ten built-in workflows ship seeded (content, micro-saas, blog-post, sticker-pack, landing-page, content-slideshow, childrens-book, motion-graphics, worksheet, digital-planner), and you can register your own through the same CRUD surface.

For the concept-level walkthrough (portal authoring sheet included) see Workflows.

The workflow objects

List entry (one per slug — the latest active version):

{
  "slug": "content",
  "version": 2,
  "name": "Content pipeline",
  "description": "Idea → research → storyboard → scenes → publish.",
  "collection": "Content",
  "tags": ["video", "long-form"],
  "phase_count": 8,
  "is_builtin": true,
  "status": "active",
  "updated_at": "2026-07-10T08:12:44Z"
}

Detail adds the full spec (the validated phase graph) plus created_at.

Endpoints

List workflows

GET /v1/workflows

One entry per slug, latest active version. Query params: collection, tag, include_archived (default false). This is what the project-create form's picker draws from.

Retrieve a workflow

GET /v1/workflows/{slug}?version=N

Detail including the full phase-graph spec. Latest active version by default; ?version=N fetches a specific — possibly archived — version, so existing project pins stay resolvable. 404 for an unknown slug.

List versions

GET /v1/workflows/{slug}/versions

Every version for a slug (any status), newest first, with version, status, is_builtin, timestamps, and description.

Create a workflow

POST /v1/workflows

Body:

{
  "spec": { "slug": "podcast", "version": 1, "title": "Podcast pipeline", "phases": [ … ] },
  "collection": "Content",
  "tags": ["audio"]
}

The spec is fully validated before any write — structural validators plus step bindings (every agent step needs at least one resolvable tool or skill). owner_id is forced from your verified session; the body cannot set it. Returns 201 with the detail shape.

409 when (slug, version) already exists — versions are immutable; use PATCH with a spec to mint the next one. 400 on an invalid spec or unresolvable bindings.

Update a workflow

PATCH /v1/workflows/{slug}

Two behaviours depending on the body:

  • Metadata only (collection, tags, description) — updates the latest active version in place. 400 when the body has nothing to update.
  • Body includes spec — mints a new immutable version (max existing + 1). Older versions, and every project pinned to them, are untouched. The new spec runs the same validation as create.

Archive a workflow

DELETE /v1/workflows/{slug}

Archives all versions of the slug (soft delete — status: "archived"). Archived workflows disappear from the default list and are rejected for new projects (400 at POST /v1/projects), but stay resolvable via ?version=N so existing pins keep working. 404 for an unknown slug.

SDK coverage

The SDKs currently expose templates.list only (catentio.templates.list() in Node/Python, client.Templates.List in Go) — still named for the old resource, and still working: it calls the deprecated /v1/templates alias, which returns exactly what /v1/workflows does. Detail, versions, create, update, and archive are available via the REST API shown above.

Errors

Status When
400 Invalid spec (structural validation), unresolvable step bindings, metadata PATCH with nothing to update.
404 Unknown slug, unknown version, no active version for a metadata PATCH.
409 POST for a (slug, version) that already exists.

Next