API کے ذریعے اشاعت کسی بھی ویب سائٹ پر۔

/ جائزہ

یہ کیسے کام کرتا ہے

جب Orova کسی کی ورڈ کے لیے مضمون لکھ لیتا ہے، تو وہ آپ کے رجسٹر کردہ endpoint URL پر ایک HTTP POST درخواست بھیجتا ہے۔ درخواست کا body JSON ہے اور اس میں پورا مضمون ہوتا ہے۔ آپ کا endpoint آپ کی طرف پوسٹ بناتا ہے اور مضمون کے حتمی، عوامی URL کے ساتھ جواب دیتا ہے۔ Orova اس URL کو شائع شدہ لنک کے طور پر محفوظ کرتا ہے، بالکل جیسے WordPress پوسٹ کے لیے کرتا۔ اسے تب استعمال کریں جب آپ WordPress کے علاوہ کسی سائٹ پر خودکار اشاعت چاہتے ہوں، یا پوسٹس کے ذخیرے پر مکمل کنٹرول رکھنا چاہتے ہوں۔

/ سیٹ اپ

سیٹ اپ — چھ مراحل

• 1

  اپنے پروجیکٹ میں “Connect via API” آن کریں. اپنا پروجیکٹ کھولیں (Projects → آپ کا پروجیکٹ → Connections)۔ WordPress کارڈ کے ساتھ Connect via API کارڈ ہے۔ وہاں اپنے endpoint کا URL درج کریں۔ خفیہ کلید کا خانہ اختیاری ہے: خالی چھوڑیں تو Orova ایک بنا دیتا ہے، یا وہ کلید چسپاں کریں جو آپ کی سائٹ پہلے سے استعمال کرتی ہے۔ محفوظ کرنے کے بعد کلید کارڈ پر Copy بٹن کے ساتھ دکھائی دیتی ہے۔ ایک پروجیکٹ صرف ایک ہدف پر شائع کرتا ہے — API سے جڑنے پر WordPress بٹن مقفل ہو جاتا ہے، اور اس کے برعکس بھی۔

• 2

  ایسا endpoint بنائیں جو POST قبول کرے. اپنی سائٹ یا سرور پر ایک route بنائیں جو JSON body کے ساتھ HTTP POST سنے۔ یہی URL آپ پروجیکٹ کی Connections اسکرین میں چسپاں کرتے ہیں۔ Orova ہر مکمل مضمون کے لیے اسے ایک بار کال کرتا ہے۔

• 3

  ہر درخواست پر Bearer token کی تصدیق کریں. Orova کی ہر درخواست میں “Bearer <secret>” کی شکل میں Authorization ہیڈر ہوتا ہے، جس میں آپ کے پروجیکٹ میں دکھائی گئی بالکل وہی خفیہ کلید ہوتی ہے۔ اسے اپنی محفوظ کاپی سے ملائیں اور جو میل نہ کھائے اسے رد کریں — یہی کسی اور کو آپ کی سائٹ پر پوسٹ کرنے سے روکتا ہے۔

• 4

  Payload سے مضمون بنائیں. JSON body پڑھیں اور اپنے CMS یا ڈیٹا بیس میں پوسٹ بنائیں: مضمون کے لیے title، slug اور content_html، meta description کے طور پر excerpt، کور تصویر کے طور پر featured_image_url، اور metadata کے طور پر keyword / lang / published_at استعمال کریں۔

• 5

  مضمون کا لائیو URL واپس کریں. HTTP 200 یا 201 اور { "url": "https://yoursite.com/the-new-article" } والے JSON body کے ساتھ جواب دیں۔ Orova اس URL کو مضمون کے شائع شدہ لنک کے طور پر محفوظ کرتا ہے۔ اگر آپ non-2xx اسٹیٹس واپس کریں، یا url فیلڈ چھوڑ دیں، تو Orova اشاعت کو ناکام سمجھتا ہے۔

• 6

  Optimize انجن کی اپ ڈیٹ درخواستیں سنبھالیں. جب body میں action = "update" ہو، تو target_url (یا slug) سے موجودہ پوسٹ تلاش کریں اور اسی جگہ اس کا title، content_html اور excerpt بدل دیں — URL نہ بدلیں۔ اسی پوسٹ کی طرف اشارہ کرنے والے { "url": ... } کے ساتھ 200 جواب دیں۔ جو endpoints ابھی یہ نہیں سنبھالتے، ان پر Orova بس optimization کو ناکام رپورٹ کرے گا؛ نئے مضامین کی اشاعت پہلے کی طرح چلتی رہے گی۔

/ معاہدہ

Orova کی بھیجی گئی درخواست

ہر مکمل مضمون اس شکل کی ایک درخواست کے طور پر آتا ہے:

POST <your endpoint URL>

Headers:
  Content-Type: application/json
  Authorization: Bearer <secret>     # the secret key shown in Project -> Connections
  User-Agent: Orova-SEO

Body (JSON):
  {
    "title": "...",                  # article headline
    "slug": "...",                   # URL-friendly identifier
    "content_html": "...",           # full article HTML
    "excerpt": "...",                # meta description
    "featured_image_url": "..." | null,
    "keyword": "...",                # target keyword
    "lang": "en",                    # ISO language code
    "published_at": "2026-05-17T09:00:00.482913",  # ISO 8601, UTC, no offset suffix
    "status": "draft"                # optional: "draft" keeps it unpublished
  }
  # Optional fields are left out of the body when empty — never sent as null.

/ حوالہ

Payload فیلڈز

اشاعت (نیا مضمون) درخواست کے فیلڈز۔ حذف اور اپ ڈیٹ کی درخواستیں اسی endpoint کو چھوٹے body کے ساتھ استعمال کرتی ہیں جو نیچے ان کے اپنے حصوں میں دکھائے گئے ہیں۔

جب بھیجنے کو کچھ نہ ہو تو اختیاری فیلڈز body سے مکمل طور پر نکال دیے جاتے ہیں — Orova کبھی null نہیں بھیجتا، اس لیے انہیں احتیاط سے پڑھیں۔ status بھی اختیاری ہے: "draft" مضمون کو ڈرافٹ کے طور پر بناتا ہے، جبکہ "publish" یا status کے بغیر اسے فوراً شائع کرتا ہے۔

/ معاہدہ

آپ کو جو جواب واپس کرنا ہے

پوسٹ بنانے کے بعد HTTP 200 یا 201 اسٹیٹس اور یہ JSON body واپس کریں:

HTTP 200 (or 201)
Content-Type: application/json

{
  "url": "https://yoursite.com/published-article"
}

Orova اس url کو مضمون کے شائع شدہ لنک کے طور پر محفوظ کرتا ہے۔ اگر آپ کا endpoint کوئی non-2xx اسٹیٹس، یا ایسا body واپس کرے جو url فیلڈ والا JSON object نہ ہو، تو Orova اشاعت کو ناکام سمجھتا ہے اور مضمون کو اسی کے مطابق نشان زد کرتا ہے تاکہ آپ دوبارہ کوشش کر سکیں۔ 60 سیکنڈ کے اندر جواب دیں — اس کے بعد Orova درخواست کا وقت ختم کر دیتا ہے (یہ اشاعت، اپ ڈیٹ اور حذف سب پر لاگو ہے)۔

/ مثال

کوڈ کی مثال

Node.js اور Express میں ایک کم سے کم وصول کرنے والا endpoint۔ یہی مراحل — token کی تصدیق، action (update / delete) کے مطابق شاخ، پوسٹ بنانا یا بدلنا، URL واپس کرنا — کسی بھی زبان یا فریم ورک پر لاگو ہوتے ہیں۔

// Node.js / Express — a minimal receiving endpoint
import express from "express";

const app = express();
app.use(express.json({ limit: "5mb" }));

// The secret Orova generated for this project.
const OROVA_SECRET = process.env.OROVA_SECRET;

app.post("/orova/publish", async (req, res) => {
  // 1. Verify the Bearer token.
  const auth = req.get("authorization") || "";
  if (auth !== "Bearer " + OROVA_SECRET) {
    return res.status(401).json({ error: "unauthorized" });
  }

  // 2. Required: list your articles (duplicate check, internal links). action = "list".
  if (req.body.action === "list") {
    const posts = await listPosts(req.body.limit || 500); // newest first, 500 max
    // each post: { id, title, slug, link, date, modified, status, author, excerpt? }
    return res.status(200).json({ ok: true, posts });
  }

  // 3. Required: read one article in full (used when optimizing it). action = "get".
  if (req.body.action === "get") {
    const post = await findPost(req.body.id, req.body.target_url, req.body.slug);
    if (!post) return res.status(404).json({ ok: false, err: "not_found" });
    return res.status(200).json({ ok: true, post });
  }

  // 4. Visual Editor: store an image, answer with its absolute URL.
  if (req.body.action === "upload_image") {
    const { filename, mime, data_base64 } = req.body;
    if (!String(mime || "").startsWith("image/")) {
      return res.status(422).json({ error: "image files only" });
    }
    const bytes = Buffer.from(data_base64, "base64");
    if (bytes.length > 15 * 1024 * 1024) {
      return res.status(413).json({ error: "image too large" });
    }
    return res.status(200).json({ ok: true, url: await saveImage(filename, bytes) });
  }

  // 5. Delete requests: body carries action = "delete".
  if (req.body.action === "delete") {
    const removed = await deletePostByUrl(req.body.url, req.body.slug);
    if (!removed) return res.status(404).json({ deleted: true }); // already gone
    return res.status(200).json({ deleted: true });
  }

  // 6. Update requests: action = "update". Optional fields may be absent.
  if (req.body.action === "update") {
    const updated = await updatePost(req.body.id, req.body.target_url, {
      title: req.body.title,
      html: req.body.content_html,
      metaDescription: req.body.excerpt,
      coverImage: req.body.featured_image_url,  // optional
      status: req.body.status,                  // optional: "publish" | "draft"
    });
    if (!updated) return res.status(404).json({ error: "post not found" });
    return res.status(200).json({ url: updated.url });
  }

  // 7. New article: read the payload Orova sent.
  const {
    title, slug, content_html, excerpt,
    featured_image_url, keyword, lang, published_at, status,
  } = req.body;

  // 8. Create the article in your own CMS or database.
  const post = await createPost({
    title,
    slug,
    html: content_html,
    metaDescription: excerpt,
    coverImage: featured_image_url,
    keyword,
    lang,
    publishedAt: published_at,
    draft: status === "draft",   // status is optional; absent means publish now
  });

  // 9. Return 200/201 with the live URL.
  return res.status(201).json({
    url: "https://yoursite.com/" + post.slug,
  });
});

app.listen(3000);

/ معاہدہ — اپ ڈیٹ

مضامین اپ ڈیٹ کرنا (Optimize)

Orova کا Optimize انجن پہلے سے لائیو مضامین کو دوبارہ لکھتا ہے — تازہ حقائق، بہتر عنوانات، یکجا مواد — اور پھر موجودہ پوسٹ کو اسی جگہ، URL بدلے بغیر اوور رائٹ کرتا ہے۔ درخواست اسی endpoint URL پر، اسی Bearer token کے ساتھ POST کے طور پر جاتی ہے:

POST <your endpoint URL>

Headers:
  Content-Type: application/json
  Authorization: Bearer <secret>
  User-Agent: Orova-SEO

Body (JSON):
  {
    "action": "update",          # always the literal string "update"
    "id": 123,                   # optional: post id, match on this first
    "target_url": "...",         # public URL of the post to overwrite (match next)
    "title": "...",              # new headline
    "slug": "...",               # slug fallback for matching, may be empty
    "content_html": "...",       # full new article body as HTML
    "excerpt": "...",            # new meta description
    "featured_image_url": "...", # optional: new cover image
    "status": "publish"          # optional: "publish" or "draft"
  }
  # Optional fields are left out of the body when empty — never sent as null.

پوسٹ کو target_url سے تلاش کریں (ورنہ slug سے)، اس کا title، متن اور meta description بدلیں، URL جوں کا توں رکھیں، پھر { "url": "<same post URL>" } کے ساتھ 200 جواب دیں۔ کوئی بھی non-2xx اسٹیٹس، یا url کے بغیر body، Orova کو وہ optimization ناکام نشان زد کرنے پر مجبور کرتا ہے (یہ کبھی ڈپلیکیٹ پوسٹ نہیں بناتا)۔ جن endpoints نے ابھی یہ نافذ نہیں کیا وہ نئے مضامین بغیر تبدیلی شائع کرتے رہتے ہیں — update نافذ کرنا صرف تب ضروری ہے جب آپ Optimize اسکرین استعمال کریں۔

29 اگست سے update body میں id (target_url سے پہلے اسی پر میل کریں)، نئی کور تصویر کے لیے featured_image_url، اور "publish" یا "draft" والا status بھی ہو سکتا ہے۔ تینوں اختیاری ہیں؛ خالی ہوں تو body سے نکال دیے جاتے ہیں، کبھی null کے طور پر نہیں بھیجے جاتے۔

/ معاہدہ — Visual Editor

مضامین پڑھنا (لازمی)

Orova کو آپ کی سائٹ پر پہلے سے موجود مضامین پڑھنے ہوتے ہیں — موضوعات کی تکرار سے بچنے، اندرونی لنکس شامل کرنے اور پرانی پوسٹس کو optimize کرنے کے لیے۔ اسی endpoint URL پر، اسی Bearer token کے ساتھ دو مزید actions شامل کریں: list آپ کے مضامین واپس کرتا ہے، get ان میں سے ایک مکمل طور پر واپس کرتا ہے۔

POST <your endpoint URL>     # same endpoint, same Bearer secret

Body (JSON):
  {
    "action": "list",            # always the literal string "list"
    "limit": 500                 # newest article first, 500 maximum
  }

Response — HTTP 200:
  {
    "ok": true,
    "posts": [
      {
        "id": 123,               # your own post id, reused by "get" and "update"
        "title": "...",
        "slug": "...",
        "link": "https://yoursite.com/the-article",
        "date": "2026-08-29",    # published date, YYYY-MM-DD
        "modified": "2026-08-29",
        "status": "publish",     # "publish" or "draft"
        "author": "...",
        "excerpt": "..."         # optional: short summary, 300 characters max
      }
    ]
  }
  # Required: Orova reads this list to avoid duplicate topics,
  # add internal links and analyze the whole site.

POST <your endpoint URL>

Body (JSON):
  {
    "action": "get",             # always the literal string "get"
    "id": 123,                   # match on this first
    "target_url": "...",         # then the public URL
    "slug": "..."                # then the slug
  }

Response — HTTP 200:
  {
    "ok": true,
    "post": {
      "id": 123,
      "title": "...",
      "slug": "...",
      "link": "https://yoursite.com/the-article",
      "content_html": "...",     # full article body as HTML
      "excerpt": "...",
      "featured_image_url": "...",
      "status": "publish"        # "publish" or "draft"
    }
  }

No such post — HTTP 404:
  { "ok": false, "err": "not_found" }

limit کی حد 500 ہے اور سب سے نیا مضمون پہلے آتا ہے۔ get کے لیے Orova id، target_url اور slug ایک ساتھ بھیجتا ہے — جو آپ پہچانیں اسی ترتیب میں اس پر میل کریں۔ کچھ میل نہ کھائے تو { "ok": false, "err": "not_found" } کے ساتھ 404 جواب دیں۔ list میں excerpt اختیاری ہے (زیادہ سے زیادہ 300 حروف)۔ لازمی: Orova یہ جاننے کے لیے list کال کرتا ہے کہ کون سے مضامین پہلے سے موجود ہیں (تکرار سے بچنے، اندرونی لنکس شامل کرنے اور پوری سائٹ کا تجزیہ کرنے کے لیے) اور optimize کرتے وقت مضمون پڑھنے کے لیے get کال کرتا ہے۔ اگر آپ کی سائٹ ان دو actions کا جواب نہ دے، تو نئے مضامین کو اندرونی لنکس نہیں ملتے اور پرانے مضامین optimize نہیں ہو سکتے۔

/ معاہدہ — Visual Editor

تصاویر اپ لوڈ کرنا (Visual Editor)

جب آپ Visual Editor میں تصویر ڈالتے ہیں، تو Orova اسے JSON body کے اندر base64 کے طور پر اسی endpoint URL پر بھیجتا ہے — نہ multipart، نہ محفوظ کرنے کے لیے دوسرا URL۔

POST <your endpoint URL>

Body (JSON):
  {
    "action": "upload_image",    # always the literal string "upload_image"
    "filename": "cover.png",     # original file name, extension included
    "mime": "image/png",         # image/* only
    "data_base64": "iVBORw0KGgo..."   # file bytes, base64, 15 MB maximum
  }

Response — HTTP 200 (or 201):
  {
    "ok": true,
    "url": "https://yoursite.com/uploads/cover.png"   # absolute URL
  }

صرف image/* قبول کریں اور 15 MB سے بڑی ہر چیز رد کریں۔ فائل محفوظ کریں، پھر تصویر کے مکمل (absolute) URL کے ساتھ جواب دیں: نسبتی راستہ مضمون کو کہیں اور دکھائے جاتے ہی توڑ دیتا ہے۔ یہ action صرف Visual Editor کے لیے ضروری ہے۔

/ معاہدہ — حذف

مضامین حذف کرنا

جب کوئی صارف Orova کے اندر (Write یا Reports اسکرین سے) شائع شدہ مضمون ہٹاتا ہے، تو Orova آپ کی سائٹ سے بھی اسے حذف کرنے کو کہتا ہے۔ درخواست اسی endpoint URL پر، اسی Bearer token کے ساتھ POST کے طور پر جاتی ہے — فرق صرف body کا ہے:

POST <your endpoint URL>

Headers:
  Content-Type: application/json
  Authorization: Bearer <secret>
  User-Agent: Orova-SEO

Body (JSON):
  {
    "action": "delete",          # always the literal string "delete"
    "url": "...",                # public URL of the article to remove (match on this first)
    "slug": "...",               # slug fallback, may be empty
    "keyword": "..."             # the article's target keyword, for your logs
  }

پوسٹ کو url سے تلاش کریں (ورنہ slug سے)، اسے ہٹائیں یا غیر شائع کریں، پھر 200 اور { "deleted": true } کے ساتھ جواب دیں — صرف 204 بھی کام کرتا ہے۔ اگر پوسٹ اب موجود نہیں، تو 404 جواب دیں اور Orova اسے پہلے سے حذف شدہ سمجھے گا۔ { "deleted": false } واپس کرنا Orova کو بتاتا ہے کہ پوسٹ نہیں ہٹائی گئی۔ عام اشاعت کی درخواستوں میں کبھی action فیلڈ نہیں ہوتا، اس لیے موجودہ endpoints بغیر تبدیلی کام کرتے رہتے ہیں — delete نافذ کرنا اختیاری ہے لیکن تجویز کردہ ہے۔

/ سیکیورٹی

سیکیورٹی نوٹس

• ہمیشہ Bearer token کی تصدیق کریں. آپ کا endpoint ایک عوامی URL ہے — کوئی بھی اسے کال کر سکتا ہے۔ Authorization ہیڈر ہی وہ واحد چیز ہے جو ثابت کرتی ہے کہ درخواست واقعی Orova سے آئی، اس لیے ہر وہ درخواست رد کریں جس کا token آپ کی محفوظ خفیہ کلید سے بالکل میل نہ کھائے۔
• Endpoint کو HTTPS پر چلائیں. خفیہ کلید ہیڈر میں سفر کرتی ہے۔ HTTPS اسے راستے میں پڑھے جانے سے بچاتا ہے۔
• خفیہ کلید کو اپنے کوڈ سے باہر رکھیں. اسے environment variable یا secrets manager میں رکھیں، کبھی کمٹ کی جانے والی فائل میں hard-code نہ کریں۔ اگر یہ کبھی ظاہر ہو جائے تو Project → Connections سے نئی بنائیں۔
• content_html کو مواد سمجھیں، قابلِ اعتماد markup نہیں. اسے اسی احتیاط سے محفوظ اور ظاہر کریں جیسے اپنے CMS میں کسی بھی مضمون کے متن کو کرتے ہیں۔

/ خلاصہ

یہی پورا معاہدہ ہے

جب endpoint لائیو ہو اور آپ کے پروجیکٹ میں رجسٹر ہو، تو Orova آپ کی سائٹ پر خودکار طور پر شائع کرتا ہے — بالکل ویسے ہی جیسے WordPress صارفین کے لیے۔ ہر مکمل مضمون آپ کے سرور پر پہنچتا ہے، پوسٹ بنتا ہے، اور اس کا عوامی URL واپس Reports اور Analysis میں آتا ہے تاکہ آپ اس کی کارکردگی پر نظر رکھ سکیں۔