Preskočiť na obsah
Pozeráš si náhľad nového Puzzel.org Späť na súčasnú stránku
API pre vývojárov

Vytváraj aktivity z vlastného systému

Jeden POST na každý typ aktivity. Pošli svoj obsah ako JSON a späť dostaneš aktivitu vo svojom účte Puzzel.org a URL, ktorú odovzdáš hráčom alebo vložíš do iframe.

Základná URL
https://puzzel.org/api/public/v1
Overenie
Kľúč + e-mail v tele
Koncové body
20 typov aktivít
Kvóta
10 aktivít denne

Tvoja prvá požiadavka

Nič sa neinštaluje a žiadny handshake: pošli telo v JSON so svojím kľúčom, e-mailom a obsahom. Odpoveď obsahuje kľúč novej aktivity a URL, na ktorej sa hrá.

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": "sk",
  "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"
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

Každý príklad na tejto stránke je úplná, spustiteľná požiadavka. Doplň vlastný kľúč a obsah a funguje tak, ako je.

Overenie totožnosti

Žiadne hlavičky, žiadny bearer token. Oba údaje cestujú v tele JSON každej požiadavky a kľúč sa prijme len pre účet, ktorému daný e-mail patrí.

PoleTypČo robí
account_api_key
povinné
string
stringKľúč API tvojho účtu. Patrí do tela, nie do hlavičky.
email
povinné
string
stringAdresa, ktorou sa prihlasuje tvoj účet Puzzel.org. Kľúč platí len spolu s ňou.

Kľúč nájdeš v sekcii účtu vo svojom prehľade, pod tlačidlom Zobraziť.

Prihlásiť sa

Kľúče API sa vydávajú pri spustení predplatného, takže bezplatný účet zatiaľ žiadny nemá.

Pozrieť plány

Ku kľúču sa správaj ako k heslu. Vytvára a prepisuje aktivity v tvojom účte, tak ho drž na serveri a mimo všetkého, čo si prehliadač vie prečítať.

Telo požiadavky

Každý koncový bod berie rovnakých päť polí. Líši sa až pole s obsahom pod nimi: väčšina berie pole položiek, zopár jednu vetu alebo jeden obrázok a sudoku neberie nič.

PoleTypČo robí
account_api_key
povinné
string
stringKľúč API tvojho účtu. Patrí do tela, nie do hlavičky.
email
povinné
string
stringAdresa, ktorou sa prihlasuje tvoj účet Puzzel.org. Kľúč platí len spolu s ňou.
title
voliteľné
string
stringNázov, ktorý aktivita dostane v tvojom prehľade. Ak ho vynecháš, koncový bod použije svoj náhradný názov.
language
voliteľné
string
stringUrčuje len jazyk v URL, ktorú dostaneš späť — nič z toho, čo pošleš, nepreloží. Osemsmerovka ho navyše číta, aby pri hodnote "ar" prepla výplňové písmená na arabské.
Predvolené: "en"
activity_key
voliteľné
string
stringAk ho vynecháš, vytvorí sa nová aktivita. Ak pošleš kľúč aktivity, ktorú už vlastníš, prestaví sa namiesto toho tá.

settings je objekt s možnosťami pre daný koncový bod. Ktoré z nich koncový bod číta, je uvedené pri ňom nižšie; čokoľvek iné, čo tam dáš, sa ignoruje.

Čo príde späť

Úspešné volanie odpovie kódom 200 s kľúčom novej aktivity a URL, na ktorej sa hrá. Čokoľvek iné odpovie s success nastaveným na false a jediným reťazcom error.

Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Zlyhanie 
{
  "success": false,
  "error": "Invalid Email or API Key"
}

url, ktorú dostaneš späť, je zobrazenie embed. Vymeň embed za play a otvorí sa na celú stránku, alebo za build a otvorí sa v editore — kľúč za p= zostáva rovnaký.

Vytváranie vs. aktualizácia

Pošli activity_key a aktivita za ním sa prestaví na mieste: jej obsah sa nahradí, názov a značka verzie sa obnovia a samotný kľúč zostane rovnaký — takže už zdieľané odkazy a vloženia fungujú ďalej. Výsledky, umiestnenie v priečinku a každé nastavenie, ktoré koncový bod sám nezapisuje, zostanú tak, ako boli.

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 sa uplatní pri každej aktualizácii, vrátane svojej predvolenej hodnoty — ak ho vynecháš, aktivita sa premenuje na náhradný názov daného koncového bodu.
  • Bloky nastavení, ktoré koncový bod zapisuje sám, sa prepíšu odznova, takže aktualizácia ich zároveň vráti na hodnoty, ktoré pošleš, alebo na predvolené hodnoty koncového bodu.
  • Aktualizovať sa dajú len aktivity, ktoré vlastní tvoj účet. Cudzí kľúč odpovie kódom 403.
  • Aktualizácia stojí rovnako ako vytvorenie: jedno volanie z dnešnej kvóty.

Limit počtu volaní

10
10 aktivít na účet a deň

Počíta sa každé úspešné volanie, vytvorenie aj aktualizácia. Po prekročení odpovie ďalšia požiadavka kódom 429, kým sa počítadlo nevynuluje.

Počítadlo raz denne vynuluje naplánovaná úloha, nie kĺzavé 24-hodinové okno.

Chyby

Chyby prichádzajú vždy ako JSON s tými istými dvoma poľami, nikdy ako HTML stránka. Reťazec error je napísaný tak, aby ho čítal človek — pomenúva pole alebo limit, ktorý zlyhal.

StavČo znamená
400
Bad Request
V tele niečo chýba, má zlý tvar alebo je mimo rozsahu. Správa pomenúva dané pole.
401
Unauthorized
E-mail je neznámy alebo kľúč nepatrí k tomu účtu.
403
Forbidden
Odoslaný activity_key patrí inému účtu.
429
Too Many Requests
Dnešná kvóta je vyčerpaná. Vynuluje sa raz denne.
500
Server Error
Generátor nedokázal z odoslaného obsahu zostaviť hlavolam — zvyčajne je slov príliš málo alebo sa nedajú pospájať.

Koncové body

Jedna cesta na každý typ aktivity, všetky POST, všetky pod rovnakou základnou URL. Pri každej je uvedený obsah, ktorý potrebuje, nastavenia, ktoré číta, a požiadavka, ktorú si vieš spustiť.

Slová a písmená

Krížovka

Poprepája tvoje odpovede do mriežky a definície ti očísluje.

#
POST /api/public/v1/crossword Aspoň 2 v items
Obsah

Pole slov. Každá položka spája odpoveď s definíciou, ktorá na ňu ukazuje.

Náhradný názov je “Crossword API”

Dobré vedieť
  • Odpovede kratšie ako dva znaky sa pred zostavením mriežky vyradia a aspoň dve to musia prežiť.
  • Odpovede sa prevedú na veľké písmená a generátor má dvadsať pokusov, aby ich umiestnil. Ak nedokáže umiestniť ani jedno slovo, volanie odpovie kódom 500.
Ukážková požiadavka
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": "sk",
  "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"
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Otvoriť editor Späť nahor

Osemsmerovka

Skryje tvoje slová do mriežky písmen, v smeroch a tvare, ktoré si vyberieš.

#
POST /api/public/v1/wordseeker Aspoň 2 v items
Obsah

Pole slov. Text definície sa stane zoznamom slov, s ktorým hráči pracujú.

Náhradný názov je “Wordseeker API”

Dobré vedieť
  • Odpovede kratšie ako dva znaky sa vyradia a každá odpoveď sa pred vložením do mriežky prevedie na veľké písmená.
  • Mriežka sa dopĺňa latinkovými písmenami, kým language nie je "ar", čo prepne výplň na arabskú.
Nastavenia, ktoré číta
PoleTypČo robí
hidden_solution
voliteľné v settings
string
stringZvyšné písmená vyskladajú práve toto. Nastavením zároveň generátoru povieš, aby najprv umiestnil riešenie a nesnažil sa napchať čo najviac slov.
directions
voliteľné v settings
string[]
string[]Ktorými smermi môže slovo viesť. Ak to vynecháš, slová idú len na východ, juhovýchod a juh.
Jedno z westeastnorthsouthnorthwestnortheastsouthwestsoutheast
Predvolené: ["east", "southeast", "south"]
template
voliteľné v settings
string
stringVyreže mriežku do tvaru namiesto toho, aby zostala štvorcová.
Jedno z squarecirclecrossdiamondpyramidsmileystarcross_plus
Ukážková požiadavka
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": "sk",
  "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"
  }
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordseeker/embed?p=-Nq8sample_activity_key",
  "message": "Wordseeker created successfully"
}
Otvoriť editor Späť nahor

Akrostich

Naskladá tvoje odpovede tak, aby jeden stĺpec vyskladal skryté slovo.

#
POST /api/public/v1/acrostic Aspoň 1 v items
Obsah

Pole slov. Dohromady musia dodať každé písmeno skrytého slova.

Náhradný názov je “Acrostic API”

Dobré vedieť
  • Ak odpovede nedokážu dodať písmená, ktoré riešenie potrebuje, volanie odpovie kódom 500, namiesto toho aby uložilo napoly zostavenú mriežku.
  • Generátor tvoje odpovede preusporiada, aby stĺpec vyšiel, takže poradie, v ktorom ich pošleš, nie je poradie, ktoré vidia hráči.
Nastavenia, ktoré číta
PoleTypČo robí
hidden_solution
povinné v settings
string
stringSlovo, ktoré vyskladá zvýraznený stĺpec. Bez neho tento koncový bod nezbehne.
Ukážková požiadavka
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": "sk",
  "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"
  }
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/acrostic/embed?p=-Nq8sample_activity_key",
  "message": "Acrostic created successfully"
}
Otvoriť editor Späť nahor

Pomiešané písmená

api_e_word_scramble

#
POST /api/public/v1/word-scramble Aspoň 1 v items
Obsah

api_c_word_scramble

Náhradný názov je “Word Scramble API”

Dobré vedieť
  • Aktivity vytvorené cez API majú vždy zapnuté nastavenie na premiešanie poradia, takže poradie, v ktorom ich pošleš, nie je poradie, ktoré dostanú hráči.
Nastavenia, ktoré číta
PoleTypČo robí
hidden_solution
voliteľné v settings
string
stringVoliteľné bonusové slovo, ktoré hráči zadajú, keď vyriešia zvyšok.
Ukážková požiadavka
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": "sk",
  "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"
  }
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/word-scramble/embed?p=-Nq8sample_activity_key",
  "message": "Word Scramble created successfully"
}
Otvoriť editor Späť nahor

Obesenec

Zmení tvoje slová alebo slovné spojenia na kolá s hádaním písmen.

#
POST /api/public/v1/hangman Aspoň 1 v items
Obsah

Pole slov alebo krátkych slovných spojení. Indícia je tip, ktorý hráči vidia.

Náhradný názov je “Hangman API”

Ukážková požiadavka
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": "sk",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/hangman/embed?p=-Nq8sample_activity_key",
  "message": "Hangman created successfully"
}
Otvoriť editor Späť nahor

Wordle

Z každého slova, ktoré pošleš, spraví hru na hádanie slova.

#
POST /api/public/v1/wordle Aspoň 1 v items
Obsah

Pole slov. Hráči dostanú jedno kolo na každé slovo.

Náhradný názov je “Wordle API”

Dobré vedieť
  • Vytvorí sa so zapnutým nastavením na kontrolu, či sú hádané slová skutočné. Ak sú tvoje slová mená alebo vymyslené, vypni ho v editore.
Ukážková požiadavka
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": "sk",
  "items": [
    {
      "answer": "MELON",
      "description": "Sweet and green",
      "type": "text"
    },
    {
      "answer": "PEACH",
      "description": "Fuzzy and orange",
      "type": "text"
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordle/embed?p=-Nq8sample_activity_key",
  "message": "Wordle created successfully"
}
Otvoriť editor Späť nahor

Nácvik písania

api_e_typing_practice

#
POST /api/public/v1/typing-practice Aspoň 1 v items
Obsah

api_c_typing_practice

Náhradný názov je “Typing Practice API”

Ukážková požiadavka
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": "sk",
  "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"
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
  "message": "Typing Practice created successfully"
}
Otvoriť editor Späť nahor

Koleso šťastia

api_e_wheel_of_fortune

#
POST /api/public/v1/wheel-of-fortune Aspoň 1 v items
Obsah

api_c_wheel_of_fortune

Náhradný názov je “Wheel of Fortune API”

Dobré vedieť
  • Vytvorí sa s nastavením “zobraziť výsledok len v kolese”, takže výsledok sa číta z kolesa a neoznamuje sa vedľa neho.
Ukážková požiadavka
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": "sk",
  "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"
    }
  ]
}'
Úspech 
{
  "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"
}
Otvoriť editor Späť nahor
Karty a dvojice

Memory

Karty otočené lícom nadol, ktoré sa otáčajú a párujú do dvojíc.

#
POST /api/public/v1/memory Aspoň 2 v items
Obsah

Pole dvojíc. Každá dvojica obsahuje dve karty, ktoré patria k sebe.

Náhradný názov je “Memory Game API”

Dobré vedieť
  • Karta je objekt s poľom type a value. Pre slová použi "text", alebo "image", "audio", "youtube" či "link" s URL v poli value, a pre popis pridaj alt.
Ukážková požiadavka
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": "sk",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/memory/embed?p=-Nq8sample_activity_key",
  "message": "Memory game created successfully"
}
Otvoriť editor Späť nahor

Priraďovacia hra

api_e_matching_pairs

#
POST /api/public/v1/matching-pairs Aspoň 2 v items
Obsah

api_c_matching_pairs

Náhradný názov je “Matching Game API”

Dobré vedieť
  • Karta je objekt s poľom type a value. Pre slová použi "text", alebo "image", "audio", "youtube" či "link" s URL v poli value, a pre popis pridaj alt.
Ukážková požiadavka
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": "sk",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/matching-pairs/embed?p=-Nq8sample_activity_key",
  "message": "Matching pairs game created successfully"
}
Otvoriť editor Späť nahor

Kartičky na učenie

api_e_flash_cards

#
POST /api/public/v1/flash-cards Aspoň 1 v items
Obsah

api_c_flash_cards

Náhradný názov je “Flash Cards API”

Dobré vedieť
  • Koncový bod uloží toľko kariet, koľko ich pošleš, tak posielaj presne dve na položku — najprv prednú, potom zadnú.
  • Karta je objekt s poľom type a value. Pre slová použi "text", alebo "image", "audio", "youtube" či "link" s URL v poli value, a pre popis pridaj alt.
Ukážková požiadavka
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": "sk",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/flash-cards/embed?p=-Nq8sample_activity_key",
  "message": "Flash Cards created successfully"
}
Otvoriť editor Späť nahor

Triedenie do kategórií

Karty na roztriedenie do kategórie, kam patria.

#
POST /api/public/v1/categorize Aspoň 2 v items
Obsah

Pole kategórií, každá s názvom a kartami, ktoré do nej patria.

Náhradný názov je “Categorize Game API”

Dobré vedieť
  • Kategória poslaná bez názvu sa uloží ako “Untitled Category”, tak vždy nejaký pošli.
  • Karta je objekt s poľom type a value. Pre slová použi "text", alebo "image", "audio", "youtube" či "link" s URL v poli value, a pre popis pridaj alt.
Ukážková požiadavka
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": "sk",
  "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"
        }
      ]
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/categorize/embed?p=-Nq8sample_activity_key",
  "message": "Categorize game created successfully"
}
Otvoriť editor Späť nahor

Zoraďovačka

Postupnosť, ktorú musia hráči dať späť do správneho poradia.

#
POST /api/public/v1/reorder Aspoň 1 v items
Obsah

Pole postupností. Každá obsahuje svoje karty v správnom poradí.

Náhradný názov je “Reorder Game API”

Dobré vedieť
  • Poradie, v ktorom ich pošleš, sa uloží ako správne poradie — prvé je číslo jeden.
  • Karta je objekt s poľom type a value. Pre slová použi "text", alebo "image", "audio", "youtube" či "link" s URL v poli value, a pre popis pridaj alt.
Ukážková požiadavka
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": "sk",
  "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"
        }
      ]
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/reorder/embed?p=-Nq8sample_activity_key",
  "message": "Reorder game created successfully"
}
Otvoriť editor Späť nahor
Otázky a odpovede

Kvíz

Otázky s výberom aj otvorené otázky, bodované priebežne.

#
POST /api/public/v1/quiz Aspoň 1 v items
Obsah

Pole otázok. Otázky s výberom nesú svoje odpovede; otvorené otázky nesú odpoveď, ktorú uznáš.

Náhradný názov je “Quiz API”

Dobré vedieť
  • question_type je buď "multiple_choice", kde má správna možnosť isCorrect true, alebo "open_answer", ktorý namiesto toho používa correct_answer. Ak chýba, berie sa ako otázka s výberom.
  • Koncový bod kvízu posiela settings priamo ďalej ako bloky nastavení aktivity, takže to nie je miesto pre voľné možnosti — kvíz potom uprav v editore.
Ukážková požiadavka
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": "sk",
  "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."
    }
  ]
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key",
  "message": "Quiz created successfully"
}
Otvoriť editor Späť nahor

Stolová hra

api_e_board_game

#
POST /api/public/v1/board-game Aspoň 1 v items
Obsah

api_c_board_game

Náhradný názov je “Board Game API”

Dobré vedieť
  • question_type je buď "multiple_choice", kde má správna možnosť isCorrect true, alebo "open_answer", ktorý namiesto toho používa correct_answer. Ak chýba, berie sa ako otázka s výberom.
Nastavenia, ktoré číta
PoleTypČo robí
number_of_tiles
voliteľné v settings
number
numberKoľko políčok má doska. Od 10 do 75.
Predvolené: 30
game_mode
voliteľné v settings
string
stringČi hráči pretekajú do cieľa, alebo cestou zbierajú predmety.
Jedno z race_to_finishcollect_items
Predvolené: "race_to_finish"
Ukážková požiadavka
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": "sk",
  "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"
  }
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
  "message": "Board Game created successfully"
}
Otvoriť editor Späť nahor
Vety a čísla

Kryptogram

Zmení vetu na kód na rozlúštenie, znak po znaku.

#
POST /api/public/v1/cryptogram Neberie žiadne items
Obsah

Jedna veta v poli sentence. Tento koncový bod neberie žiadne items.

Náhradný názov je “Cryptogram API”

Dobré vedieť
  • Čokoľvek pošleš v items, sa ignoruje — hlavolam sa zostaví len z vety.
Nastavenia, ktoré číta
PoleTypČo robí
sentence
povinné
string
stringVeta, ktorá sa zašifruje. Hráči ju dekódujú znak po znaku.
helpers
voliteľné v settings
string
stringKtoré znaky sa prezradia zadarmo ako pomoc na začiatok: žiadne, najčastejšie, samohlásky alebo tie, ktoré uvedieš.
Jedno z nonemost_commonvowelscustom
Predvolené: "none"
character_list
voliteľné v settings
string
stringAbeceda, z ktorej sa šifra zostaví. Ak zostane prázdna, šifrovanie si zvolí vlastnú.
extra_letters
voliteľné v settings
string
stringZnaky, ktoré sa prezradia, keď je helpers "custom". Pri ostatných režimoch pomoci sa ignoruje.
hide_unused_characters
voliteľné v settings
boolean
booleanVynechá z kľúča šifry znaky, ktoré sa vo vete nikdy nevyskytujú.
Predvolené: false
Ukážková požiadavka
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": "sk",
  "sentence": "An apple a day keeps the doctor away",
  "settings": {
    "helpers": "vowels",
    "hide_unused_characters": false
  }
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/cryptogram/embed?p=-Nq8sample_activity_key",
  "message": "Cryptogram created successfully"
}
Otvoriť editor Späť nahor

Počtové cvičenie

Skryje vetu za príklady — vyrieš príklad, odkryješ písmeno.

#
POST /api/public/v1/calculation Neberie žiadne items
Obsah

Jedna veta v poli sentence. Tento koncový bod neberie žiadne items.

Náhradný názov je “Calculation Game API”

Dobré vedieť
  • Ak sú obmedzenia príliš tesné na zakódovanie vety, volanie odpovie kódom 400 s výzvou uvoľniť ich, namiesto toho aby uložilo neúplný hlavolam.
Nastavenia, ktoré číta
PoleTypČo robí
sentence
povinné
string
stringVeta, ktorú hráči odkrývajú riešením príkladov.
difficulty_level
voliteľné v settings
number
numberNajvyšší výsledok, ktorý smie príklad mať.
Jedno z 20501001000
Predvolené: "100"
operators
voliteľné v settings
string[]
string[]Ktoré operácie sa môžu objaviť. x je násobenie, : je delenie.
Jedno z +-x:
Predvolené: ["+", "-", "x", ":"]
max_operations
voliteľné v settings
number
numberKoľko operácií môže jeden príklad reťaziť.
Jedno z 123
Predvolené: 1
number_difficulty
voliteľné v settings
number
numberObmedzuje jednotlivé čísla v príklade. Kdekoľvek od 5 do 1000.
Predvolené: 100
Ukážková požiadavka
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": "sk",
  "sentence": "Fruit salad for everyone",
  "settings": {
    "difficulty_level": "100",
    "operators": [
      "+",
      "-",
      "x",
      ":"
    ],
    "max_operations": 1,
    "number_difficulty": 100
  }
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/calculation/embed?p=-Nq8sample_activity_key",
  "message": "Calculation game created successfully"
}
Otvoriť editor Späť nahor

Sudoku

Vygeneruje vyriešenú mriežku a potom z nej vyberie čísla.

#
POST /api/public/v1/sudoku Neberie žiadne items
Obsah

Nič. Celý hlavolam vznikne z jeho dvoch nastavení.

Náhradný názov je “Sudoku API”

Dobré vedieť
  • Neposielaj items ani sentence — veľkosť a obťažnosť sú celý vstup.
  • Editor ponúka obťažnosť len pre 2x3, 3x3 a 3x4. API ju uplatní na každú veľkosť, vrátane 2x2 a 4x4.
Nastavenia, ktoré číta
PoleTypČo robí
size
voliteľné v settings
string
stringVeľkosť jedného bloku zapísaná ako riadky krát stĺpce — 3x3 dáva klasickú mriežku 9x9. Koncový bod overuje len to, že sa to dá načítať ako dve čísla, tak zostaň pri veľkostiach, ktoré ponúka editor.
Jedno z 2x22x33x33x44x4
Predvolené: "3x3"
difficulty_level
voliteľné v settings
string
stringKoľko čísel zostane v mriežke na začiatok.
Jedno z easynormalhard
Predvolené: "normal"
Ukážková požiadavka
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": "sk",
  "settings": {
    "size": "3x3",
    "difficulty_level": "normal"
  }
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/sudoku/embed?p=-Nq8sample_activity_key",
  "message": "Sudoku created successfully"
}
Otvoriť editor Späť nahor
Obrázky

Puzzle

Rozstrihá obrázok na diely, ktoré sa ťahaním poskladajú späť.

#
POST /api/public/v1/jigsaw Neberie žiadne items
Obsah

Jedna URL obrázka v poli image. Tento koncový bod neberie žiadne items.

Náhradný názov je “Jigsaw Game API”

Dobré vedieť
  • API vždy vytvorí puzzle 4 krát 4. Počet dielov, nepravidelné diely a rovné okraje sú nastavenia editora — poslať sem rows alebo columns nemá žiadny účinok.
  • URL sa uloží presne tak, ako ju pošleš, a súbor sa nikdy nekopíruje, takže musí zostať verejne dostupná tak dlho, kým sa aktivita hrá.
Nastavenia, ktoré číta
PoleTypČo robí
image
povinné
string
stringAbsolútna URL obrázka, ktorý sa rozstrihá. Posiela sa na najvyššej úrovni, nie vnútri settings.
Ukážková požiadavka
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": "sk",
  "image": "https://example.com/orchard.jpg"
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jigsaw/embed?p=-Nq8sample_activity_key",
  "message": "Jigsaw game created successfully"
}
Otvoriť editor Späť nahor

Posuvná skladačka

Pomieša obrázok na dlaždice, ktoré sa posúvajú na miesto.

#
POST /api/public/v1/slidingpuzzle Neberie žiadne items
Obsah

Jedna URL obrázka vnútri settings. Tento koncový bod neberie žiadne items.

Náhradný názov je “Sliding Puzzle API”

Dobré vedieť
  • Na rozdiel od puzzle číta tento koncový bod svoj obrázok zo settings.image. Pole image na najvyššej úrovni sa ignoruje a volanie odpovie kódom 400.
  • URL sa uloží presne tak, ako ju pošleš, a súbor sa nikdy nekopíruje, takže musí zostať verejne dostupná tak dlho, kým sa aktivita hrá.
Nastavenia, ktoré číta
PoleTypČo robí
image
povinné v settings
string
stringAbsolútna URL obrázka, ktorý sa pomieša. Na rozdiel od puzzle je táto vnútri settings.
Ukážková požiadavka
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": "sk",
  "settings": {
    "image": "https://example.com/orchard.jpg"
  }
}'
Úspech 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/slidingpuzzle/embed?p=-Nq8sample_activity_key",
  "message": "Sliding puzzle created successfully"
}
Otvoriť editor Späť nahor

Niečo nefunguje, ako má?

Pošli svoju požiadavku aj chybu, ktorá prišla späť, a dostaneš skutočnú odpoveď od človeka, ktorý ten koncový bod napísal.

Napísať podpore