> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Async AI pipelines — start, poll, retrieve output, and handle human review.

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.

<Tabs>
  <Tab title="MCP">
    ```json theme={null}
    {
      "keyword": "best project management tools",
      "prompt": "Compare top 5 tools for small teams",
      "strategy": "Comparison",
      "start_drafting": true
    }
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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
      }'
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "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

<Tabs>
  <Tab title="MCP">
    Call `workflows_get_status` with `workflow_id`.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl https://api.clickflow.com/v1/api/workflows/wf_xyz789/status \
      -H "Authorization: Bearer cf_ak_your_key_here"
    ```
  </Tab>
</Tabs>

### In Progress

```json theme={null}
{
  "status": "In Progress",
  "progress": 45,
  "currentAction": "Analyzing competition for target keyword"
}
```

### Completed

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<Tabs>
  <Tab title="MCP">
    Call `workflows_resume` with the `workflow_id` and a `decision` object matching the review type:

    ```json theme={null}
    {
      "workflow_id": "wf_xyz789",
      "decision": {
        "approved": true,
        "selected_change_ids": [1, 3, 5]
      }
    }
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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]
        }
      }'
    ```
  </Tab>
</Tabs>

### Decision payloads by review type

**`implementation_spec_review`:**

```json theme={null}
{"approved": true, "selected_change_ids": [1, 3, 5]}
```

**`answer_review`:**

```json theme={null}
{"approved_faqs": [{"question": "What is SEO?", "answer": "SEO stands for..."}]}
```

**`keywords_review`:**

```json theme={null}
{"keywords": ["project management", "task tracking", "team collaboration"]}
```

**`internal_link_review`:**

```json theme={null}
{
  "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`                    |

<Note>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.</Note>

## 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`.                                |