# Authentication
Source: https://docs.clickflow.com/authentication
API keys, OAuth, and headers for MCP and REST API access.
ClickFlow uses different authentication for MCP and the REST API:
* **MCP** — OAuth via Clerk. No API key needed — your MCP client handles login automatically.
* **REST API** — API keys. Required for all REST requests.
## OAuth (MCP)
MCP authentication works via OAuth — the same login you use at app.clickflow\.com. When you connect an MCP client like Claude, Cursor, or Windsurf, it will open a browser login on first use. You sign in with your regular ClickFlow account. No API key or manual setup required.
**Flow:**
1. MCP client discovers auth requirements via `/.well-known/oauth-protected-resource`
2. Client redirects to Clerk for login
3. User authenticates and grants access
4. MCP client receives a token
5. All subsequent tool calls use this token automatically
OAuth users have full access to all tools — no scope restrictions.
### OAuth metadata endpoint
```
GET https://api.clickflow.com/v1/.well-known/oauth-protected-resource
```
```json theme={null}
{
"resource": "https://api.clickflow.com/v1/mcp",
"authorization_servers": ["https://your-app.clerk.accounts.dev"]
}
```
## API Keys (REST API)
API keys are required for the REST API. They can also be used with MCP as an alternative to OAuth (e.g., for non-interactive/automated setups).
**Format:** Keys start with `cf_ak_` followed by a random string.
**Create a key:** Dashboard > Settings > API Keys > Create API Key.
### Headers
Every request requires an `Authorization` header:
```
Authorization: Bearer cf_ak_your_key_here
```
Optionally, override the default organization:
```
X-Organization-Id: org_abc123
```
### Access
API keys have full access to all tools — no scope restrictions.
### Key properties
| Property | Description |
| ---------------- | --------------------------------- |
| `status` | `active`, `revoked`, or `expired` |
| `expiresAt` | Optional expiration timestamp |
| `lastUsedAt` | Updated on each use |
| `organizationId` | Default org for this key |
## Error responses
### 401 Unauthorized
Returned when the token is missing, invalid, or expired.
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.clickflow.com/v1/.well-known/oauth-protected-resource"
{"error": "unauthorized"}
```
### 403 Forbidden
Returned when access is denied (e.g., wrong organization).
```
HTTP/1.1 403 Forbidden
{"detail": "Access denied"}
```
# AI Agents
Source: https://docs.clickflow.com/capabilities/ai-agents
Synchronous AI tools for titles, meta descriptions, FAQs, images, and competitive analysis.
AI agent tools run synchronously and return results directly. They are slower than data queries (15-60 seconds) because they invoke LLM-powered agents.
## agents\_optimize\_blog\_title
Optimize a blog post title for SEO and click-through rate.
### Parameters
| Name | Type | Required | Default | Description |
| ------------------ | ------ | -------- | ------- | ------------------------------------- |
| `target_keyword` | string | Yes | — | The keyword to optimize for |
| `current_title` | string | Yes | — | The existing title |
| `content` | string | No | `""` | Page content for better context |
| `business_context` | string | No | `""` | Additional business context |
| `user_prompt` | string | No | `""` | Custom instructions for the optimizer |
### Response
```json theme={null}
{
"success": true,
"error": null,
"output": {
"original_title": "CRM Tools Review",
"optimized_title": "Best CRM for Startups: 7 Tools Compared (2026)",
"target_keyword": "best CRM for startups",
"reasoning": "Front-loaded the target keyword for SEO strength...",
"metrics": {
"ux_alignment": "High",
"seo_strength": "High",
"keyword_integration": "Natural",
"character_count": 52,
"estimated_improvement": "80%"
},
"alternative_versions": [
"Top CRM Tools for Startups — Honest Comparison",
"Which CRM Is Best for Your Startup? We Tested 7"
],
"content_alignment": {
"matches_numerical_claim": true,
"identified_sections": 7,
"suggestion": "Title claim matches content structure"
}
}
}
```
### Usage
```json theme={null}
{
"target_keyword": "best CRM for startups",
"current_title": "CRM Tools Review"
}
```
```bash theme={null}
curl -X POST https://api.clickflow.com/v1/api/optimize-blog-title \
-H "Authorization: Bearer cf_ak_your_key_here" \
-H "Content-Type: application/json" \
-d '{"target_keyword": "best CRM for startups", "current_title": "CRM Tools Review"}'
```
Takes 20-30 seconds.
***
## agents\_optimize\_meta\_description
Optimize a meta description for SEO and click-through rate. Returns a 150-160 character description.
### Parameters
| Name | Type | Required | Default | Description |
| --------------------- | ------ | -------- | ------- | ----------------------------- |
| `target_keyword` | string | Yes | — | The keyword to optimize for |
| `current_description` | string | Yes | — | The existing meta description |
| `content` | string | No | `""` | Page content for context |
| `business_context` | string | No | `""` | Additional business context |
### Response
```json theme={null}
{
"success": true,
"error": null,
"output": {
"original_description": "A review of CRM tools for startups.",
"optimized_description": "Compare the 7 best CRM tools for startups in 2026. We tested pricing, features, and ease of use to help you pick the right one.",
"target_keyword": "best CRM for startups",
"reasoning": "Included target keyword naturally, added specificity with numbers...",
"metrics": {
"ux_alignment": "High",
"seo_strength": "High",
"keyword_integration": "Natural",
"character_count": 128,
"estimated_improvement": "75%"
},
"alternative_versions": [
"Looking for the best CRM for your startup? We compared 7 top tools on pricing, features, and ease of use.",
"Startup CRM comparison: 7 tools tested side-by-side for pricing, features, and usability in 2026."
]
}
}
```
Takes 15-25 seconds.
***
## agents\_generate\_faqs
Generate FAQ question-answer pairs from content. Returns 7 structured pairs optimized for SEO.
### Parameters
| Name | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ---------------------- |
| `content` | string | Yes | — | The full text content |
| `title` | string | No | `""` | Page title for context |
### Response
```json theme={null}
{
"success": true,
"error": null,
"output": "[{\"question\": \"What is the best CRM for startups?\", \"answer\": \"The best CRM for startups depends on your team size and budget...\"}]",
"faqs": [
{
"question": "What is the best CRM for startups?",
"answer": "The best CRM for startups depends on your team size and budget..."
}
]
}
```
Takes 20-30 seconds.
***
## agents\_research\_company
Research a company from its website URL. Returns a multi-paragraph text summary covering who they are, their products, target customers, and digital marketing approach.
### Parameters
| Name | Type | Required | Description |
| ----- | ------ | -------- | ------------------------- |
| `url` | string | Yes | The company's website URL |
### Response
```json theme={null}
{
"success": true,
"error": null,
"output": "Acme Corp is a B2B SaaS company specializing in project management tools for mid-market teams.\n\nTheir core products include TaskFlow (project management) and TeamSync (collaboration suite), serving mid-market B2B companies with 50-500 employees.\n\nTheir primary audience is operations managers and team leads at growing companies who need to streamline workflows.\n\nAcme employs a content-led growth strategy with a strong SEO presence, publishing in-depth guides and comparison content targeting commercial-intent keywords.",
"result": "Acme Corp is a B2B SaaS company specializing in project management tools..."
}
```
Takes 20-40 seconds.
***
## agents\_generate\_image
Generate an image from a text prompt using AI.
### Parameters
| Name | Type | Required | Default | Description |
| --------- | ------ | -------- | ------------- | ----------------------------------------------------- |
| `prompt` | string | Yes | — | Text description of the image |
| `style` | string | No | `""` | `stock_photo`, `watercolor`, `illustration`, `sketch` |
| `size` | string | No | `"1024x1024"` | Image dimensions |
| `quality` | string | No | `"standard"` | Image quality level |
### Response
```json theme={null}
{
"success": true,
"error": null,
"output": {
"url": "https://storage.googleapis.com/clickflow-images/generated/abc123.png"
}
}
```
Takes 20-30 seconds.
***
## agents\_analyze\_competitors
Analyze top-ranking pages for a keyword. Returns competitive landscape including content gaps, ranking factors, and opportunities.
### Parameters
| Name | Type | Required | Default | Description |
| ---------------- | ------ | -------- | --------- | -------------------------- |
| `keyword` | string | Yes | — | The keyword to analyze |
| `analysis_depth` | string | No | `"basic"` | `basic` or `comprehensive` |
### Response
```json theme={null}
{
"success": true,
"error": null,
"output": {
"target_keywords": ["best CRM for startups"],
"competitor_urls": ["https://competitor1.com/crm-guide", "https://competitor2.com/crm-review"],
"serp_analysis": [
{
"keyword": "best CRM for startups",
"results": [
{
"position": 1,
"title": "Best CRM for Startups of 2026",
"url": "https://competitor1.com/crm-guide",
"domain": "competitor1.com",
"description": "Compare the top CRM tools designed for startup teams...",
"serp_features": []
}
]
}
],
"content_gaps": ["Missing pricing comparison table", "No user testimonials section"],
"competitive_advantages": ["Deeper technical analysis possible", "More recent data available"],
"content_recommendations": ["Add interactive comparison tool", "Include ROI calculator"],
"positioning_opportunities": ["Target underserved mid-market segment"],
"analysis_metadata": {
"keywords_analyzed": 1,
"competitors_found": 8,
"analysis_depth": "basic"
}
}
}
```
Takes 30-60 seconds. `comprehensive` depth takes longer.
***
## agents\_analyze\_search\_intent
Analyze the search intent behind a keyword. Returns user questions from Google PAA and social sources, grouped by source.
### Parameters
| Name | Type | Required | Description |
| --------- | ------ | -------- | ---------------------- |
| `keyword` | string | Yes | The keyword to analyze |
### Response
```json theme={null}
{
"success": true,
"error": null,
"output": {
"questions": [
{
"question": "What is the best CRM for small businesses?",
"source": "paa",
"answer": "The best CRM depends on your business size and needs...",
"url": "https://example.com/crm-guide"
},
{
"question": "How much does a CRM cost?",
"source": "social",
"answer": "CRM pricing ranges from free to $300/user/month...",
"url": "https://reddit.com/r/smallbusiness/..."
}
],
"questions_by_source": {
"paa": ["What is the best CRM for small businesses?"],
"social": ["How much does a CRM cost?"]
},
"total_count": 2
}
}
```
Takes 20-40 seconds.
***
## Error handling
All agent tools return a consistent shape. On failure:
```json theme={null}
{
"success": false,
"error": "Description of what went wrong",
"output": null
}
```
Agents never return fallback data — they fail explicitly with a clear error message.
# Analytics
Source: https://docs.clickflow.com/capabilities/analytics
SEO performance dashboards, AI visibility tracking, and answer engine optimization data.
Analytics tools pull data from Google Search Console, Google Analytics, and ClickFlow's AI visibility monitoring. Dashboard tools query Google APIs and may take 10-30 seconds.
## platform\_get\_results\_overview
Get SEO performance data from Google Search Console — clicks, impressions, CTR, position, and page-level breakdown with comparison to the previous period.
### Parameters
| Name | Type | Required | Default | Description |
| ---------------- | ------ | -------- | ------------ | -------------------------------------------------------------------- |
| `date_range` | string | No | `"30d"` | `7d`, `30d`, `90d`, `180d`, `12m`, `ytd` |
| `content_filter` | string | No | `"sitewide"` | `sitewide` (all pages) or `clickflow` (only ClickFlow-managed pages) |
### Response
```json theme={null}
{
"hasOrgData": true,
"performanceChartData": {
"current": [
{ "date": "2026-03-01", "clicks": 510, "impressions": 16000, "ctr": 0.032 }
],
"comparison": [
{ "date": "2026-02-01", "clicks": 480, "impressions": 15200, "ctr": 0.031 }
],
"totals": {
"clicks": 15230,
"impressions": 482000,
"ctr": 0.032,
"position": 18.4,
"events": 1205
}
},
"allPages": [
{
"id": "1",
"title": "Complete SEO Guide for 2026",
"url": "/blog/seo-guide",
"isClickFlow": true,
"isUpdatedByClickFlow": false,
"impressions": 8400,
"clicks": 520,
"ctr": 0.062,
"position": 5.2,
"keyEvents": 42,
"impressionsPrev": 7200,
"clicksPrev": 440,
"ctrPrev": 0.053,
"positionPrev": 6.1,
"keyEventsPrev": 35
}
],
"decayingContent": {
"count": 3,
"pages": [
{ "url": "/blog/old-post", "clicks_change": -25.0, "ctr_change": -0.8, "impressions_current": 1200 }
]
},
"growingContent": {
"count": 5,
"pages": [
{ "url": "/blog/trending-topic", "clicks_change": 45.0, "ctr_change": 1.2, "impressions_current": 6800 }
]
}
}
```
### Errors
| Error | Cause |
| -------------------------------------------------- | --------------------------- |
| `{"hasOrgData": false, "error": "no_connections"}` | No GSC connected |
| `{"hasOrgData": false, "error": "no_gsc_access"}` | GSC permissions not granted |
### Usage
```json theme={null}
{ "date_range": "90d", "content_filter": "clickflow" }
```
```bash theme={null}
curl "https://api.clickflow.com/v1/api/results-overview?date_range=90d&content_filter=clickflow" \
-H "Authorization: Bearer cf_ak_your_key_here"
```
Slow: queries Google APIs. May take 10-30 seconds.
***
## platform\_get\_aeo\_data
Get Answer Engine Optimization data from Google Analytics — AI-referred traffic by platform (ChatGPT, Perplexity, etc.), sessions, key events, and page-level breakdown.
### Parameters
| Name | Type | Required | Default | Description |
| ---------------- | ------ | -------- | ------------ | ---------------------------------------- |
| `date_range` | string | No | `"30d"` | `7d`, `30d`, `90d`, `180d`, `12m`, `ytd` |
| `content_filter` | string | No | `"sitewide"` | `sitewide` or `clickflow` |
### Response
```json theme={null}
{
"activePlatforms": ["chatgpt", "perplexity"],
"chartData": [
{ "date": "2026-03-01", "chatgpt": 15, "perplexity": 8 },
{ "date": "2026-03-02", "chatgpt": 18, "perplexity": 6 }
],
"platformTotals": [
{ "platform": "chatgpt", "sessions": 342 },
{ "platform": "perplexity", "sessions": 156 }
],
"sparklineCards": [
{ "label": "AI Sessions", "value": "498", "change": 12, "sparkline": [380, 410, 450, 498] }
],
"pages": [
{
"id": "page_001",
"url": "/blog/seo-guide",
"sources": ["chatgpt", "perplexity"],
"sourceSessions": { "chatgpt": 62, "perplexity": 27 },
"sessions": 89,
"engaged": 71,
"trend": "growing",
"isClickFlow": true
}
],
"keyEventsByPlatform": [
{ "platform": "chatgpt", "label": "ChatGPT", "keyEvents": 28 }
],
"trafficQuality": [
{
"metric": "Engagement Rate",
"llmValue": "78%",
"llmChange": 5.2,
"organicValue": "62%",
"organicChange": 1
}
],
"totalAiSessions": 498
}
```
### Errors
| Error | Cause |
| ---------------------------------------- | ----------------- |
| `"No Google Analytics connection found"` | GA4 not connected |
Requires GA4 connection. Slow: may take 10-30 seconds.
***
## platform\_get\_visibility\_rankings
Track how your brand appears across AI platforms (ChatGPT, Perplexity). Returns brand mentions, average position, visibility percentage, and competitor rankings.
### Parameters
| Name | Type | Required | Default | Description |
| ------------- | ------- | -------- | ------- | ------------------------------------------------ |
| `platform` | string | No | `""` | Filter: `chatgpt`, `perplexity`, or omit for all |
| `include_all` | boolean | No | `false` | Include untracked competitors |
### Response
```json theme={null}
{
"runId": "abc123",
"completedAt": 1711234567890,
"totalPrompts": 35,
"brand": {
"mentions": 24,
"avgPosition": 3.2,
"visibility": 68,
"positionChange": -0.4,
"visibilityChange": 5
},
"rankings": [
{
"competitorId": "comp_456",
"name": "Competitor Inc",
"domain": "competitor.com",
"tracked": true,
"mentions": 18,
"avgPosition": 4.1,
"visibility": 51,
"positionChange": 0.3,
"visibilityChange": -2
}
],
"platformBreakdown": [
{
"platform": "chatgpt",
"brandVisibility": 72,
"competitorVisibility": { "comp_456": 48 }
}
]
}
```
### Usage
```json theme={null}
{ "platform": "chatgpt", "include_all": true }
```
```bash theme={null}
curl "https://api.clickflow.com/v1/api/visibility/rankings?platform=chatgpt&include_all=true" \
-H "Authorization: Bearer cf_ak_your_key_here"
```
***
## platform\_get\_visibility\_topics
Get topic-by-topic AI visibility scores with per-prompt breakdown.
### Parameters
| Name | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ------------------------------- |
| `platform` | string | No | `""` | Filter: `chatgpt`, `perplexity` |
| `date_range_days` | integer | No | `0` | `7`, `30`, `90`, or `180` |
### Response
```json theme={null}
{
"runId": "abc123",
"completedAt": 1711234567890,
"topics": [
{
"topicId": "topic_789",
"topicName": "SEO tools",
"score": 72,
"mentionedCount": 8,
"totalCount": 12,
"rankedInCount": 6,
"yourPosition": 3.5,
"change": 2,
"competitorRankings": [
{
"competitorId": "comp_456",
"avgPosition": 4.2,
"name": "Competitor Inc",
"domain": "competitor.com",
"tracked": true,
"promptCount": 5
}
],
"prompts": [
{
"promptText": "What are the best SEO tools?",
"type": "mention",
"yourPosition": 2.0,
"change": 1,
"platforms": {
"chatgpt": { "position": 2, "type": "mention", "mentioned": true }
},
"competitorRankings": [
{ "competitorId": "comp_456", "avgPosition": 3.0, "name": "Competitor Inc", "domain": "competitor.com", "tracked": true }
]
}
]
}
]
}
```
May return `{"error": "Too much topic data. Try filtering by platform."}` for large datasets.
***
## platform\_get\_visibility\_sentiment
Get sentiment analysis from AI platform mentions — positive and negative themes with occurrence counts.
### Parameters
| Name | Type | Required | Default | Description |
| ---------- | ------ | -------- | ------- | ------------------------------- |
| `platform` | string | No | `""` | Filter: `chatgpt`, `perplexity` |
### Response
```json theme={null}
{
"positive": [
{ "theme": "Easy to use", "occurrences": 12 },
{ "theme": "Good documentation", "occurrences": 8 }
],
"negative": [
{ "theme": "Pricing concerns", "occurrences": 3 }
]
}
```
***
## platform\_get\_visibility\_status
Check the status of the latest AI visibility scan.
### Parameters
None.
### Response
```json theme={null}
{
"status": "completed",
"timestamp": "2026-03-20T10:30:00Z"
}
```
Status values: `running`, `completed`, `failed`.
# Content Pipeline
Source: https://docs.clickflow.com/capabilities/content-pipeline
Create, manage, draft, schedule, and publish content via roadmap items.
Roadmap items are the core of ClickFlow's content pipeline. Each item represents a piece of content — from initial planning through AI drafting to CMS publication.
## platform\_create\_roadmap\_item
Create a new content roadmap item. Optionally start the AI drafting workflow immediately.
### Parameters
| Name | Type | Required | Default | Description |
| ------------------- | ------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| `keyword` | string | Yes | — | Target keyword for the content |
| `prompt` | string | No | `""` | Content brief or instructions for the AI |
| `strategy` | string | No | `"Article"` | Content type: `Article`, `Listicle`, `How-to guide`, `Case study`, `News post`, `Review`, `Comparison`, `FAQ` |
| `scheduled_date` | string | No | `""` | Publication date in ISO format (e.g. `2026-03-25`) |
| `start_drafting` | boolean | No | `false` | Start the AI drafting workflow immediately |
| `image_generation` | string | No | `""` | Image style: `stock_photos`, `diagrams`, `illustrations`, `watercolor` |
| `delivery_mode` | string | No | `"draft"` | `draft` (save to roadmap item) or `cms` (publish to CMS on completion) |
| `cms_connection_id` | string | No | `""` | Required when `delivery_mode` is `cms` |
### Response
Without `start_drafting`:
```json theme={null}
{
"roadmap_item_id": "ri_abc123",
"status": "ready for review"
}
```
With `start_drafting: true`:
```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."
}
```
### Usage
```json theme={null}
{
"keyword": "best CRM for startups",
"prompt": "Write a comparison for bootstrapped founders",
"strategy": "Comparison",
"start_drafting": true
}
```
```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 CRM for startups",
"prompt": "Write a comparison for bootstrapped founders",
"strategy": "Comparison",
"start_drafting": true
}'
```
***
## platform\_list\_roadmap\_items
List all roadmap items, optionally filtered by status.
### Parameters
| Name | Type | Required | Default | Description |
| -------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------ |
| `status` | string | No | `""` | Filter: `ready for review`, `approved`, `scheduled`, `drafted`, `synced`, `archived` |
### Response
```json theme={null}
{
"items": [
{
"_id": "ri_abc123",
"keyword": "best CRM for startups",
"status": "drafted",
"title": "Best CRM for Startups in 2026",
"workflowId": "wf_xyz789"
}
],
"count": 1
}
```
### Usage
```json theme={null}
{ "status": "drafted" }
```
```bash theme={null}
curl "https://api.clickflow.com/v1/api/roadmap-items?status=drafted" \
-H "Authorization: Bearer cf_ak_your_key_here"
```
***
## platform\_get\_roadmap\_item
Get a single roadmap item with full details including draft content.
### Parameters
| Name | Type | Required | Default | Description |
| ----------------- | ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roadmap_item_id` | string | Yes | — | The roadmap item ID |
| `output_format` | string | No | `"html"` | `html` (default) or `markdown`. When `markdown`, the response includes a `draft.markdown` field with the content converted to Markdown. The `draft.html` field is always present. MCP only. |
### Response
```json theme={null}
{
"_id": "ri_abc123",
"keyword": "best CRM for startups",
"status": "drafted",
"title": "Best CRM for Startups in 2026",
"draft": {
"title": "Best CRM for Startups in 2026",
"html": "Best CRM for Startups
...",
"markdown": "# Best CRM for Startups\n...",
"metaDescription": "Compare the top CRM tools...",
"thumbnailUrl": "https://storage.googleapis.com/...",
"generatedAt": 1711324800000
},
"workflowId": "wf_xyz789",
"organizationId": "org_abc123"
}
```
The `draft.markdown` field is only present when `output_format="markdown"`.
### Usage
```json theme={null}
{ "roadmap_item_id": "ri_abc123", "output_format": "markdown" }
```
```bash theme={null}
curl https://api.clickflow.com/v1/api/roadmap-items/ri_abc123 \
-H "Authorization: Bearer cf_ak_your_key_here"
```
The `output_format` parameter is available via MCP only. REST API always returns HTML.
***
## platform\_update\_roadmap\_item
Update a roadmap item's metadata. Only provided fields are updated.
### Parameters
| Name | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------- |
| `roadmap_item_id` | string | Yes | The roadmap item ID |
| `title` | string | No | New title |
| `meta_description` | string | No | New meta description |
| `slug` | string | No | New URL slug |
### Response
```json theme={null}
{ "success": true }
```
### Usage
```json theme={null}
{
"roadmap_item_id": "ri_abc123",
"title": "Updated Title",
"meta_description": "Updated description for SEO"
}
```
```bash theme={null}
curl -X PATCH https://api.clickflow.com/v1/api/roadmap-items/ri_abc123 \
-H "Authorization: Bearer cf_ak_your_key_here" \
-H "Content-Type: application/json" \
-d '{"title": "Updated Title", "meta_description": "Updated description for SEO"}'
```
***
## platform\_update\_roadmap\_item\_status
Change the status of a roadmap item.
### Parameters
| Name | Type | Required | Description |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| `roadmap_item_id` | string | Yes | The roadmap item ID |
| `status` | string | Yes | `ready for review`, `approved`, `changes requested`, `drafted`, `synced`, `archived` |
### Response
```json theme={null}
{ "success": true }
```
### Usage
```json theme={null}
{ "roadmap_item_id": "ri_abc123", "status": "approved" }
```
```bash theme={null}
curl -X PATCH https://api.clickflow.com/v1/api/roadmap-items/ri_abc123/status \
-H "Authorization: Bearer cf_ak_your_key_here" \
-H "Content-Type: application/json" \
-d '{"status": "approved"}'
```
***
## platform\_schedule\_roadmap\_item
Set or change the scheduled publication date.
### Parameters
| Name | Type | Required | Description |
| ----------------- | ------ | -------- | ----------------------------------- |
| `roadmap_item_id` | string | Yes | The roadmap item ID |
| `date` | string | Yes | ISO date format (e.g. `2026-03-25`) |
### Response
```json theme={null}
{ "success": true }
```
### Usage
```json theme={null}
{ "roadmap_item_id": "ri_abc123", "date": "2026-04-15" }
```
```bash theme={null}
curl -X PUT https://api.clickflow.com/v1/api/roadmap-items/ri_abc123/schedule \
-H "Authorization: Bearer cf_ak_your_key_here" \
-H "Content-Type: application/json" \
-d '{"date": "2026-04-15"}'
```
***
## platform\_save\_draft
Save or replace the full draft content on a roadmap item. Sets status to `drafted`.
### Parameters
| Name | Type | Required | Description |
| ------------------ | ------ | -------- | ---------------------- |
| `roadmap_item_id` | string | Yes | The roadmap item ID |
| `title` | string | Yes | Draft title |
| `html` | string | Yes | Full HTML content body |
| `meta_description` | string | No | SEO meta description |
| `thumbnail_url` | string | No | Featured image URL |
### Response
```json theme={null}
{ "success": true }
```
### Usage
```json theme={null}
{
"roadmap_item_id": "ri_abc123",
"title": "My Custom Article",
"html": "My Custom Article
Content goes here...
",
"meta_description": "A brief summary for search engines"
}
```
```bash theme={null}
curl -X PUT https://api.clickflow.com/v1/api/roadmap-items/ri_abc123/draft \
-H "Authorization: Bearer cf_ak_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"title": "My Custom Article",
"html": "My Custom Article
Content goes here...
",
"meta_description": "A brief summary for search engines"
}'
```
***
## platform\_publish\_to\_cms
Publish a roadmap item's draft to your connected CMS.
Supported CMS: WordPress, Sanity, HubSpot, Shopify, Strapi.
### Parameters
| Name | Type | Required | Description |
| ------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roadmap_item_id` | string | Yes | The roadmap item ID (must have a draft) |
| `cms_connection_id` | string | No | CMS connection to use. If omitted, ClickFlow resolves automatically: previous publish connection > linked workflow connection > first available CMS. |
### Response
```json theme={null}
{
"success": true,
"post_id": "12345",
"permalink": "https://example.com/blog/my-article",
"edit_url": "https://example.com/wp-admin/post.php?post=12345",
"cms_type": "wordpress"
}
```
### Errors
| Error | Cause |
| ------------------------------------------------ | --------------------------------------- |
| `"Roadmap item has no draft content to publish"` | No draft saved yet |
| `"No CMS connection found"` | No CMS connected in ClickFlow dashboard |
### Usage
```json theme={null}
{ "roadmap_item_id": "ri_abc123" }
```
```bash theme={null}
curl -X POST https://api.clickflow.com/v1/api/roadmap-items/ri_abc123/publish \
-H "Authorization: Bearer cf_ak_your_key_here" \
-H "Content-Type: application/json" \
-d '{}'
```
***
## platform\_add\_target\_keyword
Add a keyword to your organization's tracking list.
### Parameters
| Name | Type | Required | Default | Description |
| ------------ | ------- | -------- | ----------------- | -------------------------------------------------------------- |
| `keyword` | string | Yes | — | The keyword to track |
| `volume` | integer | No | `0` | Monthly search volume |
| `difficulty` | integer | No | `0` | Keyword difficulty (0-100) |
| `intent` | string | No | `"informational"` | `informational`, `commercial`, `transactional`, `navigational` |
### Response
```json theme={null}
{
"keyword": "best CRM for startups",
"status": "added"
}
```
### Usage
```json theme={null}
{
"keyword": "best CRM for startups",
"volume": 8100,
"difficulty": 58,
"intent": "commercial"
}
```
```bash theme={null}
curl -X POST https://api.clickflow.com/v1/api/target-keywords \
-H "Authorization: Bearer cf_ak_your_key_here" \
-H "Content-Type: application/json" \
-d '{"keyword": "best CRM for startups", "volume": 8100, "difficulty": 58, "intent": "commercial"}'
```
```
```
# SEO Research
Source: https://docs.clickflow.com/capabilities/seo-research
Keyword analysis, competitor tracking, and brand voice retrieval.
## platform\_get\_brand\_voice
Retrieve your organization's brand voice profile — company overview, tone, audience, and competitive context. Use this to understand the brand before generating content.
### Parameters
None.
### Response
```json theme={null}
{
"companyName": "ClickFlow",
"overview": "ClickFlow is an AI-powered SEO platform...",
"products": "AI content optimization, visibility tracking, workflow automation",
"audience": "SEO professionals and content teams",
"industry": "SaaS / Marketing Technology",
"toneOptions": ["Professional", "Approachable"],
"styleOptions": ["Data-driven", "Actionable"],
"voiceContext": "Authoritative yet friendly, focused on practical SEO advice",
"website_url": "https://clickflow.com",
"brandColors": [],
"guidelines": [],
"imageStylePreference": "stock_photo",
"sophistication": 50.0,
"founded": "2017",
"concepts": "",
"constraints": "",
"contentDifferentiation": "",
"ctas": "",
"examples": "",
"knowledgeProducts": "",
"statistics": ""
}
```
### Usage
Call `platform_get_brand_voice` with no parameters.
```bash theme={null}
curl https://api.clickflow.com/v1/api/brand-voice \
-H "Authorization: Bearer cf_ak_your_key_here"
```
Returns `{"error": "No brand voice configured for this organization"}` if not set up yet. Configure it in the ClickFlow dashboard.
***
## platform\_analyze\_keyword
Get keyword difficulty, search volume, and competition metrics via DataForSEO.
### Parameters
| Name | Type | Required | Default | Description |
| ---------- | ------ | -------- | ----------------- | ---------------------- |
| `keyword` | string | Yes | — | The keyword to analyze |
| `location` | string | No | `"United States"` | Target location |
| `language` | string | No | `"en"` | Language code |
### Response
```json theme={null}
{
"keyword_difficulty": 65,
"search_intent": null,
"search_volume": 12000,
"cpc": 4.50,
"competition": 0.73,
"trend_data": { "2025-12": 11000, "2026-01": 12500 },
"serp_features": ["featured_snippet", "knowledge_graph", "people_also_ask"]
}
```
### Usage
```json theme={null}
{
"keyword": "best project management tools",
"location": "United States"
}
```
```bash theme={null}
curl -X POST https://api.clickflow.com/v1/api/analyze-keyword \
-H "Authorization: Bearer cf_ak_your_key_here" \
-H "Content-Type: application/json" \
-d '{"keyword": "best project management tools"}'
```
***
## platform\_list\_target\_keywords
List tracked target keywords with SEO metrics.
### Parameters
| Name | Type | Required | Default | Description |
| ------- | ------- | -------- | ------- | -------------------------- |
| `limit` | integer | No | `500` | Maximum keywords to return |
### Response
```json theme={null}
{
"keywords": [
{
"target_keyword": "best CRM for startups",
"search_volume": 8100,
"difficulty": 58,
"intent": "commercial"
}
],
"count": 1
}
```
### Usage
```json theme={null}
{ "limit": 100 }
```
```bash theme={null}
curl "https://api.clickflow.com/v1/api/target-keywords?limit=100" \
-H "Authorization: Bearer cf_ak_your_key_here"
```
If you have many keywords, the response may return `{"error": "Too many keywords. Try a smaller limit."}`. Reduce the `limit` parameter.
***
## platform\_list\_competitors
List tracked competitors with domain, average position, and keyword intersections.
### Parameters
None.
### Response
```json theme={null}
{
"competitors": [
{
"_id": "comp_abc123",
"organizationId": "org_xyz789",
"name": "Competitor Inc",
"domain": "competitor.com",
"avgPosition": 12.5,
"intersections": 45,
"tracked": true,
"reasoning": "Direct competitor in SEO tools space",
"createdAt": 1711234567890,
"_creationTime": 1711234567890
}
],
"count": 1
}
```
### Usage
Call `platform_list_competitors` with no parameters.
```bash theme={null}
curl https://api.clickflow.com/v1/api/competitors \
-H "Authorization: Bearer cf_ak_your_key_here"
```
# Site Monitoring
Source: https://docs.clickflow.com/capabilities/site-monitoring
Sitemap tracking and page discovery via Radar.
Radar monitors your sitemaps and discovers pages for SEO tracking.
## platform\_get\_radar\_sitemaps
List tracked sitemaps with domain, sync status, and page count.
### Parameters
None.
### Response
```json theme={null}
{
"sitemaps": [
{
"_id": "sm_abc123",
"url": "https://example.com/sitemap.xml",
"domain": "example.com",
"status": "synced",
"pageCount": 342
}
],
"count": 1
}
```
### Usage
Call `platform_get_radar_sitemaps` with no parameters.
```bash theme={null}
curl https://api.clickflow.com/v1/api/radar/sitemaps \
-H "Authorization: Bearer cf_ak_your_key_here"
```
***
## platform\_get\_radar\_pages
Get discovered pages from tracked sitemaps with URL, title, keyword data, and tracking status.
### Parameters
| Name | Type | Required | Default | Description |
| ----------------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------- |
| `sitemap_url_ids` | string\[] | No | `[]` | Filter by sitemap IDs (from `get_radar_sitemaps`). **MCP only** — not available via REST API. |
| `limit` | integer | No | `200` | Maximum pages to return |
### Response
```json theme={null}
{
"pages": [
{
"url": "https://example.com/blog/seo-guide",
"title": "Complete SEO Guide",
"keyword": "seo guide",
"tracked": true
}
],
"count": 50,
"total": 342
}
```
### Usage
```json theme={null}
{ "sitemap_url_ids": ["sm_abc123"], "limit": 50 }
```
```bash theme={null}
curl "https://api.clickflow.com/v1/api/radar/pages?limit=50" \
-H "Authorization: Bearer cf_ak_your_key_here"
```
May return `{"error": "Too many pages. Try filtering by sitemap or reducing the limit."}` for large sites.
# Workflow Management
Source: https://docs.clickflow.com/capabilities/workflows
List workflows, poll status, resume paused workflows, and view published content.
For a conceptual overview of how workflows work, see [Core Concepts: Workflows](/concepts/workflows).
## platform\_list\_workflows
List recent workflows with status and progress.
### Parameters
| Name | Type | Required | Default | Description |
| -------- | ------- | -------- | ------- | -------------------------------------------- |
| `status` | string | No | `""` | Filter: `In Progress`, `Completed`, `Failed` |
| `limit` | integer | No | `20` | Maximum workflows to return |
### Response
```json theme={null}
{
"workflows": [
{
"_id": "wf_xyz789",
"name": "Create Adaptive Prompt-Driven Post Draft",
"status": "Completed",
"progress": 100,
"currentAction": "Done"
}
],
"count": 1
}
```
### Usage
```json theme={null}
{ "status": "In Progress", "limit": 5 }
```
```bash theme={null}
curl "https://api.clickflow.com/v1/api/workflows?status=In%20Progress&limit=5" \
-H "Authorization: Bearer cf_ak_your_key_here"
```
***
## workflows\_get\_status
Check a specific workflow's progress. Returns status, progress percentage, current action, and output (when completed).
### Parameters
| Name | Type | Required | Default | Description |
| --------------- | ------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `workflow_id` | string | Yes | — | The workflow ID |
| `output_format` | string | No | `"html"` | `html` (default) or `markdown`. When `markdown`, completed workflow output includes a `markdown` field alongside `html`. MCP only. |
### Response
See [Workflows: Polling for status](/concepts/workflows#polling-for-status) for the full response shape including `In Progress`, `Completed`, `Failed`, and `Human Review` states.
When `output_format="markdown"`, the `output` object of a completed workflow includes an additional `markdown` field with the content converted to Markdown.
### Usage
```json theme={null}
{ "workflow_id": "wf_xyz789", "output_format": "markdown" }
```
```bash theme={null}
curl https://api.clickflow.com/v1/api/workflows/wf_xyz789/status \
-H "Authorization: Bearer cf_ak_your_key_here"
```
The `output_format` parameter is available via MCP only. REST API always returns HTML.
***
## workflows\_resume
Submit a review decision to resume a paused workflow. Only applicable when workflow status is `Human Review`.
### Parameters
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------------- |
| `workflow_id` | string | Yes | The workflow ID |
| `decision` | object | Yes | Decision payload — varies by review type |
See [Workflows: Decision payloads](/concepts/workflows#decision-payloads-by-review-type) for the decision format for each review type.
### Response
```json theme={null}
{
"workflow_id": "wf_xyz789",
"status": "resuming",
"review_type": "implementation_spec_review",
"message": "Decision submitted. Poll workflows_get_status for progress."
}
```
### Usage
```json theme={null}
{
"workflow_id": "wf_xyz789",
"decision": {
"approved": true,
"selected_change_ids": [1, 3, 5]
}
}
```
```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]}}'
```
***
## platform\_list\_published\_content
List all content pieces that have been published to a CMS.
### Parameters
None.
### Response
```json theme={null}
{
"items": [
{
"url": "https://example.com/blog/seo-guide",
"title": "Complete SEO Guide for 2026",
"postId": "12345",
"cmsType": "wordpress",
"publishedAt": 1711324800000,
"status": "published"
}
],
"count": 1
}
```
### Usage
Call `platform_list_published_content` with no parameters.
```bash theme={null}
curl https://api.clickflow.com/v1/api/published-content \
-H "Authorization: Bearer cf_ak_your_key_here"
```
# Organizations
Source: https://docs.clickflow.com/concepts/organizations
Multi-org support, switching orgs, and organization context.
Every ClickFlow API call operates within the context of an organization. Your API key or OAuth session determines which organizations you can access.
## Always confirm the org first
Before making changes, call `list_organizations` to see available orgs and verify you're targeting the right one.
Call the `platform_list_organizations` tool (no parameters).
```bash theme={null}
curl https://api.clickflow.com/v1/api/organizations \
-H "Authorization: Bearer cf_ak_your_key_here"
```
**Response:**
```json theme={null}
{
"organizations": [
{
"_id": "org_abc123",
"name": "My Company",
"domain": "example.com"
},
{
"_id": "org_def456",
"name": "Client Site",
"domain": "client.com"
}
],
"count": 2
}
```
## Switching organizations
By default, all calls use your API key's default organization. To operate on a different org:
Call `platform_switch_organization`:
```json theme={null}
{
"organization_id": "org_def456"
}
```
All subsequent tool calls in the session will use the new org.
Pass the `X-Organization-Id` header on each request:
```bash theme={null}
curl https://api.clickflow.com/v1/api/roadmap-items \
-H "Authorization: Bearer cf_ak_your_key_here" \
-H "X-Organization-Id: org_def456"
```
Or use the switch endpoint for session-level switching:
```bash theme={null}
curl -X POST https://api.clickflow.com/v1/api/switch-organization \
-H "Authorization: Bearer cf_ak_your_key_here" \
-H "Content-Type: application/json" \
-d '{"organization_id": "org_def456"}'
```
Operating on the wrong organization cannot be undone. Always confirm with `list_organizations` before making changes.
## Access control
* **API keys** can only access organizations they were granted access to
* **OAuth users** can access any organization they're a member of
* Cross-org access attempts return `{"error": "Organization not found or you don't have access"}`
# Workflows
Source: https://docs.clickflow.com/concepts/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.
```json theme={null}
{
"keyword": "best project management tools",
"prompt": "Compare top 5 tools for small teams",
"strategy": "Comparison",
"start_drafting": true
}
```
```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
}'
```
**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
Call `workflows_get_status` with `workflow_id`.
```bash theme={null}
curl https://api.clickflow.com/v1/api/workflows/wf_xyz789/status \
-H "Authorization: Bearer cf_ak_your_key_here"
```
### 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": "Best Project Management Tools
...",
"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
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]
}
}
```
```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]
}
}'
```
### 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` |
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`. |
# ClickFlow Developer Docs
Source: https://docs.clickflow.com/index
Integrate ClickFlow's AI-powered SEO platform into your workflows via MCP or REST API.
ClickFlow is an AI-powered SEO platform that creates, optimizes, and tracks content — driven by real Google Search Console and Analytics data, not guesswork.
These docs cover the **MCP server** and **REST API** — two ways to access the same capabilities programmatically.
## How it works
```
Keyword → Roadmap Item → AI Workflow (5-15 min) → Draft → Publish to CMS
```
1. You **research keywords** and decide what to write about
2. You create a **roadmap item** — a planned piece of content tied to a keyword
3. You start a **workflow** — an AI pipeline that researches competitors, outlines, and writes
4. The workflow produces a **draft** (HTML + title + meta description)
5. You review, edit, then **publish** to your CMS (WordPress, Sanity, HubSpot, Shopify, Strapi)
Every step can be done programmatically via MCP or API.
**You need a ClickFlow account first.** Sign up at [app.clickflow.com](https://app.clickflow.com), set up your brand voice, and connect Google Search Console. MCP clients authenticate via OAuth (no API key needed). For the REST API, generate an API key in Settings.
## What you can do
Create roadmap items, generate drafts with AI, save and publish to your CMS.
Analyze keywords, track competitors, and retrieve your brand voice profile.
Optimize titles, meta descriptions, generate FAQs, images, and run competitive analysis.
Pull SEO performance data from Google Search Console and GA4, track AI visibility.
## Get started
Connect ClickFlow to your MCP client or make your first API call in 5 minutes.
API keys, OAuth, and headers.
## Two ways to connect
Both interfaces expose the same 34 capabilities and return identical responses.
| | MCP | REST API |
| ------------ | ---------------------------------------- | ------------------------------------ |
| **Endpoint** | `https://api.clickflow.com/v1/mcp` | `https://api.clickflow.com/v1/api/*` |
| **Best for** | AI assistants (Claude, Cursor, Windsurf) | Scripts, CI/CD, custom integrations |
| **Auth** | OAuth via Clerk (no API key needed) | API key (`cf_ak_*`) |
| **Protocol** | MCP over HTTP | Standard REST (JSON) |
# Quickstart
Source: https://docs.clickflow.com/quickstart
Connect ClickFlow to your MCP client or make your first API call.
## Prerequisites
1. **Sign up** at [app.clickflow.com](https://app.clickflow.com) and create an organization
2. **Connect Google Search Console** (recommended — enables SEO data and content workflows)
3. **Set up your brand voice** (so AI-generated content matches your tone)
## Connect
Add this to your `.mcp.json` (or your MCP client's config):
```json .mcp.json theme={null}
{
"mcpServers": {
"clickflow": {
"type": "http",
"url": "https://api.clickflow.com/v1/mcp"
}
}
}
```
**No API key needed.** Your MCP client will open a browser login on first use — you sign in with your regular ClickFlow account (the same login you use at app.clickflow\.com).
Once connected, your AI assistant can call ClickFlow tools directly. Try asking:
> "List my ClickFlow organizations"
The REST API uses API keys for authentication.
### Get your API key
1. Go to **Settings > API Keys** in the ClickFlow dashboard
2. Click **Create API Key**
3. Copy the key — it starts with `cf_ak_` and is only shown once
Store your API key securely. It cannot be retrieved after creation.
### Make your first request
```bash theme={null}
curl https://api.clickflow.com/v1/api/organizations \
-H "Authorization: Bearer cf_ak_your_key_here"
```
Response:
```json theme={null}
{
"organizations": [
{
"_id": "org_abc123",
"name": "My Company",
"domain": "example.com"
}
],
"count": 1
}
```
## Try it: create your first article
This example creates a roadmap item and kicks off the AI drafting workflow.
Call the `platform_create_roadmap_item` tool:
```json theme={null}
{
"keyword": "how to improve SEO rankings",
"prompt": "Write a comprehensive guide for small business owners",
"strategy": "How-to guide",
"start_drafting": true
}
```
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."
}
```
Then poll `workflows_get_status` with the `workflow_id` until status is `Completed`. The output contains `html`, `title`, `meta_description`, and `thumbnail_url`.
```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": "how to improve SEO rankings",
"prompt": "Write a comprehensive guide for small business owners",
"strategy": "How-to guide",
"start_drafting": true
}'
```
Then poll the workflow:
```bash theme={null}
curl https://api.clickflow.com/v1/api/workflows/wf_xyz789/status \
-H "Authorization: Bearer cf_ak_your_key_here"
```
## Next steps
Deep dive into OAuth, API keys, and headers.
Multi-org support and switching between orgs.
Understand async workflows, polling, and human review.
Browse the full capability reference.