Yksi POST-pyyntö per aktiviteettityyppi. Lähetä sisältösi JSON-muodossa ja saat vastauksena aktiviteetin Puzzel.org-tilillesi sekä URL-osoitteen, jonka voit antaa pelaajille tai upottaa iframeen.
Perus-URL
https://puzzel.org/api/public/v1
Todennus
Avain + sähköposti rungossa
Päätepisteet
38 aktiviteettityyppiä
Kiintiö
10 aktiviteettia päivässä
Ensimmäinen pyyntösi
Ei asennettavaa eikä kättelyä: lähetä JSON-runko, jossa on avaimesi, sähköpostisi ja sisältösi. Vastaus sisältää uuden aktiviteetin avaimen ja URL-osoitteen, jossa sitä pelataan.
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": "fi",
"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"
}
]
}'
Jokainen tämän sivun esimerkki on täydellinen, suoraan ajettava pyyntö. Vaihda tilalle oma avaimesi ja sisältösi, niin se toimii sellaisenaan.
Todennus
Otsikkokenttiä tai bearer-tokenia ei tarvita. Molemmat tunnistetiedot kulkevat jokaisen pyynnön JSON-rungossa, ja avain hyväksytään vain sille tilille, johon kyseinen sähköposti kuuluu.
Kenttä
Tyyppi
Mitä se tekee
account_api_key
pakollinen
string
string
Tilisi API-avain. Se annetaan rungossa, ei otsikkokentässä.
email
pakollinen
string
string
Osoite, jolla Puzzel.org-tilisi kirjautuu sisään. Avain on voimassa vain yhdessä sen kanssa.
Avaimesi löytyy hallintapaneelisi tili-osiosta Näytä-painikkeen takaa.
Käsittele avainta kuin salasanaa. Se luo ja korvaa aktiviteetteja tililläsi, joten pidä se palvelinpuolella ja poissa kaikesta, mitä selain voi lukea.
Pyynnön runko
Jokainen päätepiste ottaa vastaan samat viisi kenttää. Niiden alla oleva sisältökenttä vaihtelee: useimmat ottavat vastaan taulukollisen items-kohteita, muutamat yhden lauseen tai yhden kuvan, ja sudoku ei ota vastaan mitään.
Kenttä
Tyyppi
Mitä se tekee
account_api_key
pakollinen
string
string
Tilisi API-avain. Se annetaan rungossa, ei otsikkokentässä.
email
pakollinen
string
string
Osoite, jolla Puzzel.org-tilisi kirjautuu sisään. Avain on voimassa vain yhdessä sen kanssa.
title
valinnainen
string
string
Nimi, jonka aktiviteetti saa hallintapaneelissasi. Jätä se pois, niin päätepiste käyttää omaa oletusnimeään.
language
valinnainen
string
string
Määrittää vain kielialueen palautettavassa URL-osoitteessa — se ei käännä mitään lähettämästäsi. Sanasokkelo lukee sen myös vaihtaakseen täytekirjaimensa arabiaksi, kun arvo on "ar".
Oletus: "en"
activity_key
valinnainen
string
string
Jätä pois, jos haluat luoda uuden aktiviteetin. Anna jo omistamasi aktiviteetin avain, niin kyseinen aktiviteetti rakennetaan sen sijaan uudelleen.
settings on objekti, joka sisältää päätepistekohtaiset asetukset. Mitkä niistä kukin päätepiste lukee, on lueteltu sen kohdalla alla; kaikki muu, mitä sinne laitat, jätetään huomiotta.
Mitä vastauksena tulee
Onnistunut kutsu vastaa koodilla 200 ja palauttaa uuden aktiviteetin avaimen sekä URL-osoitteen, jossa sitä pelataan. Kaikki muu vastaa siten, että success on false, ja mukana on yksi virhemerkkijono.
{
"success": false,
"error": "Invalid Email or API Key"
}
Saamasi url on upotusnäkymä. Vaihda embed sanaan play, niin se avautuu koko sivun näkymässä, tai sanaan build, niin se avautuu editorissa — p=-parametrin jälkeinen avain pysyy samana.
Luominen vs. päivittäminen
Lähetä activity_key, niin sen takana oleva aktiviteetti rakennetaan uudelleen paikallaan: sen sisältö korvataan, sen nimi ja versioleima päivitetään, ja itse avain pysyy samana — joten jo jakamasi linkit ja upotukset toimivat edelleen. Tulokset, kansiosijoitus ja jokainen asetus, jota päätepiste ei itse kirjoita, jätetään ennalleen.
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 otetaan käyttöön joka päivityksessä, myös sen oletusarvo — jätä se pois, niin aktiviteetti nimetään uudelleen kyseisen päätepisteen oletusnimeksi.
Asetuslohkot, joita päätepiste itse kirjoittaa, kirjoitetaan kokonaan uudelleen, joten päivitys palauttaa myös ne lähettämiisi arvoihin tai päätepisteen oletusarvoihin.
Voit päivittää vain aktiviteetteja, jotka oma tilisi omistaa. Toisen tilin avain vastaa koodilla 403.
Päivitys maksaa saman verran kuin luominen: yhden kutsun tämän päivän kiintiöstä.
Kutsurajoitus
10
10 aktiviteettia tiliä kohden päivässä
Jokainen onnistunut kutsu lasketaan mukaan, sekä luonnit että päivitykset. Jos raja ylittyy, seuraava pyyntö vastaa koodilla 429, kunnes laskuri nollataan.
Laskuri nollataan kerran päivässä ajastetulla tehtävällä, ei liukuvalla 24 tunnin ikkunalla.
Virheet
Virheet saapuvat aina JSON-muodossa samoilla kahdella kentällä, ei koskaan HTML-sivuna. Virhemerkkijono on kirjoitettu ihmisen luettavaksi — se nimeää kentän tai rajan, joka ei täyttynyt.
Tila
Mitä se tarkoittaa
400
Bad Request
Jokin rungossa puuttuu, on virheellinen tai ylittää sallitun alueen. Viesti nimeää kentän.
401
Unauthorized
Sähköposti on tuntematon, tai avain ei kuulu kyseiselle tilille.
403
Forbidden
Lähettämäsi activity_key kuuluu toiselle tilille.
429
Too Many Requests
Tämän päivän kiintiö on käytetty loppuun. Se nollautuu kerran päivässä.
500
Server Error
Generaattori ei pystynyt rakentamaan pulmapeliä lähettämästäsi sisällöstä — yleensä liian vähän sanoja tai sanoja, joita ei saada sovitettua yhteen.
Päätepisteet
Yksi polku per aktiviteettityyppi, kaikki POST-pyyntöjä, kaikki saman perus-URL:n alla. Jokaisen kohdalla on lueteltu tarvittava sisältö, luettavat asetukset ja pyyntö, jonka voit ajaa.
Sanat ja kirjaimet
V
O
I
E
A
S
I
A
I
Sanaristikko
Lomittaa vastauksesi ruudukkoon ja numeroi vihjeet puolestasi.
Taulukko sanoja. Jokainen kohta yhdistää vastauksen siihen viittaavaan vihjeeseen.
Käyttää oletuksena nimeä “Crossword API”
Hyvä tietää
Alle kaksi merkkiä pitkät vastaukset poistetaan ennen ruudukon rakentamista, ja vähintään kahden on säilyttävä sen jälkeen.
Vastaukset muutetaan isoiksi kirjaimiksi, ja generaattori saa kaksikymmentä yritystä niiden sovittamiseen. Jos se ei saa sijoitettua yhtäkään sanaa, kutsu vastaa koodilla 500.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
hidden_solution
valinnainenasetuksissa
string
string
Valinnainen bonussana. Sen kirjaimet merkitään valmiin ruudukon ruutuihin, ja pelaajat keräävät ne, kun sanaristikko on ratkaistu, joten jokaisen sen kirjaimen on löydyttävä vastauksista.
Esimerkkipyyntö
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": "fi",
"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"
}
]
}'
Taulukko sanoja. Vihjeteksti muodostaa sanapankin, jonka pohjalta pelaajat työskentelevät.
Käyttää oletuksena nimeä “Wordseeker API”
Hyvä tietää
Alle kaksi merkkiä pitkät vastaukset poistetaan, ja jokainen vastaus muutetaan isoiksi kirjaimiksi ennen ruudukkoon lisäämistä.
Ruudukko täytetään latinalaisilla kirjaimilla, ellei language ole "ar", jolloin täyte vaihtuu arabiaksi.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
hidden_solution
valinnainenasetuksissa
string
string
Jäljelle jäävät kirjaimet muodostavat tämän. Sen asettaminen kertoo generaattorille myös, että se sovittaa ratkaisun ensin sen sijaan, että se mahduttaisi mahdollisimman monta sanaa.
directions
valinnainenasetuksissa
string[]
string[]
Mihin suuntiin sana saa kulkea. Jätä pois, niin sanat kulkevat vain itään, kaakkoon ja etelään.
Yksi seuraavistawesteastnorthsouthnorthwestnortheastsouthwestsoutheast
Oletus: ["east", "southeast", "south"]
template
valinnainenasetuksissa
string
string
Leikkaa ruudukon muotoon sen sijaan, että se jätettäisiin neliöksi.
Yksi seuraavistasquarecirclecrossdiamondpyramidsmileystarcross_plus
Esimerkkipyyntö
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": "fi",
"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"
}
}'
Taulukko sanoja. Yhdessä niiden on sisällettävä piilotetun sanan jokainen kirjain.
Käyttää oletuksena nimeä “Acrostic API”
Hyvä tietää
Jos vastaukset eivät riitä tuottamaan ratkaisun tarvitsemia kirjaimia, kutsu vastaa koodilla 500 sen sijaan, että se tallentaisi puolivalmiin ruudukon.
Generaattori järjestää vastauksesi uudelleen, jotta sarake toimii, joten lähettämäsi järjestys ei ole se, jonka pelaajat näkevät.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
hidden_solution
pakollinenasetuksissa
string
string
Sana, jonka korostettu sarake muodostaa. Tämä päätepiste ei toimi ilman sitä.
Esimerkkipyyntö
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": "fi",
"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"
}
}'
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": "fi",
"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"
}
]
}'
Onnistui
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
"message": "Typing Practice created successfully"
}
Taulukko teemasanoja. Yhdessä spangramin kanssa niiden kirjainten on täytettävä ruudukko täsmälleen.
Käyttää oletuksena nimeä “Strands API”
Hyvä tietää
Kaikkien sanojen ja spangramin kirjainten yhteismäärän on oltava täsmälleen 30, 35, 36, 40, 42, 45, 48, 49, 50, 54, 56, 60, 63, 64, 70, 72 tai 80. Mikä tahansa muu määrä vastaa koodilla 400 ja kertoo, montako kirjainta pitää lisätä tai poistaa.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
theme
valinnainenasetuksissa
string
string
Ruudukon yläpuolella näytettävä arvoitus. Jos se jätetään pois, pelaajat näkevät otsikon.
spangram
valinnainenasetuksissa
string
string
Sana tai ilmaus, joka nimeää teeman ja ylittää ruudukon reunasta toiseen.
Kohta on objekti, jossa on answer, ja valinnaisesti aliases (muut hyväksyttävät kirjoitusasut), description (vinkki) ja group. Isoja kirjaimia, aksentteja ja välimerkkejä ei huomioida nimeä tarkistettaessa.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
list_match_mode
valinnainenasetuksissa
string
string
Lasketaanko nimi heti, kun se on kirjoitettu, vai vasta Enterillä.
Yksi seuraavistawhile_typingon_enter
Oletus: "while_typing"
list_slot_hint
valinnainenasetuksissa
string
string
Mitä tyhjä paikka paljastaa: ei mitään, nimen pituuden, sen ensimmäisen kirjaimen tai kirjoittamasi vinkin.
Yksi seuraavistanonelengthfirst_letterhint
Oletus: "none"
list_arrange
valinnainenasetuksissa
string
string
Yksi sarake per ryhmä tai yksi luettelo.
Yksi seuraavistagroupsone_list
Oletus: "groups"
list_allow_give_up
valinnainenasetuksissa
boolean
boolean
Näyttää luovutuspainikkeen, joka päättää kierroksen ja paljastaa, mitä jäi puuttumaan.
{
"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"
}
Taulukko pareja. Jokainen pari sisältää kaksi yhteenkuuluvaa korttia.
Käyttää oletuksena nimeä “Memory Game API”
Hyvä tietää
Kortti on objekti, jolla on type ja value. Käytä arvoa "text" sanoille, tai "image", "audio", "youtube" tai "link" siten, että value sisältää URL-osoitteen, ja lisää alt kuvausta varten.
Kortti on objekti, jolla on type ja value. Käytä arvoa "text" sanoille, tai "image", "audio", "youtube" tai "link" siten, että value sisältää URL-osoitteen, ja lisää alt kuvausta varten.
Päätepiste tallentaa täsmälleen niin monta korttia kuin lähetät, joten lähetä täsmälleen kaksi per kohta — ensin etupuoli, sitten takapuoli.
Kortti on objekti, jolla on type ja value. Käytä arvoa "text" sanoille, tai "image", "audio", "youtube" tai "link" siten, että value sisältää URL-osoitteen, ja lisää alt kuvausta varten.
POST/api/public/v1/categorizeVähintään 2 items-kohdassa · enintään 60 korttia yhteensä
Sisältö
Taulukko kategorioita, joista jokaisella on nimi ja siihen kuuluvat kortit.
Käyttää oletuksena nimeä “Categorize Game API”
Hyvä tietää
Ilman nimeä lähetetty kategoria tallennetaan nimellä “Untitled Category”, joten lähetä nimi aina.
Kortti on objekti, jolla on type ja value. Käytä arvoa "text" sanoille, tai "image", "audio", "youtube" tai "link" siten, että value sisältää URL-osoitteen, ja lisää alt kuvausta varten.
POST/api/public/v1/reorderVähintään 1 items-kohdassa · enintään 60 korttia yhteensä
Sisältö
Taulukko järjestyksiä. Jokainen sisältää korttinsa oikeassa järjestyksessä.
Käyttää oletuksena nimeä “Reorder Game API”
Hyvä tietää
Lähettämäsi järjestys tallennetaan oikeana järjestyksenä — numero yksi ensin.
Kortti on objekti, jolla on type ja value. Käytä arvoa "text" sanoille, tai "image", "audio", "youtube" tai "link" siten, että value sisältää URL-osoitteen, ja lisää alt kuvausta varten.
POST/api/public/v1/bingoEi ota vastaan items-kohteita
Sisältö
Taulukko kohteita, joista kortit arvotaan. Lähetä selvästi enemmän kuin yhdelle kortille mahtuu ruutuja, jotta kortit eroavat toisistaan.
Käyttää oletuksena nimeä “Bingo API”
Hyvä tietää
Kohde on objekti, jossa on value, ja valinnaisesti type ("text", "image" tai "audio", jolloin value sisältää URL-osoitteen), description (johtolanka, jonka pelinjohtaja lukee ääneen clues-tilassa) ja alt.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
mode
valinnainenasetuksissa
string
string
Mikä täyttää ruudut: omat kohteesi, omat kohteesi johtolangan mukaan nostettuina tai pelkät numerot (jotka eivät tarvitse items-kohteita).
Yksi seuraavistaitemscluesnumbers
Oletus: "items"
rows
valinnainenasetuksissa
number
number
Rivejä kussakin kortissa, 2–5.
Oletus: 3
columns
valinnainenasetuksissa
number
number
Sarakkeita kussakin kortissa, 2–5.
Oletus: 3
highest_number
valinnainenasetuksissa
number
number
Numerotilassa kortit täytetään luvuista 1 aina tähän lukuun asti, enintään 100. Pakettiominaisuus: ilman pakettia se pysyy arvossa 50.
Oletus: 50
Esimerkkipyyntö
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": "fi",
"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"
}
Taulukko kortteja. Koodiin kuuluvat kortit kantavat tiedon paikastaan siinä.
Käyttää oletuksena nimeä “Keypad API”
Hyvä tietää
Kortti on objekti, jossa on value, ja valinnaisesti type ("text", "image" tai "audio", jolloin value sisältää URL-osoitteen), alt ja code_position: sen paikka koodissa, 1 ensimmäinen. Kortti voi olla koodissa vain kerran, ja vähintään yhden kortin on oltava.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
instructions
valinnainenasetuksissa
string
string
Kysymys tai arvoitus, johon koodi vastaa, näytetään korttien kanssa.
force_solution_in_correct_order
valinnainenasetuksissa
boolean
boolean
Kortit on painettava järjestyksessä. Pois päältä oikeat kortit avaavat lukon missä järjestyksessä tahansa.
Oletus: false
randomize_order
valinnainenasetuksissa
boolean
boolean
Jokainen pelaaja saa kortit sekoitetussa järjestyksessä.
Taulukko kvartetteja. Kullakin on nimi ja täsmälleen neljä korttia.
Käyttää oletuksena nimeä “Quartets API”
Hyvä tietää
Kortti on nimi tai objekti, jossa on name ja description (kortissa näkyvä tieto). Mikään kortin nimi ei saa esiintyä pelissä kahdesti: pelaajat pyytävät kortteja nimen perusteella.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
type
valinnainenasetuksissa
string
string
Tavallinen peli tai oppimispeli, jossa jokaisessa kortissa näkyy tieto. Jos se jätetään pois, se on learn, kun jossakin kortissa on description.
Yksi seuraavistanormallearn
Esimerkkipyyntö
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": "fi",
"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"
}
}'
Onnistui
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/quartets/embed?p=-Nq8sample_activity_key",
"message": "Quartets game created successfully"
}
Taulukko kysymyksiä. Monivalintakysymyksillä on omat vastausvaihtoehtonsa; avoimilla kysymyksillä on hyväksymäsi vastaus.
Käyttää oletuksena nimeä “Quiz API”
Hyvä tietää
question_type on "multiple_choice", jolloin oikea vaihtoehto saa arvon isCorrect true; "true_false", joka on sama mutta täsmälleen kahdella vaihtoehdolla, tosi ensin ja epätosi toisena; tai "open_answer", joka käyttää sen sijaan kenttää correct_answer. Jos kenttä jätetään pois, se käsitellään monivalintana.
Tietovisan päätepiste välittää settings-kentän suoraan aktiviteetin asetuslohkoiksi, joten se ei ole paikka irrallisille valinnoille — säädä tietovisaa jälkikäteen editorissa.
Esimerkkipyyntö
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": "fi",
"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."
}
]
}'
question_type on "multiple_choice", jolloin oikea vaihtoehto saa arvon isCorrect true; "true_false", joka on sama mutta täsmälleen kahdella vaihtoehdolla, tosi ensin ja epätosi toisena; tai "open_answer", joka käyttää sen sijaan kenttää correct_answer. Jos kenttä jätetään pois, se käsitellään monivalintana.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
number_of_tiles
valinnainenasetuksissa
number
number
Kuinka monta ruutua laudalla on. Väliltä 10–75.
Oletus: 30
game_mode
valinnainenasetuksissa
string
string
Kilpailevatko pelaajat maaliin vai keräävätkö he esineitä matkan varrella.
Yksi seuraavistarace_to_finishcollect_items
Oletus: "race_to_finish"
Esimerkkipyyntö
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": "fi",
"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"
}
}'
Onnistui
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
"message": "Board Game created successfully"
}
Taulukko monivalinta- tai tosi/epätosi-kysymyksiä, täsmälleen samassa muodossa kuin tietovisan päätepiste ne ottaa vastaan. Avoimet kysymykset hylätään: oveen tarvitaan siihen kirjoitettu vastaus.
Käyttää oletuksena nimeä “Maze API”
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
maze_width
valinnainenasetuksissa
string
string
Salien sijoittelu: yksi sarake, neliö tai leveämpi.
Yksi seuraavistanarrownormalwide
Oletus: "normal"
maze_corridors
valinnainenasetuksissa
string
string
Kuinka paljon sokkeloa on kahden kysymyksen välissä.
Yksi seuraavistashortnormallong
Oletus: "normal"
maze_fog
valinnainenasetuksissa
string
string
Näytä koko sokkelo tai vain se, minkä vieressä pelaaja on ollut.
Yksi seuraavistaoffnear
Oletus: "off"
maze_wrong_door_pause
valinnainenasetuksissa
string
string
Kuinka kauan ovet pysyvät kiinni väärän oven jälkeen.
Yksi seuraavistanoneshortlong
Oletus: "short"
maze_walk_there
valinnainenasetuksissa
boolean
boolean
Tarjoaa painikkeen, joka kävelyttää pelinappulan seuraavaan saliin.
Oletus: false
maze_seed
valinnainenasetuksissa
string
string
Siemen, josta sokkelo luodaan. Sama siemen ja samat kysymykset tuottavat saman sokkelon; jos se jätetään pois, arvotaan uusi.
Esimerkkipyyntö
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": "fi",
"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"
}
}'
Taulukko kategorioita vasemmalta oikealle. Kullakin on nimi ja sen vihjeet ylimmältä riviltä alaspäin.
Käyttää oletuksena nimeä “Jeopardy API”
Hyvä tietää
Vihje on kysymys sellaisena kuin tietovisan päätepiste sen ottaa vastaan, open_answer, ellei toisin sanota, ja siinä on correct_answer sekä valinnaisesti aliases. Siinä voi olla myös value (sen oma arvo) ja daily_double. null jättää ruudun tyhjäksi.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
jeopardy_buzzer_mode
valinnainenasetuksissa
string
string
Kuka pelaa miten: pelinjohtaja ohjaa konsolista, pelaajat painavat summeria puhelimillaan tai jokainen pelaaja käy taulun läpi yksin.
Yksi seuraavistahostphonessolo
Oletus: "host"
jeopardy_contestants
valinnainenasetuksissa
string
string
Puhuuko konsoli joukkueista vai pelaajista.
Yksi seuraavistateamsplayers
Oletus: "teams"
jeopardy_value_step
valinnainenasetuksissa
number
number
Mitä rivi on arvoltaan: vihjeen arvo on tämä luku kerrottuna sen rivin numerolla. 50–500, 50 välein.
Oletus: 100
jeopardy_answer_time
valinnainenasetuksissa
number
number
Sekunteja vastaamiseen, kun vihje on avattu, enintään 300. 0 tarkoittaa, ettei kelloa ole.
Oletus: 20
jeopardy_wrong_answer_costs
valinnainenasetuksissa
boolean
boolean
Väärä vastaus vähentää pistemäärästä vihjeen arvon.
Oletus: false
jeopardy_reveal_on_timeout
valinnainenasetuksissa
boolean
boolean
Taulu näyttää vastauksen itse, kun kello loppuu.
Oletus: false
jeopardy_require_question_form
valinnainenasetuksissa
boolean
boolean
Muistuttaa pelaajia vastaamaan kysymyksen muodossa.
Oletus: false
Esimerkkipyyntö
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": "fi",
"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
}
}'
Ponnahdusikkuna on objekti, jossa on time (sekunteja tai "1:23"), kind ("question", ellei siinä lue "note", "think" tai "chapter") ja description. Kysymys on kysymys sellaisena kuin tietovisan päätepiste sen ottaa vastaan, ja siinä voi olla rewind_to: mistä kohdasta väärän vastauksen jälkeen toistetaan.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
video_url
pakollinenasetuksissa
string
string
Video: YouTube-, Vimeo- tai Bunny Stream -sivu tai suora linkki mp4-, webm- tai mov-tiedostoon.
video_duration
valinnainenasetuksissa
number
number
Videon pituus sekunteina. Kun se annetaan, lopun jälkeen oleva ponnahdusikkuna hylätään.
Esimerkkipyyntö
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": "fi",
"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
}
}'
Onnistui
{
"success": true,
"id": "-Nq8sample_activity_key",
"url": "https://puzzel.org/en/interactive-video/embed?p=-Nq8sample_activity_key",
"message": "Interactive video created successfully"
}
POST/api/public/v1/calculationEi ota vastaan items-kohteita
Sisältö
Yksi lause sentence-kentässä. Tämä päätepiste ei ota vastaan items-kohteita.
Käyttää oletuksena nimeä “Calculation Game API”
Hyvä tietää
Jos rajoitukset ovat liian tiukat lauseen koodaamiseen, kutsu vastaa koodilla 400 ja pyytää löysäämään niitä sen sijaan, että se tallentaisi keskeneräisen pulmapelin.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
sentence
pakollinen
string
string
Lause, jonka pelaajat paljastavat ratkaisemalla laskut.
difficulty_level
valinnainenasetuksissa
number
number
Suurin sallittu vastaus, joka laskulla saa olla.
Yksi seuraavista20501001000
Oletus: "100"
operators
valinnainenasetuksissa
string[]
string[]
Mitkä laskutoimitukset voivat esiintyä. x on kertolasku, : on jakolasku.
Yksi seuraavista+-x:
Oletus: ["+", "-", "x", ":"]
max_operations
valinnainenasetuksissa
number
number
Kuinka monta laskutoimitusta yksi lasku voi ketjuttaa yhteen.
Yksi seuraavista123
Oletus: 1
number_difficulty
valinnainenasetuksissa
number
number
Rajoittaa laskun yksittäisiä lukuja. Väliltä 5–1000.
POST/api/public/v1/sudokuEi ota vastaan items-kohteita
Sisältö
Ei mitään. Koko pulmapeli syntyy sen kahdesta asetuksesta.
Käyttää oletuksena nimeä “Sudoku API”
Hyvä tietää
Älä lähetä items-kohteita äläkä lausetta — size ja difficulty ovat koko syöte.
Editori tarjoaa vaikeustason vain kooille 2x3, 3x3 ja 3x4. API soveltaa sitä jokaiseen kokoon, mukaan lukien 2x2 ja 4x4.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
size
valinnainenasetuksissa
string
string
Yhden lohkon koko, kirjoitettuna rivit kertaa sarakkeet — 3x3 antaa klassisen 9x9-ruudukon. Päätepiste vain tarkistaa, että se jäsentyy kahdeksi luvuksi, joten pysy editorin tarjoamissa koissa.
Yksi seuraavista2x22x33x33x44x4
Oletus: "3x3"
difficulty_level
valinnainenasetuksissa
string
string
Kuinka monta numeroa jätetään laudalle lähtökohdaksi.
Kirjoita koko lause ja laita tähdet jokaisen pois jätettävän sanan ympärille: "Water boils at *100* degrees." Useampi sana yhden tähtiparin sisällä on yksi aukko. Kohtaan voi lisätä myös ohjeen, joka näytetään lauseen yläpuolella.
Esimerkkipyyntö
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": "fi",
"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."
}
]
}'
Onnistui
{
"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"
}
Taulukko lauseita. Jokainen merkittävä sana kirjoitetaan muodossa [word](label).
Käyttää oletuksena nimeä “Sentence analysis API”
Hyvä tietää
Kirjoita lause muodossa "The [dog](noun) [barks](verb)." Sanat ilman tunnistetta näytetään, mutta niistä ei kysytä. Tunnisteet noun, verb, adjective ja subject näytetään jokaiselle pelaajalle hänen omalla kielellään.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
categories
valinnainenasetuksissa
string[]
string[]
Tunnisteet, joista pelaajat valitsevat, järjestyksessä. Jos se jätetään pois, käytetään lauseissa esiintyviä tunnisteita. Lähetä se, jos haluat lisätä tunnisteen, jota mikään sana ei kanna, tai korjata järjestyksen.
Esimerkkipyyntö
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": "fi",
"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"
]
}
}'
Jokaisessa kategoriassa on oltava yhtä monta kohdetta, 3–6, kaikki erilaisia. Yksi kategoria voidaan merkitä järjestetyksi ordered (hinnat, ajat, iät) ja sille voi antaa valinnaisen unit-yksikön, jolloin generaattori voi kirjoittaa vihjeitä siitä, mikä on enemmän tai vähemmän ja kuinka paljon.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
story
valinnainenasetuksissa
string
string
Vihjeiden yläpuolella näytettävä taustatarina.
difficulty
valinnainenasetuksissa
string
string
Minkä tyyppisiä vihjeitä generaattori saa käyttää.
Yksi seuraavistaeasymediumhard
Oletus: "easy"
hints
valinnainenasetuksissa
boolean
boolean
Tarjoaa painikkeen, joka näyttää seuraavan vaiheen.
Oletus: true
auto_cross
valinnainenasetuksissa
boolean
boolean
Osuman merkitseminen yliviivaa loput sen riviltä ja sarakkeesta.
Oletus: true
clue_mode
valinnainenasetuksissa
string
string
Kuka kirjoittaa pelaajien näkemät vihjeet: ne luodaan taulukosta, omat lauseesi kohdassa free_clues, tai ei kukaan.
Yksi seuraavistageneratedfreenone
Oletus: "generated"
free_clues
valinnainenasetuksissa
string[]
string[]
Omat vihjelauseesi, jotka näytetään sellaisinaan, kun clue_mode on "free". Mikään ei tarkista niitä.
Esimerkkipyyntö
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": "fi",
"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"
}
}'
Vaihe on objekti, jossa on title, description, code ja valinnaisesti accepted_codes (muut hyväksyttävät kirjoitusasut), url ja link_text. Koodin tarkistuksessa isoilla kirjaimilla ja välilyönneillä ei ole väliä. Karttaa nastoineen voi lisätä vain editorissa.
Esimerkkipyyntö
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": "fi",
"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"
]
}
]
}'
Objektit ja kohteet ovat square, triangle, circle, hexagon, pentagon, star, diamond tai heart. Suhteet ovat inside, outside, behind, in_front_of, right_of, left_of, above, below, same_color_as, different_color_from, larger_than ja smaller_than. Sääntö, jota ei voi koskaan täyttää, vastaa koodilla 400.
Taulukko lauseita. Kukin luettelee kuvina piirretyt sanat; kaikki muut sanat pysyvät kirjaimina.
Käyttää oletuksena nimeä “Rebus API”
Hyvä tietää
Sana piirretään osista, jotka yhdessä kirjoittavat sen. Osassa on kirjaimet, joita se edustaa (text), emoji ja shows: sana sille, mitä kuva esittää ("broom" kuvalle, joka edustaa sanaa "room"). Puzzel laskee kirjainmuutokset. Osa voi olla myös symboli, kuten 4 sanalle "for".
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
rebus_commas
valinnainenasetuksissa
boolean
boolean
Piirtää pudonneen ensimmäisen tai viimeisen kirjaimen pilkuksi kuvan viereen.
POST/api/public/v1/jigsawEi ota vastaan items-kohteita
Sisältö
Yksi kuvan URL-osoite image-kentässä. Tämä päätepiste ei ota vastaan items-kohteita.
Käyttää oletuksena nimeä “Jigsaw Game API”
Hyvä tietää
API tekee aina 4x4-palapelin. Palojen määrä, epäsäännölliset palat ja suorat reunat ovat editorin asetuksia — rivien tai sarakkeiden lähettäminen tässä ei tee mitään.
URL-osoite tallennetaan sellaisenaan kuin lähetit sen, eikä tiedostoa koskaan kopioida, joten sen on pysyttävä julkisesti saatavilla niin kauan kuin aktiviteettia pelataan.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
image
pakollinen
string
string
Pilkottavan kuvan absoluuttinen URL-osoite. Lähetetään ylätasolla, ei settings-kentän sisällä.
POST/api/public/v1/slidingpuzzleEi ota vastaan items-kohteita
Sisältö
Yksi kuvan URL-osoite settings-kentän sisällä. Tämä päätepiste ei ota vastaan items-kohteita.
Käyttää oletuksena nimeä “Sliding Puzzle API”
Hyvä tietää
Toisin kuin palapeli, tämä päätepiste lukee kuvansa kohdasta settings.image. Ylätason image-kenttä jätetään huomiotta, ja kutsu vastaa koodilla 400.
URL-osoite tallennetaan sellaisenaan kuin lähetit sen, eikä tiedostoa koskaan kopioida, joten sen on pysyttävä julkisesti saatavilla niin kauan kuin aktiviteettia pelataan.
Luettavat asetukset
Kenttä
Tyyppi
Mitä se tekee
image
pakollinenasetuksissa
string
string
Sekoitettavan kuvan absoluuttinen URL-osoite. Toisin kuin palapelissä, tämä sijaitsee settings-kentän sisällä.