كل مثال في هذه الصفحة هو طلب كامل وقابل للتشغيل. استبدل المفتاح والمحتوى بما يخصّك وسيعمل كما هو.
المصادقة
لا رؤوس (headers) ولا رمز حامل (bearer token). ينتقل بيانا الاعتماد كلاهما داخل محتوى JSON لكل طلب، ولا يُقبل المفتاح إلا للحساب الذي يخصّه ذلك البريد الإلكتروني.
الحقل
النوع
ما يفعله
account_api_key
مطلوب
string
string
مفتاح API الخاص بحسابك. يُوضع في المحتوى، لا في رأس الطلب.
email
مطلوب
string
string
العنوان الذي يسجّل به حسابك على Puzzel.org الدخول. لا يكون المفتاح صالحًا إلا معه.
يوجد مفتاحك في قسم الحساب من لوحة التحكم، خلف زر "إظهار".
تعامل مع المفتاح معاملة كلمة المرور. فهو ينشئ الأنشطة ويستبدلها في حسابك، لذا احتفظ به على الخادم بعيدًا عن أي شيء يمكن للمتصفح قراءته.
محتوى الطلب
تأخذ كل نقطة نهاية الحقول الخمسة نفسها. ما يختلف هو حقل المحتوى تحتها: تأخذ معظمها مصفوفة من 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": 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/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"
}
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/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
ما تكشفه الخانة الفارغة: لا شيء، أو طول الاسم، أو حرفه الأول، أو التلميح الذي كتبته.
{
"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"
}
مصفوفة من العناصر التي تُسحب منها البطاقات. أرسل عددًا أكبر بوضوح من خانات البطاقة الواحدة لتختلف البطاقات.
تعود إلى الاسم الاحتياطي "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/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
يجب الضغط على البطاقات بالترتيب. وإن عُطّل يفتح القفل أي ترتيب للبطاقات الصحيحة.
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."
}
]
}'
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"
}
مصفوفة من أسئلة الاختيار من متعدد أو صحيح/خطأ، بالشكل نفسه الذي تأخذه نقطة نهاية الاختبار. الأسئلة المفتوحة مرفوضة: فالباب يحتاج إلى إجابة مكتوبة عليه.
تعود إلى الاسم الاحتياطي "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"
}
}'
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
}
}'
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"
}
لا ترسل items ولا sentence — الحجم والصعوبة هما المُدخل بأكمله.
لا يوفّر المحرِّر إعداد الصعوبة إلا للأحجام 2x3 و3x3 و3x4. أما API فيطبّقه على كل الأحجام، بما فيها 2x2 و4x4.
الإعدادات التي تقرؤها
الحقل
النوع
ما يفعله
size
اختياريفي settings
string
string
حجم الكتلة الواحدة، مكتوبًا كصفوف × أعمدة — يعطي 3x3 الشبكة الكلاسيكية 9x9. لا تتحقق نقطة النهاية إلا من إمكانية تفسيره كرقمين، لذا التزم بالأحجام التي يوفّرها المحرِّر.
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"
]
}
}'
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"
}
}'
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"
]
}
]
}'
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.
POST/api/public/v1/rebusمن 1 إلى 30 عناصر في items
المحتوى
مصفوفة من الجمل. تسرد كل جملة الكلمات المرسومة صورًا؛ وكل كلمة أخرى تبقى بحروفها.
تعود إلى الاسم الاحتياطي "Rebus API"
جدير بالمعرفة
تُرسم الكلمة من أجزاء تتهجّاها معًا. للجزء الحروف التي يمثّلها (text)، وemoji، وshows: الكلمة التي تدل عليها الصورة ("broom" لصورة تمثّل "room"). يحسب Puzzel تغييرات الحروف. وقد يكون الجزء رمزًا بدلًا من ذلك، مثل 4 لـ "for".
الإعدادات التي تقرؤها
الحقل
النوع
ما يفعله
rebus_commas
اختياريفي settings
boolean
boolean
يرسم الحرف الأول أو الأخير المحذوف فاصلة بجانب الصورة.
رابط صورة واحد، في حقل image. لا تأخذ نقطة النهاية هذه أي items.
تعود إلى الاسم الاحتياطي "Jigsaw Game API"
جدير بالمعرفة
ينشئ API دائمًا صورة مقطّعة بحجم 4×4. عدد القطع والقطع غير المنتظمة والحواف المستقيمة إعدادات خاصة بالمحرِّر — إرسال rows أو columns هنا لا يفعل شيئًا.
يُخزَّن الرابط كما أرسلته ولا يُنسخ الملف أبدًا، لذا يجب أن يبقى قابلًا للوصول العام طالما ظل النشاط يُلعب.
الإعدادات التي تقرؤها
الحقل
النوع
ما يفعله
image
مطلوب
string
string
الرابط المطلق للصورة المراد تقطيعها. يُرسَل في المستوى الأعلى، لا داخل settings.