Udvikler-API

Byg aktiviteter fra dit eget system

Ét POST-kald pr. aktivitetstype. Send dit indhold som JSON, og få en aktivitet i din Puzzel.org-konto og en URL, du kan give til spillerne eller sætte ind i et iframe.

Base-URL: https://puzzel.org/api/public/v1
Godkendelse: Nøgle + e-mail i JSON-bodyen
Endpoints: 38 aktivitetstyper
Kvote: 10 aktiviteter om dagen

Din første anmodning

Intet at installere og intet håndtryk: send en JSON-body med din nøgle, din e-mail og dit indhold. Svaret indeholder den nye aktivitets nøgle og den URL, den spilles på.

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": "da",
  "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"
    }
  ]
}'

Succes

{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

Hvert eksempel på denne side er en komplet anmodning, du kan køre direkte. Sæt din egen nøgle og dit eget indhold ind, og det virker uden ændringer.

Godkendelse

Der er ingen headers og ingen bearer-token. Begge oplysninger sendes i JSON-bodyen for hver anmodning, og nøglen bliver kun accepteret for den konto, som e-mailen tilhører.

Felt	Type	Hvad det gør
`account_api_key` påkrævet string	string	Din kontos API-nøgle. Den bliver sendt i bodyen, ikke i en header.
`email` påkrævet string	string	Adressen, din Puzzel.org-konto logger ind med. Nøglen er kun gyldig sammen med den.

Din nøgle ligger under kontoafsnittet på dit dashboard, bag Vis.

Log ind

API-nøgler bliver uddelt, når et abonnement starter, så en gratis konto har endnu ikke en.

Se planerne

Behandl nøglen som en adgangskode. Den opretter og overskriver aktiviteter på din konto, så hold den på serversiden og væk fra alt, en browser kan læse.

Anmodningens body

Hvert endpoint tager de samme fem felter. Det, der adskiller dem, er content-feltet nedenunder: de fleste tager en liste af items, nogle få tager én sentence eller ét image, og sudoku tager slet intet.

Felt	Type	Hvad det gør
`account_api_key` påkrævet string	string	Din kontos API-nøgle. Den bliver sendt i bodyen, ikke i en header.
`email` påkrævet string	string	Adressen, din Puzzel.org-konto logger ind med. Nøglen er kun gyldig sammen med den.
`title` valgfri string	string	Navnet, aktiviteten får på dit dashboard. Udelad det, så bruger endpointet sit eget standardnavn.
`language` valgfri string	string	Bestemmer kun locale i den URL, du får tilbage — den oversætter ikke noget af det, du sender. Ordsøgning bruger den også til at skifte fyldbogstaverne til arabisk, når den er "ar". Standard: "en"
`activity_key` valgfri string	string	Udelad det for at oprette en ny aktivitet. Angiv nøglen til en, du allerede ejer, så bliver den aktivitet genopbygget i stedet.

settings er et objekt med indstillinger for det enkelte endpoint. Hvilke indstillinger et endpoint læser, står angivet under det; alt andet, du putter der, bliver ignoreret.

Hvad du får tilbage

Et vellykket kald svarer 200 med den nye aktivitets nøgle og den URL, den spilles på. Alt andet svarer med success sat til false og en enkelt error-streng.

Succes

{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

Fejl

{
  "success": false,
  "error": "Invalid Email or API Key"
}

Den url, du får tilbage, er embed-visningen. Skift embed ud med play for at åbne den i fuld side, eller med build for at åbne den i editoren — nøglen efter p= er den samme.

Oprettelse vs. opdatering

Send activity_key, så bliver aktiviteten bag den genopbygget på stedet: dens indhold bliver udskiftet, dens navn og versionsstempel bliver opdateret, og selve nøglen forbliver den samme — så links og indlejringer, du allerede har delt, bliver ved med at virke. Resultater, mappeplacering og alle indstillinger, som endpointet ikke selv skriver til, forbliver som de var.

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 bliver anvendt ved hver opdatering, også dens standardværdi — udelad det, så bliver aktiviteten omdøbt til det pågældende endpoints standardnavn.
De indstillingsblokke, et endpoint selv skriver til, bliver skrevet helt om, så en opdatering også nulstiller dem til de værdier, du sender, eller til endpointets standardværdier.
Du kan kun opdatere aktiviteter, din egen konto ejer. En andens nøgle svarer 403.
En opdatering koster det samme som en oprettelse: ét kald af dagens kvote.

Kaldegrænse

10 aktiviteter pr. konto pr. dag

Hvert vellykket kald tæller, oprettelser og opdateringer på lige fod. Går du over grænsen, svarer den næste anmodning 429, indtil tælleren bliver nulstillet.

Tælleren bliver nulstillet én gang om dagen af et planlagt job, ikke over et glidende 24-timers vindue.

Fejl

Fejl kommer altid som JSON med de samme to felter, aldrig som en HTML-side. Error-strengen er skrevet, så et menneske kan læse den — den navngiver det felt eller den grænse, der fejlede.

Status	Hvad det betyder
`400` Bad Request	Noget i bodyen mangler, er forkert formet eller ligger uden for det tilladte område. Beskeden navngiver feltet.
`401` Unauthorized	E-mailen er ukendt, eller nøglen hører ikke til den konto.
`403` Forbidden	Den activity_key, du sendte, hører til en anden konto.
`429` Too Many Requests	Dagens kvote er brugt op. Den nulstilles én gang om dagen.
`500` Server Error	Generatoren kunne ikke bygge en opgave ud fra det, du sendte — som regel for få ord, eller ord, der ikke kan passes sammen.

Endpoints

Én sti pr. aktivitetstype, alle er POST, alle under samme base-URL. Hver enkelt lister det indhold, den skal bruge, de settings, den læser, og en anmodning, du kan køre.

Ord & bogstaver

Krydsord

Sammenfletter dine svar i et gitter og nummererer definitionerne for dig.

POST /api/public/v1/crossword 2 til 80 i items

Indhold

En liste af ord. Hver post parrer svaret med den clue, der peger på det.

Falder tilbage til navnet “Crossword API”

Værd at vide

Svar, der er kortere end to tegn, bliver fjernet, før gitteret bliver bygget, og mindst to skal overleve det.
Svar bliver sat med store bogstaver, og generatoren får tyve forsøg til at placere dem. Hvis den ikke kan placere et eneste ord, svarer kaldet 500.

Settings, den læser

Felt	Type	Hvad det gør
`hidden_solution` valgfri i settings string	string	Et valgfrit bonusord. Dets bogstaver bliver markeret i felter i det færdige gitter, som spillerne kan samle, når krydsordet er løst, så hvert bogstav i det skal findes i svarene.

Eksempel på anmodning

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": "da",
  "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"
    }
  ]
}'

Succes

{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}

Felt	Type	Hvad det gør
`hidden_solution` valgfri i settings string	string	De resterende bogstaver staver dette. Når du angiver den, fortæller det også generatoren, at den skal placere løsningen først i stedet for at proppe så mange ord ind, den kan.
`directions` valgfri i settings string[]	string[]	Hvilke retninger et ord må løbe i. Udelad det, og ord løber kun mod øst, sydøst og syd. En af `westeastnorthsouthnorthwestnortheastsouthwestsoutheast` Standard: ["east", "southeast", "south"]
`template` valgfri i settings string	string	Skærer gitteret til i en form i stedet for at lade det være kvadratisk. En af `squarecirclecrossdiamondpyramidsmileystarcross_plus`

Felt	Type	Hvad det gør
`theme` valgfri i settings string	string	Gåden, der bliver vist over gitteret. Udelades den, ser spillerne titlen.
`spangram` valgfri i settings string	string	Ordet eller udtrykket, der navngiver temaet og krydser gitteret fra den ene kant til den anden.

Felt	Type	Hvad det gør
`list_match_mode` valgfri i settings string	string	Om et navn tæller i det øjeblik, det bliver skrevet, eller først, når der trykkes på Enter. En af `while_typingon_enter` Standard: "while_typing"
`list_slot_hint` valgfri i settings string	string	Hvad en tom plads afslører: ingenting, navnets længde, dets første bogstav eller det tip, du har skrevet. En af `nonelengthfirst_letterhint` Standard: "none"
`list_arrange` valgfri i settings string	string	Én kolonne pr. gruppe eller én liste. En af `groupsone_list` Standard: "groups"
`list_allow_give_up` valgfri i settings boolean	boolean	Viser en knap til at give op, der afslutter runden og afslører det, der blev overset. Standard: false

Felt	Type	Hvad det gør
`mode` valgfri i settings string	string	Hvad der fylder felterne: dine items, dine items råbt op ved deres definition, eller almindelige tal (som ikke kræver nogen items). En af `itemscluesnumbers` Standard: "items"
`rows` valgfri i settings number	number	Rækker på hvert kort, 2 til 5. Standard: 3
`columns` valgfri i settings number	number	Kolonner på hvert kort, 2 til 5. Standard: 3
`highest_number` valgfri i settings number	number	I talfunktionen bliver kortene fyldt fra 1 op til dette tal, højst 100. En planfunktion: uden en plan forbliver den 50. Standard: 50

Felt	Type	Hvad det gør
`instructions` valgfri i settings string	string	Spørgsmålet eller gåden, koden er svaret på, vist sammen med kortene.
`force_solution_in_correct_order` valgfri i settings boolean	boolean	Kortene skal trykkes i rækkefølge. Slået fra åbner enhver rækkefølge af de rigtige kort låsen. Standard: false
`randomize_order` valgfri i settings boolean	boolean	Hver spiller får kortene i en blandet rækkefølge. Standard: true

Felt	Type	Hvad det gør
`number_of_tiles` valgfri i settings number	number	Hvor mange felter brættet har. Mellem 10 og 75. Standard: 30
`game_mode` valgfri i settings string	string	Om spillerne kapløber til mål, eller om de samler genstande undervejs. En af `race_to_finishcollect_items` Standard: "race_to_finish"

Felt	Type	Hvad det gør
`maze_width` valgfri i settings string	string	Hvordan salene er lagt ud: én kolonne, et kvadrat eller bredere. En af `narrownormalwide` Standard: "normal"
`maze_corridors` valgfri i settings string	string	Hvor meget labyrint der ligger mellem to spørgsmål. En af `shortnormallong` Standard: "normal"
`maze_fog` valgfri i settings string	string	Vis hele labyrinten, eller kun det, spilleren har været ved siden af. En af `offnear` Standard: "off"
`maze_wrong_door_pause` valgfri i settings string	string	Hvor længe dørene forbliver lukkede efter en forkert dør. En af `noneshortlong` Standard: "short"
`maze_walk_there` valgfri i settings boolean	boolean	Tilbyder en knap, der går med figuren hen til den næste sal. Standard: false
`maze_seed` valgfri i settings string	string	Det frø, labyrinten bliver genereret ud fra. Det samme frø og de samme spørgsmål giver den samme labyrint; udelades det, bliver der trukket en ny.

Felt	Type	Hvad det gør
`jeopardy_buzzer_mode` valgfri i settings string	string	Hvem der spiller hvordan: værten styrer det fra konsollen, spillerne buzzer ind fra deres telefoner, eller hver spiller klarer brættet alene. En af `hostphonessolo` Standard: "host"
`jeopardy_contestants` valgfri i settings string	string	Om konsollen taler om hold eller om spillere. En af `teamsplayers` Standard: "teams"
`jeopardy_value_step` valgfri i settings number	number	Hvad en række er værd: en definition er værd dette gange sit rækkenummer. Fra 50 til 500, i trin på 50. Standard: 100
`jeopardy_answer_time` valgfri i settings number	number	Sekunder til at svare, når en definition er åbnet, op til 300. 0 er intet tidsur. Standard: 20
`jeopardy_wrong_answer_costs` valgfri i settings boolean	boolean	Et forkert svar trækker definitionens værdi fra scoren. Standard: false
`jeopardy_reveal_on_timeout` valgfri i settings boolean	boolean	Brættet viser selv svaret, når tidsuret løber ud. Standard: false
`jeopardy_require_question_form` valgfri i settings boolean	boolean	Minder spillerne om at svare i form af et spørgsmål. Standard: false

Felt	Type	Hvad det gør
`video_url` påkrævet i settings string	string	Videoen: en side på YouTube, Vimeo eller Bunny Stream eller et direkte link til en mp4-, webm- eller mov-fil.
`video_duration` valgfri i settings number	number	Videoens længde i sekunder. Når den er angivet, bliver en pop-up efter slutningen afvist.

Felt	Type	Hvad det gør
`sentence` påkrævet string	string	Sætningen, der skal krypteres. Spillerne afkoder den tegn for tegn.
`helpers` valgfri i settings string	string	Hvilke tegn der bliver givet gratis som en indgang: ingen, de mest almindelige, vokalerne, eller dem, du selv angiver i en liste. En af `nonemost_commonvowelscustom` Standard: "none"
`character_list` valgfri i settings string	string	Alfabetet, chifferet bliver bygget ud fra. Efterlades det tomt, vælger krypteringen sit eget.
`extra_letters` valgfri i settings string	string	De tegn, der bliver givet væk, når helpers er "custom". Ignoreres for de andre hjælpetilstande.
`hide_unused_characters` valgfri i settings boolean	boolean	Udelader tegn, som sætningen aldrig bruger, fra nøglen. Standard: false

Felt	Type	Hvad det gør
`sentence` påkrævet string	string	Sætningen, spillerne afslører ved at løse regnestykkerne.
`difficulty_level` valgfri i settings number	number	Det højeste svar, et regnestykke må have. En af `20501001000` Standard: "100"
`operators` valgfri i settings string[]	string[]	Hvilke regnearter der må optræde. x er gange, : er division. En af `+-x:` Standard: ["+", "-", "x", ":"]
`max_operations` valgfri i settings number	number	Hvor mange regnearter ét regnestykke må kæde sammen. En af `123` Standard: 1
`number_difficulty` valgfri i settings number	number	Sætter loft over de enkelte tal inde i et regnestykke. Alt fra 5 til 1000. Standard: 100

Felt	Type	Hvad det gør
`size` valgfri i settings string	string	Størrelsen på én blok, skrevet som rækker gange kolonner — 3x3 giver det klassiske 9x9-gitter. Endpointet tjekker kun, at det kan tolkes som to tal, så hold dig til de størrelser, editoren tilbyder. En af `2x22x33x33x44x4` Standard: "3x3"
`difficulty_level` valgfri i settings string	string	Hvor mange tal der bliver stående i gitteret til at starte ud fra. En af `easynormalhard` Standard: "normal"

Felt	Type	Hvad det gør
`sentence` påkrævet string	string	Sætningen, der skal skjules: et citat, et ordsprog, en nøglesætning. Højst 120 bogstaver og tal.
`columns` valgfri i settings number	number	Hvor bredt gitteret er, fra 8 til 18. Smallere stabler flere bogstaver i hver kolonne og er sværere. Standard: 14
`helpers` valgfri i settings string	string	Hvilke bogstaver der bliver stående i gitteret som en indgang: ingen, de mest almindelige, vokalerne, eller dem, du selv angiver i en liste. En af `nonemost_commonvowelscustom` Standard: "none"
`extra_letters` valgfri i settings string	string	De bogstaver, der bliver givet væk, når helpers er "custom".

Felt	Type	Hvad det gør
`tables` valgfri i settings number[]	number[]	De tabeller, der skal øves. Udelades den, er det 1 til 10; et 11 eller 12 gør gitteret 12 gange 12. En af `123456789101112`
`order` valgfri i settings string	string	Om rækkerne og kolonnerne løber i rækkefølge eller blandet. En af `ascendingshuffled` Standard: "ascending"
`picture` valgfri i settings string	string	Billedet, de rigtige svar maler. En af `sailboatheartrockettreecatfishflowerhouse` Standard: "sailboat"
`players_choose_tables` valgfri i settings boolean	boolean	Lader hver spiller vælge, hvilke af tabellerne der skal øves. Standard: false
`fill_same_sums` valgfri i settings boolean	boolean	Ét rigtigt svar udfylder alle felter med det samme regnestykke. Standard: true

Felt	Type	Hvad det gør
`story` valgfri i settings string	string	Baggrundshistorien, der bliver vist over definitionerne.
`difficulty` valgfri i settings string	string	Hvilke slags definitioner generatoren må bruge. En af `easymediumhard` Standard: "easy"
`hints` valgfri i settings boolean	boolean	Tilbyder en knap, der viser det næste trin. Standard: true
`auto_cross` valgfri i settings boolean	boolean	Når et match bliver markeret, bliver resten af dets række og kolonne streget ud. Standard: true
`clue_mode` valgfri i settings string	string	Hvem der skriver de definitioner, spillerne ser: genereret ud fra tabellen, dine egne sætninger i free_clues, eller ingen. En af `generatedfreenone` Standard: "generated"
`free_clues` valgfri i settings string[]	string[]	Dine egne definitioner, vist som skrevet, med clue_mode "free". Intet tjekker dem.

Felt	Type	Hvad det gør
`clue_mode` valgfri i settings string	string	Regler vist som billeder eller som sætninger. En af `visualtext` Standard: "visual"
`unique_object_picks` valgfri i settings boolean	boolean	Hver figur må kun placeres én gang. Standard: false
`hide_color_picker` valgfri i settings boolean	boolean	Spillerne kan ikke give figurerne en anden farve. Standard: false

Byg aktiviteter fra dit eget system

Din første anmodning

Godkendelse

Anmodningens body

Hvad du får tilbage

Oprettelse vs. opdatering

Kaldegrænse

Fejl

Endpoints

Opfører noget sig ikke, som det skal?