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

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

Example Request

fetch("https://koala.sh/api/articles/", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    targetKeyword: "can you eat watermelon seeds?",
    gptVersion: "gpt-4o",
    integrationId: "329cf56d-5409-43f3-b7fc-9cb64d725f6c",
  }),
});

Example Response

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

Parameters

Below is a full list of available parameters. Only the targetKeyword is required.

Checking Article Status

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

This endpoint is used to check the status of an article and to get the HTML (if it is finished).

Example Response (Completed Article)

{
  "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><h2>Introduction</h2><p>Great Danes are one of the largest dog breeds in the world, known for their majestic appearance and gentle nature...",
    "polishedHtml": null
  }
}

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

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: The article is queued
• processing: The article is being written
• finished: The article is finished 🎉
• failed: An error occurred and we could not finish writing the article

Complete Example

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

    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 articleFinished = false;
    let article = null;

    while (!articleFinished) {
      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 article status: ${statusResponse.status}`);
      }

      article = await statusResponse.json();
      
      if (article.status === "finished") {
        articleFinished = true;
        console.log("Article is complete!");
      } else if (article.status === "failed") {
        throw new Error(`Article failed: ${article.error}`);
      } else {
        console.log(`Article status: ${article.status} - ${article.statusDetail || "In progress"} (${Math.round(article.progress * 100)}%)`);
        // Wait 5 seconds before checking again
        await new Promise(resolve => setTimeout(resolve, 5000));
      }
    }

    // Step 3: Use the completed article
    console.log("Article HTML:", article.output.html);
    return article;
  } catch (error) {
    console.error("Error:", error);
    return null;
  }
}

// Example usage
createAndWaitForArticle("best hiking trails in colorado");

Error Handling

The API will return appropriate HTTP status codes for different error conditions:

• 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.