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

> Generate AI-powered content briefs, retrieve SERP analysis, and create outlines via the API

Generate comprehensive content briefs with SERP-based headings, AI title/description suggestions, and word count benchmarks — all programmatically.

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

### Quick Start

Create a content brief for a target keyword:

<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": "en",
      "location": "United States",
      "folder_id": "<your_folder_id>",
  }

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

  data = response.json()
  print(data)
  # {"status": true, "payload": {"id": "339ca10b-...", "status": true, "cost": 500}}
  ```

  ```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: "en",
    location: "United States",
    folder_id: "<your_folder_id>",
  };

  const response = await fetch(`${BASE_URL}/api/content-brief/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": "339ca10b-...", "status": true, "cost": 500}}
  ```
</CodeGroup>

### Endpoints

| Method | Path                                                                       | Description                 |
| ------ | -------------------------------------------------------------------------- | --------------------------- |
| POST   | `/api/content-brief/order/`                                                | Create a content brief      |
| GET    | `/api/content-brief/order/?id={id}`                                        | Get brief results           |
| DELETE | `/api/content-brief/order/?ids={id1}&ids={id2}`                            | Delete briefs               |
| GET    | `/api/content-brief/orders/?page=1&page_size=10`                           | List all briefs (paginated) |
| GET    | `/api/content-brief/languages/`                                            | Supported languages         |
| POST   | `/api/content-brief/order/{order_id}/outline/`                             | Generate AI outline         |
| GET    | `/api/content-brief/order/{order_id}/outline/?auto_generate_order_id={id}` | Get AI outline results      |

### Parameters

#### Create Brief — Required

| Parameter   | Type   | Description                                                                                      |
| ----------- | ------ | ------------------------------------------------------------------------------------------------ |
| `keyword`   | string | Target keyword or topic                                                                          |
| `language`  | string | Language code (e.g. `en`). See `/api/content-brief/languages/`                                   |
| `location`  | string | Location name (e.g. `United States`). See `/api/keywords-insights/locations/`                    |
| `folder_id` | string | Dashboard folder ID to save the project into. Retrieve from the browser URL in the KWI dashboard |

### Retrieving Results

Content briefs process asynchronously. Poll the results endpoint until the data is ready:

<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 = "339ca10b-80c1-4248-b8d0-c11377c204c7"

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

      data = response.json()["result"]["payload"]

      if data["status"]:
          break

      print("Processing...")
      time.sleep(15)

  # Brief is ready
  print(f"Keyword: {data['keyword']}")
  print(f"Avg word count: {data['word_count_avg']}")
  print(f"Recommended: {data['word_count_min']}–{data['word_count_max']} words")
  print(f"Pages analyzed: {data['pages_count']}")
  print(f"Headings found: {data['headings_count']}")
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = process.env.KWI_API_KEY;
  const BASE_URL = "https://api.keywordinsights.ai";

  const order_id = "339ca10b-80c1-4248-b8d0-c11377c204c7";

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

    const json = await response.json();
    data = json.result.payload;

    if (data.status) {
      break;
    }

    console.log("Processing...");
    await new Promise((r) => setTimeout(r, 15000));
  }

  // Brief is ready
  console.log(`Keyword: ${data.keyword}`);
  console.log(`Avg word count: ${data.word_count_avg}`);
  console.log(`Recommended: ${data.word_count_min}–${data.word_count_max} words`);
  console.log(`Pages analyzed: ${data.pages_count}`);
  console.log(`Headings found: ${data.headings_count}`);
  ```
</CodeGroup>

The results include:

| Field                               | Description                                                            |
| ----------------------------------- | ---------------------------------------------------------------------- |
| `raw`                               | SERP page structures with headings, bullet points, and content weights |
| `brief_title_suggests`              | AI-generated meta title suggestions                                    |
| `brief_description_suggests`        | AI-generated meta description suggestions                              |
| `word_count_avg`                    | Average word count across top-ranking pages                            |
| `word_count_min` / `word_count_max` | Recommended word count range                                           |
| `pages_count`                       | Number of SERP pages analyzed                                          |
| `headings_count`                    | Total headings scraped from top results                                |
| `processing_status`                 | Status of each processing stage                                        |

### Generating an AI Outline

After a content brief is complete, you can generate an AI-powered outline:

<CodeGroup>
  ```python Python theme={null}
  # Step 1: Trigger outline generation
  response = requests.post(
      f"{BASE_URL}/api/content-brief/order/{order_id}/outline/",
      headers=HEADERS,
      json={"additional_context": "Focus on B2B companies"},  # optional
  )

  auto_id = response.json()["result"]["payload"]["auto_generate_order_id"]

  # Step 2: Poll until outline is ready
  while True:
      response = requests.get(
          f"{BASE_URL}/api/content-brief/order/{order_id}/outline/",
          headers=HEADERS,
          params={"auto_generate_order_id": auto_id},
      )

      data = response.json()["result"]["payload"]

      if data["status"]:
          break

      time.sleep(10)

  print(data["string"])  # Full outline as text
  ```

  ```javascript JavaScript theme={null}
  // Step 1: Trigger outline generation
  const response = await fetch(`${BASE_URL}/api/content-brief/order/${order_id}/outline/`, {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ additional_context: "Focus on B2B companies" }), // optional
  });

  const json = await response.json();
  const auto_id = json.result.payload.auto_generate_order_id;

  // Step 2: Poll until outline is ready
  let data;
  while (true) {
    const response = await fetch(
      `${BASE_URL}/api/content-brief/order/${order_id}/outline/?auto_generate_order_id=${auto_id}`,
      {
        headers: { "X-API-Key": API_KEY },
      }
    );

    const json = await response.json();
    data = json.result.payload;

    if (data.status) {
      break;
    }

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

  console.log(data.string); // Full outline as text
  ```
</CodeGroup>

### Listing Briefs

Retrieve a paginated list of all your content briefs:

<CodeGroup>
  ```python Python theme={null}
  response = requests.get(
      f"{BASE_URL}/api/content-brief/orders/",
      headers=HEADERS,
      params={"page": 1, "page_size": 20},
  )

  data = response.json()["result"]["payload"]
  print(f"Total briefs: {data['total_orders']}")

  for brief in data["orders"]:
      print(f"  {brief['keyword']} — {brief['status']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`${BASE_URL}/api/content-brief/orders/?page=1&page_size=20`, {
    headers: { "X-API-Key": API_KEY },
  });

  const json = await response.json();
  const data = json.result.payload;
  console.log(`Total briefs: ${data.total_orders}`);

  for (const brief of data.orders) {
    console.log(`  ${brief.keyword} — ${brief.status}`);
  }
  ```
</CodeGroup>

### Complete Example

End-to-end: create a content brief, wait for results, then generate an AI outline.

<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_brief(keyword, language="en", location="United States"):
      """Create a content brief order."""
      response = requests.post(
          f"{BASE_URL}/api/content-brief/order/",
          headers=HEADERS,
          json={"keyword": keyword, "language": language, "location": location, "folder_id": "<your_folder_id>"},
      )
      response.raise_for_status()
      return response.json()["result"]["payload"]


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

          if data["status"]:
              return data

          print("Brief processing...")
          time.sleep(15)


  def generate_outline(order_id, context=""):
      """Trigger AI outline generation and wait for results."""
      response = requests.post(
          f"{BASE_URL}/api/content-brief/order/{order_id}/outline/",
          headers=HEADERS,
          json={"additional_context": context},
      )
      auto_id = response.json()["result"]["payload"]["auto_generate_order_id"]

      while True:
          response = requests.get(
              f"{BASE_URL}/api/content-brief/order/{order_id}/outline/",
              headers=HEADERS,
              params={"auto_generate_order_id": auto_id},
          )
          data = response.json()["result"]["payload"]

          if data["status"]:
              return data

          time.sleep(10)


  # --- Run ---

  result = create_brief("best project management tools")
  order_id = result["id"]
  print(f"Brief created: {order_id} (cost: {result['cost']} credits)")

  brief = wait_for_brief(order_id)
  print(f"Target: {brief['word_count_min']}–{brief['word_count_max']} words")
  print(f"Title suggestions: {brief['brief_title_suggests']}")

  outline = generate_outline(order_id, context="Focus on remote teams")
  print(f"\nAI Outline:\n{outline['string']}")
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = process.env.KWI_API_KEY;
  const BASE_URL = "https://api.keywordinsights.ai";

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

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

      if (data.status) {
        return data;
      }

      console.log("Brief processing...");
      await new Promise((r) => setTimeout(r, 15000));
    }
  }

  async function generateOutline(orderId, context = "") {
    const response = await fetch(`${BASE_URL}/api/content-brief/order/${orderId}/outline/`, {
      method: "POST",
      headers: {
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ additional_context: context }),
    });
    const json = await response.json();
    const autoId = json.result.payload.auto_generate_order_id;

    while (true) {
      const response = await fetch(
        `${BASE_URL}/api/content-brief/order/${orderId}/outline/?auto_generate_order_id=${autoId}`,
        {
          headers: { "X-API-Key": API_KEY },
        }
      );
      const json = await response.json();
      const data = json.result.payload;

      if (data.status) {
        return data;
      }

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

  // --- Run ---
  (async () => {
    const result = await createBrief("best project management tools");
    const orderId = result.id;
    console.log(`Brief created: ${orderId} (cost: ${result.cost} credits)`);

    const brief = await waitForBrief(orderId);
    console.log(`Target: ${brief.word_count_min}–${brief.word_count_max} words`);
    console.log(`Title suggestions: ${brief.brief_title_suggests}`);

    const outline = await generateOutline(orderId, "Focus on remote teams");
    console.log(`\nAI Outline:\n${outline.string}`);
  })();
  ```
</CodeGroup>