KoalaWriter API

The KoalaWriter API is the best API for creating SEO-optimized articles. It is billed based on the number of words generated, the same as if you were using KoalaWriter manually. All paid plans can use this API with no additional costs.

How It Works

The KoalaWriter API is asynchronous, meaning the article is created in the background. The process works as follows:

1. Make an API call to queue an article for writing
2. Call the API to check the status of the article
3. Once the status is finished, access the full HTML of the completed article

When an article is completed, it is automatically saved to your account so you can also access it there.

You can specify an integrationId so that when the article is completed it will automatically be created as a draft in WordPress, Shopify, Webflow, etc! Webhooks are also supported by specifying the webhookUrl parameter.

If you are just wanting to do bulk writing, please check out the Bulk Mode in KoalaWriter.

Endpoints

Creating an Article (v2)

POST https://koala.sh/api/articles/v2/

The v2 endpoint uses a new generation engine for higher quality articles. For the legacy v1 engine, use /api/articles/ instead — see the Legacy v1 section below.

Example Request (v2)

fetch("https://koala.sh/api/articles/v2/", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetKeyword: "can you eat watermelon seeds?",
    gptVersion: "gpt-5.2",
    realTimeData: true,
    shouldCiteSources: true,
    multimediaOption: "images",
    imageStyle: "photo",
    brandId: "your-brand-uuid",
    brandMentionLevel: "subtle",
    articleInstructions: "Focus on health benefits. Write from a nutritionist's perspective.",
  }),
});

Example Response

{"articleId": "7b53671d-da26-4ab1-b096-6e014125f712"}

Parameters

Below is a full list of parameters for the v2 endpoint. Only the targetKeyword is required.

Checking Article Status

GET https://koala.sh/api/articles/{article_id}

Check the status of an article and retrieve the HTML when finished.

Example Response (Completed)

{
  "config": {
    "targetKeyword": "are great danes good pets?"
  },
  "status": "finished",
  "statusDetail": "Finished article",
  "updatedAt": 1683095362612,
  "progress": 1,
  "error": null,
  "output": {
    "html": "<h1>Are Great Danes Good Pets? Pros and Cons You Need to Know</h1>...",
    "polishedHtml": null
  }
}

polishedHtml will be null unless autoPolish was set to true or the article was manually polished.

Example Response (In Progress)

{
  "config": {
    "targetKeyword": "are great danes good pets?"
  },
  "status": "processing",
  "statusDetail": "Writing section 3",
  "updatedAt": 1683095271489,
  "progress": 0.33,
  "error": null
}

Status Values

• queued: Article is queued
• processing: Article is being written
• finished: Article is finished
• failed: An error occurred

Complete Example

async function createAndWaitForArticle(keyword) {
  try {
    // Step 1: Create the article
    const createResponse = await fetch("https://koala.sh/api/articles/v2/", {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        targetKeyword: keyword,
        gptVersion: "gpt-5.2",
        realTimeData: true,
        shouldCiteSources: true,
      }),
    });

    if (!createResponse.ok) {
      throw new Error(`Failed to create article: ${createResponse.status}`);
    }

    const { articleId } = await createResponse.json();
    console.log(`Article created with ID: ${articleId}`);

    // Step 2: Poll for article status
    let article = null;

    while (true) {
      const statusResponse = await fetch(
        `https://koala.sh/api/articles/${articleId}`,
        {
          headers: { Authorization: "Bearer YOUR_API_KEY" },
        }
      );

      if (!statusResponse.ok) {
        throw new Error(`Failed to check status: ${statusResponse.status}`);
      }

      article = await statusResponse.json();

      if (article.status === "finished") {
        console.log("Article is complete!");
        break;
      } else if (article.status === "failed") {
        throw new Error(`Article failed: ${article.error}`);
      }

      console.log(`${article.status} - ${article.statusDetail || "In progress"} (${Math.round(article.progress * 100)}%)`);
      await new Promise(resolve => setTimeout(resolve, 5000));
    }

    console.log("Article HTML:", article.output.html);
    return article;
  } catch (error) {
    console.error("Error:", error);
    return null;
  }
}

createAndWaitForArticle("best hiking trails in colorado");

Error Handling

• 400 Bad Request: Invalid parameters or request format
• 401 Unauthorized: Invalid or missing API key
• 500 Internal Server Error: Server-side error

Need Help?

If you need additional assistance with the KoalaWriter API, please contact us.