Public API: Writer Agent - Keyword Insights Documentation

Generate full AI-written articles from a keyword — including research, outline, and polished content.

Full endpoint reference available on Swagger.

Quick Start

Create a writer agent order to generate an article:

import os
import requests

API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}

payload = {
    "keyword": "content marketing strategies",
    "language_code": "en",
    "location_name": "United States",
    "folder_id": "<your_folder_id>",
}

response = requests.post(
    f"{BASE_URL}/api/writer-agent/order/",
    headers=HEADERS,
    json=payload,
)

data = response.json()
print(data)
# {"status": true, "payload": {"id": "550e8400-...", "keyword": "content marketing strategies", ...}}

const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";

const payload = {
  keyword: "content marketing strategies",
  language_code: "en",
  location_name: "United States",
  folder_id: "<your_folder_id>",
};

const response = await fetch(`${BASE_URL}/api/writer-agent/order/`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const data = await response.json();
console.log(data);
// {"status": true, "payload": {"id": "550e8400-...", "keyword": "content marketing strategies", ...}}

Endpoints

Method	Path	Description
POST	`/api/writer-agent/order/`	Create a writer agent order
GET	`/api/writer-agent/order/?id={id}`	Get order status and generated article
GET	`/api/writer-agent/options/`	Get available options (POV, content types, tones)

Parameters

Required

Parameter	Type	Description
`keyword`	string	The main keyword or topic for the article
`language_code`	string	ISO 639-1 language code (e.g. `en`)
`location_name`	string	Location name (e.g. `United States`). See `/api/keywords-insights/locations/`
`folder_id`	string	Dashboard folder ID to organize the order. Retrieve from the browser URL in the KWI dashboard

Optional

Parameter	Type	Default	Description
`point_of_view`	string	`First person (I/We)`	`First person (I/We)`, `Second Person (You)`, `Third Person (He/She/They/It)`
`content_type`	string	`article`	`article` or `landing_page`
`additional_insights`	string	—	Extra context or instructions for the AI (e.g. “Focus on B2B companies”)

Customizations

Point of View

Control the writing perspective:

payload = {
    "keyword": "best CRM software",
    "language_code": "en",
    "location_name": "United States",
    "point_of_view": "Second Person (You)",  # Speaks directly to the reader
}

const payload = {
  keyword: "best CRM software",
  language_code: "en",
  location_name: "United States",
  point_of_view: "Second Person (You)", // Speaks directly to the reader
};

Content Type

Choose between article-style content or landing page copy:

payload = {
    "keyword": "project management tool",
    "language_code": "en",
    "location_name": "United States",
    "content_type": "landing_page",
}

const payload = {
  keyword: "project management tool",
  language_code: "en",
  location_name: "United States",
  content_type: "landing_page",
};

Additional Context

Steer the AI with specific instructions:

payload = {
    "keyword": "email marketing tips",
    "language_code": "en",
    "location_name": "United States",
    "additional_insights": "Focus on e-commerce businesses. Include real-world case studies.",
}

const payload = {
  keyword: "email marketing tips",
  language_code: "en",
  location_name: "United States",
  additional_insights: "Focus on e-commerce businesses. Include real-world case studies.",
};

Getting Available Options

Retrieve all available options before creating an order:

response = requests.get(
    f"{BASE_URL}/api/writer-agent/options/",
    headers=HEADERS,
)

options = response.json()["result"]["payload"]
print("Points of view:", options["points_of_view"])
print("Content types:", options["content_types"])
print("Tones of voice:", [t["name"] for t in options["tones_of_voice"]])

const response = await fetch(`${BASE_URL}/api/writer-agent/options/`, {
  headers: { "X-API-Key": API_KEY },
});

const json = await response.json();
const options = json.result.payload;
console.log("Points of view:", options.points_of_view);
console.log("Content types:", options.content_types);
console.log("Tones of voice:", options.tones_of_voice.map((t) => t.name));

Retrieving Results

Writer agent orders process through multiple stages (outline, plan, article). Poll until the article is generated:

import os
import time
import requests

API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}

order_id = "550e8400-e29b-41d4-a716-446655440000"

while True:
    response = requests.get(
        f"{BASE_URL}/api/writer-agent/order/",
        headers=HEADERS,
        params={"id": order_id},
    )

    data = response.json()["result"]["payload"]
    status = data.get("processing_status", {})
    print(f"Status: {data.get('status', 'processing')}")

    if data.get("generated_article"):
        break

    time.sleep(30)

print(data["generated_article"])

const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";

const order_id = "550e8400-e29b-41d4-a716-446655440000";

let data;
while (true) {
  const response = await fetch(`${BASE_URL}/api/writer-agent/order/?id=${order_id}`, {
    headers: { "X-API-Key": API_KEY },
  });

  const json = await response.json();
  data = json.result.payload;
  console.log(`Status: ${data.status || "processing"}`);

  if (data.generated_article) {
    break;
  }

  await new Promise((r) => setTimeout(r, 30000));
}

console.log(data.generated_article);

Complete Example

End-to-end: create a writer agent order, wait for the article, and save it.

import os
import time
import requests

API_KEY = os.environ["KWI_API_KEY"]
BASE_URL = "https://api.keywordinsights.ai"
HEADERS = {"X-API-Key": API_KEY}


def create_article(keyword, language="en", location="United States", **kwargs):
    """Create a writer agent order."""
    payload = {
        "keyword": keyword,
        "language_code": language,
        "location_name": location,
        "folder_id": "<your_folder_id>",
        **kwargs,
    }
    response = requests.post(
        f"{BASE_URL}/api/writer-agent/order/",
        headers=HEADERS,
        json=payload,
    )
    response.raise_for_status()
    return response.json()["result"]["payload"]


def wait_for_article(order_id):
    """Poll until the article is generated."""
    while True:
        response = requests.get(
            f"{BASE_URL}/api/writer-agent/order/",
            headers=HEADERS,
            params={"id": order_id},
        )
        data = response.json()["result"]["payload"]

        if data.get("generated_article"):
            return data

        print(f"Processing... status: {data.get('status', 'unknown')}")
        time.sleep(30)


# --- Run ---

result = create_article(
    keyword="best project management tools for startups",
    point_of_view="Second Person (You)",
    content_type="article",
    additional_insights="Include comparisons and pricing information",
)
order_id = result["id"]
print(f"Order created: {order_id}")

article = wait_for_article(order_id)

# Save the article
with open("article.md", "w") as f:
    f.write(article["generated_article"])

print(f"Article saved ({len(article['generated_article'])} characters)")

const fs = require("fs");
const API_KEY = process.env.KWI_API_KEY;
const BASE_URL = "https://api.keywordinsights.ai";

async function createArticle(keyword, language = "en", location = "United States", options = {}) {
  const payload = {
    keyword,
    language_code: language,
    location_name: location,
    folder_id: "<your_folder_id>",
    ...options,
  };
  const response = await fetch(`${BASE_URL}/api/writer-agent/order/`, {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });
  const json = await response.json();
  return json.result.payload;
}

async function waitForArticle(orderId) {
  while (true) {
    const response = await fetch(`${BASE_URL}/api/writer-agent/order/?id=${orderId}`, {
      headers: { "X-API-Key": API_KEY },
    });
    const json = await response.json();
    const data = json.result.payload;

    if (data.generated_article) {
      return data;
    }

    console.log(`Processing... status: ${data.status || "unknown"}`);
    await new Promise((r) => setTimeout(r, 30000));
  }
}

// --- Run ---
(async () => {
  const result = await createArticle("best project management tools for startups", "en", "United States", {
    point_of_view: "Second Person (You)",
    content_type: "article",
    additional_insights: "Include comparisons and pricing information",
  });
  const orderId = result.id;
  console.log(`Order created: ${orderId}`);

  const article = await waitForArticle(orderId);

  // Save the article
  fs.writeFileSync("article.md", article.generated_article);

  console.log(`Article saved (${article.generated_article.length} characters)`);
})();

​Quick Start

​Endpoints

​Parameters

​Required

​Optional

​Customizations

​Point of View

​Content Type

​Additional Context

​Getting Available Options

​Retrieving Results

​Complete Example

Quick Start

Endpoints

Parameters

Required

Optional

Customizations

Point of View

Content Type

Additional Context

Getting Available Options

Retrieving Results

Complete Example