KW Agent Dashboard

Overview

-

Total Jobs

-

Completed

-

Themes Saved

-

Total Cost

Recent Jobs

ID	Seed	Intent	Mode	Status	Themes	Cost	Created
Loading...

Agent Jobs

Submit New Job

Seed (niche)

Intent (product)

Store

Quality

Advanced Config

Max Iterations

Max Tool Calls

Max External APIs

Temperature

Live Monitor

Submit a job or select one to monitor

Job History

ID	Seed	Intent	Status	Themes	Cost	Actions
Loading...

Pipeline Flow

Step-by-Step Pipeline

1. SERP Data

▶

2. Theme AI

▶

3. Group Keywords

▶

4. Search Operator

▶

5. Theme Intent

Theme

Intent

Job ID (optional)

Pipeline Result

No results yet. Run a pipeline step above.

Settings

General

AI Extraction

Crawler API

Volume API

Grouping

API Keys

Agent

Hybrid

Performance

Notifications

General Settings

Store

Result Count

Structured Operator Domain

Structured Operator Path

Queue & Workers

Queue Status

Loading...

Worker Controls

Agent Monitor

Job ID

Select a job to monitor

API Documentation kwagent.webnow.ai

Base URL: https://kwagent.webnow.ai | Auth: JWT for /auth/* /keyword-seed/* | Bearer API_KEY for /api/* /mcp/*

1. Auth Endpoints

POST

/auth/registerNo auth (first user) / Admin JWT

Register new user. First user auto-becomes admin.

Body & Response

// Request
{ "email": "admin@example.com", "password": "SecurePass123", "username": "admin", "role": "admin" }

// Response 201
{ "success": true, "data": { "id": "plZWvg0KMQ", "email": "admin@example.com", "username": "admin", "role": "admin" } }

POST

/auth/loginNo auth

Login with email/password. Returns access token (15m) + refresh token (7d).

Body & Response

// Request
{ "email": "admin@example.com", "password": "SecurePass123" }

// Response
{ "success": true, "data": { "accessToken": "eyJ...", "refreshToken": "eyJ...", "expiresIn": "15m",
  "user": { "id": "plZWvg0KMQ", "email": "admin@example.com", "username": "admin", "role": "admin" } } }

POST

/auth/refreshRefresh token

Get new access token using refresh token (body or cookie).

Body & Response

// Request
{ "refreshToken": "eyJ..." }

// Response
{ "success": true, "data": { "accessToken": "eyJ...", "expiresIn": "15m" } }

POST

/auth/logoutJWT

Revoke refresh token, clear cookie.

GET

/auth/meJWT

Get current user info (id, email, username, role).

PUT

/auth/change-passwordJWT

Change password. Revokes refresh token — must login again.

Body

{ "currentPassword": "OldPass", "newPassword": "NewPass123" }

2. Agent API `/api/v1/agent/research`

POST

/api/v1/agent/researchBearer API_KEY

Submit keyword research job. Returns jobId for polling.

Body & Response

// Request
{ "seed": "plumber", "intent": "shirt", "store": "my-store",
  "agentConfig": { "maxIterations": 15, "qualityThreshold": "EXCELLENT",
    "reasoningModel": "gpt-5.2", "temperature": 0.3, "maxToolCalls": 80,
    "maxExternalApiCalls": 50, "maxExecutionTimeMs": 900000 },
  "callbackUrl": "https://your-webhook.com/callback" }

// Response 201
{ "success": true, "data": { "jobId": "abc1234567", "seed": "plumber", "intent": "shirt",
  "status": "processing", "statusUrl": "/api/v1/agent/research/abc1234567",
  "resultsUrl": "/api/v1/agent/research/abc1234567/results" } }

GET

/api/v1/agent/research/:idBearer API_KEY

Get job status. Status: processing | completed | failed.

Response

{ "success": true, "data": { "jobId": "abc1234567", "seed": "plumber", "intent": "shirt",
  "status": "completed", "mode": "agent", "themesFound": 107, "themesSaved": 42,
  "iterations": 13, "toolCalls": 63, "tokensUsed": 285000, "estimatedCostUsd": 0.75,
  "progress": { "progress": 65, "message": "Iteration 8/20: Found 28 themes..." } } }

GET

/api/v1/agent/research/:id/resultsBearer API_KEY

Get full results with themes, quality scores, SERP data.

Response

{ "success": true, "data": { "jobId": "abc1234567", "totalThemes": 42,
  "meta": { "themesFound": 107, "themesSaved": 42, "iterations": 13, "estimatedCostUsd": 0.75 },
  "themes": [{ "theme": "Funny Plumber Dad", "searchQuery": "funny plumber dad shirt...",
    "quality": { "score": 0.92, "recommendation": "EXCELLENT", "reasoning": "..." },
    "serpResults": [{ "title": "Funny Plumber Dad T-Shirt", "link": "https://etsy.com/...", "position": 1 }] }] } }

GET

/api/v1/agent/research?store=&page=1&limit=20Bearer API_KEY

List recent jobs. Params: store, page, limit.

Benchmarks: plumber=$0.44/6m | dentist=$0.46/8m | carpenter=$0.75/9m | barber=$0.76/10m | firefighter=$0.76/10m

6. Agent Tools (18 registered)

Tool	Ext. API	Description
`serp_search`		Google SERP results via Serper
`theme_extract`	-	AI theme extraction from search results
`theme_quality`	-	Score theme quality (EXCELLENT/GOOD/FAIR/POOR)
`keyword_group`	-	Cluster related keywords
`search_volume`		Keyword search volume via DataForSEO
`grounding_search`		Google Gemini grounding search
`perplexity_search`		Perplexity Sonar topical map
`google_grounding_serp`		Google Gemini SERP grounding
`keyword_planner`		Google Ads Keyword Planner
`semrush_keywords`		Semrush related keywords
`semrush_mcp`		Semrush MCP reports
`save_result`	-	Save theme to database
`report_progress`	-	Update progress in Redis
`get_saved_themes`	-	Retrieve already-saved themes
`check_theme_overlap`	-	Check for duplicate themes
`classify_search_intent`	-	Classify search intent
`semantic_cluster`	-	Semantic theme clustering
`assess_coverage`	-	Assess niche coverage completeness
`validate_and_save`	-	Validate theme + save in one call
`brainstorm_themes`	-	AI brainstorm new theme ideas

= counts toward maxExternalApiCalls budget

7. Error Responses

{ "statusCode": 400, "error": "Bad Request", "message": "body must have required property 'seed'" }

Status	Meaning
`400`	Bad Request — Invalid input
`401`	Unauthorized — Missing or invalid auth token
`404`	Not Found — Job or resource not found
`429`	Too Many Requests — Rate limited
`500`	Internal Server Error

Typical Workflows

Third-Party (Agent API)
1. POST /api/v1/agent/research → jobId
2. GET /api/v1/agent/research/:id → poll
3. GET /api/v1/agent/research/:id/results → themes

MCP Pipeline (Step-by-Step)
1. POST /mcp/.../serp-data
2. POST /mcp/.../theme-ai
3. POST /mcp/.../group-keyword
4. POST /mcp/.../search-operator
5. POST /mcp/.../theme-intent

Users

Create User

Email

Username

Password

Role

Current User

Loading...

Change Password

Current Password

New Password

Recent Jobs

Submit New Job

Live Monitor

Job History

Step-by-Step Pipeline

Pipeline Result

General Settings

AI Theme Extraction

Crawler API (SERP)

Volume API (Search Volume)

Keyword Grouping

AI Services

SERP & Search

Google Keyword Planner

Semrush

DataForSEO

Notifications

Agent Configuration

Hybrid Mode Configuration

Phase 1 (Pipeline)

Phase 2 (Agent)

Performance

Notifications

Queue Status

Worker Controls

Agent Monitor

1. Auth Endpoints

2. Agent API `/api/v1/agent/research`

3. Keyword Seed `/keyword-seed`

External Data Sources

4. MCP Pipeline `/mcp/keyword-research`

5. Legacy Keyword Research `/keyword-research`

6. Agent Tools (18 registered)

7. Error Responses

Typical Workflows

Create User

Current User

Change Password

Login to KW Agent

Recent Jobs

Submit New Job

Live Monitor

Job History Refresh

Step-by-Step Pipeline

Pipeline Result

General Settings

AI Theme Extraction

Crawler API (SERP)

Volume API (Search Volume)

Keyword Grouping

AI Services

SERP & Search

Google Keyword Planner

Semrush

DataForSEO

Notifications

Agent Configuration

Hybrid Mode Configuration

Phase 1 (Pipeline)

Phase 2 (Agent)

Performance

Notifications

Queue Status Refresh

Worker Controls

Agent Monitor

1. Auth Endpoints

2. Agent API /api/v1/agent/research

3. Keyword Seed /keyword-seed

External Data Sources

4. MCP Pipeline /mcp/keyword-research

5. Legacy Keyword Research /keyword-research

6. Agent Tools (18 registered)

7. Error Responses

Typical Workflows

Create User

Current User

Change Password

Job History

Queue Status

2. Agent API `/api/v1/agent/research`

3. Keyword Seed `/keyword-seed`

4. MCP Pipeline `/mcp/keyword-research`

5. Legacy Keyword Research `/keyword-research`