MarkaestroMarkaestro

لوكلاء الذكاء الاصطناعي

اربط وكيلك في خطوة واحدة. وهو يدير قنواتك الاجتماعية.

بُني Markaestro ليُشغَّل بواسطة البرمجيات. عميل MCP مثل Claude Code يسجّل الدخول عبر المتصفح ويحصل على مفتاح مرتبط بعلامة تجارية واحدة؛ وأي وكيل آخر يحصل على المفتاح نفسه من الإعدادات. في الحالتين يستطيع الوكيل اكتشاف الحسابات التي يمكنه النشر عليها، ورفع الوسائط، وإنشاء المنشورات وجدولتها، ونشرها، والإبلاغ عمّا نُشر فعلًا، على Facebook وInstagram وTikTok وLinkedIn وThreads وPinterest.

لا حزمة SDK للتثبيت ولا بيانات اعتماد منصات لمتابعتها. يربط فريقك الحسابات مرة واحدة في لوحة التحكم؛ ومن ثم يتعامل الوكيل مع واجهة API واحدة برمز Bearer.

مصمم للاستقلالية، ومقيّد بغرض

لماذا يكون مفتاح API هو التكامل بأكمله

الجزء الصعب في السماح لوكيل بلمس وسائل التواصل الاجتماعي ليس HTTP. بل التأكد من أن نموذجًا مرتبكًا لا يمكنه النشر إلى العلامة التجارية الخاطئة، أو النشر المزدوج عند إعادة محاولة، أو إرسال شيء لم يقرأه أحد. تلك الضمانات موجودة في واجهة API نفسها، لا في موجهك.

مفتاح واحد، علامة تجارية واحدة
يُربط كل مفتاح API بعلامة تجارية واحدة عند إنشائه. يمكن للوكيل الذي يحمل ذلك المفتاح أن يرى وينشر فقط إلى تلك العلامة، تُرفض الطلبات عبر العلامات التجارية عند المصادقة، لا بالاتفاق.
اكتشاف، لا معرّفات ثابتة
يسأل الوكيل عن الحسابات التي يمكنه النشر إليها ويحصل على معرّفات غير شفافة لإعادتها مباشرة. لا معرّفات صفحات، ولا تنقيب في Business Manager، ولا ملف تكوين يفسد عندما تُعاد ربط اتصال.
كتابات متكافئة القوة
أرسل Idempotency-Key مع أي عملية إنشاء أو نشر. تعيد الاستدعاءات المكررة خلال 24 ساعة الاستجابة الأصلية بدلًا من إنشاء منشور ثانٍ، نمط الفشل الأكثر شيوعًا الذي تصادفه الوكلاء.
يبقى إنسان في الحلقة
منشورات Facebook وInstagram وTikTok يدوية أولًا: يعدّها وكيلك، ويقوم شخص بنشرها بشكل أصلي. لا يخرج شيء دون إشراف ما لم تختر ذلك المنشور صراحة.

عملاء MCP

سجّل الدخول من العميل. لا شيء للصق.

يمكن لـ Claude Code وClaude وCursor وChatGPT وGrok وGrok Bot وOpenClaw وHermes وكل عميل آخر يتحدث بروتوكول Model Context Protocol الاتصال بخادم MCP المستضاف لدى Markaestro دون أي بيانات اعتماد مضبوطة. أول استدعاء لأداة يفتح متصفحك: سجّل الدخول، واختر مساحة العمل والعلامة التجارية التي يجوز للوكيل التصرف فيها، وراجع الأذونات، ثم انقر على السماح. يتلقى العميل مفتاحًا مرتبطًا بتلك العلامة التجارية ويجدّده بنفسه.

هذا هو OAuth 2.1 القياسي مع PKCE والتسجيل الديناميكي للعملاء، وهي الآلية نفسها خلف خوادم MCP المستضافة الأخرى، لذا يعمل دون أي إضافة خاصة بـ Markaestro. يقع الخادم على https://markaestro.com/api/public/v1/mcp ويتيح إحدى وثلاثين أداة فوق واجهة API العامة: اكتشاف العلامات التجارية والوجهات، ورفع الوسائط، والمسودات والمنشورات المجدولة، والنشر مع متابعة تنفيذ المهام، والعمليات الجماعية، وWebhooks، وقواعد كل قناة.

اربط وكيلك

اختر وكيلك. ثلاث خطوات، ثم يستطيع النشر.

كل عميل أدناه يصل إلى خادم MCP المستضاف نفسه. معظمها يسجّل الدخول عبر المتصفح: أول استدعاء لأداة يفتح صفحة موافقة تختار فيها مساحة العمل والعلامة التجارية التي يمكن للوكيل التصرف فيها، ويحصل العميل على مفتاح مرتبط بتلك العلامة. أما العملاء الذين لا يستطيعون فتح متصفح فيستخدمون مفتاح API لمساحة العمل. الخادم نفسه، الأذونات نفسها، القائمة نفسها في الإعدادات.

Claude Code

يثبّت المكوّن الإضافي المهارة والخادم المستضاف معًا. لا شيء لتهيئته ولا شيء للصقه.

تسجيل الدخول أو مفتاح APIمستندات Claude Code
01

قبل أن تبدأ

  • أنت مالك مساحة العمل أو مشرف فيها ببريد إلكتروني مؤكد، في مساحة عمل لها خطة نشطة وعلامة تجارية واحدة على الأقل.
  • Claude Code مثبّت ومسجّل الدخول إلى حساب Anthropic الخاص بك.
03

سجّل الدخول

  1. اسأل Claude أي شيء عن Markaestro، أو نفّذ /mcp واختر markaestro.
  2. يفتح متصفحك صفحة الموافقة. اختر مساحة العمل والعلامة التجارية، راجع الأذونات، ثم انقر على السماح.
  3. لتبديل العلامة لاحقًا، نفّذ /mcp مجددًا، سجّل الخروج، ثم سجّل الدخول بالعلامة الأخرى.
فضّل تسجيل الدخول. استخدم مفتاحًا فقط عندما لا يستطيع العميل فتح متصفح.
04

تحقّق

  • اطلب من الوكيل استدعاء list_products. يجب أن يرد بالعلامة التجارية الوحيدة التي منحتها وقنواتها المتصلة.
  • يظهر الاتصال في الإعدادات، API مع شارة وكيل متصل ووقت آخر استخدام وحجم الطلبات. يمكنك إلغاؤه من هناك في أي وقت.
افتح الإعدادات، API
02

أضف الخادم

  1. نفّذ أمري المكوّن الإضافي في أي طرفية، أو أضف الخادم فقط بالأمر الثالث.
Bash
# The plugin bundles the skill and the hosted server.
claude plugin marketplace add D3vBaba/Markaestro
claude plugin install markaestro@markaestro

# Or add just the server. No key, no header: the first call opens the browser.
claude mcp add --transport http markaestro https://markaestro.com/api/public/v1/mcp

ما الذي يحدث عندما يتصل العميل

خمس خطوات يتولّاها العميل والمتصفح بالكامل. أنت لا ترى سوى صفحة الموافقة.

01التحدي
POST /api/public/v1/mcp → 401 + WWW-Authenticate

يستدعي العميل نقطة نهاية MCP دون بيانات اعتماد. يردّ Markaestro بالرمز 401 مع ترويسة WWW-Authenticate تشير إلى مستند بيانات المورد المحمي. هذه الترويسة هي ما يخبر العميل بأن تسجيل الدخول متاح.

02الاكتشاف
GET /.well-known/oauth-protected-resource · /.well-known/oauth-authorization-server

يقرأ العميل مستندين عامين: أي خادم تفويض يحمي نقطة النهاية، وأين توجد نقاط التسجيل والتفويض والرمز الخاصة به. يُقدَّم المستندان على markaestro.com ويمكن تخزينهما مؤقتًا.

03التسجيل
POST /api/public/v1/oauth/register

يسجّل العميل نفسه باسم وعنوان رد الاتصال الخاص به. تُقبل عناوين loopback وردود الاتصال عبر https ومخططات التطبيقات الأصلية؛ ويُرفض http العادي إلى مضيف حقيقي. لا حاجة إلى معرّف عميل مُشارك مسبقًا.

04الموافقة
GET /oauth/authorize (browser)

يفتح متصفحك صفحة الموافقة. يختار مالك مساحة العمل أو مسؤولها ذو البريد الموثّق مساحة العمل والعلامة التجارية، ويعدّل الأذونات، ثم ينقر على السماح. يعيد Markaestro المتصفح إلى العميل مع رمز يُستخدم مرة واحدة.

05الرمز
POST /api/public/v1/oauth/token

يستبدل العميل الرمز مع مُحقّق PKCE برمز وصول ورمز تحديث. رمز الوصول هو مفتاح API عادي لمساحة العمل، مرتبط بالعلامة التجارية المختارة. تنتهي صلاحيته بعد 30 يومًا؛ والتحديث يبدّل سرّه ويمدّده 30 يومًا أخرى.

الرمز هو مفتاح API حقيقي

النطاقات، والارتباط بالعلامة التجارية، وحدود المعدل، وفحوصات الاشتراك، وعدم التكرار، والإلغاء تمرّ عبر مسار الشيفرة نفسه الخاص بمفتاح أُنشئ يدويًا. لا يوجد نموذج أذونات ثانٍ لفهمه.

مُدرج وقابل للإلغاء في الإعدادات

يظهر الوكيل المتصل في الإعدادات، API مع شارة وكيل متصل، ووقت آخر استخدام، وحجم الطلبات. ألغِه هناك فيفشل الاستدعاء التالي للعميل؛ ويمكن للعميل أيضًا إلغاء رمزه بنفسه عند فصله.

اتصال واحد، علامة تجارية واحدة

كل اتصال مرتبط بعلامة تجارية واحدة بالضبط تُختار عند الموافقة. لتمكين الوكيل من العمل على علامة تجارية ثانية، اربطه مجددًا واختر تلك العلامة. لا يمكن للعميل أبدًا الوصول إلى علامة تجارية لم تُمنح له.

الرموز ورموز التحديث تُستخدم مرة واحدة

تعيش رموز التفويض عشر دقائق وتُستهلك بشكل ذرّي، لذا يفشل أي رمز مُعاد. تُبدَّل رموز التحديث عند كل استخدام وتُخزَّن مجزّأة. وتنتهي صلاحية تسجيلات العملاء الخاملة بعد 180 يومًا.

نقاط النهاية

لمن يبني عميل MCP أو يدقق في التدفق. كل شيء قابل للاكتشاف من مستندي well-known؛ ولا شيء هنا يحتاج إلى إعداد يدوي.

مرجع
# Discovery (public, cacheable)
GET  /.well-known/oauth-protected-resource            RFC 9728
GET  /.well-known/oauth-authorization-server          RFC 8414

# Authorization server
POST /api/public/v1/oauth/register                    RFC 7591, public clients (PKCE) or client_secret
GET  /oauth/authorize?response_type=code&client_id=…&redirect_uri=…
                     &code_challenge=…&code_challenge_method=S256&state=…
POST /api/public/v1/oauth/token                       grant_type=authorization_code | refresh_token
POST /api/public/v1/oauth/revoke                      RFC 7009

# Token response
{ "access_token": "mk_live_<ws>.<client>.<secret>", "token_type": "Bearer",
  "expires_in": 2592000, "refresh_token": "…", "scope": "products.read posts.write …" }

حلقة الوكيل

خمسة استدعاءات، من البداية إلى النهاية

كل أتمتة في Markaestro هي نسخة من هذه الحلقة. الخطوات من واحد إلى ثلاثة هي Connect API، الواجهة المسطّحة التي ينبغي لمعظم الوكلاء استهدافها. تصل الخطوتان أربعة وخمسة إلى واجهة /api/public/v1 الكاملة للنشر الصريح وتتبّع المهام.

01اكتشاف
GET /api/connect/v1/social-accounts

يُرجع كل حساب متصل قابل للنشر إليه لعلامة المفتاح، كل واحد بمنصة واسم مستخدم ومعرّف غير شفاف. استدعه في بداية كل تشغيل، تتغير الاتصالات.

02رفع الوسائط
POST /api/connect/v1/media/create-upload-url → PUT

أصدر عنوان URL موقّعًا قصير الأمد وأحادي الاستخدام، ثم نفّذ PUT للبايتات الخام إليه. تحصل على معرّف وسائط. الصور حتى 10 ميجابايت؛ تقبل واجهة API الكاملة أيضًا فيديو حتى 250 ميجابايت.

03مسودة أو جدولة
POST /api/connect/v1/posts

مرّر التعليق ومعرّفات الوسائط ومعرّفات الحسابات حرفيًا. اتركه مسودة للمراجعة، أو أرسل is_draft false مع scheduled_at لوضعه على التقويم.

04نشر
POST /api/public/v1/posts/:id/publish

يضع مهمة غير متزامنة في قائمة الانتظار. تُرسل LinkedIn وThreads وPinterest عبر واجهة API الرسمية. تصل Facebook وInstagram وTikTok إلى قائمة انتظار 'للنشر' في مساحة العمل ليقوم إنسان بالنشر بشكل أصلي.

05تقديم تقرير
GET /api/public/v1/job-runs/:id · webhooks

استعلم عن معرّف المهمة، أو سجّل نقطة نهاية ويب هوك ودع Markaestro تدفع لك post.published وpost.action_required وpost.failed. لا تفترض أبدًا أن النشر انتهى بشكل متزامن.

بدء سريع

تكامل عملي في أربعة أوامر

أولًا، أصدر المفتاح: افتح الإعدادات ← API، اختر العلامة التجارية المسموح له بالوصول إليها، وحدد النطاقات التي يحتاجها، وامنحه اختياريًا صلاحية. يُعرض المفتاح مرة واحدة، ضعه مباشرة في مخزن أسرار وكيلك. يتطلب إنشاء المفاتيح مسؤولًا أو مالكًا ببريد إلكتروني موثّق.

1. اكتشاف الحسابات
أول استدعاء في كل تشغيل. تتغير الاتصالات؛ يجب ألا تُدمج المعرّفات في موجه أبدًا.
Bash
# The API is served from the marketing apex and the app subdomain alike.
export MARKAESTRO_URL="https://markaestro.com"
export MARKAESTRO_API_KEY="mk_live_<workspaceId>.<clientId>.<secret>"

# 1. What can this key post to?
curl -s "$MARKAESTRO_URL/api/connect/v1/social-accounts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
الاستجابة
{
  "data": [
    {
      "id": "prod_123#instagram:instagram:ig_123",
      "product_id": "prod_123",
      "product": "Northwind Coffee",
      "platform": "instagram",
      "username": "northwindcoffee"
    }
  ]
}
2. رفع الوسائط
خطوتان: أصدر عنوان URL موقّعًا أحادي الاستخدام، ثم نفّذ PUT للبايتات. تنتهي صلاحية العنوان بعد 15 دقيقة ولا يحتاج إلى ترويسة مصادقة خاصة به.
Bash
# 2. Mint a signed upload url, then PUT the bytes.
RESP=$(curl -s -X POST "$MARKAESTRO_URL/api/connect/v1/media/create-upload-url" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mime_type": "image/png", "size_bytes": 184320, "name": "cold-brew.png" }')
# → { "media_id": "ast_777", "upload_url": "https://.../media/upload?token=..." }

curl -X PUT "<upload_url>" \
  -H "Content-Type: image/png" \
  --data-binary @cold-brew.png
3. جدوِله، ثم راقبه
الإنشاء مسودة أولًا افتراضيًا. أرسل بدلًا من ذلك is_draft: false مع طابع زمني scheduled_at لوضع المنشور على التقويم.
Bash
# 3. Put it on the calendar. Pass the account id back verbatim.
curl -X POST "$MARKAESTRO_URL/api/connect/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Cold brew season starts Friday.",
    "media": ["ast_777"],
    "social_accounts": ["prod_123#instagram:instagram:ig_123"],
    "is_draft": false,
    "scheduled_at": "2026-08-14T15:00:00.000Z"
  }'

# 4. Check where everything stands.
curl -s "$MARKAESTRO_URL/api/connect/v1/posts?limit=20" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

جاهز للاستخدام

تعريفات الأدوات وملخص للوكيل

شيئان لنسخهما. الأول مجموعة مخططات أدوات تغطي حلقة النشر بأكملها، مكتوبة بـJSON Schema، بحيث تعمل كتعريفات أدوات Claude أو وظائف OpenAI أو شكل الإدخال لخادم MCP تستضيفه أنت. الثاني هو الملخص التشغيلي الذي يمنع النموذج من فعل شيء غير متوقع بها.

مخططات الأدوات
ست أدوات: سرد الحسابات، رفع الوسائط، إنشاء، نشر، سرد، حذف. اربط كل واحدة بنقطة النهاية المطابقة أعلاه.
tools.json
[
  {
    "name": "markaestro_list_accounts",
    "description": "List the social accounts this Markaestro key can publish to. Call this first in every run. Never hardcode account ids. Returns id, platform, and username.",
    "input_schema": { "type": "object", "properties": {}, "required": [] }
  },
  {
    "name": "markaestro_upload_media",
    "description": "Upload one image or video to Markaestro and return a media asset id. Images: png, jpeg, webp, gif up to 10 MB. Video: mp4, mov, webm up to 250 MB.",
    "input_schema": {
      "type": "object",
      "properties": {
        "file_path": { "type": "string", "description": "Local path to the file to upload." },
        "mime_type": { "type": "string", "description": "MIME type of the file." }
      },
      "required": ["file_path", "mime_type"]
    }
  },
  {
    "name": "markaestro_create_post",
    "description": "Create a post for one channel. Facebook, Instagram, and TikTok are manual-first: a human posts them natively from the To Post queue. Omit delivery_mode unless the user explicitly asked for unattended publishing.",
    "input_schema": {
      "type": "object",
      "properties": {
        "channel": {
          "type": "string",
          "enum": ["facebook", "instagram", "tiktok", "linkedin", "threads", "pinterest", "x"]
        },
        "caption": { "type": "string", "description": "Caption text, max 4000 characters." },
        "media_asset_ids": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Ids from markaestro_upload_media. Instagram and TikTok require at least one."
        },
        "destination_id": {
          "type": "string",
          "description": "From markaestro_list_accounts. Required only when the brand has more than one destination on that channel."
        },
        "delivery_mode": {
          "type": "string",
          "enum": ["manual_reminder", "direct_publish", "platform_inbox"],
          "description": "Omit for the channel default."
        }
      },
      "required": ["channel", "caption"]
    }
  },
  {
    "name": "markaestro_publish_post",
    "description": "Queue an async publish run for an existing post. Returns a run id. Poll it, do not assume the post is live.",
    "input_schema": {
      "type": "object",
      "properties": { "post_id": { "type": "string" } },
      "required": ["post_id"]
    }
  },
  {
    "name": "markaestro_list_posts",
    "description": "List posts for this brand, newest first. Filter by status: draft, scheduled, publishing, published, platform_action_required, failed, partial_failed.",
    "input_schema": {
      "type": "object",
      "properties": {
        "status": { "type": "string" },
        "limit": { "type": "integer", "minimum": 1, "maximum": 100 }
      },
      "required": []
    }
  },
  {
    "name": "markaestro_delete_post",
    "description": "Remove a post from Markaestro. Use it to cancel something scheduled. Deleting an already-published post does NOT retract the live copy on the platform.",
    "input_schema": {
      "type": "object",
      "properties": { "post_id": { "type": "string" } },
      "required": ["post_id"]
    }
  }
]
ملخص للوكيل
الصقه في موجه النظام الخاص بك. يُرمّز السلوكيات التي تفصل وكيل نشر موثوق عن وكيل ينشر مزدوجًا ويعلن الفوز مبكرًا.
موجه النظام
You have a Markaestro API key for exactly one brand. Markaestro is the
publishing layer: you supply the caption and the media, it handles the
platform rules, the calendar, and delivery.

Base URL: https://markaestro.com
Auth: Authorization: Bearer $MARKAESTRO_API_KEY

Rules:
- Call GET /api/connect/v1/social-accounts before posting. Pass the returned
  account ids back verbatim. Never invent or cache an id across runs.
- Upload media before creating a post; posts reference media ids, not files.
- Facebook, Instagram, and TikTok are manual-first. Creating and publishing
  them queues a reminder for a human. That is the intended behavior. Only
  send deliveryMode "direct_publish" if the operator explicitly asked for it.
- Send a unique Idempotency-Key on every POST. Reuse the SAME key when
  retrying the SAME request; never reuse it for a different one.
- On 429, wait the number of seconds in Retry-After, then retry. On 4xx other
  than 429, do not retry. Report the error code and requestId and stop.
- Publishing is async. POST /publish returns a run id; poll
  GET /api/public/v1/job-runs/<id> until succeeded or failed.
- To cancel, list with ?status=scheduled and DELETE the post id. Deleting a
  published post does not remove it from the platform.
- Never claim a post is live until a run reports succeeded or a post reports
  published.

يمكن لوكيلك أيضًا جلب هذا بنفسه: curl https://markaestro.com/llms.txt يُرجع ملخصًا نصيًا عاديًا لواجهة API بأكملها، نقاط النهاية، والقواعد، ومعالجة الأخطاء، صغير بما يكفي ليبقى في السياق.

وصفات

سير العمل الأربعة التي تنفذها الوكلاء فعليًا

النشر والتأكيد
أنشئ مسودة، وانشرها صراحة، ثم استعلم عن المهمة. الطريقة الصادقة الوحيدة لإخبار المشغّل أن منشورًا قد خرج.
Bash
# Full control: draft → publish → poll. No productId needed:
# the key is already bound to one brand.

POST_ID=$(curl -s -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-2026-08-14-linkedin" \
  -d '{
    "channel": "linkedin",
    "caption": "We shipped agent-driven publishing.",
    "mediaAssetIds": ["ast_777"]
  }' | jq -r .post.id)

RUN_ID=$(curl -s -X POST "$MARKAESTRO_URL/api/public/v1/posts/$POST_ID/publish" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Idempotency-Key: publish-$POST_ID" | jq -r .run.id)

# queued → running → succeeded | failed
curl -s "$MARKAESTRO_URL/api/public/v1/job-runs/$RUN_ID" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
التدقيق وإلغاء قائمة الانتظار
اسرد ما هو مجدول، واعرضه على إنسان، واحذف ما يرفضه. يستخدم كلا الاستدعاءين نطاقات يحملها مفتاح موجود بالفعل.
Bash
# Review the queue, then cancel what the operator rejected.
curl -s "$MARKAESTRO_URL/api/public/v1/posts?status=scheduled&limit=100" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

curl -X DELETE "$MARKAESTRO_URL/api/public/v1/posts/pst_123" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
# → { "deleted": true, "id": "pst_123" }
املأ أسبوعًا في استدعاء واحد
يستقبل الإنشاء الدفعي حتى 25 منشورًا ويُرجع نتائج لكل عنصر، بحيث لا يُغرق عنصر واحد مشوّه المهمة بأكملها.
Bash
# One call, up to 25 posts. Per-item results: one bad item
# does not fail the batch.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: week-33-drop" \
  -d '{
    "posts": [
      { "channel": "instagram", "caption": "Monday",  "mediaAssetIds": ["ast_1"] },
      { "channel": "facebook",  "caption": "Tuesday", "mediaAssetIds": ["ast_2"] },
      { "channel": "linkedin",  "caption": "Thursday" }
    ]
  }'
# → { "results": [...], "created": 3, "total": 3 }
تلقَّ اتصالًا بدلًا من الاستعلام
ينبغي للوكلاء طويلي التشغيل تسجيل ويب هوك والسكون. تُوقَّع التسليمات بـHMAC باستخدام سر يُعرض مرة واحدة عند الإنشاء.
Bash
# Let Markaestro call you instead of polling.
curl -X POST "$MARKAESTRO_URL/api/public/v1/webhook-endpoints" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-agent.example.com/hooks/markaestro",
    "events": ["post.published", "post.action_required", "post.failed"]
  }'

# Each delivery carries:
#   X-Markaestro-Event      post.action_required
#   X-Markaestro-Timestamp  2026-08-14T15:00:04.000Z
#   X-Markaestro-Signature  HMAC of the body with your webhook secret
# The secret is shown once at creation and stored hashed. Verify before acting.

ضوابط الحماية

ما يمكن للوكيل فعله وما لا يمكنه

الاستقلالية مفيدة فقط إذا كان نطاق التأثير صغيرًا. تفترض إعدادات Markaestro الافتراضية أن المتصل برنامج قد يكون مخطئًا.

Facebook وInstagram وTikTok يدوية أولًا

تستخدم المنشورات التي ينشئها وكيلك لهذه القنوات افتراضيًا manual_reminder: لا تستدعي Markaestro أبدًا واجهة المنصة نيابة عنها. يُنقل النشر المنشور إلى قائمة انتظار 'للنشر' في مساحة العمل، حيث يقوم شخص بتنزيل الوسائط والنشر بشكل أصلي والتأكيد، بحيث يبدو المنشور تمامًا كما لو صُنع يدويًا، ويراه إنسان قبل وجوده علنيًا. يمكن لوكيل اختيار منشور واحد للنشر عبر API الرسمية باستخدام deliveryMode: "direct_publish"، وعلى TikTok يعني ذلك التسليم إلى صندوق وارد المنشئ، وليس أبدًا منشورًا علنيًا دون إشراف. تنشر LinkedIn وThreads وPinterest برمجيًا بمجرد أن يطلب وكيلك ذلك صراحة.

قلّص نطاق المفتاح

اختر فقط النطاقات التي يحتاجها الوكيل: products.read وmedia.write وposts.read وposts.write وposts.publish وjob_runs.read وwebhooks.manage. يحصل وكيل بحثي يقرأ التقويم فقط على posts.read ولا شيء آخر.

امنحه صلاحية

يمكن إنشاء المفاتيح بصلاحية. يتصرف المفتاح منتهي الصلاحية تمامًا مثل المُلغى، بحيث يتوقف المفتاح الذي يتسرب من بيئة وكيل عن العمل من تلقاء نفسه.

التدوير والإلغاء

دوّر مفتاحًا في مكانه أو ألغه تمامًا من الإعدادات ← API. يعرض كل مفتاح وقت آخر استخدام له وحجم الطلبات، بحيث يكون الوكيل الذي يصمت، أو يخرج عن السيطرة، مرئيًا.

تُفرض حدود المعدل

60 طلبًا في الدقيقة لكل نقطة نهاية و240 في الدقيقة لكل مفتاح. تحمل كل استجابة X-RateLimit-Limit وRemaining- وReset-؛ يحمل 429 Retry-After. احترمه بدلًا من الإلحاح.

Markaestro لا تكتب نيابة عنك أبدًا

لا توجد خطوة توليد. يأتي التعليق من وكيلك، وتأتي الوسائط من مكتبتك أو من خط أنابيب وكيلك. Markaestro هي اليدان، لا الصوت.

الحذف يتم من جانب Markaestro

حذف منشور مجدول يلغيه قبل أن يُرسل. حذف منشور منشور يوقف فقط تتبع Markaestro له، يبقى المنشور الحي حتى يزيله شخص ما على المنصة.

معالجة الفشل

علّمه أي الأخطاء تستحق إعادة المحاولة

كل استجابة خطأ هي JSON برمز error ثابت وrequestId. اجعل وكيلك يقتبس requestId عند الإبلاغ عن فشل، فهذا ما يحتاجه الدعم لتتبّع الاستدعاء.

الحالةالرمزما ينبغي للوكيل فعله
401UNAUTHENTICATEDالمفتاح مفقود أو مُلغى أو منتهي الصلاحية. توقف واطلب من إنسان مفتاحًا جديدًا، إعادة المحاولة لن تساعد.
403FORBIDDENيفتقر المفتاح إلى النطاق لهذا الاستدعاء. أبلغ عن الاستدعاء الذي فشل؛ تُغيّر النطاقات في الإعدادات ← API.
403API_KEY_NOT_BOUND_TO_PRODUCTمفتاح صادر قبل ربط العلامة التجارية. اطلب مفتاحًا بديلًا.
400VALIDATION_*خالفت الحمولة قاعدة قناة (وسائط مفقودة، وضع تسليم خاطئ، scheduled_at خاطئ). صحّح الطلب؛ لا تعد المحاولة دون تغيير.
400VALIDATION_IDEMPOTENCY_KEY_REUSEDأُرسل نفس Idempotency-Key بنص مختلف. أصدر مفتاحًا جديدًا لكل طلب مميز.
400VALIDATION_POST_IS_PUBLISHINGحاول حذف منشور بينما مهمة نشر قيد التنفيذ. انتظر حتى تستقر المهمة، ثم احذف.
409VALIDATION_POST_ALREADY_PUBLISHINGمهمة نشر لهذا المنشور موجودة بالفعل في قائمة الانتظار. لا تنشر مرة أخرى، استعلم بدلًا من ذلك عن المهمة الحالية.
402SUBSCRIPTION_REQUIREDلا توجد خطة نشطة مرتبطة بمساحة العمل. اطلب من مالك مساحة العمل مراجعة الفوترة في الإعدادات.
402QUOTA_EXCEEDED_MEDIA_UPLOADSوصلت مساحة العمل إلى حصتها الشهرية للرفع. توقف عن الرفع وأبرز ذلك، لا تزال الوسائط الحالية تُنشر.
404NOT_FOUNDالمعرّف خارج علامة هذا المفتاح التجارية. تمت الإجابة بـ404 بدلًا من 403 بحيث لا يمكن للمفاتيح استكشاف معرّفات لا تملكها.
429RATE_LIMITEDانتظر عدد الثواني المحدد في Retry-After، ثم أعد نفس الطلب بنفس Idempotency-Key.

استخدم مكدسك الخاص

إذا استطاع إجراء طلب HTTPS، يمكنه النشر

لا توجد مكتبة عميل خاصة بـMarkaestro لاعتمادها ولا إطار عمل للتوحيد القياسي عليه. رمز حامل، JSON للدخول، JSON للخروج.

Claude وClaude Agent SDK

أضف تعريفات الأدوات أعلاه إلى قائمة أدواتك. أشكال JSON Schema موجودة بالفعل بتنسيق استخدام أدوات Claude.

استدعاء الوظائف في OpenAI

تُطابق المخططات نفسها واحدًا لواحد تعريفات الوظائف، أعد تسمية input_schema إلى parameters.

عملاء MCP

Claude Code وClaude وCursor وChatGPT وGrok وGrok Bot وOpenClaw وHermes: أضف عنوان URL الخادم المستضاف وسجّل الدخول عبر المتصفح. وللعملاء الذين يدعمون stdio فقط، يشغّل npx -y @markaestro/mcp الأدوات الإحدى وثلاثين نفسها محليًا.

n8n وMake وZapier

كل نقطة نهاية هي طلب HTTP عادي برمز حامل. لا SDK، لا مراسم توقيع، لا رقصة OAuth للوكيل.

LangChain وLlamaIndex

أدوات REST قياسية. رفع الوسائط بخطوتين هو التدفق الوحيد متعدد الاستدعاءات، وهو سطران فقط.

مهمة cron وcurl

ليس كل وكيل بحاجة إلى إطار عمل. البدء السريع أعلاه تكامل كامل وعملي في أربعة أوامر.

امنح وكيلك شيئًا حقيقيًا ليفعله

اربط قنواتك، ثم اربط وكيلك: سجّل الدخول من عميل MCP، أو أنشئ مفتاحًا مرتبطًا بعلامة تجارية. أيٌّ منهما هو التكامل بأكمله.