Přeskočit na obsah
Prohlížíš si nový Puzzel.org Zpět na současný web
Vývojářské API

Vytvářej aktivity z vlastního systému

Jeden POST požadavek na každý typ aktivity. Pošli svůj obsah jako JSON a získáš zpět aktivitu ve svém účtu Puzzel.org a URL adresu, kterou můžeš předat hráčům nebo vložit do iframe.

Základní URL
https://puzzel.org/api/public/v1
Ověření
Klíč + e-mail v těle požadavku
Endpointy
20 typů aktivit
Kvóta
10 aktivit denně

Tvůj první požadavek

Nic se neinstaluje a žádné handshake není potřeba: pošli tělo JSON se svým klíčem, e-mailem a obsahem. Odpověď obsahuje klíč nové aktivity a URL adresu, na které se hraje.

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

Každý příklad na této stránce je kompletní, spustitelný požadavek. Stačí dosadit vlastní klíč a obsah a funguje tak, jak je.

Ověření

Nejsou tu žádné hlavičky ani bearer token. Oba údaje cestují v těle JSON každého požadavku a klíč je přijat jen pro účet, ke kterému ten e-mail patří.

PoleTypCo dělá
account_api_key
povinné
string
stringKlíč API tvého účtu. Patří do těla požadavku, ne do hlavičky.
email
povinné
string
stringAdresa, kterou se přihlašuje tvůj účet Puzzel.org. Klíč je platný jen společně s ní.

Tvůj klíč najdeš v sekci účtu na nástěnce, za tlačítkem Zobrazit.

Přihlásit se

Klíče API se přidělují při aktivaci předplatného, takže bezplatný účet ho ještě nemá.

Zobrazit tarify

Zacházej s klíčem jako s heslem. Vytváří a přepisuje aktivity ve tvém účtu, takže ho drž na straně serveru a mimo dosah čehokoliv, co může číst prohlížeč.

Tělo požadavku

Každý endpoint přijímá stejných pět polí. Liší se obsahové pole pod nimi: většina bere pole items, pár z nich jednu větu nebo jeden obrázek, a sudoku nebere vůbec nic.

PoleTypCo dělá
account_api_key
povinné
string
stringKlíč API tvého účtu. Patří do těla požadavku, ne do hlavičky.
email
povinné
string
stringAdresa, kterou se přihlašuje tvůj účet Puzzel.org. Klíč je platný jen společně s ní.
title
volitelné
string
stringNázev, který aktivita dostane na tvé nástěnce. Když ho vynecháš, endpoint použije svůj vlastní výchozí název.
language
volitelné
string
stringRozhoduje jen o jazykové verzi v URL adrese, kterou dostaneš zpět — nepřekládá nic, co pošleš. Osmisměrka ho navíc používá k přepnutí výplňových písmen na arabštinu, když je "ar".
Výchozí: "en"
activity_key
volitelné
string
stringVynech ho a vytvoří se nová aktivita. Pošli klíč aktivity, kterou už vlastníš, a místo toho se ta aktivita přestaví.

settings je objekt s možnostmi pro jednotlivé endpointy. Které z nich endpoint čte, je uvedeno níže u něj; cokoliv dalšího tam vložíš, se ignoruje.

Co se vrátí

Úspěšné volání odpoví 200 s klíčem nové aktivity a URL adresou, na které se hraje. Cokoliv jiného odpoví se success nastaveným na false a jedním řetězcem s chybou.

Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Selhání 
{
  "success": false,
  "error": "Invalid Email or API Key"
}

URL adresa, kterou dostaneš zpět, je pohled embed. Nahraď embed za play a otevřeš ji na celou stránku, nebo za build a otevřeš ji v editoru — klíč za p= zůstává stejný.

Vytváření vs. aktualizace

Pošli activity_key a aktivita za ním se přestaví na místě: její obsah se nahradí, název a časové razítko verze se obnoví a samotný klíč zůstává stejný — takže odkazy a vložení, které jsi už sdílel, dál fungují. Výsledky, umístění ve složce a každé nastavení, které endpoint sám nezapisuje, zůstávají beze změny.

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 se použije při každé aktualizaci, včetně výchozí hodnoty — když ho vynecháš, aktivita se přejmenuje na výchozí název daného endpointu.
  • Bloky nastavení, které endpoint zapisuje sám, se přepíšou od základu, takže aktualizace je zároveň resetuje na hodnoty, které pošleš, nebo na výchozí hodnoty endpointu.
  • Aktualizovat můžeš jen aktivity, které vlastní tvůj účet. Cizí klíč odpoví 403.
  • Aktualizace stojí stejně jako vytvoření: jedno volání z dnešní kvóty.

Limit požadavků

10
10 aktivit na účet a den

Počítá se každé úspěšné volání, vytvoření i aktualizace stejně. Když limit překročíš, další požadavek odpoví 429, dokud se počítadlo nevynuluje.

Počítadlo vynuluje jednou denně naplánovaná úloha, ne plovoucí 24hodinové okno.

Chyby

Chyby vždy přicházejí jako JSON se stejnými dvěma poli, nikdy jako stránka HTML. Řetězec s chybou je napsaný tak, aby ho přečetl člověk — pojmenovává pole nebo limit, který selhal.

StavCo to znamená
400
Bad Request
Něco v těle chybí, je špatně formátované nebo mimo rozsah. Zpráva pojmenovává dané pole.
401
Unauthorized
E-mail není známý, nebo klíč nepatří k danému účtu.
403
Forbidden
activity_key, který jsi poslal, patří jinému účtu.
429
Too Many Requests
Dnešní kvóta je vyčerpaná. Vynuluje se jednou denně.
500
Server Error
Generátor nedokázal z toho, co jsi poslal, sestavit hlavolam — obvykle je slov málo, nebo je nejde poskládat dohromady.

Endpointy

Jedna cesta pro každý typ aktivity, všechny POST, všechny pod stejnou základní URL adresou. Ke každé je uvedený obsah, který potřebuje, nastavení, které čte, a požadavek, který si můžeš vyzkoušet.

Slova a písmena

Křížovka

Propojí tvé odpovědi do mřížky a definice očísluje za tebe.

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

Pole slov. Každá položka spojuje odpověď s definicí, která na ni odkazuje.

Bez zadání se použije záložní název “Crossword API”

Co je dobré vědět
  • Odpovědi kratší než dva znaky se před sestavením mřížky vyřadí a alespoň dvě to musí přežít.
  • Odpovědi se převedou na velká písmena a generátor má dvacet pokusů, jak je umístit. Pokud se mu nepodaří umístit ani jedno slovo, volání odpoví 500.
Ukázkový požadavek
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": "cs",
  "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"
    }
  ]
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Otevřít editor Zpět nahoru

Osmisměrka

Skryje tvá slova v mřížce písmen ve směrech a tvaru, které si vybereš.

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

Pole slov. Text definice se stane seznamem slov, se kterým hráči pracují.

Bez zadání se použije záložní název “Wordseeker API”

Co je dobré vědět
  • Odpovědi kratší než dva znaky se vyřadí a každá odpověď se před vložením do mřížky převede na velká písmena.
  • Mřížka se doplňuje latinskými písmeny, pokud language není "ar" — pak se výplň přepne na arabštinu.
Nastavení, které čte
PoleTypCo dělá
hidden_solution
volitelné v settings
string
stringZbylá písmena tvoří tenhle text. Nastavením zároveň řekneš generátoru, aby nejdřív umístil řešení, místo aby napěchoval co nejvíc slov.
directions
volitelné v settings
string[]
string[]Kterými směry může slovo vést. Když ho vynecháš, slova vedou jen na východ, jihovýchod a jih.
Jedno z westeastnorthsouthnorthwestnortheastsouthwestsoutheast
Výchozí: ["east", "southeast", "south"]
template
volitelné v settings
string
stringVyřízne z mřížky tvar, místo aby zůstala čtvercová.
Jedno z squarecirclecrossdiamondpyramidsmileystarcross_plus
Ukázkový požadavek
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": "cs",
  "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"
  }
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordseeker/embed?p=-Nq8sample_activity_key",
  "message": "Wordseeker created successfully"
}
Otevřít editor Zpět nahoru

Akrostich

Naskládá tvé odpovědi tak, aby jeden sloupec skládal skryté slovo.

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

Pole slov. Dohromady musí obsahovat každé písmeno skrytého slova.

Bez zadání se použije záložní název “Acrostic API”

Co je dobré vědět
  • Pokud odpovědi nedokážou dodat písmena, která řešení potřebuje, volání odpoví 500, místo aby uložilo napůl sestavenou mřížku.
  • Generátor přeuspořádá tvé odpovědi, aby sloupec fungoval, takže pořadí, které pošleš, není pořadí, které vidí hráči.
Nastavení, které čte
PoleTypCo dělá
hidden_solution
povinné v settings
string
stringSlovo, které skládá zvýrazněný sloupec. Bez něj tenhle endpoint neproběhne.
Ukázkový požadavek
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": "cs",
  "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"
  }
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/acrostic/embed?p=-Nq8sample_activity_key",
  "message": "Acrostic created successfully"
}
Otevřít editor Zpět nahoru

Zpřeházená písmena

api_e_word_scramble

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

api_c_word_scramble

Bez zadání se použije záložní název “Word Scramble API”

Co je dobré vědět
  • Aktivity vytvořené přes API mají vždy zapnuté nastavení pro zamíchání pořadí, takže pořadí, které pošleš, není pořadí, které dostanou hráči.
Nastavení, které čte
PoleTypCo dělá
hidden_solution
volitelné v settings
string
stringVolitelné bonusové slovo, které hráči zadají, jakmile vyřeší zbytek.
Ukázkový požadavek
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": "cs",
  "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"
  }
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/word-scramble/embed?p=-Nq8sample_activity_key",
  "message": "Word Scramble created successfully"
}
Otevřít editor Zpět nahoru

Šibenice

Změní tvá slova nebo fráze na kola hádání písmen.

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

Pole slov nebo krátkých frází. Definice je nápověda, kterou vidí hráči.

Bez zadání se použije záložní název “Hangman API”

Ukázkový požadavek
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": "cs",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    }
  ]
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/hangman/embed?p=-Nq8sample_activity_key",
  "message": "Hangman created successfully"
}
Otevřít editor Zpět nahoru

Wordle

Z každého slova, které pošleš, udělá hru na hádání slova.

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

Pole slov. Hráči dostanou jedno kolo na slovo.

Bez zadání se použije záložní název “Wordle API”

Co je dobré vědět
  • Vytvořeno se zapnutým nastavením pro kontrolu, že tipy jsou skutečná slova. Pokud jsou tvá slova jména nebo vymyšlená, vypni ho v editoru.
Ukázkový požadavek
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": "cs",
  "items": [
    {
      "answer": "MELON",
      "description": "Sweet and green",
      "type": "text"
    },
    {
      "answer": "PEACH",
      "description": "Fuzzy and orange",
      "type": "text"
    }
  ]
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordle/embed?p=-Nq8sample_activity_key",
  "message": "Wordle created successfully"
}
Otevřít editor Zpět nahoru

Nácvik psaní

api_e_typing_practice

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

api_c_typing_practice

Bez zadání se použije záložní název “Typing Practice API”

Ukázkový požadavek
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": "cs",
  "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"
    }
  ]
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
  "message": "Typing Practice created successfully"
}
Otevřít editor Zpět nahoru

Kolo štěstí

api_e_wheel_of_fortune

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

api_c_wheel_of_fortune

Bez zadání se použije záložní název “Wheel of Fortune API”

Co je dobré vědět
  • Vytvořeno s možností “zobrazit výsledek jen v kole”, takže výsledek se čte z kola, místo aby byl oznámen vedle něj.
Ukázkový požadavek
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": "cs",
  "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"
    }
  ]
}'
Úspěch 
{
  "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"
}
Otevřít editor Zpět nahoru
Karty a dvojice

Memory

Karty lícem dolů, které se otáčí a spojují do dvojic.

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

Pole dvojic. Každá dvojice obsahuje dvě karty, které k sobě patří.

Bez zadání se použije záložní název “Memory Game API”

Co je dobré vědět
  • Karta je objekt s type a value. Použij "text" pro slova, nebo "image", "audio", "youtube" či "link" s URL adresou ve value, a přidej alt pro popis.
Ukázkový požadavek
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": "cs",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/memory/embed?p=-Nq8sample_activity_key",
  "message": "Memory game created successfully"
}
Otevřít editor Zpět nahoru

Spojovačka

api_e_matching_pairs

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

api_c_matching_pairs

Bez zadání se použije záložní název “Matching Game API”

Co je dobré vědět
  • Karta je objekt s type a value. Použij "text" pro slova, nebo "image", "audio", "youtube" či "link" s URL adresou ve value, a přidej alt pro popis.
Ukázkový požadavek
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": "cs",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/matching-pairs/embed?p=-Nq8sample_activity_key",
  "message": "Matching pairs game created successfully"
}
Otevřít editor Zpět nahoru

Kartičky

api_e_flash_cards

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

api_c_flash_cards

Bez zadání se použije záložní název “Flash Cards API”

Co je dobré vědět
  • Endpoint uloží tolik kartiček, kolik jich pošleš, takže pošli přesně dvě na položku — přední a pak zadní stranu.
  • Karta je objekt s type a value. Použij "text" pro slova, nebo "image", "audio", "youtube" či "link" s URL adresou ve value, a přidej alt pro popis.
Ukázkový požadavek
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": "cs",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/flash-cards/embed?p=-Nq8sample_activity_key",
  "message": "Flash Cards created successfully"
}
Otevřít editor Zpět nahoru

Třídění do kategorií

Karty, které se třídí do skupiny, kam patří.

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

Pole kategorií, každá s názvem a kartami, které do ní patří.

Bez zadání se použije záložní název “Categorize Game API”

Co je dobré vědět
  • Kategorie poslaná bez názvu se uloží jako “Untitled Category”, takže ho vždy pošli.
  • Karta je objekt s type a value. Použij "text" pro slova, nebo "image", "audio", "youtube" či "link" s URL adresou ve value, a přidej alt pro popis.
Ukázkový požadavek
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": "cs",
  "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"
        }
      ]
    }
  ]
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/categorize/embed?p=-Nq8sample_activity_key",
  "message": "Categorize game created successfully"
}
Otevřít editor Zpět nahoru

Seřazování

Posloupnost, kterou hráči musí seřadit zpátky do pořadí.

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

Pole posloupností. Každá obsahuje své karty ve správném pořadí.

Bez zadání se použije záložní název “Reorder Game API”

Co je dobré vědět
  • Pořadí, které pošleš, se uloží jako správné pořadí — číslo jedna první.
  • Karta je objekt s type a value. Použij "text" pro slova, nebo "image", "audio", "youtube" či "link" s URL adresou ve value, a přidej alt pro popis.
Ukázkový požadavek
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": "cs",
  "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"
        }
      ]
    }
  ]
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/reorder/embed?p=-Nq8sample_activity_key",
  "message": "Reorder game created successfully"
}
Otevřít editor Zpět nahoru
Otázky a odpovědi

Kvíz

Otázky s výběrem odpovědi i otevřené otázky, bodované za chodu.

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

Pole otázek. Otázky s výběrem odpovědi nesou své možnosti; otevřené otázky nesou odpověď, kterou uznáš.

Bez zadání se použije záložní název “Quiz API”

Co je dobré vědět
  • question_type je buď "multiple_choice", kde správná možnost nese isCorrect true, nebo "open_answer", které místo toho používá correct_answer. Když ho vynecháš, bere se to jako výběr z možností.
  • Endpoint pro kvíz předává settings rovnou jako bloky nastavení aktivity, takže to není místo pro volné možnosti — kvíz doladíš dodatečně v editoru.
Ukázkový požadavek
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": "cs",
  "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."
    }
  ]
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key",
  "message": "Quiz created successfully"
}
Otevřít editor Zpět nahoru

Desková hra

api_e_board_game

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

api_c_board_game

Bez zadání se použije záložní název “Board Game API”

Co je dobré vědět
  • question_type je buď "multiple_choice", kde správná možnost nese isCorrect true, nebo "open_answer", které místo toho používá correct_answer. Když ho vynecháš, bere se to jako výběr z možností.
Nastavení, které čte
PoleTypCo dělá
number_of_tiles
volitelné v settings
number
numberKolik políček má herní plán. Mezi 10 a 75.
Výchozí: 30
game_mode
volitelné v settings
string
stringJestli hráči závodí do cíle, nebo cestou sbírají předměty.
Jedno z race_to_finishcollect_items
Výchozí: "race_to_finish"
Ukázkový požadavek
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": "cs",
  "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"
  }
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
  "message": "Board Game created successfully"
}
Otevřít editor Zpět nahoru
Věty a čísla

Kryptogram

Změní větu na šifru k rozluštění, znak po znaku.

#
POST /api/public/v1/cryptogram Nebere žádné items
Obsah

Jedna věta v poli sentence. Tento endpoint nebere žádné items.

Bez zadání se použije záložní název “Cryptogram API”

Co je dobré vědět
  • Cokoliv pošleš v items, se ignoruje — hlavolam se sestaví jen z věty.
Nastavení, které čte
PoleTypCo dělá
sentence
povinné
string
stringVěta, která se zašifruje. Hráči ji dekódují znak po znaku.
helpers
volitelné v settings
string
stringKteré znaky se prozradí zdarma jako vstup do hry: žádné, nejčastější, samohlásky, nebo ty, které si sám vypíšeš.
Jedno z nonemost_commonvowelscustom
Výchozí: "none"
character_list
volitelné v settings
string
stringAbeceda, ze které se šifra sestavuje. Když ji necháš prázdnou, šifrování si vybere vlastní.
extra_letters
volitelné v settings
string
stringZnaky, které se prozradí, když je helpers "custom". U ostatních režimů nápovědy se ignoruje.
hide_unused_characters
volitelné v settings
boolean
booleanVynechá z klíče znaky, které věta vůbec nepoužívá.
Výchozí: false
Ukázkový požadavek
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": "cs",
  "sentence": "An apple a day keeps the doctor away",
  "settings": {
    "helpers": "vowels",
    "hide_unused_characters": false
  }
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/cryptogram/embed?p=-Nq8sample_activity_key",
  "message": "Cryptogram created successfully"
}
Otevřít editor Zpět nahoru

Početní cvičení

Skryje větu za příklady — vyřeš příklad, odhalíš písmeno.

#
POST /api/public/v1/calculation Nebere žádné items
Obsah

Jedna věta v poli sentence. Tento endpoint nebere žádné items.

Bez zadání se použije záložní název “Calculation Game API”

Co je dobré vědět
  • Pokud jsou omezení příliš přísná na to, aby se věta dala zakódovat, volání odpoví 400 a požádá tě, ať je uvolníš, místo aby uložilo neúplný hlavolam.
Nastavení, které čte
PoleTypCo dělá
sentence
povinné
string
stringVěta, kterou hráči odhalí řešením příkladů.
difficulty_level
volitelné v settings
number
numberNejvyšší výsledek, jaký může mít příklad.
Jedno z 20501001000
Výchozí: "100"
operators
volitelné v settings
string[]
string[]Které operace se mohou objevit. x je násobení, : je dělení.
Jedno z +-x:
Výchozí: ["+", "-", "x", ":"]
max_operations
volitelné v settings
number
numberKolik operací může jeden příklad řetězit za sebou.
Jedno z 123
Výchozí: 1
number_difficulty
volitelné v settings
number
numberOmezuje jednotlivá čísla uvnitř příkladu. Od 5 do 1000.
Výchozí: 100
Ukázkový požadavek
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": "cs",
  "sentence": "Fruit salad for everyone",
  "settings": {
    "difficulty_level": "100",
    "operators": [
      "+",
      "-",
      "x",
      ":"
    ],
    "max_operations": 1,
    "number_difficulty": 100
  }
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/calculation/embed?p=-Nq8sample_activity_key",
  "message": "Calculation game created successfully"
}
Otevřít editor Zpět nahoru

Sudoku

Vygeneruje vyřešenou mřížku a pak z ní zase vezme čísla zpátky.

#
POST /api/public/v1/sudoku Nebere žádné items
Obsah

Nic. Celý hlavolam vzejde ze svých dvou nastavení.

Bez zadání se použije záložní název “Sudoku API”

Co je dobré vědět
  • Nepošli žádné items ani sentence — size a difficulty jsou celý vstup.
  • Editor nabízí obtížnost jen pro 2x3, 3x3 a 3x4. API ji použije pro každou velikost, včetně 2x2 a 4x4.
Nastavení, které čte
PoleTypCo dělá
size
volitelné v settings
string
stringVelikost jednoho bloku, zapsaná jako řádky krát sloupce — 3x3 dá klasickou mřížku 9x9. Endpoint jen kontroluje, že se to dá rozebrat na dvě čísla, takže zůstaň u velikostí, které nabízí editor.
Jedno z 2x22x33x33x44x4
Výchozí: "3x3"
difficulty_level
volitelné v settings
string
stringKolik čísel zůstane na startu na herní ploše.
Jedno z easynormalhard
Výchozí: "normal"
Ukázkový požadavek
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": "cs",
  "settings": {
    "size": "3x3",
    "difficulty_level": "normal"
  }
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/sudoku/embed?p=-Nq8sample_activity_key",
  "message": "Sudoku created successfully"
}
Otevřít editor Zpět nahoru
Obrázky

Puzzle

Rozřeže obrázek na dílky, které se skládají zpátky.

#
POST /api/public/v1/jigsaw Nebere žádné items
Obsah

Jedna URL adresa obrázku v poli image. Tento endpoint nebere žádné items.

Bez zadání se použije záložní název “Jigsaw Game API”

Co je dobré vědět
  • API vždy vytvoří puzzle 4×4. Počet dílků, nepravidelné dílky a rovné okraje jsou nastavení editoru — poslání rows nebo columns sem nic neudělá.
  • URL adresa se uloží přesně tak, jak ji pošleš, a soubor se nikdy nekopíruje, takže musí zůstat veřejně dostupná po celou dobu, kdy se aktivita hraje.
Nastavení, které čte
PoleTypCo dělá
image
povinné
string
stringAbsolutní URL adresa obrázku, který se rozřeže. Posílá se na nejvyšší úrovni, ne uvnitř settings.
Ukázkový požadavek
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": "cs",
  "image": "https://example.com/orchard.jpg"
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jigsaw/embed?p=-Nq8sample_activity_key",
  "message": "Jigsaw game created successfully"
}
Otevřít editor Zpět nahoru

Posuvný hlavolam

Rozseká obrázek na dílky, které se posouvají na místo.

#
POST /api/public/v1/slidingpuzzle Nebere žádné items
Obsah

Jedna URL adresa obrázku uvnitř settings. Tento endpoint nebere žádné items.

Bez zadání se použije záložní název “Sliding Puzzle API”

Co je dobré vědět
  • Na rozdíl od puzzle tento endpoint čte obrázek z settings.image. Pole image na nejvyšší úrovni se ignoruje a volání odpoví 400.
  • URL adresa se uloží přesně tak, jak ji pošleš, a soubor se nikdy nekopíruje, takže musí zůstat veřejně dostupná po celou dobu, kdy se aktivita hraje.
Nastavení, které čte
PoleTypCo dělá
image
povinné v settings
string
stringAbsolutní URL adresa obrázku, který se rozseká na posuvné dílky. Na rozdíl od puzzle je tahle uvnitř settings.
Ukázkový požadavek
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": "cs",
  "settings": {
    "image": "https://example.com/orchard.jpg"
  }
}'
Úspěch 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/slidingpuzzle/embed?p=-Nq8sample_activity_key",
  "message": "Sliding puzzle created successfully"
}
Otevřít editor Zpět nahoru

Něco se nechová, jak má?

Pošli požadavek, který jsi zkusil, a chybu, kterou jsi dostal zpátky, a dostaneš skutečnou odpověď od člověka, který ten endpoint napsal.

Napsat podpoře