Custom workflows

An article type is a workflow: a named record that owns an ordered list of steps, each step an AI call with its own prompts, output format, and context flags. The output of every step is available to the ones after it.

A workflow has a slug — that is the article_type you pass when creating an article — plus a name, an optional description, and a revision that increments on every change to the workflow or any of its steps. Steps hang off the workflow and are numbered within it.

Serpon ships built-in workflows for the standard formats. A custom workflow lets you define your own — your own article type name, your own prompts, your own number of steps — scoped to a single project.

Global vs custom

Custom workflows cannot reuse a built-in type name — blog_post and the other reserved values are rejected with "Custom workflows cannot use reserved global article type names."

Why build one

• Formats that don't fit a standard type — datasheets, release notes, email sequences, changelog entries.
• Compliance and brand rules baked into the prompts rather than re-stated in every request.
• Extra quality gates — an SEO audit step, a fact-check step, a readability pass.
• Single-step pipelines for a strong model, which are the fastest and cheapest route, and the only ones eligible for batch mode.
• A/B testing — duplicate a workflow, change one prompt, compare the output.

Building one

Anatomy of a step

{
  "article_type": "product_datasheet",
  "step_number": 1,
  "step_name": "Research product details",
  "step_description": "Compile specifications and use cases",
  "system": "You are a technical writer specializing in product documentation.",
  "user": "Research and compile detailed specifications for: {title}. Focus on features, specifications, and target use cases.",
  "output_format": "json",
  "timeout_seconds": 120,
  "include_additional_context": true
}

Template variables

Prompts are templates. These are substituted before the call:

Chaining through {step_N_output} is what turns a list of prompts into a pipeline:

{
  "step_number": 3,
  "step_name": "Draft",
  "system": "You are an experienced technical copywriter.",
  "user": "Using this research:

{step_1_output}

and this outline:

{step_2_output}

write a {target_word_count}-word datasheet for {title} in a {tone} tone.",
  "output_format": "markdown",
  "include_requirements": true
}

Design guidance

Gather structured data early, write prose late. Steps 1–2 do best with output_format: "json" and a json_schema, so later steps consume reliable fields rather than parsing prose. Writing steps use markdown.

Set the include flags deliberately. Each one adds tokens to the call. Research context belongs on the step that needs facts, not on every step. include_requirements belongs on the steps that actually write, so word count, tone, and point of view land where they matter.

Add a review step. A JSON critique step followed by a Markdown revision step measurably improves output, at the cost of one extra call.

The last step produces the article. Whatever it returns is what gets stored as the article's content, so it should emit the finished body — not a critique of it.

Managing an existing workflow

Because step_number is unique within a workflow, swapping two steps by updating them one at a time collides. Use the reorder endpoint, which applies the whole new order in a single transaction.

A workflow lives exactly as long as it has steps. Deleting the last step deletes the workflow, and moving the last step to another article type does the same — in both cases the article type stops being accepted.