Siirry sisältöön
Esikatselet Puzzel.orgin uutta versiota Takaisin nykyiselle sivustolle
Kehittäjä-API

Rakenna aktiviteetteja omasta järjestelmästäsi

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

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äTyyppiMitä se tekee
account_api_key
pakollinen
string
stringTilisi API-avain. Se annetaan rungossa, ei otsikkokentässä.
email
pakollinen
string
stringOsoite, jolla Puzzel.org-tilisi kirjautuu sisään. Avain on voimassa vain yhdessä sen kanssa.

Avaimesi löytyy hallintapaneelisi tili-osiosta Näytä-painikkeen takaa.

Kirjaudu sisään

API-avaimia jaetaan tilauksen alkaessa, joten ilmaisella tilillä ei vielä ole sellaista.

Katso paketit

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äTyyppiMitä se tekee
account_api_key
pakollinen
string
stringTilisi API-avain. Se annetaan rungossa, ei otsikkokentässä.
email
pakollinen
string
stringOsoite, jolla Puzzel.org-tilisi kirjautuu sisään. Avain on voimassa vain yhdessä sen kanssa.
title
valinnainen
string
stringNimi, jonka aktiviteetti saa hallintapaneelissasi. Jätä se pois, niin päätepiste käyttää omaa oletusnimeään.
language
valinnainen
string
stringMää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
stringJä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.

Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Epäonnistui 
{
  "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.

TilaMitä 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

Sanaristikko

Lomittaa vastauksesi ruudukkoon ja numeroi vihjeet puolestasi.

#
POST /api/public/v1/crossword Vähintään 2 items-kohdassa
Sisältö

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

Sanasokkelo

Piilottaa sanasi kirjainruudukkoon valitsemiisi suuntiin ja muotoon.

#
POST /api/public/v1/wordseeker Vähintään 2 items-kohdassa
Sisältö

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äTyyppiMitä se tekee
hidden_solution
valinnainen asetuksissa
string
stringJä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
valinnainen asetuksissa
string[]
string[]Mihin suuntiin sana saa kulkea. Jätä pois, niin sanat kulkevat vain itään, kaakkoon ja etelään.
Yksi seuraavista westeastnorthsouthnorthwestnortheastsouthwestsoutheast
Oletus: ["east", "southeast", "south"]
template
valinnainen asetuksissa
string
stringLeikkaa ruudukon muotoon sen sijaan, että se jätettäisiin neliöksi.
Yksi seuraavista squarecirclecrossdiamondpyramidsmileystarcross_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"
  }
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordseeker/embed?p=-Nq8sample_activity_key",
  "message": "Wordseeker created successfully"
}
Avaa editori Takaisin alkuun

Akrostikon

Pinoaa vastauksesi niin, että yksi sarake muodostaa piilotetun sanan.

#
POST /api/public/v1/acrostic Vähintään 1 items-kohdassa
Sisältö

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äTyyppiMitä se tekee
hidden_solution
pakollinen asetuksissa
string
stringSana, 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"
  }
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/acrostic/embed?p=-Nq8sample_activity_key",
  "message": "Acrostic created successfully"
}
Avaa editori Takaisin alkuun

Kirjainsekoitus

api_e_word_scramble

#
POST /api/public/v1/word-scramble Vähintään 1 items-kohdassa
Sisältö

api_c_word_scramble

Käyttää oletuksena nimeä “Word Scramble API”

Hyvä tietää
  • API:n kautta tehdyissä aktiviteeteissa järjestyksen sekoitus -asetus on aina päällä, joten lähettämäsi järjestys ei ole se, jonka pelaajat saavat.
Luettavat asetukset
KenttäTyyppiMitä se tekee
hidden_solution
valinnainen asetuksissa
string
stringValinnainen bonussana, jonka pelaajat syöttävät, kun muu on ratkaistu.
Esimerkkipyyntö
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": "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"
  }
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/word-scramble/embed?p=-Nq8sample_activity_key",
  "message": "Word Scramble created successfully"
}
Avaa editori Takaisin alkuun

Hirsipuu

Muuttaa sanasi tai ilmauksesi kirjaimenarvauskierroksiksi.

#
POST /api/public/v1/hangman Vähintään 1 items-kohdassa
Sisältö

Taulukko sanoja tai lyhyitä ilmauksia. Vihje on se, minkä pelaajat näkevät.

Käyttää oletuksena nimeä “Hangman API”

Esimerkkipyyntö
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": "fi",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    }
  ]
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/hangman/embed?p=-Nq8sample_activity_key",
  "message": "Hangman created successfully"
}
Avaa editori Takaisin alkuun

Wordle

Tekee jokaisesta lähettämästäsi sanasta sananarvauspelin.

#
POST /api/public/v1/wordle Vähintään 1 items-kohdassa
Sisältö

Taulukko sanoja. Pelaajat saavat yhden kierroksen per sana.

Käyttää oletuksena nimeä “Wordle API”

Hyvä tietää
  • Tehty niin, että arvausten tarkistus oikeiksi sanoiksi -asetus on päällä. Kytke se pois editorissa, jos sanasi ovat nimiä tai keksittyjä.
Esimerkkipyyntö
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": "fi",
  "items": [
    {
      "answer": "MELON",
      "description": "Sweet and green",
      "type": "text"
    },
    {
      "answer": "PEACH",
      "description": "Fuzzy and orange",
      "type": "text"
    }
  ]
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordle/embed?p=-Nq8sample_activity_key",
  "message": "Wordle created successfully"
}
Avaa editori Takaisin alkuun

Näppäilyharjoitus

api_e_typing_practice

#
POST /api/public/v1/typing-practice Vähintään 1 items-kohdassa
Sisältö

api_c_typing_practice

Käyttää oletuksena nimeä “Typing Practice API”

Esimerkkipyyntö
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": "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"
}
Avaa editori Takaisin alkuun

Onnenpyörä

api_e_wheel_of_fortune

#
POST /api/public/v1/wheel-of-fortune Vähintään 1 items-kohdassa
Sisältö

api_c_wheel_of_fortune

Käyttää oletuksena nimeä “Wheel of Fortune API”

Hyvä tietää
  • Tehty asetuksella “näytä tulos vain pyörässä”, joten tulos luetaan pyörästä sen sijaan, että se ilmoitettaisiin sen vierellä.
Esimerkkipyyntö
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": "fi",
  "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"
    }
  ]
}'
Onnistui 
{
  "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"
}
Avaa editori Takaisin alkuun
Kortit ja parit

Memory

Pöytään käännettyjä kortteja, jotka käännetään ja yhdistetään pareiksi.

#
POST /api/public/v1/memory Vähintään 2 items-kohdassa
Sisältö

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.
Esimerkkipyyntö
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": "fi",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/memory/embed?p=-Nq8sample_activity_key",
  "message": "Memory game created successfully"
}
Avaa editori Takaisin alkuun

Yhdistelypeli

api_e_matching_pairs

#
POST /api/public/v1/matching-pairs Vähintään 2 items-kohdassa
Sisältö

api_c_matching_pairs

Käyttää oletuksena nimeä “Matching 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.
Esimerkkipyyntö
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": "fi",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/matching-pairs/embed?p=-Nq8sample_activity_key",
  "message": "Matching pairs game created successfully"
}
Avaa editori Takaisin alkuun

Kertauskortit

api_e_flash_cards

#
POST /api/public/v1/flash-cards Vähintään 1 items-kohdassa
Sisältö

api_c_flash_cards

Käyttää oletuksena nimeä “Flash Cards API”

Hyvä tietää
  • 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.
Esimerkkipyyntö
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": "fi",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/flash-cards/embed?p=-Nq8sample_activity_key",
  "message": "Flash Cards created successfully"
}
Avaa editori Takaisin alkuun

Luokittelutehtävä

Kortteja lajiteltavaksi niille kuuluvaan kategoriaan.

#
POST /api/public/v1/categorize Vähintään 2 items-kohdassa
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.
Esimerkkipyyntö
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": "fi",
  "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"
        }
      ]
    }
  ]
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/categorize/embed?p=-Nq8sample_activity_key",
  "message": "Categorize game created successfully"
}
Avaa editori Takaisin alkuun

Järjestystehtävä

Järjestys, jonka pelaajat palauttavat oikeaksi.

#
POST /api/public/v1/reorder Vähintään 1 items-kohdassa
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.
Esimerkkipyyntö
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": "fi",
  "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"
        }
      ]
    }
  ]
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/reorder/embed?p=-Nq8sample_activity_key",
  "message": "Reorder game created successfully"
}
Avaa editori Takaisin alkuun
Kysymykset ja vastaukset

Quiz

Monivalinta- ja avoimia kysymyksiä, joista pisteet lasketaan pelin edetessä.

#
POST /api/public/v1/quiz Vähintään 1 items-kohdassa
Sisältö

Taulukko kysymyksiä. Monivalintakysymyksillä on omat vastausvaihtoehtonsa; avoimilla kysymyksillä on hyväksymäsi vastaus.

Käyttää oletuksena nimeä “Quiz API”

Hyvä tietää
  • question_type on joko "multiple_choice", jolloin oikealla vaihtoehdolla on isCorrect true, tai "open_answer", joka käyttää sen sijaan kenttää correct_answer. Jos se jätetään pois, sitä käsitellään monivalintana.
  • Quiz-päätepiste välittää settings-kentän suoraan aktiviteetin asetuslohkoiksi, joten se ei ole paikka irrallisille valinnoille — säädä quiz 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."
    }
  ]
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key",
  "message": "Quiz created successfully"
}
Avaa editori Takaisin alkuun

Lautapeli

api_e_board_game

#
POST /api/public/v1/board-game Vähintään 1 items-kohdassa
Sisältö

api_c_board_game

Käyttää oletuksena nimeä “Board Game API”

Hyvä tietää
  • question_type on joko "multiple_choice", jolloin oikealla vaihtoehdolla on isCorrect true, tai "open_answer", joka käyttää sen sijaan kenttää correct_answer. Jos se jätetään pois, sitä käsitellään monivalintana.
Luettavat asetukset
KenttäTyyppiMitä se tekee
number_of_tiles
valinnainen asetuksissa
number
numberKuinka monta ruutua laudalla on. Väliltä 10–75.
Oletus: 30
game_mode
valinnainen asetuksissa
string
stringKilpailevatko pelaajat maaliin vai keräävätkö he esineitä matkan varrella.
Yksi seuraavista race_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"
}
Avaa editori Takaisin alkuun
Lauseet ja luvut

Kryptogrammi

Muuttaa lauseen murrettavaksi koodiksi, yksi merkki kerrallaan.

#
POST /api/public/v1/cryptogram Ei ota vastaan items-kohteita
Sisältö

Yksi lause sentence-kentässä. Tämä päätepiste ei ota vastaan items-kohteita.

Käyttää oletuksena nimeä “Cryptogram API”

Hyvä tietää
  • Kaikki, mitä lähetät kohdassa items, jätetään huomiotta — pulmapeli rakennetaan pelkästä lauseesta.
Luettavat asetukset
KenttäTyyppiMitä se tekee
sentence
pakollinen
string
stringSalattava lause. Pelaajat purkavat sen merkki kerrallaan.
helpers
valinnainen asetuksissa
string
stringMitkä merkit annetaan ilmaiseksi avuksi alkuun: ei mitään, yleisimmät, vokaalit tai itse luettelemasi.
Yksi seuraavista nonemost_commonvowelscustom
Oletus: "none"
character_list
valinnainen asetuksissa
string
stringAakkosto, josta salakirjoitus rakennetaan. Jos jätetään tyhjäksi, salaus valitsee omansa.
extra_letters
valinnainen asetuksissa
string
stringMerkit, jotka annetaan, kun helpers on "custom". Jätetään huomiotta muissa aputiloissa.
hide_unused_characters
valinnainen asetuksissa
boolean
booleanJättää avaimen ulkopuolelle merkit, joita lause ei koskaan käytä.
Oletus: false
Esimerkkipyyntö
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": "fi",
  "sentence": "An apple a day keeps the doctor away",
  "settings": {
    "helpers": "vowels",
    "hide_unused_characters": false
  }
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/cryptogram/embed?p=-Nq8sample_activity_key",
  "message": "Cryptogram created successfully"
}
Avaa editori Takaisin alkuun

Laskutehtävä

Piilottaa lauseen laskujen taakse — ratkaise lasku, paljasta kirjain.

#
POST /api/public/v1/calculation Ei 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äTyyppiMitä se tekee
sentence
pakollinen
string
stringLause, jonka pelaajat paljastavat ratkaisemalla laskut.
difficulty_level
valinnainen asetuksissa
number
numberSuurin sallittu vastaus, joka laskulla saa olla.
Yksi seuraavista 20501001000
Oletus: "100"
operators
valinnainen asetuksissa
string[]
string[]Mitkä laskutoimitukset voivat esiintyä. x on kertolasku, : on jakolasku.
Yksi seuraavista +-x:
Oletus: ["+", "-", "x", ":"]
max_operations
valinnainen asetuksissa
number
numberKuinka monta laskutoimitusta yksi lasku voi ketjuttaa yhteen.
Yksi seuraavista 123
Oletus: 1
number_difficulty
valinnainen asetuksissa
number
numberRajoittaa laskun yksittäisiä lukuja. Väliltä 5–1000.
Oletus: 100
Esimerkkipyyntö
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": "fi",
  "sentence": "Fruit salad for everyone",
  "settings": {
    "difficulty_level": "100",
    "operators": [
      "+",
      "-",
      "x",
      ":"
    ],
    "max_operations": 1,
    "number_difficulty": 100
  }
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/calculation/embed?p=-Nq8sample_activity_key",
  "message": "Calculation game created successfully"
}
Avaa editori Takaisin alkuun

Sudoku

Luo ratkaistun ruudukon ja poistaa siitä sitten numeroita.

#
POST /api/public/v1/sudoku Ei 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äTyyppiMitä se tekee
size
valinnainen asetuksissa
string
stringYhden 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 seuraavista 2x22x33x33x44x4
Oletus: "3x3"
difficulty_level
valinnainen asetuksissa
string
stringKuinka monta numeroa jätetään laudalle lähtökohdaksi.
Yksi seuraavista easynormalhard
Oletus: "normal"
Esimerkkipyyntö
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": "fi",
  "settings": {
    "size": "3x3",
    "difficulty_level": "normal"
  }
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/sudoku/embed?p=-Nq8sample_activity_key",
  "message": "Sudoku created successfully"
}
Avaa editori Takaisin alkuun
Kuvat

Palapeli

Leikkaa kuvan palasiksi, jotka vedetään takaisin yhteen.

#
POST /api/public/v1/jigsaw Ei 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äTyyppiMitä se tekee
image
pakollinen
string
stringPilkottavan kuvan absoluuttinen URL-osoite. Lähetetään ylätasolla, ei settings-kentän sisällä.
Esimerkkipyyntö
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": "fi",
  "image": "https://example.com/orchard.jpg"
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jigsaw/embed?p=-Nq8sample_activity_key",
  "message": "Jigsaw game created successfully"
}
Avaa editori Takaisin alkuun

Liukupalapeli

Sekoittaa kuvan ruutuihin, jotka liu'utetaan paikoilleen.

#
POST /api/public/v1/slidingpuzzle Ei 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äTyyppiMitä se tekee
image
pakollinen asetuksissa
string
stringSekoitettavan kuvan absoluuttinen URL-osoite. Toisin kuin palapelissä, tämä sijaitsee settings-kentän sisällä.
Esimerkkipyyntö
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": "fi",
  "settings": {
    "image": "https://example.com/orchard.jpg"
  }
}'
Onnistui 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/slidingpuzzle/embed?p=-Nq8sample_activity_key",
  "message": "Sliding puzzle created successfully"
}
Avaa editori Takaisin alkuun

Jokin ei toimi odotetusti?

Lähetä pyyntö, jota kokeilit, ja virhe, jonka sait vastaukseksi, niin saat oikean vastauksen henkilöltä, joka kirjoitti päätepisteen.

Lähetä sähköpostia tukeen