Workflows

Workflows are long-running AI pipelines (3-20 minutes) that research, write, and optimize content. They run asynchronously — you start one, then poll for completion.

Lifecycle

Start workflow → Poll status → Retrieve output
                    ↓
              (may pause for human review)
                    ↓
              Resume with decision → Poll again → Output

Starting a workflow

Workflows are started via platform_create_roadmap_item with start_drafting: true. This creates a roadmap item and immediately kicks off the drafting workflow.

{
  "keyword": "best project management tools",
  "prompt": "Compare top 5 tools for small teams",
  "strategy": "Comparison",
  "start_drafting": true
}

curl -X POST https://api.clickflow.com/v1/api/roadmap-items \
  -H "Authorization: Bearer cf_ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "best project management tools",
    "prompt": "Compare top 5 tools for small teams",
    "strategy": "Comparison",
    "start_drafting": true
  }'

Response:

{
  "roadmap_item_id": "ri_abc123",
  "workflow_id": "wf_xyz789",
  "status": "In Progress",
  "message": "Roadmap item created and drafting started. Poll workflows_get_status for progress."
}

Polling for status

Call workflows_get_status with workflow_id.

curl https://api.clickflow.com/v1/api/workflows/wf_xyz789/status \
  -H "Authorization: Bearer cf_ak_your_key_here"

In Progress

{
  "status": "In Progress",
  "progress": 45,
  "currentAction": "Analyzing competition for target keyword"
}

Completed

{
  "status": "Completed",
  "progress": 100,
  "output": {
    "html": "<h1>Best Project Management Tools</h1>...",
    "title": "Best Project Management Tools for Small Teams (2026)",
    "meta_description": "Compare the top 5 project management tools...",
    "thumbnail_url": "https://storage.googleapis.com/..."
  }
}

Failed

{
  "status": "Failed",
  "error": "Description of what went wrong"
}

Human review

Some workflows pause to let a human review intermediate results before continuing.

Detecting a paused workflow

When status is "Human Review", the response includes a review object:

{
  "status": "Human Review",
  "progress": 85,
  "currentAction": "Waiting for review",
  "review": {
    "type": "implementation_spec_review",
    "task_id": "task_abc",
    "data": {
      "proposed_changes": [...]
    }
  }
}

Review types

Type	Workflow	What you’re reviewing
`implementation_spec_review`	Content optimization	Proposed changes to the page
`answer_review`	FAQ generation	Generated FAQ question-answer pairs
`keywords_review`	Internal linking	Suggested keywords to link
`internal_link_review`	Internal linking	Pages and anchor text for links

Resuming a workflow

Call workflows_resume with the workflow_id and a decision object matching the review type:

{
  "workflow_id": "wf_xyz789",
  "decision": {
    "approved": true,
    "selected_change_ids": [1, 3, 5]
  }
}

curl -X POST https://api.clickflow.com/v1/api/workflows/wf_xyz789/resume \
  -H "Authorization: Bearer cf_ak_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": {
      "approved": true,
      "selected_change_ids": [1, 3, 5]
    }
  }'

Decision payloads by review type

implementation_spec_review:

{"approved": true, "selected_change_ids": [1, 3, 5]}

answer_review:

{"approved_faqs": [{"question": "What is SEO?", "answer": "SEO stands for..."}]}

keywords_review:

{"keywords": ["project management", "task tracking", "team collaboration"]}

internal_link_review:

{
  "selected_pages": [
    {
      "url": "https://example.com/blog/task-management",
      "anchor_text": "task management tools",
      "context": "paragraph about productivity",
      "implementation_method": "auto"
    }
  ]
}

Workflow types

Workflow	How to start	Duration	Output
Create Post Draft	`create_roadmap_item` with `start_drafting: true`	5-15 min	`html`, `title`, `meta_description`, `thumbnail_url`
Optimize Content	Dashboard only (content decay suggestion)	10-20 min	`html`, `changes_applied`, `metadata`
Generate FAQs	Dashboard only (FAQ suggestion)	3-8 min	`faqs`, `schema_markup` (JSON-LD)
Internal Linking	Dashboard only (linking suggestion)	5-15 min	`links_created`, `pages_modified`

Only Create Post Draft can be started directly via MCP or API. The other 3 workflows are triggered when you approve optimization suggestions in the ClickFlow dashboard. Once running, all workflows can be polled and resumed via MCP/API.

Delivery modes

Mode	Behavior
`draft` (default)	Output saved to workflow result + roadmap item draft. Retrieve via `workflows_get_status` or `platform_get_roadmap_item`.
`cms`	Automatically publishes to your connected CMS on completion. Requires `cms_connection_id`.

Getting Started

Core Concepts

Lifecycle

Starting a workflow

Polling for status

In Progress

Completed

Failed

Human review

Detecting a paused workflow

Review types

Resuming a workflow

Decision payloads by review type

Workflow types

Delivery modes

​Lifecycle

​Starting a workflow

​Polling for status

​In Progress

​Completed

​Failed

​Human review

​Detecting a paused workflow

​Review types

​Resuming a workflow

​Decision payloads by review type

​Workflow types

​Delivery modes

Lifecycle

Starting a workflow

Polling for status

In Progress

Completed

Failed

Human review

Detecting a paused workflow

Review types

Resuming a workflow

Decision payloads by review type

Workflow types

Delivery modes