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

# Public API: Writer Agent

> Generate AI-powered articles with outlines, plans, and full content via the API

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

<Info>
  Full endpoint reference available on [Swagger](https://api.keywordinsights.ai/apidocs/#/Writer%20Agent).
</Info>

### Quick Start

Create a writer agent order to generate an article:

<CodeGroup>
  ```python Python theme={null}
  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", ...}}
  ```

  ```javascript JavaScript theme={null}
  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", ...}}
  ```
</CodeGroup>

### 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:

<CodeGroup>
  ```python Python theme={null}
  payload = {
      "keyword": "best CRM software",
      "language_code": "en",
      "location_name": "United States",
      "point_of_view": "Second Person (You)",  # Speaks directly to the reader
  }
  ```

  ```javascript JavaScript theme={null}
  const payload = {
    keyword: "best CRM software",
    language_code: "en",
    location_name: "United States",
    point_of_view: "Second Person (You)", // Speaks directly to the reader
  };
  ```
</CodeGroup>

#### Content Type

Choose between article-style content or landing page copy:

<CodeGroup>
  ```python Python theme={null}
  payload = {
      "keyword": "project management tool",
      "language_code": "en",
      "location_name": "United States",
      "content_type": "landing_page",
  }
  ```

  ```javascript JavaScript theme={null}
  const payload = {
    keyword: "project management tool",
    language_code: "en",
    location_name: "United States",
    content_type: "landing_page",
  };
  ```
</CodeGroup>

#### Additional Context

Steer the AI with specific instructions:

<CodeGroup>
  ```python Python theme={null}
  payload = {
      "keyword": "email marketing tips",
      "language_code": "en",
      "location_name": "United States",
      "additional_insights": "Focus on e-commerce businesses. Include real-world case studies.",
  }
  ```

  ```javascript JavaScript theme={null}
  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.",
  };
  ```
</CodeGroup>

### Getting Available Options

Retrieve all available options before creating an order:

<CodeGroup>
  ```python Python theme={null}
  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"]])
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

### Retrieving Results

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

<CodeGroup>
  ```python Python theme={null}
  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"])
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

### Complete Example

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

<CodeGroup>
  ```python Python theme={null}
  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)")
  ```

  ```javascript JavaScript theme={null}
  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)`);
  })();
  ```
</CodeGroup>