المطورون
واجهة النشر العامة (API)
ارفع الوسائط، وأنشئ منشورات، وانشر إلى Facebook وInstagram وTikTok وLinkedIn وThreads وPinterest، وكل ذلك مقتصر على منتج عبر مفتاح API لمساحة العمل. الطريقة الموصى بها للتكامل هي Connect API، واجهة صغيرة ومسطّحة على /api/connect/v1 يمكن لمعظم أدوات الجدولة استهدافها كما هي.
هل تحتاج إلى تحكم كامل، نشر صريح، واستعلام عن حالة المهام، وويب هوكس موقّعة، ودفعات، وإعدادات لكل قناة؟ توفر واجهة /api/public/v1 المتقدمة أدناه كل ذلك. تشترك كلتاهما في المصادقة نفسها والمنتجات نفسها وخط أنابيب النشر نفسه؛ استخدم فقط هذه المسارات العامة المُصدَّرة (مسارات التطبيق الداخلية تتطلب مصادقة مستخدم Firebase وليست جزءًا من العقد العام).
Facebook وInstagram وTikTok يدوية أولًا حتى عبر API. تستخدم منشورات هذه القنوات افتراضيًا تسليم manual_reminder: لا تستدعي Markaestro واجهة المنصة أبدًا نيابة عنها. يُنقل النشر المنشور إلى قائمة انتظار 'للنشر' الخاصة بمساحة العمل، حيث يقوم المالك بتنزيل الوسائط والنشر بشكل أصلي والتأكيد. مرّر deliveryMode: "direct_publish" عند الإنشاء لاختيار النشر عبر API الرسمية. على TikTok يُستخدم التسليم إلى صندوق الوارد افتراضيًا، إلا عند ضبط settings.postMode على direct_post. تنشر LinkedIn وThreads وPinterest برمجيًا افتراضيًا.
يمكن أن تحتوي مساحات العمل على منتجات متعددة. يُربط كل مفتاح API بمنتج واحد عند إنشائه، بحيث تستهدف الاستدعاءات ذلك المنتج تلقائيًا وتُرفض الطلبات لأي منتج آخر.
هل تبني وكيل ذكاء اصطناعي؟
ابدأ بدلًا من ذلك بـدليل وكيل الذكاء الاصطناعي. يحتوي على مخططات أدوات جاهزة للنسخ واللصق، وملخص لموجه النظام، وقواعد إعادة المحاولة ومعالجة الأخطاء التي يحتاجها الوكيل، ودليل بدء سريع بأربعة أوامر. يمكن لوكيلك أيضًا قراءة /llms.txt مباشرة.
مواصفات قابلة للقراءة آليًا
كل نقطة نهاية وشكل طلب واستجابة وكل رمز خطأ، بصيغة OpenAPI 3.1. تُولَّد من المخططات نفسها التي تتحقق بها الواجهة، فلا يمكن أن تصف واجهة لا نقدّمها.
/api/connect/v1 يمكن لمعظم أدوات الجدولة استهدافها كما هي. تربط اصطلاح create-upload-url → PUT → post الشائع بمساحة العمل والمصادقة والمنتجات وخط أنابيب النشر نفسها كما في واجهة API الكاملة أدناه. اضبط عنوان URL الأساسي للعميل على /api/connect وصادق باستخدام مفتاح API لمساحة عمل مقتصر على منتج (النطاقات posts.read وposts.write وmedia.write)./api/connect/v1/social-accountsيعرض وجهات Facebook وInstagram وTikTok وLinkedIn المتصلة كحسابات مسطّحة، كل منها موسوم بمنتجه ليتمكن العملاء من التجميع والتمييز. لكل قناة مسارها المخصص، دون توزيع بين القنوات.
/api/connect/v1/productsيسرد العلامات التجارية (الاسم في التنسيق: products) مع حساباتها المتصلة متداخلة، منتقٍ يقدّم العلامة التجارية أولًا.
/api/connect/v1/media/create-upload-urlيُرجع عنوان URL موقّعًا قصير الأمد وأحادي الاستخدام لـPUT مع معرّف وسائط.
<upload_url>ارفع بايتات الصورة الخام إلى عنوان URL الموقّع. لا حاجة إلى مفتاح API، يُصرِّح التوقيع بذلك.
/api/connect/v1/postsينشئ مسودة لكل حساب مُحدد. اضبط is_draft=false مع scheduled_at لجدولة التسليم؛ تستخدم TikTok التسليم إلى صندوق وارد المنشئ.
/api/connect/v1/postsيسرد منشورات مساحة العمل بحالة مسطّحة وتعليق وعناوين URL للوسائط.
# 1. List connected accounts
curl "$MARKAESTRO_URL/api/connect/v1/social-accounts" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY"
# 2. Request a signed upload url, then PUT the bytes
curl -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": "slide-1.png" }'
curl -X PUT "<upload_url>" -H "Content-Type: image/png" --data-binary @slide-1.png
# 3. Create a draft post for one or more accounts
curl -X POST "$MARKAESTRO_URL/api/connect/v1/posts" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"caption": "New drop",
"media": ["ast_111", "ast_222"],
"social_accounts": ["prod_123#instagram:instagram:ig_123"]
}'كل حساب من /social-accounts موسوم بـproduct الخاص به، الاسم بتنسيق النقل لعلامة تجارية (يمكن أن يظهر الحساب نفسه ضمن عدة علامات تجارية)، ويشفّر id الخاص به productId#destinationId، أعده حرفيًا في social_accounts، وسيتوزع الطلب إلى منشور واحد لكل حساب. يُربط كل مفتاح بعلامة تجارية واحدة، بحيث يرى وينشر فقط إلى تلك العلامة. منشورات Facebook وInstagram وTikTok يدوية أولًا، تُنشأ كمسودات وتُنشر بشكل أصلي بواسطة مالك مساحة العمل من قائمة انتظار 'للنشر' في Markaestro، وليس أبدًا عبر واجهة المنصة. تنشر LinkedIn وThreads وPinterest برمجيًا بعد إجراء نشر صريح. تكون حالة المنشور واحدة من draft أو processing أو posted أو failed. تُعد Facebook وInstagram وLinkedIn وTikTok وThreads كل منها وجهتها المخصصة الخاصة، النشر إلى واحدة لا يتوزع أبدًا إلى أخرى. تتبّع حالة النشر عبر GET /api/connect/v1/posts.
متقدم: واجهة API العامة الكاملة
الواجهة الكاملة /api/public/v1، نشر صريح، ومهام غير متزامنة، وويب هوكس موقّعة، وإنشاء دفعات، وإعدادات لكل قناة. استخدمها عندما لا تكون Connect API كافية.
/api/public/v1/productsيسرد العلامات التجارية للمفتاح إضافة إلى القنوات المتاحة حاليًا لكل واحدة.
/api/public/v1/products/:id/destinationsيسرد وجهات النشر لتلك العلامة التجارية، بما في ذلك تسجيل دخول Instagram المستقل وصفحة Facebook وThreads وملف/صفحة LinkedIn ووجهات TikTok المتصلة.
/api/public/v1/media/upload-sessionsينشئ جلسة رفع مباشر مدتها 15 دقيقة باستخدام اسم الملف ونوع المحتوى والحجم الدقيق.
<uploadSession.uploadUrl>يرفع البايتات مباشرة إلى التخزين باستخدام ترويسة Content-Type المُعادة، دون مفتاح API.
/api/public/v1/media/upload-sessions/:id/finalizeيتحقق من النوع والحجم ويُرجع أصل الوسائط؛ ويمكن إعادة محاولة الجلسات المكتملة بأمان.
/api/public/v1/mediaرفع متعدد الأجزاء للتوافق. يُرجع معرّف أصل وعنوان URL مستضاف.
/api/public/v1/postsينشئ مسودة في مساحة العمل. تعتمد Facebook وInstagram وTikTok افتراضيًا على النشر اليدوي (deliveryMode manual_reminder)؛ مرّر deliveryMode direct_publish لاختيار النشر عبر API.
/api/public/v1/postsيسرد المنشورات، الأحدث أولًا. صفِّ باستخدام ?status=scheduled لرؤية ما هو في قائمة الانتظار، و?productId= للاقتصار على علامة تجارية واحدة. يقتصر المفتاح المرتبط بعلامة تجارية دائمًا على علامته الخاصة ويمكنه حذف productId.
/api/public/v1/posts/:idيُرجع حالة المنشور الحالية، ووضع التسليم، ونتائج النشر.
/api/public/v1/posts/:id/publishيضع مهمة نشر غير متزامنة في قائمة الانتظار. تصل المنشورات اليدوية إلى قائمة انتظار 'للنشر' في مساحة العمل للنشر الأصلي؛ تنشر LinkedIn وThreads وPinterest مباشرة؛ تنشر منشورات Meta المختارة عبر API الرسمية، وتستخدم منشورات TikTok المختارة التسليم إلى صندوق الوارد.
/api/public/v1/posts/:idيحذف المنشور من Markaestro. يستخدم نطاق posts.write الحالي. يُرجع 400 VALIDATION_POST_IS_PUBLISHING أثناء تنفيذ مهمة نشر. حذف منشور منشور لا يسحب النسخة الحية على المنصة.
/api/public/v1/job-runs/:idيُرجع queued أو running أو succeeded أو failed.
/api/public/v1/webhook-endpointsيسجّل وجهة ويب هوك، بحد أقصى 25 نقطة نهاية نشطة لكل مساحة عمل.
/api/public/v1/webhook-endpointsيسرد وجهات الويب هوك المسجّلة لنطاق مفتاح API ذلك.
/api/public/v1/webhook-endpoints/:idيعطّل وجهة ويب هوك.
curl "$MARKAESTRO_URL/api/public/v1/products" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY"destinationId المُرجع عندما يكون للمنتج وجهات متعددة، مثل ملف LinkedIn إضافة إلى صفحات.curl "$MARKAESTRO_URL/api/public/v1/products/prod_123/destinations" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY"# 1. Create a 15-minute upload session
UPLOAD=$(curl -s -X POST "$MARKAESTRO_URL/api/public/v1/media/upload-sessions" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"fileName":"launch-1.jpg","contentType":"image/jpeg","sizeBytes":184320}')
# 2. PUT bytes directly to uploadSession.uploadUrl with its returned headers
curl -X PUT "<upload_url>" -H "Content-Type: image/jpeg" --data-binary @launch-1.jpg
# 3. Finalize; the response contains asset.id for mediaAssetIds
curl -X POST "$MARKAESTRO_URL/api/public/v1/media/upload-sessions/<session_id>/finalize" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY""deliveryMode": "direct_publish" لاختيار هذا المنشور للنشر عبر API الرسمية.curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: post-001" \
-d '{
"channel": "instagram",
"caption": "Launch day carousel",
"mediaAssetIds": ["ast_123", "ast_124"],
"productId": "prod_123",
"destinationId": "instagram:instagram:ig_123"
}'deliveryMode: "platform_inbox" (أو direct_publish)، يرسل النشر الصريح المسودة بدلًا من ذلك إلى صندوق وارد المنشئ على TikTok.curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: post-tt-001" \
-d '{
"channel": "tiktok",
"caption": "Spring drop teaser",
"mediaAssetIds": ["ast_vid_123"],
"productId": "prod_123",
"destinationId": "tiktok:tiktok:tt_open_123"
}'post.action_required؛ تنشر LinkedIn وThreads وPinterest ومنشورات Meta المختارة مباشرة؛ وتضع منشورات TikTok المختارة التسليم إلى صندوق الوارد في قائمة الانتظار.curl -X POST "$MARKAESTRO_URL/api/public/v1/posts/pst_123/publish" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Idempotency-Key: publish-001"posts.read وposts.write.# The key is already bound to one brand
curl "$MARKAESTRO_URL/api/public/v1/posts?status=scheduled&limit=100" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY"
# Cancel one
curl -X DELETE "$MARKAESTRO_URL/api/public/v1/posts/pst_123" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY"{
"id": "evt_123",
"type": "post.action_required",
"createdAt": "2026-04-08T18:06:10.000Z",
"workspaceId": "ws_123",
"data": {
"postId": "pst_123",
"channel": "instagram",
"status": "platform_action_required",
"nextAction": "post_manually_from_reminder"
}
}منشورات نصية أو صور أو فيديو فقط. حتى 10 صور أو فيديو واحد لكل منشور. النشر اليدوي افتراضيًا؛ النشر المباشر عند الاختيار.
صورة أو فيديو واحد على الأقل، حتى 10 عناصر. يُنشر الفيديو الواحد كـReel. النشر اليدوي افتراضيًا؛ النشر المباشر عند الاختيار.
TikTok
صورة أو فيديو واحد على الأقل. حتى 35 صورة أو فيديو واحد. النشر اليدوي افتراضياً؛ المنشورات المفعّلة تذهب إلى صندوق وارد TikTok لدى المنشئ، أو مباشرةً إلى الملف الشخصي عبر postMode direct_post في TikTok.
نص، صورة واحدة، فيديو واحد، أو منشورات عضوية متعددة الصور حتى 20 صورة. استهدف إما الملف الشخصي المتصل أو صفحة مُدارة.
X
نص، وحتى أربع صور، أو GIF واحد، أو فيديو واحد. تُطبَّق ضوابط الرد لكل منشور، ويُحظر النشر عند استنفاد ميزانية تكاليف X لمساحة العمل.