تخطّي إلى المحتوى
واجهة برمجة التطبيقات للمطورين

أنشئ الأنشطة من نظامك الخاص

طلب POST واحد لكل نوع نشاط. أرسل محتواك بصيغة JSON، واحصل في المقابل على نشاط في حسابك على Puzzel.org ورابط يمكنك تسليمه للاعبين أو وضعه داخل iframe.

الرابط الأساسي
https://puzzel.org/api/public/v1
المصادقة
المفتاح والبريد الإلكتروني داخل المحتوى
نقاط النهاية
38 أنواع أنشطة
الحصة
10 أنشطة يوميًا

طلبك الأول

لا شيء لتثبيته ولا مصافحة أولية: أرسل محتوى JSON يتضمّن مفتاحك وبريدك الإلكتروني ومحتواك. يحمل الرد مفتاح النشاط الجديد والرابط الذي يُلعب عليه.

POST crossword
curl -X POST https://puzzel.org/api/public/v1/crossword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Crossword",
  "language": "ar",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

كل مثال في هذه الصفحة هو طلب كامل وقابل للتشغيل. استبدل المفتاح والمحتوى بما يخصّك وسيعمل كما هو.

المصادقة

لا رؤوس (headers) ولا رمز حامل (bearer token). ينتقل بيانا الاعتماد كلاهما داخل محتوى JSON لكل طلب، ولا يُقبل المفتاح إلا للحساب الذي يخصّه ذلك البريد الإلكتروني.

الحقلالنوعما يفعله
account_api_key
مطلوب
string
stringمفتاح API الخاص بحسابك. يُوضع في المحتوى، لا في رأس الطلب.
email
مطلوب
string
stringالعنوان الذي يسجّل به حسابك على Puzzel.org الدخول. لا يكون المفتاح صالحًا إلا معه.

يوجد مفتاحك في قسم الحساب من لوحة التحكم، خلف زر "إظهار".

تسجيل الدخول

تُمنح مفاتيح API عند بدء الاشتراك، لذا لا يملك الحساب المجاني مفتاحًا بعد.

عرض الخطط

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

محتوى الطلب

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

الحقلالنوعما يفعله
account_api_key
مطلوب
string
stringمفتاح API الخاص بحسابك. يُوضع في المحتوى، لا في رأس الطلب.
email
مطلوب
string
stringالعنوان الذي يسجّل به حسابك على Puzzel.org الدخول. لا يكون المفتاح صالحًا إلا معه.
title
اختياري
string
stringالاسم الذي يحمله النشاط في لوحة التحكم. اتركه فارغًا لتستخدم نقطة النهاية اسمها الاحتياطي الخاص.
language
اختياري
string
stringيحدّد فقط اللغة في الرابط الذي تحصل عليه — ولا يترجم أي شيء ترسله. تقرؤه الكلمات المخفية أيضًا لتبديل حروف الحشو إلى العربية عندما تكون قيمته "ar".
الافتراضي: "en"
activity_key
اختياري
string
stringاتركه فارغًا لإنشاء نشاط جديد. مرّر مفتاح نشاط تملكه بالفعل ليُعاد بناء ذلك النشاط بدلًا من ذلك.

settings كائن يحوي خيارات خاصة بكل نقطة نهاية. الخيارات التي تقرأها كل نقطة نهاية مذكورة معها أدناه؛ وأي شيء آخر تضعه فيها يُتجاهَل.

ما الذي يعود إليك

يردّ الطلب الناجح بالرمز 200 مع مفتاح النشاط الجديد والرابط الذي يُلعب عليه. وأي حالة أخرى تردّ بقيمة success مضبوطة على false ونص خطأ واحد.

نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
فشل
{
  "success": false,
  "error": "Invalid Email or API Key"
}

الرابط url الذي تحصل عليه هو عرض التضمين. استبدل embed بـ play لفتحه في صفحة كاملة، أو بـ build لفتحه في المحرِّر — يبقى المفتاح بعد p= كما هو.

الإنشاء مقابل التحديث

أرسل activity_key ليُعاد بناء النشاط الذي يمثّله في مكانه: يُستبدَل محتواه، ويُحدَّث اسمه وختم نسخته، ويبقى المفتاح نفسه كما هو — فتظل الروابط وأدوات التضمين التي شاركتها من قبل تعمل. أما النتائج ومكان المجلد وكل إعداد لا تكتبه نقطة النهاية بنفسها فتبقى كما كانت.

activity_key
{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "activity_key": "-Nq8sample_activity_key",
  "title": "Fruit crossword, week 2",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}
  • يُطبَّق title في كل تحديث، بما في ذلك قيمته الافتراضية — اتركه فارغًا ليُعاد تسمية النشاط باسم نقطة النهاية الاحتياطي.
  • تُعاد كتابة كتل الإعدادات التي تكتبها نقطة النهاية بنفسها من الصفر، لذا يعيد التحديث أيضًا ضبطها على القيم التي ترسلها، أو على القيم الافتراضية لنقطة النهاية.
  • لا يمكنك تحديث إلا الأنشطة التي يملكها حسابك. مفتاح حساب آخر يردّ بالرمز 403.
  • يكلّف التحديث مثل الإنشاء تمامًا: طلبًا واحدًا يُخصَم من حصة اليوم.

حد معدل الطلبات

10
10 أنشطة لكل حساب يوميًا

يُحتسَب كل طلب ناجح، سواء كان إنشاءً أو تحديثًا. وإذا تجاوزت الحد، يردّ الطلب التالي بالرمز 429 حتى تُصفَّر العدّادات.

تُصفَّر العدّادات مرة واحدة يوميًا بمهمة مجدولة، لا وفق نافذة متحركة مدتها 24 ساعة.

الأخطاء

تصل الأخطاء دائمًا بصيغة JSON بالحقلين نفسهما، ولا تصل أبدًا كصفحة HTML. نص الخطأ مكتوب ليقرأه إنسان — فهو يسمّي الحقل أو الحد الذي فشل.

الحالةما يعنيه
400
Bad Request
شيء ما في المحتوى مفقود أو غير صحيح الصياغة أو خارج النطاق المسموح. تسمّي الرسالة الحقل المعني.
401
Unauthorized
البريد الإلكتروني غير معروف، أو المفتاح لا يخصّ ذلك الحساب.
403
Forbidden
activity_key الذي أرسلته يخصّ حسابًا آخر.
429
Too Many Requests
استُنفدت حصة اليوم. تُصفَّر مرة واحدة يوميًا.
500
Server Error
لم يتمكّن المولّد من بناء لغز مما أرسلته — غالبًا بسبب قلة الكلمات، أو كلمات يتعذّر ترتيبها معًا.

نقاط النهاية

مسار واحد لكل نوع نشاط، جميعها POST، وجميعها تحت الرابط الأساسي نفسه. تسرد كل واحدة المحتوى الذي تحتاجه، والإعدادات التي تقرؤها، وطلبًا يمكنك تشغيله.

الكلمات والحروف

الكلمات المتقاطعة

يشابك إجاباتك في شبكة ويرقّم التعريفات نيابة عنك.

#
POST /api/public/v1/crossword من 2 إلى 80 عناصر في items
المحتوى

مصفوفة من الكلمات. يقرن كل عنصر الإجابة بالتعريف الذي يشير إليها.

تعود إلى الاسم الاحتياطي "Crossword API"

جدير بالمعرفة
  • تُستبعَد الإجابات الأقصر من حرفين قبل بناء الشبكة، ويجب أن يتبقى منها اثنتان على الأقل.
  • تُكتب الإجابات بأحرف كبيرة ويحصل المولّد على عشرين محاولة لترتيبها. وإن تعذّر عليه وضع كلمة واحدة يردّ الطلب بالرمز 500.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
hidden_solution
اختياري في settings
string
stringكلمة إضافية اختيارية. تُعلَّم حروفها في خانات الشبكة المكتملة ليجمعها اللاعبون بعد حل الكلمات المتقاطعة، لذا يجب أن يظهر كل حرف منها في الإجابات.
طلب مثال
POST crossword
curl -X POST https://puzzel.org/api/public/v1/crossword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Crossword",
  "language": "ar",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

الكلمات المخفية

يخفي كلماتك في شبكة حروف، بالاتجاهات والشكل اللذين تختارهما.

#
POST /api/public/v1/wordseeker من 2 إلى 40 عناصر في items
المحتوى

مصفوفة من الكلمات. يصبح نص التعريف قائمة الكلمات التي يعمل عليها اللاعبون.

تعود إلى الاسم الاحتياطي "Wordseeker API"

جدير بالمعرفة
  • تُستبعَد الإجابات الأقل من حرفين، وتُكتب كل إجابة بأحرف كبيرة قبل إدراجها في الشبكة.
  • تُحشى الشبكة بحروف لاتينية ما لم تكن قيمة language هي "ar"، التي تبدّل الحشو إلى العربية.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
hidden_solution
اختياري في settings
string
stringتتهجّى الحروف المتبقية هذه القيمة. كما يخبر ضبطها المولّد بترتيب الحل أولًا بدلًا من حشو أكبر عدد ممكن من الكلمات.
directions
اختياري في settings
string[]
string[]الاتجاهات التي يمكن أن تسير فيها الكلمة. اتركها فارغة لتسير الكلمات شرقًا وجنوبًا شرقيًا وجنوبًا فقط.
واحد من westeastnorthsouthnorthwestnortheastsouthwestsoutheast
الافتراضي: ["east", "southeast", "south"]
template
اختياري في settings
string
stringيقصّ الشبكة على شكل معيّن بدلًا من تركها مربّعة.
واحد من squarecirclecrossdiamondpyramidsmileystarcross_plus
طلب مثال
POST wordseeker
curl -X POST https://puzzel.org/api/public/v1/wordseeker \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wordseeker",
  "language": "ar",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "FRUIT",
    "directions": [
      "east",
      "south",
      "southeast"
    ],
    "template": "square"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordseeker/embed?p=-Nq8sample_activity_key",
  "message": "Wordseeker created successfully"
}

الأكروستيك

يرصّ إجاباتك بحيث يتهجّى عمود واحد كلمة مخفية.

#
POST /api/public/v1/acrostic من 1 إلى 40 عناصر في items
المحتوى

مصفوفة من الكلمات. يجب أن توفّر مجتمعةً كل حرف من الكلمة المخفية.

تعود إلى الاسم الاحتياطي "Acrostic API"

جدير بالمعرفة
  • إذا تعذّر على الإجابات توفير الحروف التي يحتاجها الحل، يردّ الطلب بالرمز 500 بدلًا من حفظ شبكة غير مكتملة.
  • يعيد المولّد ترتيب إجاباتك ليعمل العمود، لذا فالترتيب الذي ترسله ليس الترتيب الذي يراه اللاعبون.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
hidden_solution
مطلوب في settings
string
stringالكلمة التي يتهجّاها العمود المميَّز. لن تعمل نقطة النهاية هذه من دونها.
طلب مثال
POST acrostic
curl -X POST https://puzzel.org/api/public/v1/acrostic \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Acrostic",
  "language": "ar",
  "items": [
    {
      "answer": "PEACH",
      "description": "Fuzzy skin, sweet flesh",
      "type": "text"
    },
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "PLUM"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/acrostic/embed?p=-Nq8sample_activity_key",
  "message": "Acrostic created successfully"
}

الكلمات المبعثرة

api_e_word_scramble

#
POST /api/public/v1/word-scramble من 1 إلى 40 عناصر في items
المحتوى

api_c_word_scramble

تعود إلى الاسم الاحتياطي "Word Scramble API"

جدير بالمعرفة
  • الأنشطة المُنشأة عبر API يكون فيها إعداد خلط الترتيب مفعّلًا دائمًا، لذا فالترتيب الذي ترسله ليس الترتيب الذي يحصل عليه اللاعبون.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
hidden_solution
اختياري في settings
string
stringكلمة إضافية اختيارية يُدخلها اللاعبون بعد حل البقية.
طلب مثال
POST word-scramble
curl -X POST https://puzzel.org/api/public/v1/word-scramble \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Word Scramble",
  "language": "ar",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    },
    {
      "answer": "CHERRY",
      "description": "A small red stone fruit",
      "type": "text"
    },
    {
      "answer": "MELON",
      "description": "Big, green outside, sweet inside",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "FRUIT"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/word-scramble/embed?p=-Nq8sample_activity_key",
  "message": "Word Scramble created successfully"
}

لعبة المشنقة

يحوّل كلماتك أو عباراتك إلى جولات لتخمين الحروف.

#
POST /api/public/v1/hangman من 1 إلى 50 عناصر في items
المحتوى

مصفوفة من الكلمات أو العبارات القصيرة. التعريف هو التلميح الذي يراه اللاعبون.

تعود إلى الاسم الاحتياطي "Hangman API"

طلب مثال
POST hangman
curl -X POST https://puzzel.org/api/public/v1/hangman \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Hangman",
  "language": "ar",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/hangman/embed?p=-Nq8sample_activity_key",
  "message": "Hangman created successfully"
}

Wordle

يصنع لعبة تخمين الكلمة من كل كلمة ترسلها.

#
POST /api/public/v1/wordle من 1 إلى 50 عناصر في items
المحتوى

مصفوفة من الكلمات. يحصل اللاعبون على جولة واحدة لكل كلمة.

تعود إلى الاسم الاحتياطي "Wordle API"

جدير بالمعرفة
  • يُنشأ وإعداد التحقق من أن التخمينات كلمات حقيقية مفعّل. أوقفه في المحرِّر إذا كانت كلماتك أسماء أو مبتكَرة.
طلب مثال
POST wordle
curl -X POST https://puzzel.org/api/public/v1/wordle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wordle",
  "language": "ar",
  "items": [
    {
      "answer": "MELON",
      "description": "Sweet and green",
      "type": "text"
    },
    {
      "answer": "PEACH",
      "description": "Fuzzy and orange",
      "type": "text"
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordle/embed?p=-Nq8sample_activity_key",
  "message": "Wordle created successfully"
}

تمرين الطباعة

api_e_typing_practice

#
POST /api/public/v1/typing-practice من 1 إلى 50 عناصر في items
المحتوى

api_c_typing_practice

تعود إلى الاسم الاحتياطي "Typing Practice API"

طلب مثال
POST typing-practice
curl -X POST https://puzzel.org/api/public/v1/typing-practice \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Typing Practice",
  "language": "ar",
  "items": [
    {
      "answer": "The quick brown fox jumps over the lazy dog",
      "description": "Every letter of the alphabet",
      "type": "text"
    },
    {
      "answer": "Pack my box with five dozen liquor jugs",
      "description": "Another pangram",
      "type": "text"
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
  "message": "Typing Practice created successfully"
}

عجلة الحظ

api_e_wheel_of_fortune

#
POST /api/public/v1/wheel-of-fortune من 1 إلى 50 عناصر في items
المحتوى

api_c_wheel_of_fortune

تعود إلى الاسم الاحتياطي "Wheel of Fortune API"

جدير بالمعرفة
  • يُنشأ بإعداد "إظهار النتيجة في العجلة فقط"، لذا تُقرأ النتيجة من العجلة بدلًا من إعلانها بجانبها.
طلب مثال
POST wheel-of-fortune
curl -X POST https://puzzel.org/api/public/v1/wheel-of-fortune \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Wheel of Fortune",
  "language": "ar",
  "items": [
    {
      "answer": "Read a page aloud",
      "description": "Segment 1",
      "type": "text"
    },
    {
      "answer": "Name three fruits",
      "description": "Segment 2",
      "type": "text"
    },
    {
      "answer": "Spell it backwards",
      "description": "Segment 3",
      "type": "text"
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wheel-of-fortune/embed?p=-Nq8sample_activity_key",
  "message": "Wheel of Fortune created successfully"
}

الكلمات المتقاطعة السويدية

كلمات متقاطعة سويدية: التعريفات داخل الشبكة، ويشير سهم من كل تعريف إلى إجابته.

#
POST /api/public/v1/arrowword من 2 إلى 80 عناصر في items
المحتوى

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

تعود إلى الاسم الاحتياطي "Arrowword API"

الإعدادات التي تقرؤها
الحقلالنوعما يفعله
hidden_solution
اختياري في settings
string
stringكلمة إضافية اختيارية. تُعلَّم حروفها في خانات الشبكة المكتملة، لذا يجب أن يظهر كل حرف منها في الإجابات.
طلب مثال
POST arrowword
curl -X POST https://puzzel.org/api/public/v1/arrowword \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Arrowword",
  "language": "ar",
  "items": [
    {
      "answer": "Stockholm",
      "description": "Capital of Sweden",
      "type": "text"
    },
    {
      "answer": "Oslo",
      "description": "Capital of Norway",
      "type": "text"
    },
    {
      "answer": "Helsinki",
      "description": "Capital of Finland",
      "type": "text"
    }
  ],
  "settings": {
    "hidden_solution": "North"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/arrowword/embed?p=-Nq8sample_activity_key",
  "message": "Arrowword created successfully"
}

Strands

شبكة ينتمي كل حرف فيها إلى كلمة من موضوع واحد، مع كلمة واحدة تسمّي الموضوع وتمتد من حافة إلى حافة.

#
POST /api/public/v1/strands من 2 إلى 24 عناصر في items
المحتوى

مصفوفة من كلمات الموضوع. يجب أن تملأ حروفها مع حروف Spangram اللوحة تمامًا.

تعود إلى الاسم الاحتياطي "Strands API"

جدير بالمعرفة
  • يجب أن يبلغ مجموع حروف كل الكلمات مع Spangram بالضبط 30 أو 35 أو 36 أو 40 أو 42 أو 45 أو 48 أو 49 أو 50 أو 54 أو 56 أو 60 أو 63 أو 64 أو 70 أو 72 أو 80. أي عدد آخر يردّ بالرمز 400 ويذكر كم حرفًا عليك أن تضيف أو تحذف.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
theme
اختياري في settings
string
stringاللغز المعروض فوق الشبكة. إن تركته فارغًا يرى اللاعبون العنوان.
spangram
اختياري في settings
string
stringالكلمة أو العبارة التي تسمّي الموضوع وتعبر اللوحة من حافة إلى الحافة الأخرى.
طلب مثال
POST strands
curl -X POST https://puzzel.org/api/public/v1/strands \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Strands",
  "language": "ar",
  "items": [
    {
      "answer": "whisk",
      "type": "text"
    },
    {
      "answer": "ladle",
      "type": "text"
    },
    {
      "answer": "spatula",
      "type": "text"
    },
    {
      "answer": "grater",
      "type": "text"
    },
    {
      "answer": "peeler",
      "type": "text"
    },
    {
      "answer": "skillet",
      "type": "text"
    }
  ],
  "settings": {
    "theme": "What the cook reaches for",
    "spangram": "Kitchen tools"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/strands/embed?p=-Nq8sample_activity_key",
  "message": "Strands created successfully"
}

استرجاع الأسماء

api_e_name_them_all

#
POST /api/public/v1/name-them-all من 1 إلى 250 عناصر في items
المحتوى

api_c_name_them_all

تعود إلى الاسم الاحتياطي "Name Them All API"

جدير بالمعرفة
  • العنصر كائن له answer، وله اختياريًا aliases (تهجئات أخرى تُقبل) وdescription (التلميح) وgroup. تُتجاهل حالة الأحرف والعلامات فوق الحروف وعلامات الترقيم عند فحص الاسم.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
list_match_mode
اختياري في settings
string
stringهل يُحتسب الاسم لحظة كتابته، أم عند الضغط على Enter فقط.
واحد من while_typingon_enter
الافتراضي: "while_typing"
list_slot_hint
اختياري في settings
string
stringما تكشفه الخانة الفارغة: لا شيء، أو طول الاسم، أو حرفه الأول، أو التلميح الذي كتبته.
واحد من nonelengthfirst_letterhint
الافتراضي: "none"
list_arrange
اختياري في settings
string
stringعمود لكل مجموعة، أو قائمة واحدة.
واحد من groupsone_list
الافتراضي: "groups"
list_allow_give_up
اختياري في settings
boolean
booleanيعرض زر استسلام ينهي المحاولة ويكشف ما فات.
الافتراضي: false
طلب مثال
POST name-them-all
curl -X POST https://puzzel.org/api/public/v1/name-them-all \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Name Them All",
  "language": "ar",
  "items": [
    {
      "answer": "United Kingdom",
      "aliases": [
        "UK",
        "Great Britain",
        "Britain"
      ],
      "group": "Islands"
    },
    {
      "answer": "Ireland",
      "aliases": [
        "Éire"
      ],
      "group": "Islands"
    },
    {
      "answer": "Côte d'Azur's neighbour Monaco",
      "aliases": [
        "Monaco"
      ],
      "description": "The smallest one",
      "group": "Mainland"
    }
  ],
  "settings": {
    "list_slot_hint": "first_letter",
    "list_match_mode": "on_enter",
    "list_allow_give_up": true
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/name-them-all/embed?p=-Nq8sample_activity_key",
  "message": "Name them all list created successfully"
}
البطاقات والأزواج

لعبة الذاكرة

بطاقات مقلوبة يقلبها اللاعبون ويطابقونها في أزواج.

#
POST /api/public/v1/memory من 2 إلى 30 عناصر في items
المحتوى

مصفوفة من الأزواج. يحمل كل زوج البطاقتين اللتين تنتميان معًا.

تعود إلى الاسم الاحتياطي "Memory Game API"

جدير بالمعرفة
  • البطاقة كائن له type وvalue. استخدم "text" للكلمات، أو "image" أو "audio" أو "youtube" أو "link" مع رابط في value، وأضف alt لوصف.
طلب مثال
POST memory
curl -X POST https://puzzel.org/api/public/v1/memory \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Memory Game",
  "language": "ar",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/memory/embed?p=-Nq8sample_activity_key",
  "message": "Memory game created successfully"
}

المطابقة

api_e_matching_pairs

#
POST /api/public/v1/matching-pairs من 2 إلى 30 عناصر في items
المحتوى

api_c_matching_pairs

تعود إلى الاسم الاحتياطي "Matching Game API"

جدير بالمعرفة
  • البطاقة كائن له type وvalue. استخدم "text" للكلمات، أو "image" أو "audio" أو "youtube" أو "link" مع رابط في value، وأضف alt لوصف.
طلب مثال
POST matching-pairs
curl -X POST https://puzzel.org/api/public/v1/matching-pairs \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Matching Game",
  "language": "ar",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/matching-pairs/embed?p=-Nq8sample_activity_key",
  "message": "Matching pairs game created successfully"
}

بطاقات المراجعة

api_e_flash_cards

#
POST /api/public/v1/flash-cards من 1 إلى 150 عناصر في items
المحتوى

api_c_flash_cards

تعود إلى الاسم الاحتياطي "Flash Cards API"

جدير بالمعرفة
  • تخزّن نقطة النهاية عدد البطاقات نفسه الذي ترسله، لذا أرسل بطاقتين بالضبط لكل عنصر — الوجه الأمامي ثم الخلفي.
  • البطاقة كائن له type وvalue. استخدم "text" للكلمات، أو "image" أو "audio" أو "youtube" أو "link" مع رابط في value، وأضف alt لوصف.
طلب مثال
POST flash-cards
curl -X POST https://puzzel.org/api/public/v1/flash-cards \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Flash Cards",
  "language": "ar",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/flash-cards/embed?p=-Nq8sample_activity_key",
  "message": "Flash Cards created successfully"
}

لعبة التصنيف

بطاقات تُصنَّف في الفئة التي تنتمي إليها.

#
POST /api/public/v1/categorize على الأقل 2 عناصر في items · على الأكثر 60 بطاقات في المجموع
المحتوى

مصفوفة من الفئات، لكل منها اسم والبطاقات التي تنتمي إليها.

تعود إلى الاسم الاحتياطي "Categorize Game API"

جدير بالمعرفة
  • تُحفَظ الفئة المُرسَلة بلا اسم باسم "فئة بلا عنوان"، لذا أرسل اسمًا دائمًا.
  • البطاقة كائن له type وvalue. استخدم "text" للكلمات، أو "image" أو "audio" أو "youtube" أو "link" مع رابط في value، وأضف alt لوصف.
طلب مثال
POST categorize
curl -X POST https://puzzel.org/api/public/v1/categorize \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Categorize Game",
  "language": "ar",
  "items": [
    {
      "name": "Red fruits",
      "cards": [
        {
          "type": "text",
          "value": "Strawberry"
        },
        {
          "type": "text",
          "value": "Cherry"
        }
      ]
    },
    {
      "name": "Yellow fruits",
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "Lemon"
        }
      ]
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/categorize/embed?p=-Nq8sample_activity_key",
  "message": "Categorize game created successfully"
}

إعادة الترتيب

تسلسل يجب على اللاعبين إعادة ترتيبه.

#
POST /api/public/v1/reorder على الأقل 1 عناصر في items · على الأكثر 60 بطاقات في المجموع
المحتوى

مصفوفة من التسلسلات. يحمل كل منها بطاقاته بالترتيب الصحيح.

تعود إلى الاسم الاحتياطي "Reorder Game API"

جدير بالمعرفة
  • يُخزَّن الترتيب الذي ترسله بوصفه الترتيب الصحيح — رقم واحد أولًا.
  • البطاقة كائن له type وvalue. استخدم "text" للكلمات، أو "image" أو "audio" أو "youtube" أو "link" مع رابط في value، وأضف alt لوصف.
طلب مثال
POST reorder
curl -X POST https://puzzel.org/api/public/v1/reorder \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Reorder Game",
  "language": "ar",
  "items": [
    {
      "name": "From seed to fruit",
      "cards": [
        {
          "type": "text",
          "value": "Plant the seed"
        },
        {
          "type": "text",
          "value": "Water it"
        },
        {
          "type": "text",
          "value": "Watch it grow"
        },
        {
          "type": "text",
          "value": "Pick the fruit"
        }
      ]
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/reorder/embed?p=-Nq8sample_activity_key",
  "message": "Reorder game created successfully"
}

البينغو

بينغو للفصل يناديه مقدّم اللعبة مباشرةً: يحصل كل لاعب على بطاقة تُسحب من عناصرك.

#
POST /api/public/v1/bingo لا تأخذ أي items
المحتوى

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

تعود إلى الاسم الاحتياطي "Bingo API"

جدير بالمعرفة
  • العنصر كائن له value، وله اختياريًا type ("text" أو "image" أو "audio" مع رابط في value)، وdescription (الدليل الذي يقرؤه مقدّم اللعبة في وضع الأدلة) وalt.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
mode
اختياري في settings
string
stringما يملأ الخانات: عناصرك، أو عناصرك يُنادى عليها بدليلها، أو أرقام عادية (لا تحتاج إلى عناصر).
واحد من itemscluesnumbers
الافتراضي: "items"
rows
اختياري في settings
number
numberعدد الصفوف في كل بطاقة، من 2 إلى 5.
الافتراضي: 3
columns
اختياري في settings
number
numberعدد الأعمدة في كل بطاقة، من 2 إلى 5.
الافتراضي: 3
highest_number
اختياري في settings
number
numberفي وضع الأرقام تُملأ البطاقات من 1 حتى هذا الرقم، وبحد أقصى 100. ميزة ضمن الخطط: من دون خطة يبقى 50.
الافتراضي: 50
طلب مثال
POST bingo
curl -X POST https://puzzel.org/api/public/v1/bingo \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Bingo",
  "language": "ar",
  "items": [
    {
      "type": "text",
      "value": "Paris",
      "description": "The capital of France"
    },
    {
      "type": "text",
      "value": "Berlin",
      "description": "The capital of Germany"
    },
    {
      "type": "text",
      "value": "Madrid",
      "description": "The capital of Spain"
    }
  ],
  "settings": {
    "mode": "clues",
    "rows": 3,
    "columns": 4,
    "highest_number": 75
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/bingo/embed?p=-Nq8sample_activity_key",
  "message": "Bingo created successfully"
}

عندي، من لديه

api_e_i_have_who_has

#
POST /api/public/v1/i-have-who-has من 3 إلى 40 عناصر في items
المحتوى

api_c_i_have_who_has

تعود إلى الاسم الاحتياطي "I Have, Who Has API"

جدير بالمعرفة
  • يجب ألا يتكرر أي سؤال ولا أي إجابة: فالطالب الذي بيده الإجابة لن يعرف أي سؤال تخصّه.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
chain_shape
اختياري في settings
string
stringالحلقة تُغلق على نفسها فيمكن لأي بطاقة أن تبدأ؛ أما الخط فيُفتح ببطاقة بداية وينتهي ببطاقة نهاية.
واحد من loopline
الافتراضي: "loop"
طلب مثال
POST i-have-who-has
curl -X POST https://puzzel.org/api/public/v1/i-have-who-has \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "I Have, Who Has",
  "language": "ar",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "3 × 4"
        },
        {
          "type": "text",
          "value": "12"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "6 × 7"
        },
        {
          "type": "text",
          "value": "42"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "9 × 9"
        },
        {
          "type": "text",
          "value": "81"
        }
      ]
    }
  ],
  "settings": {
    "chain_shape": "line"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/i-have-who-has/embed?p=-Nq8sample_activity_key",
  "message": "I have, who has created successfully"
}

قفل الأرقام

قفل أرقام: مجموعة من البطاقات، بعضها معًا يشكّل الرمز.

#
POST /api/public/v1/keypad من 1 إلى 30 عناصر في items
المحتوى

مصفوفة من البطاقات. تحمل البطاقات التي تدخل في الرمز موضعها فيه.

تعود إلى الاسم الاحتياطي "Keypad API"

جدير بالمعرفة
  • البطاقة كائن له value، وله اختياريًا type ("text" أو "image" أو "audio" مع رابط في value) وalt وcode_position: موضعها في الرمز، و1 هو الأول. يمكن أن تدخل البطاقة في الرمز مرة واحدة، ويجب أن توجد بطاقة واحدة على الأقل فيه.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
instructions
اختياري في settings
string
stringالسؤال أو اللغز الذي يجيب عنه الرمز، ويظهر مع البطاقات.
force_solution_in_correct_order
اختياري في settings
boolean
booleanيجب الضغط على البطاقات بالترتيب. وإن عُطّل يفتح القفل أي ترتيب للبطاقات الصحيحة.
الافتراضي: false
randomize_order
اختياري في settings
boolean
booleanيحصل كل لاعب على البطاقات بترتيب مخلوط.
الافتراضي: true
طلب مثال
POST keypad
curl -X POST https://puzzel.org/api/public/v1/keypad \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Keypad",
  "language": "ar",
  "items": [
    {
      "type": "text",
      "value": "4"
    },
    {
      "type": "text",
      "value": "7",
      "code_position": 2
    },
    {
      "type": "text",
      "value": "9"
    },
    {
      "type": "text",
      "value": "2",
      "code_position": 1
    }
  ],
  "settings": {
    "instructions": "Press the prime numbers, smallest first.",
    "force_solution_in_correct_order": true,
    "randomize_order": false
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/keypad/embed?p=-Nq8sample_activity_key",
  "message": "Keypad created successfully"
}

لعبة الرباعيات

لعبة الورق: يطلب اللاعبون البطاقات من بعضهم لجمع مجموعات من أربع.

#
POST /api/public/v1/quartets من 2 إلى 16 عناصر في items
المحتوى

مصفوفة من المجموعات. لكل مجموعة اسم وأربع بطاقات بالضبط.

تعود إلى الاسم الاحتياطي "Quartets API"

جدير بالمعرفة
  • البطاقة اسم، أو كائن له name وdescription (المعلومة المعروضة عليها). لا يجوز أن يتكرر اسم أي بطاقة في اللعبة: فاللاعبون يطلبون البطاقات بالاسم.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
type
اختياري في settings
string
stringلعبة عادية، أو لعبة تعلّم تُظهر كل بطاقة فيها معلومة. إن تُركت فارغة فهي learn عندما تحمل أي بطاقة description.
واحد من normallearn
طلب مثال
POST quartets
curl -X POST https://puzzel.org/api/public/v1/quartets \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Quartets",
  "language": "ar",
  "items": [
    {
      "name": "Birds",
      "cards": [
        {
          "name": "Owl",
          "description": "Hunts at night and turns its head three quarters of the way round."
        },
        {
          "name": "Robin",
          "description": "Sings through the winter."
        },
        {
          "name": "Woodpecker",
          "description": "Drums on trees up to twenty times a second."
        },
        {
          "name": "Jay",
          "description": "Buries thousands of acorns each autumn."
        }
      ]
    },
    {
      "name": "Mammals",
      "cards": [
        {
          "name": "Hedgehog",
          "description": "Carries about five thousand spines."
        },
        {
          "name": "Fox",
          "description": "Hears a mouse under the snow."
        },
        {
          "name": "Badger",
          "description": "Lives in a sett with its clan."
        },
        {
          "name": "Otter",
          "description": "Sleeps holding hands so it does not drift off."
        }
      ]
    }
  ],
  "settings": {
    "type": "learn"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quartets/embed?p=-Nq8sample_activity_key",
  "message": "Quartets game created successfully"
}
الأسئلة والإجابات

الاختبار

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

#
POST /api/public/v1/quiz من 1 إلى 100 عناصر في items
المحتوى

مصفوفة من الأسئلة. تحمل أسئلة الاختيار من متعدد إجاباتها؛ وتحمل الأسئلة المفتوحة الإجابة التي تقبلها.

تعود إلى الاسم الاحتياطي "Quiz API"

جدير بالمعرفة
  • question_type هو "multiple_choice"، وفيه يحمل الخيار الصحيح isCorrect بقيمة true؛ أو "true_false"، وهو مثله لكن بخيارين فقط، الأول صحيح والثاني خطأ؛ أو "open_answer"، الذي يستخدم correct_answer بدلًا من ذلك. وإن حُذف الحقل عومل السؤال كاختيار من متعدد.
  • تمرّر نقطة نهاية الاختبار settings مباشرة كما هي كتل إعدادات النشاط، لذا فهي ليست مكانًا لخيارات متفرقة — عدّل الاختبار في المحرِّر بعد ذلك.
طلب مثال
POST quiz
curl -X POST https://puzzel.org/api/public/v1/quiz \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Quiz",
  "language": "ar",
  "items": [
    {
      "question_type": "multiple_choice",
      "description": "Which fruit is yellow?",
      "answers": [
        {
          "type": "text",
          "description": "Banana",
          "isCorrect": true
        },
        {
          "type": "text",
          "description": "Cherry",
          "isCorrect": false
        }
      ]
    },
    {
      "question_type": "open_answer",
      "description": "What colour is a lemon?",
      "correct_answer": "Yellow",
      "explanation": "Lemons ripen from green to yellow."
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key",
  "message": "Quiz created successfully"
}

اللعبة اللوحية

api_e_board_game

#
POST /api/public/v1/board-game من 1 إلى 100 عناصر في items
المحتوى

api_c_board_game

تعود إلى الاسم الاحتياطي "Board Game API"

جدير بالمعرفة
  • question_type هو "multiple_choice"، وفيه يحمل الخيار الصحيح isCorrect بقيمة true؛ أو "true_false"، وهو مثله لكن بخيارين فقط، الأول صحيح والثاني خطأ؛ أو "open_answer"، الذي يستخدم correct_answer بدلًا من ذلك. وإن حُذف الحقل عومل السؤال كاختيار من متعدد.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
number_of_tiles
اختياري في settings
number
numberعدد مربّعات اللوح. بين 10 و75.
الافتراضي: 30
game_mode
اختياري في settings
string
stringما إذا كان اللاعبون يتسابقون إلى خط النهاية أم يجمعون عناصر في الطريق.
واحد من race_to_finishcollect_items
الافتراضي: "race_to_finish"
طلب مثال
POST board-game
curl -X POST https://puzzel.org/api/public/v1/board-game \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Board Game",
  "language": "ar",
  "items": [
    {
      "question_type": "multiple_choice",
      "description": "Which fruit is yellow?",
      "answers": [
        {
          "type": "text",
          "description": "Banana",
          "isCorrect": true
        },
        {
          "type": "text",
          "description": "Cherry",
          "isCorrect": false
        }
      ]
    },
    {
      "question_type": "open_answer",
      "description": "What colour is a lemon?",
      "correct_answer": "Yellow",
      "explanation": "Lemons ripen from green to yellow."
    }
  ],
  "settings": {
    "number_of_tiles": 30,
    "game_mode": "race_to_finish"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
  "message": "Board Game created successfully"
}

المتاهة

متاهة يمشي اللاعب عبرها: كل سؤال قاعة، وإجاباته هي الأبواب.

#
POST /api/public/v1/maze على الأقل 1 عناصر في items
المحتوى

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

تعود إلى الاسم الاحتياطي "Maze API"

الإعدادات التي تقرؤها
الحقلالنوعما يفعله
maze_width
اختياري في settings
string
stringطريقة ترتيب القاعات: عمود واحد، أو مربّع، أو أوسع.
واحد من narrownormalwide
الافتراضي: "normal"
maze_corridors
اختياري في settings
string
stringمقدار المتاهة الواقع بين سؤالين.
واحد من shortnormallong
الافتراضي: "normal"
maze_fog
اختياري في settings
string
stringإظهار المتاهة كاملة، أو فقط ما مرّ بجواره اللاعب.
واحد من offnear
الافتراضي: "off"
maze_wrong_door_pause
اختياري في settings
string
stringالمدة التي تبقى فيها الأبواب مغلقة بعد باب خاطئ.
واحد من noneshortlong
الافتراضي: "short"
maze_walk_there
اختياري في settings
boolean
booleanيعرض زرًا ينقل اللاعب إلى القاعة التالية.
الافتراضي: false
maze_seed
اختياري في settings
string
stringالبذرة التي تُولَّد منها المتاهة. البذرة نفسها مع الأسئلة نفسها تعطي المتاهة نفسها؛ وإن تُركت فارغة تُسحب متاهة جديدة.
طلب مثال
POST maze
curl -X POST https://puzzel.org/api/public/v1/maze \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Maze",
  "language": "ar",
  "items": [
    {
      "question_type": "multiple_choice",
      "description": "What is it called when water vapour turns back into liquid droplets?",
      "answers": [
        {
          "type": "text",
          "description": "Evaporation",
          "isCorrect": false
        },
        {
          "type": "text",
          "description": "Condensation",
          "isCorrect": true
        },
        {
          "type": "text",
          "description": "Transpiration",
          "isCorrect": false
        }
      ],
      "explanation": "Cooling vapour condenses into the droplets that make clouds."
    },
    {
      "question_type": "true_false",
      "description": "Most of the water on Earth is fresh water.",
      "answers": [
        {
          "type": "text",
          "description": "True",
          "isCorrect": false
        },
        {
          "type": "text",
          "description": "False",
          "isCorrect": true
        }
      ]
    }
  ],
  "settings": {
    "maze_width": "wide",
    "maze_corridors": "short",
    "maze_seed": "water123",
    "maze_fog": "near"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/maze/embed?p=-Nq8sample_activity_key",
  "message": "Maze created successfully"
}

Jeopardy

لوحة برنامج مسابقات: الفئات في الأعلى، وتحتها أدلة تزيد قيمتها كلما نزلت.

#
POST /api/public/v1/jeopardy على الأقل 2 عناصر في items
المحتوى

مصفوفة من الفئات، من اليسار إلى اليمين. لكل فئة اسم وأدلتها من الصف الأعلى إلى الأسفل.

تعود إلى الاسم الاحتياطي "Jeopardy API"

جدير بالمعرفة
  • الدليل سؤال بالشكل الذي تأخذه نقطة نهاية الاختبار، من نوع open_answer ما لم يُذكر غير ذلك، مع correct_answer وaliases اختياريًا. ويمكن أن يحمل أيضًا value (قيمته الخاصة) وdaily_double. القيمة null تترك الخانة فارغة.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
jeopardy_buzzer_mode
اختياري في settings
string
stringمن يلعب وكيف: يديرها المقدّم من لوحة مقدّم اللعبة، أو يضغط اللاعبون الجرس من هواتفهم، أو يخوض كل لاعب اللوحة بمفرده.
واحد من hostphonessolo
الافتراضي: "host"
jeopardy_contestants
اختياري في settings
string
stringهل تتحدث لوحة مقدّم اللعبة عن فرق أم عن لاعبين.
واحد من teamsplayers
الافتراضي: "teams"
jeopardy_value_step
اختياري في settings
number
numberقيمة كل صف: قيمة الدليل هي هذا الرقم مضروبًا في رقم صفه. من 50 إلى 500، بخطوات 50.
الافتراضي: 100
jeopardy_answer_time
اختياري في settings
number
numberعدد الثواني المتاحة للإجابة بعد فتح الدليل، حتى 300. القيمة 0 تعني بلا مؤقّت.
الافتراضي: 20
jeopardy_wrong_answer_costs
اختياري في settings
boolean
booleanالإجابة الخاطئة تخصم قيمة الدليل من النقاط.
الافتراضي: false
jeopardy_reveal_on_timeout
اختياري في settings
boolean
booleanتعرض اللوحة الإجابة بنفسها عند انتهاء الوقت.
الافتراضي: false
jeopardy_require_question_form
اختياري في settings
boolean
booleanيذكّر اللاعبين بالإجابة في صورة سؤال.
الافتراضي: false
طلب مثال
POST jeopardy
curl -X POST https://puzzel.org/api/public/v1/jeopardy \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Jeopardy",
  "language": "ar",
  "items": [
    {
      "name": "Planets",
      "questions": [
        {
          "question_type": "open_answer",
          "description": "The planet closest to the Sun.",
          "correct_answer": "Mercury"
        },
        {
          "question_type": "open_answer",
          "description": "It is known as the red planet.",
          "correct_answer": "Mars",
          "explanation": "Iron oxide in its soil gives it the colour."
        },
        {
          "question_type": "multiple_choice",
          "description": "This planet has the most confirmed moons.",
          "answers": [
            {
              "description": "Jupiter",
              "isCorrect": false
            },
            {
              "description": "Saturn",
              "isCorrect": true
            },
            {
              "description": "Neptune",
              "isCorrect": false
            }
          ],
          "daily_double": true
        }
      ]
    },
    {
      "name": "Moons",
      "questions": [
        {
          "question_type": "open_answer",
          "description": "The only world besides Earth that people have walked on.",
          "correct_answer": "The Moon",
          "aliases": [
            "Luna"
          ]
        },
        null,
        {
          "question_type": "name_them_all",
          "description": "Name the four Galilean satellites.",
          "answers": [
            {
              "description": "Io"
            },
            {
              "description": "Europa"
            },
            {
              "description": "Ganymede",
              "aliases": [
                "Ganymedes"
              ]
            },
            {
              "description": "Callisto"
            }
          ],
          "required_count": 3,
          "value": 500
        }
      ]
    }
  ],
  "settings": {
    "jeopardy_buzzer_mode": "solo",
    "jeopardy_value_step": 200,
    "jeopardy_wrong_answer_costs": true
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jeopardy/embed?p=-Nq8sample_activity_key",
  "message": "Jeopardy board created successfully"
}

الفيديو التفاعلي

api_e_interactive_video

#
POST /api/public/v1/interactive-video من 1 إلى 50 عناصر في items
المحتوى

api_c_interactive_video

تعود إلى الاسم الاحتياطي "Interactive Video API"

جدير بالمعرفة
  • النافذة كائن له time (بالثواني، أو "1:23") وkind ("question" ما لم يُذكر "note" أو "think" أو "chapter") وdescription. السؤال هو سؤال بالشكل الذي تأخذه نقطة نهاية الاختبار، ويمكن أن يحمل rewind_to: الموضع الذي يُعاد التشغيل منه بعد إجابة خاطئة.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
video_url
مطلوب في settings
string
stringالفيديو: صفحة على YouTube أو Vimeo أو Bunny Stream، أو رابط مباشر لملف mp4 أو webm أو mov.
video_duration
اختياري في settings
number
numberمدة الفيديو بالثواني. إذا ذُكرت، تُرفض أي نافذة تقع بعد نهايته.
طلب مثال
POST interactive-video
curl -X POST https://puzzel.org/api/public/v1/interactive-video \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Interactive Video",
  "language": "ar",
  "items": [
    {
      "time": 5,
      "kind": "chapter",
      "description": "Evaporation"
    },
    {
      "time": 42.5,
      "kind": "question",
      "question_type": "multiple_choice",
      "description": "What turns liquid water into vapour?",
      "answers": [
        {
          "type": "text",
          "description": "Heat from the sun",
          "isCorrect": true
        },
        {
          "type": "text",
          "description": "Wind from the north",
          "isCorrect": false
        },
        {
          "type": "text",
          "description": "Salt in the sea",
          "isCorrect": false
        }
      ],
      "explanation": "The sun warms the surface and the water evaporates.",
      "rewind_to": 20
    }
  ],
  "settings": {
    "video_url": "https://www.youtube.com/watch?v=al-do-HGuIk",
    "video_duration": 180,
    "video_allow_skipping": true
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/interactive-video/embed?p=-Nq8sample_activity_key",
  "message": "Interactive video created successfully"
}
الجمل والأرقام

لغز الشيفرة

يحوّل جملة إلى شيفرة يجب فكّها، حرفًا واحدًا في كل مرة.

#
POST /api/public/v1/cryptogram لا تأخذ أي items
المحتوى

جملة واحدة، في حقل sentence. لا تأخذ نقطة النهاية هذه أي items.

تعود إلى الاسم الاحتياطي "Cryptogram API"

جدير بالمعرفة
  • يُتجاهَل أي شيء ترسله في items — يُبنى اللغز من الجملة وحدها.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
sentence
مطلوب
string
stringالجملة المراد تشفيرها. يفكّها اللاعبون حرفًا حرفًا.
helpers
اختياري في settings
string
stringالحروف التي تُمنح مجانًا كمدخل للحل: لا شيء، أو الأكثر شيوعًا، أو أحرف العلة، أو تلك التي تسردها بنفسك.
واحد من nonemost_commonvowelscustom
الافتراضي: "none"
character_list
اختياري في settings
string
stringالأبجدية التي يُبنى منها الشيفرة. إن تُركت فارغة، يختار التشفير أبجديته الخاصة.
extra_letters
اختياري في settings
string
stringالحروف التي تُمنح عندما تكون قيمة helpers هي "custom". تُتجاهَل في أوضاع المساعدة الأخرى.
hide_unused_characters
اختياري في settings
boolean
booleanيستبعد من المفتاح الحروف التي لا تستخدمها الجملة على الإطلاق.
الافتراضي: false
طلب مثال
POST cryptogram
curl -X POST https://puzzel.org/api/public/v1/cryptogram \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Cryptogram",
  "language": "ar",
  "sentence": "An apple a day keeps the doctor away",
  "settings": {
    "helpers": "vowels",
    "hide_unused_characters": false
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/cryptogram/embed?p=-Nq8sample_activity_key",
  "message": "Cryptogram created successfully"
}

تمرين الحساب

يخفي جملة خلف عمليات حسابية — حلّ العملية، تكشف الحرف.

#
POST /api/public/v1/calculation لا تأخذ أي items
المحتوى

جملة واحدة، في حقل sentence. لا تأخذ نقطة النهاية هذه أي items.

تعود إلى الاسم الاحتياطي "Calculation Game API"

جدير بالمعرفة
  • إذا كانت القيود ضيقة جدًا بحيث يتعذّر ترميز الجملة، يردّ الطلب بالرمز 400 طالبًا منك تخفيفها بدلًا من حفظ لغز غير مكتمل.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
sentence
مطلوب
string
stringالجملة التي يكشفها اللاعبون بحل العمليات الحسابية.
difficulty_level
اختياري في settings
number
numberأعلى ناتج يُسمح لعملية حسابية أن تصل إليه.
واحد من 20501001000
الافتراضي: "100"
operators
اختياري في settings
string[]
string[]العمليات التي يمكن أن تظهر. x تعني الضرب، و: تعني القسمة.
واحد من +-x:
الافتراضي: ["+", "-", "x", ":"]
max_operations
اختياري في settings
number
numberعدد العمليات التي يمكن أن تسلسلها عملية حسابية واحدة.
واحد من 123
الافتراضي: 1
number_difficulty
اختياري في settings
number
numberيحدّ الأرقام المفردة داخل العملية الحسابية. من 5 إلى 1000.
الافتراضي: 100
طلب مثال
POST calculation
curl -X POST https://puzzel.org/api/public/v1/calculation \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Calculation Game",
  "language": "ar",
  "sentence": "Fruit salad for everyone",
  "settings": {
    "difficulty_level": "100",
    "operators": [
      "+",
      "-",
      "x",
      ":"
    ],
    "max_operations": 1,
    "number_difficulty": 100
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/calculation/embed?p=-Nq8sample_activity_key",
  "message": "Calculation game created successfully"
}

السودوكو

يولّد شبكة محلولة، ثم يزيل منها بعض الأرقام.

#
POST /api/public/v1/sudoku لا تأخذ أي items
المحتوى

لا شيء. يصدر اللغز بأكمله من إعداديه الاثنين.

تعود إلى الاسم الاحتياطي "Sudoku API"

جدير بالمعرفة
  • لا ترسل items ولا sentence — الحجم والصعوبة هما المُدخل بأكمله.
  • لا يوفّر المحرِّر إعداد الصعوبة إلا للأحجام 2x3 و3x3 و3x4. أما API فيطبّقه على كل الأحجام، بما فيها 2x2 و4x4.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
size
اختياري في settings
string
stringحجم الكتلة الواحدة، مكتوبًا كصفوف × أعمدة — يعطي 3x3 الشبكة الكلاسيكية 9x9. لا تتحقق نقطة النهاية إلا من إمكانية تفسيره كرقمين، لذا التزم بالأحجام التي يوفّرها المحرِّر.
واحد من 2x22x33x33x44x4
الافتراضي: "3x3"
difficulty_level
اختياري في settings
string
stringعدد الأرقام المتروكة على اللوح للبدء منها.
واحد من easynormalhard
الافتراضي: "normal"
طلب مثال
POST sudoku
curl -X POST https://puzzel.org/api/public/v1/sudoku \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sudoku",
  "language": "ar",
  "settings": {
    "size": "3x3",
    "difficulty_level": "normal"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/sudoku/embed?p=-Nq8sample_activity_key",
  "message": "Sudoku created successfully"
}

العبارة المتساقطة

api_e_fallen_phrase

#
POST /api/public/v1/fallen-phrase لا تأخذ أي items
المحتوى

api_c_fallen_phrase

تعود إلى الاسم الاحتياطي "Fallen Phrase API"

الإعدادات التي تقرؤها
الحقلالنوعما يفعله
sentence
مطلوب
string
stringالعبارة المراد إخفاؤها: اقتباس أو مثل أو جملة أساسية. بحد أقصى 120 حرفًا ورقمًا.
columns
اختياري في settings
number
numberعرض اللوحة، من 8 إلى 18. كلما قلّ العرض تكدّست حروف أكثر في كل عمود وصار اللغز أصعب.
الافتراضي: 14
helpers
اختياري في settings
string
stringالحروف التي تبقى في الشبكة كمدخل للحل: لا شيء، أو الأكثر شيوعًا، أو أحرف العلة، أو تلك التي تسردها بنفسك.
واحد من nonemost_commonvowelscustom
الافتراضي: "none"
extra_letters
اختياري في settings
string
stringالحروف التي تُمنح عندما تكون قيمة helpers هي "custom".
طلب مثال
POST fallen-phrase
curl -X POST https://puzzel.org/api/public/v1/fallen-phrase \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Fallen Phrase",
  "language": "ar",
  "sentence": "Don't count your chickens before they hatch.",
  "settings": {
    "columns": 12,
    "helpers": "custom",
    "extra_letters": "ky"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/fallen-phrase/embed?p=-Nq8sample_activity_key",
  "message": "Fallen phrase created successfully"
}

جداول الضرب

api_e_times_tables

#
POST /api/public/v1/times-tables لا تأخذ أي items
المحتوى

api_c_times_tables

تعود إلى الاسم الاحتياطي "Times Tables API"

الإعدادات التي تقرؤها
الحقلالنوعما يفعله
tables
اختياري في settings
number[]
number[]جداول الضرب المراد التدرّب عليها. إن تُركت فارغة فهي من 1 إلى 10؛ وإضافة 11 أو 12 تجعل الشبكة 12 في 12.
واحد من 123456789101112
order
اختياري في settings
string
stringهل تسير الصفوف والأعمدة بالترتيب أم مخلوطة.
واحد من ascendingshuffled
الافتراضي: "ascending"
picture
اختياري في settings
string
stringالصورة التي تلوّنها الإجابات الصحيحة.
واحد من sailboatheartrockettreecatfishflowerhouse
الافتراضي: "sailboat"
players_choose_tables
اختياري في settings
boolean
booleanيتيح لكل لاعب أن يختار أيًّا من الجداول يتدرّب عليها.
الافتراضي: false
fill_same_sums
اختياري في settings
boolean
booleanإجابة صحيحة واحدة تملأ كل خانة تحمل العملية نفسها.
الافتراضي: true
طلب مثال
POST times-tables
curl -X POST https://puzzel.org/api/public/v1/times-tables \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Times Tables",
  "language": "ar",
  "settings": {
    "tables": [
      7,
      3,
      4
    ],
    "order": "shuffled",
    "seed": "k3x9q2ab",
    "picture": "rocket",
    "players_choose_tables": true,
    "fill_same_sums": false
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/times-tables/embed?p=-Nq8sample_activity_key",
  "message": "Times tables created successfully"
}

النص الناقص

api_e_fill_in_the_gap

#
POST /api/public/v1/fill-in-the-gap من 1 إلى 50 عناصر في items
المحتوى

api_c_fill_in_the_gap

تعود إلى الاسم الاحتياطي "Fill in the gap API"

جدير بالمعرفة
  • اكتب الجملة كاملة وضع علامتي * حول كل كلمة تريد حذفها: "Water boils at *100* degrees." عدة كلمات داخل زوج واحد من العلامتين تُعدّ فراغًا واحدًا. ويمكن أن يحمل العنصر أيضًا تعليمة تظهر فوق الجملة.
طلب مثال
POST fill-in-the-gap
curl -X POST https://puzzel.org/api/public/v1/fill-in-the-gap \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Fill in the gap",
  "language": "ar",
  "items": [
    {
      "sentence": "The capital of France is *Paris*, and the river that runs through it is the *Seine*."
    },
    {
      "sentence": "*Amsterdam* is the capital of the Netherlands, but the government sits in *The Hague*.",
      "instruction": "Two cities, one of them two words."
    },
    {
      "sentence": "The *Danube* flows through Vienna, Bratislava, *Budapest* and Belgrade."
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/fill-in-the-gap/embed?p=-Nq8sample_activity_key",
  "message": "Fill in the gap created successfully"
}

تحليل الجملة

جمل يصنّف فيها اللاعبون الكلمات: أقسام الكلام، أو أجزاء الجملة، أو تصنيفات من وضعك.

#
POST /api/public/v1/deconstruct من 1 إلى 50 عناصر في items
المحتوى

مصفوفة من الجمل. تُكتب كل كلمة مطلوب تصنيفها بصيغة [word](label).

تعود إلى الاسم الاحتياطي "Sentence analysis API"

جدير بالمعرفة
  • اكتب الجملة هكذا: "The [dog](noun) [barks](verb)." الكلمات التي بلا وسم تُعرض ولا يُسأل عنها. التصنيفات noun وverb وadjective وsubject تظهر لكل لاعب بلغته.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
categories
اختياري في settings
string[]
string[]التصنيفات التي يختار منها اللاعبون، بالترتيب. إن تُركت فارغة فهي التصنيفات المستخدمة في الجمل. أرسلها لإضافة تصنيف لا تحمله أي كلمة، أو لضبط الترتيب.
طلب مثال
POST deconstruct
curl -X POST https://puzzel.org/api/public/v1/deconstruct \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sentence analysis",
  "language": "ar",
  "items": [
    {
      "sentence": "The [old](adjective) [farmer](noun) [feeds](verb) the [hungry](adjective) [chickens](noun) [early](adverb).",
      "instruction": "Label the nouns, verbs, adjectives and adverbs."
    },
    {
      "sentence": "A [brown](adjective) [horse](noun) [jumped](verb) [quickly](adverb) over the [fence](noun)."
    },
    {
      "sentence": "[Two small lambs](subject) [sleep](verb) in the [barn](noun), and the [dog](noun) [watches](verb) [quietly](adverb)."
    }
  ],
  "settings": {
    "categories": [
      "noun",
      "verb",
      "adjective",
      "adverb",
      {
        "name": "subject",
        "color": "#224466"
      },
      "preposition"
    ]
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/deconstruct/embed?p=-Nq8sample_activity_key",
  "message": "Sentence analysis created successfully"
}

اللغز المنطقي

api_e_logic_puzzle

#
POST /api/public/v1/logic-puzzle على الأقل 3 عناصر في items
المحتوى

api_c_logic_puzzle

تعود إلى الاسم الاحتياطي "Logic Puzzle API"

جدير بالمعرفة
  • كل فئة تحتاج إلى العدد نفسه من العناصر، من 3 إلى 6، وكلها مختلفة. يمكن وسم فئة واحدة بـ ordered (أسعار، أوقات، أعمار) مع unit اختياري، وهذا يتيح للمولّد كتابة أدلة عن الأكثر والأقل ومقدار الفرق.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
story
اختياري في settings
string
stringالقصة التمهيدية المعروضة فوق الأدلة.
difficulty
اختياري في settings
string
stringأنواع الأدلة التي يجوز للمولّد استخدامها.
واحد من easymediumhard
الافتراضي: "easy"
hints
اختياري في settings
boolean
booleanيعرض زرًا يُظهر الخطوة التالية.
الافتراضي: true
auto_cross
اختياري في settings
boolean
booleanوضع علامة تطابق يشطب بقية صفها وعمودها.
الافتراضي: true
clue_mode
اختياري في settings
string
stringمن يكتب الأدلة التي يراها اللاعبون: تُولَّد من الجدول، أو جملك الخاصة في free_clues، أو لا شيء.
واحد من generatedfreenone
الافتراضي: "generated"
free_clues
اختياري في settings
string[]
string[]جمل الأدلة التي تكتبها أنت، تُعرض كما هي، مع clue_mode بقيمة "free". لا شيء يتحقق منها.
طلب مثال
POST logic-puzzle
curl -X POST https://puzzel.org/api/public/v1/logic-puzzle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Logic Puzzle",
  "language": "ar",
  "items": [
    {
      "name": "Baker",
      "items": [
        "Amira",
        "Jonas",
        "Priya",
        "Tobias"
      ]
    },
    {
      "name": "Cake",
      "items": [
        "Lemon drizzle",
        "Carrot cake",
        "Brownies",
        "Apple pie"
      ]
    },
    {
      "name": "Price",
      "items": [
        "$2",
        "$4",
        "$6",
        "$8"
      ],
      "ordered": true,
      "unit": "dollars"
    }
  ],
  "settings": {
    "story": "Four friends each baked one thing for the school bake sale and each set a different price. Who baked what, and what did it cost?",
    "difficulty": "medium"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/logic-puzzle/embed?p=-Nq8sample_activity_key",
  "message": "Logic puzzle created successfully"
}

البحث عن الكنز

api_e_scavenger_hunt

#
POST /api/public/v1/scavenger-hunt من 1 إلى 50 عناصر في items
المحتوى

api_c_scavenger_hunt

تعود إلى الاسم الاحتياطي "Scavenger Hunt API"

جدير بالمعرفة
  • الخطوة كائن له title وdescription وcode، وله اختياريًا accepted_codes (تهجئات أخرى تُقبل) وurl وlink_text. يُفحص الرمز دون اعتبار لحالة الأحرف والمسافات. أما الخريطة ذات الدبابيس فلا يمكن إضافتها إلا في المحرِّر.
طلب مثال
POST scavenger-hunt
curl -X POST https://puzzel.org/api/public/v1/scavenger-hunt \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Scavenger Hunt",
  "language": "ar",
  "items": [
    {
      "title": "Start at the front desk",
      "description": "Which year is carved above the entrance?",
      "code": "1897",
      "accepted_codes": [
        "eighteen ninety-seven"
      ]
    },
    {
      "title": "The quiet corner",
      "description": "Find the atlas shelf. What colour is the biggest atlas?",
      "code": "crimson",
      "accepted_codes": [
        "dark red"
      ]
    }
  ]
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/scavenger-hunt/embed?p=-Nq8sample_activity_key",
  "message": "Scavenger hunt created successfully"
}

التفكير المكاني

api_e_spatial_reasoning

#
POST /api/public/v1/spatial-reasoning من 1 إلى 50 عناصر في items
المحتوى

api_c_spatial_reasoning

تعود إلى الاسم الاحتياطي "Spatial Reasoning API"

جدير بالمعرفة
  • الكائنات والأهداف هي square, triangle, circle, hexagon, pentagon, star, diamond أو heart. العلاقات هي inside, outside, behind, in_front_of, right_of, left_of, above, below, same_color_as, different_color_from, larger_than أو smaller_than. القاعدة التي لا يمكن تحقيقها أبدًا تردّ بالرمز 400.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
clue_mode
اختياري في settings
string
stringالقواعد تُعرض صورًا أو جملًا.
واحد من visualtext
الافتراضي: "visual"
unique_object_picks
اختياري في settings
boolean
booleanيمكن وضع كل شكل مرة واحدة فقط.
الافتراضي: false
hide_color_picker
اختياري في settings
boolean
booleanلا يستطيع اللاعبون تغيير ألوان الأشكال.
الافتراضي: false
طلب مثال
POST spatial-reasoning
curl -X POST https://puzzel.org/api/public/v1/spatial-reasoning \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Spatial Reasoning",
  "language": "ar",
  "items": [
    {
      "rules": [
        {
          "object": "square",
          "relation": "inside",
          "target": "circle"
        }
      ]
    },
    {
      "rules": [
        {
          "object": "triangle",
          "relation": "above",
          "target": "square"
        },
        {
          "object": "star",
          "relation": "left_of",
          "target": "triangle"
        }
      ]
    }
  ],
  "settings": {
    "clue_mode": "text",
    "unique_object_picks": true,
    "hide_color_picker": false
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/spatial-reasoning/embed?p=-Nq8sample_activity_key",
  "message": "Spatial reasoning activity created successfully"
}

اللغز المصوّر

جمل مكتوبة على شكل صور: يقرأ اللاعبون الصور وتغييرات الحروف ويعيدونها إلى كلمات.

#
POST /api/public/v1/rebus من 1 إلى 30 عناصر في items
المحتوى

مصفوفة من الجمل. تسرد كل جملة الكلمات المرسومة صورًا؛ وكل كلمة أخرى تبقى بحروفها.

تعود إلى الاسم الاحتياطي "Rebus API"

جدير بالمعرفة
  • تُرسم الكلمة من أجزاء تتهجّاها معًا. للجزء الحروف التي يمثّلها (text)، وemoji، وshows: الكلمة التي تدل عليها الصورة ("broom" لصورة تمثّل "room"). يحسب Puzzel تغييرات الحروف. وقد يكون الجزء رمزًا بدلًا من ذلك، مثل 4 لـ "for".
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
rebus_commas
اختياري في settings
boolean
booleanيرسم الحرف الأول أو الأخير المحذوف فاصلة بجانب الصورة.
الافتراضي: false
طلب مثال
POST rebus
curl -X POST https://puzzel.org/api/public/v1/rebus \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Rebus",
  "language": "ar",
  "items": [
    {
      "sentence": "I sweep the room before the sunflower wilts.",
      "words": [
        {
          "word": "I",
          "parts": [
            {
              "text": "I",
              "kind": "sound",
              "emoji": "👁️"
            }
          ]
        },
        {
          "word": "room",
          "parts": [
            {
              "text": "room",
              "kind": "picture",
              "shows": "broom",
              "emoji": "🧹"
            }
          ]
        },
        {
          "word": "before",
          "parts": [
            {
              "text": "be",
              "kind": "picture",
              "shows": "bee",
              "emoji": "🐝"
            },
            {
              "text": "for",
              "kind": "sound",
              "glyph": "4"
            },
            {
              "text": "e",
              "kind": "letters"
            }
          ]
        },
        {
          "word": "the",
          "position": 6,
          "parts": [
            {
              "text": "the",
              "kind": "picture",
              "shows": "tree",
              "emoji": "🌳"
            }
          ]
        },
        {
          "word": "sunflower",
          "parts": [
            {
              "text": "sun",
              "kind": "picture",
              "shows": "sun",
              "emoji": "☀️"
            },
            {
              "text": "flower",
              "kind": "picture",
              "shows": "flower",
              "emoji": "🌸"
            }
          ]
        }
      ]
    }
  ],
  "settings": {
    "rebus_commas": true
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/rebus/embed?p=-Nq8sample_activity_key",
  "message": "Rebus created successfully"
}
الصور

الصورة المقطّعة

يقطّع صورة إلى قطع تُسحب لإعادة تجميعها.

#
POST /api/public/v1/jigsaw لا تأخذ أي items
المحتوى

رابط صورة واحد، في حقل image. لا تأخذ نقطة النهاية هذه أي items.

تعود إلى الاسم الاحتياطي "Jigsaw Game API"

جدير بالمعرفة
  • ينشئ API دائمًا صورة مقطّعة بحجم 4×4. عدد القطع والقطع غير المنتظمة والحواف المستقيمة إعدادات خاصة بالمحرِّر — إرسال rows أو columns هنا لا يفعل شيئًا.
  • يُخزَّن الرابط كما أرسلته ولا يُنسخ الملف أبدًا، لذا يجب أن يبقى قابلًا للوصول العام طالما ظل النشاط يُلعب.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
image
مطلوب
string
stringالرابط المطلق للصورة المراد تقطيعها. يُرسَل في المستوى الأعلى، لا داخل settings.
طلب مثال
POST jigsaw
curl -X POST https://puzzel.org/api/public/v1/jigsaw \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Jigsaw Game",
  "language": "ar",
  "image": "https://example.com/orchard.jpg"
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jigsaw/embed?p=-Nq8sample_activity_key",
  "message": "Jigsaw game created successfully"
}

اللغز المنزلق

يقسّم صورة إلى مربّعات تنزلق إلى مكانها.

#
POST /api/public/v1/slidingpuzzle لا تأخذ أي items
المحتوى

رابط صورة واحد، داخل settings. لا تأخذ نقطة النهاية هذه أي items.

تعود إلى الاسم الاحتياطي "Sliding Puzzle API"

جدير بالمعرفة
  • خلافًا للصورة المقطّعة، تقرأ نقطة النهاية هذه صورتها من settings.image. يُتجاهَل حقل image في المستوى الأعلى ويردّ الطلب بالرمز 400.
  • يُخزَّن الرابط كما أرسلته ولا يُنسخ الملف أبدًا، لذا يجب أن يبقى قابلًا للوصول العام طالما ظل النشاط يُلعب.
الإعدادات التي تقرؤها
الحقلالنوعما يفعله
image
مطلوب في settings
string
stringالرابط المطلق للصورة المراد تشويشها. خلافًا للصورة المقطّعة، يوجد هذا الحقل داخل settings.
طلب مثال
POST slidingpuzzle
curl -X POST https://puzzel.org/api/public/v1/slidingpuzzle \
  -H "Content-Type: application/json" \
  -d '{
  "account_api_key": "YOUR_API_KEY",
  "email": "you@example.com",
  "title": "Sliding Puzzle",
  "language": "ar",
  "settings": {
    "image": "https://example.com/orchard.jpg"
  }
}'
نجاح
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/slidingpuzzle/embed?p=-Nq8sample_activity_key",
  "message": "Sliding puzzle created successfully"
}

هل هناك خلل ما؟

أرسل الطلب الذي جرّبته والخطأ الذي حصلت عليه، وستحصل على إجابة حقيقية من الشخص الذي كتب نقطة النهاية.

راسل الدعم عبر البريد الإلكتروني