Ranklify API

https://www.getranklify.com/api/v1

Authorization: Bearer lfy_your_token_here

curl -X POST https://www.getranklify.com/api/v1/generate \
  -H "Authorization: Bearer lfy_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Stainless Steel Pour-Over Kettle",
    "features": "Gooseneck spout, 1L, food-grade steel, keeps heat",
    "platform": "amazon",
    "tone": "Professional"
  }'

// 202 Accepted — job queued
{
  "api_version": "v1",
  "job_id": "9f3c1a2b-...",
  "status": "queued",
  "platform": "woocommerce",
  "external_ref": "4471",
  "brand_id": "a9d4...",
  "poll_url": "/api/v1/jobs/9f3c1a2b-...",
  "poll_after_ms": 3000,
  "usage": { "used": 12, "limit": 100, "plan": "pro" }
}

// 200 OK — a later poll, once generation finished
{
  "api_version": "v1",
  "job_id": "9f3c1a2b-...",
  "status": "complete",
  "platform": "woocommerce",
  "external_ref": "4471",
  "listing": { "title": "...", "bullets": ["..."], "focus_keyphrase": "...", "...": "..." },
  "listing_id": "b1c2..."
}

# 1. Queue the job — returns immediately
curl -X POST https://www.getranklify.com/api/v1/jobs \
  -H "Authorization: Bearer lfy_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-4471-run1" \
  -d '{
    "product_name": "Stainless Steel Pour-Over Kettle",
    "features": "Gooseneck spout, 1L, food-grade steel, keeps heat",
    "platform": "woocommerce",
    "external_ref": "4471"
  }'

# → 202 { "job_id": "9f3c…", "status": "queued", "poll_after_ms": 3000 }

# 2. Poll until status is complete or failed
curl https://www.getranklify.com/api/v1/jobs/9f3c… \
  -H "Authorization: Bearer lfy_YOUR_KEY"

Idempotency-Key: sku-4471-run1

{
  "api_version": "v1",
  "account": { "email": "owner@example.com", "plan": "pro", "is_member": false },
  "usage":   { "used": 12, "limit": 100, "plan": "pro", "remaining": 88 },
  "token":   {
    "scope": "plugin",
    "name": "shop.example.com",
    "site_url": "https://shop.example.com",
    "platform": "woocommerce"
  },
  "brands": [{ "id": "a9d4...", "name": "Hydrosteel", "locked": false }],
  "capabilities": { "generate": true, "async_jobs": true, "bulk": true },
  "upgrade_url": "https://www.getranklify.com/pricing"
}

# 1. Send the store owner's browser here (from your plugin's settings screen)
https://www.getranklify.com/connect
  ?site=https%3A%2F%2Fshop.example.com
  &platform=woocommerce
  &return_url=https%3A%2F%2Fshop.example.com%2Fwp-admin%2Fadmin.php%3Fpage%3Dranklify
  &state=RANDOM_NONCE

# 2. They approve, and we redirect back to return_url with:
#    ?ranklify_code=ONE_TIME_CODE&state=RANDOM_NONCE

# 3. Your server (never the browser) trades the code for a token
curl -X POST https://www.getranklify.com/api/v1/connect/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ONE_TIME_CODE",
    "site": "https://shop.example.com"
  }'

# → 200 { "token": "lfy_...", "token_prefix": "lfy_a1b2c3d4",
#         "site_url": "https://shop.example.com", "platform": "woocommerce",
#         "account": { "plan": "free" },
#         "usage": { "used": 0, "limit": 3, "plan": "free", "remaining": 3 } }

{
  "api_version": "v1",
  "listing": {
    "title": "HYDROSTEEL Stainless Steel Pour-Over Kettle ...",
    "bullets": ["PRECISE POUR — ...", "BUILT TO LAST — ...", "..."],
    "description": "<p>...</p>",
    "keywords": ["pour over kettle", "gooseneck kettle", "..."],
    "backend_terms": "coffee kettle, drip kettle, ...",
    "focus_keyphrase": "",
    "meta_description": "",
    "product_tags": [],
    "seo_scores": {
      "keyword_density": 89,
      "readability": 92,
      "conversion_potential": 91,
      "platform_compliance": 95
    },
    "pro_tip": "Add a lifestyle image showing the spout mid-pour."
  },
  "listing_id": "b1c2...",
  "platform": "amazon",
  "tone": "Professional",
  "brand_id": "a9d4...",
  "usage": { "used": 12, "limit": 1000, "plan": "agency" }
}

{ "error": { "code": "invalid_api_key", "message": "Invalid or revoked API key." } }

curl -X POST https://www.getranklify.com/api/v1/generate \
  -H "Authorization: Bearer lfy_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Stainless Steel Pour-Over Kettle",
    "features": "Gooseneck spout, 1L, food-grade steel, keeps heat",
    "platform": "amazon",
    "tone": "Professional"
  }'

const res = await fetch("https://www.getranklify.com/api/v1/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.RANKLIFY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    product_name: "Stainless Steel Pour-Over Kettle",
    features: "Gooseneck spout, 1L, food-grade steel, keeps heat",
    platform: "amazon",
    tone: "Professional",
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(error.code + ": " + error.message);
}
const data = await res.json();
console.log(data.listing.title);

import os, requests

resp = requests.post(
    "https://www.getranklify.com/api/v1/generate",
    headers={
        "Authorization": f"Bearer {os.environ['RANKLIFY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "product_name": "Stainless Steel Pour-Over Kettle",
        "features": "Gooseneck spout, 1L, food-grade steel, keeps heat",
        "platform": "amazon",
        "tone": "Professional",
    },
    timeout=60,
)

if resp.status_code != 200:
    err = resp.json()["error"]
    raise RuntimeError(f"{err['code']}: {err['message']}")

print(resp.json()["listing"]["title"])

<?php
$ch = curl_init("https://www.getranklify.com/api/v1/generate");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("RANKLIFY_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "product_name" => "Stainless Steel Pour-Over Kettle",
        "features"     => "Gooseneck spout, 1L, food-grade steel, keeps heat",
        "platform"     => "amazon",
        "tone"         => "Professional",
    ]),
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
if ($status !== 200) {
    throw new Exception($data["error"]["code"] . ": " . $data["error"]["message"]);
}
echo $data["listing"]["title"];

import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();

String body = """
    {
      "product_name": "Stainless Steel Pour-Over Kettle",
      "features": "Gooseneck spout, 1L, food-grade steel, keeps heat",
      "platform": "amazon",
      "tone": "Professional"
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://www.getranklify.com/api/v1/generate"))
    .header("Authorization", "Bearer " + System.getenv("RANKLIFY_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) {
    throw new RuntimeException("Request failed: " + response.body());
}
System.out.println(response.body());

# 1. Queue the job — returns immediately
curl -X POST https://www.getranklify.com/api/v1/jobs \
  -H "Authorization: Bearer lfy_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-4471-run1" \
  -d '{
    "product_name": "Stainless Steel Pour-Over Kettle",
    "features": "Gooseneck spout, 1L, food-grade steel, keeps heat",
    "platform": "woocommerce",
    "external_ref": "4471"
  }'

# → 202 { "job_id": "9f3c…", "status": "queued", "poll_after_ms": 3000 }

# 2. Poll until status is complete or failed
curl https://www.getranklify.com/api/v1/jobs/9f3c… \
  -H "Authorization: Bearer lfy_YOUR_KEY"

<?php
// Queue, then poll. No single request stays open long enough to hit a
// shared host's PHP execution limit.

function ranklify_post($path, $body, $extraHeaders = []) {
    $ch = curl_init("https://www.getranklify.com" . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
        CURLOPT_HTTPHEADER     => array_merge([
            "Authorization: Bearer " . getenv("RANKLIFY_TOKEN"),
            "Content-Type: application/json",
        ], $extraHeaders),
        CURLOPT_POSTFIELDS     => json_encode($body),
    ]);
    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $res;
}

// Idempotency-Key makes a retried POST return the ORIGINAL job instead of
// queueing a second generation — without it a network timeout burns a credit.
$job = ranklify_post("/api/v1/jobs", [
    "product_name" => "Stainless Steel Pour-Over Kettle",
    "features"     => "Gooseneck spout, 1L, food-grade steel, keeps heat",
    "platform"     => "woocommerce",
    "external_ref" => "4471",
], ["Idempotency-Key: sku-4471-run1"]);

$jobId = $job["job_id"];

for ($i = 0; $i < 40; $i++) {
    sleep(3);
    $ch = curl_init("https://www.getranklify.com/api/v1/jobs/" . $jobId);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
        CURLOPT_HTTPHEADER     => ["Authorization: Bearer " . getenv("RANKLIFY_TOKEN")],
    ]);
    $poll = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if ($poll["status"] === "complete") { echo $poll["listing"]["title"]; break; }
    if ($poll["status"] === "failed")   { throw new Exception($poll["error"]["code"]); }
}