Quickstart

This 5-minute walkthrough takes you from a fresh account to your first AI-generated SEO article via the AutoRanq API. By the end you’ll have:

• An API key (test mode)
• A project to organize your work
• A generated article you can read, edit, or publish

Note

All endpoints below use the base URL https://api.autoranq.ai/api/public/v1. Test-mode keys (prefix ar_test_) are safe to use against real endpoints — they create real resources but won’t be billed.

Before you start

You need:

• An AutoRanq account (sign up at autoranq.ai)
• A terminal with curl, OR Node 18+ / Python 3.9+ if you prefer those
• Five uninterrupted minutes

Step 1: Create an API key

1. Open the dashboard at app.autoranq.ai and go to Settings → API.

2. Create a key with scope read,write. Pick test mode for this walkthrough (your key starts with ar_test_).

3. Copy the key now — it’s shown only once. Paste it into your terminal:

   export AUTORANQ_KEY="ar_test_paste_your_key_here"

Tip

Lost your key? You can create a new one or rotate an existing key in Settings → API at any time.

Step 2: Find your project ID

You need a project_id to generate articles. List your projects:

curl

curl https://api.autoranq.ai/api/public/v1/projects \
  -H "Authorization: Bearer $AUTORANQ_KEY"

JavaScript

const response = await fetch(
  'https://api.autoranq.ai/api/public/v1/projects',
  { headers: { Authorization: `Bearer ${process.env.AUTORANQ_KEY}` } }
);
const { data } = await response.json();
console.log(data);

Python

import os, requests

response = requests.get(
    "https://api.autoranq.ai/api/public/v1/projects",
    headers={"Authorization": f"Bearer {os.environ['AUTORANQ_KEY']}"},
)
print(response.json())

Copy a project_id from the response — it looks like clxabc123def456ghi789. Export it:

export PROJECT_ID="clxabc123def456ghi789"

Tip

Don’t have a project yet? Create one in the dashboard at Projects → New project, or via POST /projects with { "name": "My first project", "domain": "example.com" }.

Step 3: Generate your first article

Fire a generation job for the keyword "how to start a blog":

curl

curl -X POST https://api.autoranq.ai/api/public/v1/generate \
  -H "Authorization: Bearer $AUTORANQ_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"project_id\": \"$PROJECT_ID\",
    \"keyword\": \"how to start a blog\"
  }"

JavaScript

const response = await fetch(
  'https://api.autoranq.ai/api/public/v1/generate',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.AUTORANQ_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      project_id: process.env.PROJECT_ID,
      keyword: 'how to start a blog',
    }),
  }
);
const { data } = await response.json();
console.log('generation_id:', data.generation_id);

Python

import os, requests

response = requests.post(
    "https://api.autoranq.ai/api/public/v1/generate",
    headers={
        "Authorization": f"Bearer {os.environ['AUTORANQ_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "project_id": os.environ["PROJECT_ID"],
        "keyword": "how to start a blog",
    },
)
print("generation_id:", response.json()["data"]["generation_id"])

The response includes a generation_id. Save it:

export GEN_ID="clxgen123def456ghi789"  # paste from response

Step 4: Watch the generation finish

Generation takes 30-90 seconds depending on the recipe. Poll the status endpoint:

curl

# Poll every 5 seconds until status is COMPLETED or FAILED
while true; do
  status=$(curl -s https://api.autoranq.ai/api/public/v1/generations/$GEN_ID \
    -H "Authorization: Bearer $AUTORANQ_KEY" | jq -r '.data.status')
  echo "$(date +%T) — $status"
  [[ "$status" == "COMPLETED" || "$status" == "FAILED" ]] && break
  sleep 5
done

JavaScript

while (true) {
  const res = await fetch(
    `https://api.autoranq.ai/api/public/v1/generations/${process.env.GEN_ID}`,
    { headers: { Authorization: `Bearer ${process.env.AUTORANQ_KEY}` } }
  );
  const { data } = await res.json();
  console.log(new Date().toLocaleTimeString(), '—', data.status);
  if (data.status === 'COMPLETED' || data.status === 'FAILED') break;
  await new Promise(r => setTimeout(r, 5000));
}

Python

import os, time, requests
from datetime import datetime

while True:
    res = requests.get(
        f"https://api.autoranq.ai/api/public/v1/generations/{os.environ['GEN_ID']}",
        headers={"Authorization": f"Bearer {os.environ['AUTORANQ_KEY']}"},
    )
    status = res.json()["data"]["status"]
    print(datetime.now().strftime("%H:%M:%S"), "—", status)
    if status in ("COMPLETED", "FAILED"):
        break
    time.sleep(5)

Don't want to poll?

Skip the loop entirely — set up a webhook to be notified when generation finishes. We push you a signed POST the moment status flips to COMPLETED.

Step 5: Read the article

Once status is COMPLETED, the generation contains an article_id. Fetch the article:

curl

article_id=$(curl -s https://api.autoranq.ai/api/public/v1/generations/$GEN_ID \
  -H "Authorization: Bearer $AUTORANQ_KEY" | jq -r '.data.article_id')

curl https://api.autoranq.ai/api/public/v1/articles/$article_id \
  -H "Authorization: Bearer $AUTORANQ_KEY"

JavaScript

const gen = await fetch(
  `https://api.autoranq.ai/api/public/v1/generations/${process.env.GEN_ID}`,
  { headers: { Authorization: `Bearer ${process.env.AUTORANQ_KEY}` } }
).then(r => r.json());

const article = await fetch(
  `https://api.autoranq.ai/api/public/v1/articles/${gen.data.article_id}`,
  { headers: { Authorization: `Bearer ${process.env.AUTORANQ_KEY}` } }
).then(r => r.json());

console.log(article.data.title);
console.log(article.data.content_html.slice(0, 500));

Python

import os, requests

gen = requests.get(
    f"https://api.autoranq.ai/api/public/v1/generations/{os.environ['GEN_ID']}",
    headers={"Authorization": f"Bearer {os.environ['AUTORANQ_KEY']}"},
).json()

article = requests.get(
    f"https://api.autoranq.ai/api/public/v1/articles/{gen['data']['article_id']}",
    headers={"Authorization": f"Bearer {os.environ['AUTORANQ_KEY']}"},
).json()

print(article["data"]["title"])
print(article["data"]["content_html"][:500])

You’ll get back the full article: title, content HTML, meta description, SEO fields, and FAQ section.

What you just built

In ~5 minutes you went from no integration to a programmatic SEO-content pipeline. Real-world usage looks like:

Trigger from your CMS

POST to /generate whenever editors mark a keyword as “ready”. Webhook notifies your CMS when the draft is done.

Bulk-generate from a sheet

Loop through a list of keywords with 100ms throttling — well under the 1000 req/hour rate limit.

Publish to WordPress

Pull content_html after generation, push to WP REST API. ~10 lines of code.

Next steps

• Authentication — production keys, scopes, rotating compromised keys
• Webhooks — stop polling, get pushed events with HMAC signatures
• CLI — same workflow without writing fetch boilerplate (coming in Phase 3)
• API Reference — full endpoint catalog (coming in v2)