Quickstart

Before you begin#

• An Autoranko account with a WordPress site connected through the plugin (see WordPress integration).
• For the last step, publishing permission on that site: wp_connected must be true. Without it you still get the full draft, you just can't publish it from the API.
• An article left in the site's allowance: 3 in total on Free, 8 a month on Starter, 30 a month on Pro. A job uses one as soon as it's created; jobs that fail give it back.

1. 1Step 1: Create a token

   In Dashboard → API, create a token and copy it; it's shown only once. Keep it in an environment variable.

   ShellCopy

   export AUTORANKO_TOKEN="ar_live_…"

2. 2Step 2: Find your site ID

   Sites are the WordPress installs connected to your account. Note the id, and check wp_connected: it must be true for publishing.

   cURLNode.jsPythonPHP

   Copy

   curl https://autoranko.com/api/public/v1/sites \
     -H "Authorization: Bearer $AUTORANKO_TOKEN"

   Example response · 200 OKCopy

   {
     "sites": [
       {
         "id": "1",
         "site_url": "https://demo.autoranko.com",
         "site_name": "Autoranko Demo Site",
         "domain": "demo.autoranko.com",
         "plan": "pro",
         "is_active": true,
         "wp_connected": false,
         "created_at": "2026-10-25T19:57:53.200Z"
       }
     ]
   }

3. 3Step 3: Create a job

   Send a topic and, optionally, a target keyword (replace 1 with your site ID). The job is created in pending and starts generating right away. Keep the returned id.

   cURLNode.jsPythonPHP

   Copy

   curl -X POST https://autoranko.com/api/public/v1/sites/1/jobs \
     -H "Authorization: Bearer $AUTORANKO_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "topic": "How to winterize a sprinkler system before the first freeze",
       "target_keyword": "winterize sprinkler system"
     }'

   Example response · 201 CreatedCopy

   {
     "job": {
       "id": "3",
       "site_id": "1",
       "topic": "How to winterize a sprinkler system before the first freeze",
       "target_keyword": "winterize sprinkler system",
       "status": "pending",
       "article_title": null,
       "meta_description": null,
       "wp_post_id": null,
       "auto_publish": false,
       "scheduled_for": null,
       "created_at": "2026-10-25T20:10:51.035Z"
     }
   }

   There's no idempotency key. If a create request times out, check GET /sites/{id}/jobs before retrying, or you may generate the same article twice and use up allowance for it.

4. 4Step 4: Wait for the draft

   Generation takes a few minutes. Poll the job (replace 3 with your job's id) every 15–30 seconds until status is review (or failed), or subscribe to the job.review webhook instead. The draft is in article_html.

   cURLNode.jsPythonPHP

   Copy

   curl https://autoranko.com/api/public/v1/jobs/3 \
     -H "Authorization: Bearer $AUTORANKO_TOKEN"

   Example response · 200 OKCopy

   {
     "job": {
       "id": "3",
       "site_id": "1",
       "topic": "How to winterize a sprinkler system before the first freeze",
       "target_keyword": "winterize sprinkler system",
       "status": "review",
       "article_title": "How to Winterize a Sprinkler System Before the First Freeze",
       "meta_description": "Learn how to winterize a sprinkler system before the first freeze, with steps for shutting off water, draining lines and protecting equipment.",
       "wp_post_id": null,
       "auto_publish": false,
       "scheduled_for": null,
       "error": "Publishing failed: WordPress publishing is not authorized for this site.",
       "outline": {
         "title": "How to Winterize a Sprinkler System Before the First Freeze",
         "meta_description": "Learn how to winterize a sprinkler system before the first freeze, with steps for shutting off water, draining lines and protecting equipment.",
         "slug": "winterize-sprinkler-system",
         "target_keyword": "winterize sprinkler system",
         "secondary_keywords": [
           "sprinkler blowout",
           "drain irrigation lines",
           "insulate backflow preventer"
         ],
         "sections": [
           {
             "level": "h2",
             "heading": "Why winterizing your sprinkler system matters",
             "description": "How trapped water freezes, expands and cracks pipes, fittings and valves.",
             "word_count": 220
           },
           {
             "level": "h2",
             "heading": "Step 1: Shut off the water supply",
             "description": "Find the main shut-off valve and protect it from freezing.",
             "word_count": 180
           }
         ],
         "faqs": [
           {
             "question": "When should I winterize my sprinkler system?",
             "answer_brief": "Before the first hard freeze, once nights approach 32 °F (0 °C)."
           }
         ],
         "image_suggestions": [
           {
             "description": "Homeowner blowing out sprinkler lines with an air compressor in autumn",
             "alt_text": "Blowing out sprinkler lines with an air compressor"
           }
         ],
         "google_image_queries": [
           "sprinkler system blowout"
         ],
         "video_query": "how to winterize a sprinkler system"
       },
       "article_html": "<h2>Why winterizing your sprinkler system matters</h2>\n<p>Water left inside an irrigation system can freeze and expand, cracking pipes, splitting fittings, or damaging valves. Exposed backflow preventers are especially vulnerable because they lack the protection that soil provides to buried components.</p>\n<!-- … shortened for the docs … -->",
       "created_at": "2026-10-25T20:10:51.035Z",
       "updated_at": "2026-10-25T20:42:05.140Z"
     }
   }

   Skip the polling with a webhook

   Add an endpoint in Dashboard → API and Autoranko sends job.review the moment the draft is ready, so you don't need to poll at all. Set up webhooks.

   job.review payloadCopy

   {
     "event": "job.review",
     "created_at": "2026-10-25T20:13:48.902Z",
     "data": {
       "id": "3",
       "site_id": "1",
       "topic": "How to winterize a sprinkler system before the first freeze",
       "target_keyword": "winterize sprinkler system",
       "status": "review",
       "article_title": "How to Winterize a Sprinkler System Before the First Freeze",
       "meta_description": "Learn how to winterize a sprinkler system before the first freeze, with steps for shutting off water, draining lines and protecting equipment.",
       "wp_post_id": null
     }
   }

5. 5Step 5: Publish it

   Approving the job publishes it to WordPress as a live post. The job moves to publishing, then to published with the new wp_post_id, and job.published fires.

   cURLNode.jsPythonPHP

   Copy

   curl -X POST https://autoranko.com/api/public/v1/jobs/3/publish \
     -H "Authorization: Bearer $AUTORANKO_TOKEN"

   Example response · 200 OKCopy

   {
     "ok": true,
     "status": "publishing"
   }

   Confirm it's live

   Poll GET /jobs/{id} until status is published; wp_post_id is then the new WordPress post (or wait for job.published, which also carries the post URL). If WordPress rejected the post, the job is back in review and error says why: fix it and publish again.

The whole flow in one script#

The same steps as one program: create the job, poll every 15 seconds until the draft is ready, then publish it. Replace 1 with your site ID.

const API = "https://autoranko.com/api/public/v1";
const headers = {
  Authorization: `Bearer ${process.env.AUTORANKO_TOKEN}`,
  "Content-Type": "application/json",
};

async function call(method, path, body) {
  const res = await fetch(API + path, { method, headers, body: body && JSON.stringify(body) });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
  return data;
}

// 1. Create the job (site 1; find yours with GET /sites)
let { job } = await call("POST", "/sites/1/jobs", {
  topic: "How to winterize a sprinkler system before the first freeze",
  target_keyword: "winterize sprinkler system",
});

// 2. Wait for the draft
while (job.status === "pending" || job.status === "generating") {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  ({ job } = await call("GET", `/jobs/${job.id}`));
}
if (job.status !== "review") throw new Error(`Job ${job.id} is ${job.status}: ${job.error}`);

// 3. Approve: publish to WordPress
await call("POST", `/jobs/${job.id}/publish`);
console.log(`Publishing job ${job.id}: ${job.article_title}`);

import os
import time

import requests

API = "https://autoranko.com/api/public/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['AUTORANKO_TOKEN']}"


def call(method, path, body=None):
    res = session.request(method, API + path, json=body, timeout=30)
    data = res.json()
    if not res.ok:
        raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
    return data


# 1. Create the job (site 1; find yours with GET /sites)
job = call("POST", "/sites/1/jobs", {
    "topic": "How to winterize a sprinkler system before the first freeze",
    "target_keyword": "winterize sprinkler system",
})["job"]

# 2. Wait for the draft
while job["status"] in ("pending", "generating"):
    time.sleep(15)
    job = call("GET", f"/jobs/{job['id']}")["job"]
if job["status"] != "review":
    raise RuntimeError(f"Job {job['id']} is {job['status']}: {job.get('error')}")

# 3. Approve: publish to WordPress
call("POST", f"/jobs/{job['id']}/publish")
print(f"Publishing job {job['id']}: {job['article_title']}")

<?php
function autoranko(string $method, string $path, ?array $body = null): array
{
    $ch = curl_init('https://autoranko.com/api/public/v1' . $path);
    $options = [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('AUTORANKO_TOKEN'),
            'Content-Type: application/json',
        ],
    ];
    if ($method !== 'GET') {
        $options[CURLOPT_POSTFIELDS] = $body === null ? '' : json_encode($body);
    }
    curl_setopt_array($ch, $options);
    $data = json_decode(curl_exec($ch), true);
    if (isset($data['error'])) throw new RuntimeException($data['error']['message']);
    return $data;
}

// 1. Create the job (site 1; find yours with GET /sites)
$job = autoranko('POST', '/sites/1/jobs', [
    'topic' => 'How to winterize a sprinkler system before the first freeze',
    'target_keyword' => 'winterize sprinkler system',
])['job'];

// 2. Wait for the draft
while (in_array($job['status'], ['pending', 'generating'], true)) {
    sleep(15);
    $job = autoranko('GET', "/jobs/{$job['id']}")['job'];
}
if ($job['status'] !== 'review') {
    throw new RuntimeException("Job {$job['id']} is {$job['status']}: {$job['error']}");
}

// 3. Approve: publish to WordPress
autoranko('POST', "/jobs/{$job['id']}/publish");
echo "Publishing job {$job['id']}: {$job['article_title']}\n";

Generation usually takes a few minutes. If the job ends in failed the script stops with the reason, and that job doesn't count toward the allowance.

Job lifecycle#

Every job follows one of these routes. auto_publish decides whether it stops in review for you or goes straight to WordPress; the webhook badges show which event fires as the job enters a status.

1. Review first

   auto_publish off (the default). The draft waits in review until you call POST /jobs/{id}/publish.

   1. pending
   2. generating
   3. reviewfires job.review
   4. publishing
   5. publishedfires job.published

2. Autopilot

   auto_publish on and WordPress connected (wp_connected: true). Without the connection the job stops in review.

   1. pending
   2. generating
   3. publishing
   4. publishedfires job.published

3. Generation fails

   error says why. Failed jobs don't count toward the allowance; create a new job to try again.

   1. pending
   2. generating
   3. failedfires job.failed

4. WordPress rejects the post

   The job returns to review with error set (Publishing failed: …). Fix the cause, then publish again.

   1. publishing
   2. reviewfires job.review
   3. publishing

5. Stuck job recovered

   Still generating after an hour (a server restart, say): reset to pending and retried automatically.

   1. generating
   2. pending
   3. generating

Next steps#

• WebhooksGet told when drafts are ready instead of polling.
• Errors & rate limitsHandle every error code and retry safely.
• Generation jobs referenceScheduling, auto-publish and every field.
• Keyword researchPick topics with volume and difficulty estimates.