API Documentation

The Koala AI API allows you to easily generate SEO-optimized articles, AI images, internal links, and more! All paid plans can use our API and there are no additional costs!

Authentication

You will need an API key, which requires an active paid subscription. Plans start at $49/month.

Getting Your API Key

1. If you don't already have an account then first Register.
2. Sign up for a paid plan.
3. Once you have an active plan visit your Account page.
4. Click the Add API Key button to create an API key.
5. Copy the value of the created key, it will look like this: a0ce8c2f-60ad-4edc-89eb-bd6da042e572

Making a Request

Every Koala API uses the same base URL and authentication header:

• Base URL: https://koala.sh/api/
• Authentication: Authorization: Bearer YOUR_API_KEY
• Content-Type: application/json for all requests with a JSON body.

Our APIs

Custom Webhooks

Connect a custom CMS or any glue tool (Zapier, Make, your own backend) by creating a Custom Webhook integration on your Account page. Link it to a brand or pass its ID as integrationId in API calls, and every completed article POSTs to your endpoint. It replaces the deprecated webhookUrl parameter.

Payload

POST <your endpoint>
Content-Type: application/json
User-Agent: KoalaAI-Webhook/1.0
X-Koala-Event: article.completed
X-Koala-Delivery-Id: <uuid>            (same value on every retry)
X-Koala-Signature: sha256=<hex HMAC>   (only when a signing secret is set)

{
  "event": "article.completed",
  "articleId": "1b2c3d4e-...",
  "title": "The Article Title",
  "targetKeyword": "target keyword",
  "content": "<p>Full article HTML, without the H1...</p>"
}

Discord webhook URLs are recognized automatically and receive a chat message in place of the payload above: the article title and a link to it. Discord reads content as the message body and caps it at 2000 characters, so the full article cannot be delivered there.

A response with a 2xx status counts as delivered. Each attempt times out after 10 seconds, and a delivery is tried up to 3 times when the endpoint cannot be reached or answers 5xx, waiting 1 then 3 seconds between attempts. A 4xx is taken as a decision and is never retried. Retries reuse the same X-Koala-Delivery-Id, so an endpoint that processed an article and then failed to answer can recognize the repeat and ignore it. Respond fast and do the work asynchronously. All deliveries (tests included) are sent through Koala AI's proxy and arrive from a stable source IP: 24.144.68.208. Add it to your allow-list if your endpoint restricts callers.

Verifying the signature

When your integration has a signing secret, every request carries X-Koala-Signature: the string sha256= followed by a hex-encoded HMAC-SHA256 of the raw request body, keyed with your secret. Compute the same HMAC over the exact bytes you received (before any JSON parsing or re-serialization) and compare with a constant-time comparison:

// Node.js example
const crypto = require("crypto");

function verifyKoalaSignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader?.startsWith("sha256=")) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  const received = signatureHeader.slice("sha256=".length);
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(
      Buffer.from(received, "hex"),
      Buffer.from(expected, "hex")
    )
  );
}

Testing your endpoint

Use the test button on the integration's row on your Account page. It sends a sample payload with "event": "article.test" through the exact delivery path a real article takes, same headers and same signature, and shows you the HTTP status your endpoint returned. Test sends are rate limited (a handful per minute, 20 per hour), and your handler can key on the event field to keep test deliveries out of production processing.

Need Help?

If you have any questions about our API or need assistance with integration, please don't hesitate to contact our support team.