API for utviklere

Bygg aktiviteter fra ditt eget system

Én POST per aktivitetstype. Send innholdet ditt som JSON, og få tilbake en aktivitet i Puzzel.org-kontoen din og en URL du kan gi til spillere eller sette inn i en iframe.

Base-URL: https://puzzel.org/api/public/v1
Autentisering: Nøkkel og e-post i forespørselsteksten
Endepunkter: 38 aktivitetstyper
Kvote: 10 aktiviteter om dagen

Din første forespørsel

Ingenting å installere og ingen håndtrykk: send JSON-innhold med nøkkelen din, e-posten din og innholdet ditt. Svaret inneholder nøkkelen til den nye aktiviteten og URL-en 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": "no",
  "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"
    }
  ]
}'

Vellykket

{
  "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 siden er en komplett forespørsel du kan kjøre direkte. Bytt ut med din egen nøkkel og ditt eget innhold, så fungerer det som det er.

Autentisering

Det er ingen headere og ingen bearer-token. Begge opplysningene sendes som JSON-innhold i hver forespørsel, og nøkkelen godtas bare for kontoen som e-postadressen tilhører.

Felt	Type	Hva det gjør
`account_api_key` obligatorisk string	string	API-nøkkelen til kontoen din. Den skal være i forespørselsteksten, ikke i en header.
`email` obligatorisk string	string	Adressen Puzzel.org-kontoen din logger inn med. Nøkkelen er bare gyldig sammen med den.

Nøkkelen din ligger under kontodelen av dashbordet, bak Vis.

Logg inn

API-nøkler deles ut når et abonnement starter, så en gratis konto har ikke fått noen ennå.

Se planene

Behandle nøkkelen som et passord. Den oppretter og overskriver aktiviteter i kontoen din, så hold den på serversiden og unna alt en nettleser kan lese.

Forespørselsteksten

Hvert endepunkt tar imot de samme fem feltene. Det som er forskjellig, er innholdsfeltet under dem: de fleste tar imot en liste med items, noen få tar imot én setning eller ett bilde, og sudoku tar imot ingenting i det hele tatt.

Felt	Type	Hva det gjør
`account_api_key` obligatorisk string	string	API-nøkkelen til kontoen din. Den skal være i forespørselsteksten, ikke i en header.
`email` obligatorisk string	string	Adressen Puzzel.org-kontoen din logger inn med. Nøkkelen er bare gyldig sammen med den.
`title` valgfritt string	string	Navnet aktiviteten får i dashbordet ditt. Utelater du det, bruker endepunktet sitt eget standardnavn.
`language` valgfritt string	string	Bestemmer bare språket i URL-en du får tilbake — den oversetter ikke noe av det du sender. Ordsøk bruker den også til å bytte fyllbokstavene til arabisk når den er "ar". Standard: "en"
`activity_key` valgfritt string	string	Utelat det for å opprette en ny aktivitet. Send inn nøkkelen til en du allerede eier, så bygges den aktiviteten om i stedet.

settings er et objekt med innstillinger som er spesifikke for hvert endepunkt. Hvilke det gjelder for et endepunkt, er listet opp under det; alt annet du legger der, blir ignorert.

Hva du får tilbake

Et vellykket kall svarer 200 med nøkkelen til den nye aktiviteten og URL-en den spilles på. Alt annet svarer med success satt til false og én enkelt feilmelding.

Vellykket

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

Feil

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

URL-en du får tilbake, er innbyggingsvisningen. Bytt ut embed med play for å åpne den på hele siden, eller med build for å åpne den i editoren — nøkkelen etter p= er den samme.

Opprette vs. oppdatere

Send inn activity_key, så bygges aktiviteten bak den om på stedet: innholdet erstattes, navnet og versjonsstempelet oppdateres, og selve nøkkelen forblir den samme — så lenker og innbygginger du allerede har delt, fortsetter å fungere. Resultater, mappeplassering og alle innstillinger endepunktet ikke skriver til selv, forblir 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 brukes ved hver oppdatering, inkludert standardverdien — utelater du det, blir aktiviteten omdøpt til endepunktets standardnavn.
Innstillingsblokkene et endepunkt skriver til selv, blir skrevet helt på nytt, så en oppdatering nullstiller også disse til verdiene du sender, eller til endepunktets standardverdier.
Du kan bare oppdatere aktiviteter din egen konto eier. En annens nøkkel svarer 403.
En oppdatering koster det samme som en opprettelse: ett kall av dagens kvote.

Hastighetsgrense

10 aktiviteter per konto per dag

Hvert vellykkede kall telles, opprettelser og oppdateringer likt. Går du over, svarer neste forespørsel 429 helt til telleren nullstilles.

Telleren nullstilles én gang om dagen av en planlagt jobb, ikke over et rullerende 24-timersvindu.

Feil

Feil kommer alltid som JSON med de samme to feltene, aldri som en HTML-side. Feilmeldingen er skrevet for at et menneske skal kunne lese den — den navngir feltet eller grensen som feilet.

Status	Hva det betyr
`400` Bad Request	Noe i forespørselsteksten mangler, er feil formatert eller utenfor gyldig område. Meldingen navngir feltet.
`401` Unauthorized	E-postadressen er ukjent, eller nøkkelen tilhører ikke den kontoen.
`403` Forbidden	activity_key du sendte, tilhører en annen konto.
`429` Too Many Requests	Dagens kvote er brukt opp. Den nullstilles én gang om dagen.
`500` Server Error	Generatoren klarte ikke å bygge en oppgave av det du sendte inn — vanligvis for få ord, eller ord som ikke kan settes sammen.

Endepunkter

Én sti per aktivitetstype, alle POST, alle under samme base-URL. Hver av dem lister opp innholdet den trenger, innstillingene den leser og en forespørsel du kan kjøre.

Ord og bokstaver

Kryssord

Fletter svarene dine sammen i et rutenett og nummererer definisjonene for deg.

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

Innhold

En liste med ord. Hver oppføring parer svaret med definisjonen som peker på det.

Faller tilbake til navnet “Crossword API”

Verdt å vite

Svar som er kortere enn to tegn, blir fjernet før rutenettet bygges, og minst to må overleve det.
Svarene skrives med store bokstaver, og generatoren får tjue forsøk på å plassere dem. Klarer den ikke å plassere et eneste ord, svarer kallet 500.

Innstillinger den leser

Felt	Type	Hva det gjør
`hidden_solution` valgfritt i settings string	string	Et valgfritt bonusord. Bokstavene i det er markert i rutene i det ferdige rutenettet, så spillerne kan samle dem når kryssordet er løst. Derfor må hver bokstav i det finnes i svarene.

Eksempelforespørsel

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

Vellykket

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

Felt	Type	Hva det gjør
`hidden_solution` valgfritt i settings string	string	De resterende bokstavene staver dette. Setter du den, ber du også generatoren om å plassere løsningen først i stedet for å presse inn flest mulig ord.
`directions` valgfritt i settings string[]	string[]	Hvilke retninger et ord kan gå i. Utelater du den, går ordene bare østover, sørøstover og sørover. Én av `westeastnorthsouthnorthwestnortheastsouthwestsoutheast` Standard: ["east", "southeast", "south"]
`template` valgfritt i settings string	string	Kutter rutenettet til en form i stedet for å la det være kvadratisk. Én av `squarecirclecrossdiamondpyramidsmileystarcross_plus`

Felt	Type	Hva det gjør
`theme` valgfritt i settings string	string	Gåten som vises over rutenettet. Utelater du den, ser spillerne tittelen.
`spangram` valgfritt i settings string	string	Ordet eller frasen som navngir temaet og krysser brettet fra den ene kanten til den andre.

Felt	Type	Hva det gjør
`list_match_mode` valgfritt i settings string	string	Om et navn teller i det øyeblikket det skrives, eller først når du trykker Enter. Én av `while_typingon_enter` Standard: "while_typing"
`list_slot_hint` valgfritt i settings string	string	Hva en tom plass røper: ingenting, lengden på navnet, første bokstav, eller tipset du skrev. Én av `nonelengthfirst_letterhint` Standard: "none"
`list_arrange` valgfritt i settings string	string	Én kolonne per gruppe, eller én liste. Én av `groupsone_list` Standard: "groups"
`list_allow_give_up` valgfritt i settings boolean	boolean	Viser en gi opp-knapp som avslutter runden og viser det som ble glemt. Standard: false

Felt	Type	Hva det gjør
`mode` valgfritt i settings string	string	Hva som fyller rutene: dine items, dine items trukket etter ledetråden, eller vanlige tall (som ikke trenger items). Én av `itemscluesnumbers` Standard: "items"
`rows` valgfritt i settings number	number	Rader på hvert kort, 2 til 5. Standard: 3
`columns` valgfritt i settings number	number	Kolonner på hvert kort, 2 til 5. Standard: 3
`highest_number` valgfritt i settings number	number	I tallmodus fylles kortene fra 1 og opp til dette tallet, høyst 100. Krever en plan: uten plan forblir det 50. Standard: 50

Felt	Type	Hva det gjør
`instructions` valgfritt i settings string	string	Spørsmålet eller gåten koden svarer på, vist sammen med kortene.
`force_solution_in_correct_order` valgfritt i settings boolean	boolean	Kortene må trykkes i rekkefølge. Slått av åpner enhver rekkefølge av de riktige kortene låsen. Standard: false
`randomize_order` valgfritt i settings boolean	boolean	Hver spiller får kortene i en stokket rekkefølge. Standard: true

Felt	Type	Hva det gjør
`number_of_tiles` valgfritt i settings number	number	Hvor mange ruter brettet har. Mellom 10 og 75. Standard: 30
`game_mode` valgfritt i settings string	string	Om spillerne kappløper til mål eller samler gjenstander underveis. Én av `race_to_finishcollect_items` Standard: "race_to_finish"

Felt	Type	Hva det gjør
`maze_width` valgfritt i settings string	string	Hvordan rommene er lagt ut: én kolonne, et kvadrat eller bredere. Én av `narrownormalwide` Standard: "normal"
`maze_corridors` valgfritt i settings string	string	Hvor mye labyrint det er mellom to spørsmål. Én av `shortnormallong` Standard: "normal"
`maze_fog` valgfritt i settings string	string	Vis hele labyrinten, eller bare det spilleren har vært ved siden av. Én av `offnear` Standard: "off"
`maze_wrong_door_pause` valgfritt i settings string	string	Hvor lenge dørene forblir stengt etter en feil dør. Én av `noneshortlong` Standard: "short"
`maze_walk_there` valgfritt i settings boolean	boolean	Viser en knapp som går med figuren til neste rom. Standard: false
`maze_seed` valgfritt i settings string	string	Frøet labyrinten genereres fra. Samme frø og samme spørsmål gir samme labyrint. Utelater du det, trekkes en ny.

Felt	Type	Hva det gjør
`jeopardy_buzzer_mode` valgfritt i settings string	string	Hvem som spiller hvordan: spillederen styrer det fra konsollen, spillerne bruker summeren fra telefonene sine, eller hver spiller jobber seg gjennom brettet alene. Én av `hostphonessolo` Standard: "host"
`jeopardy_contestants` valgfritt i settings string	string	Om konsollen snakker om lag eller om spillere. Én av `teamsplayers` Standard: "teams"
`jeopardy_value_step` valgfritt i settings number	number	Hva en rad er verdt: en ledetråd er verdt dette ganger radnummeret. Fra 50 til 500, i trinn på 50. Standard: 100
`jeopardy_answer_time` valgfritt i settings number	number	Sekunder til å svare når en ledetråd er åpnet, opptil 300. 0 betyr ingen klokke. Standard: 20
`jeopardy_wrong_answer_costs` valgfritt i settings boolean	boolean	Et feil svar trekker ledetrådens verdi fra poengsummen. Standard: false
`jeopardy_reveal_on_timeout` valgfritt i settings boolean	boolean	Brettet viser selve svaret når klokken går ut. Standard: false
`jeopardy_require_question_form` valgfritt i settings boolean	boolean	Minner spillerne om å svare i form av et spørsmål. Standard: false

Felt	Type	Hva det gjør
`video_url` obligatorisk i settings string	string	Videoen: en YouTube-, Vimeo- eller Bunny Stream-side, eller en direkte lenke til en mp4-, webm- eller mov-fil.
`video_duration` valgfritt i settings number	number	Lengden på videoen i sekunder. Når den er oppgitt, avvises et øyeblikk etter slutten.

Felt	Type	Hva det gjør
`sentence` obligatorisk string	string	Setningen som skal krypteres. Spillerne dekoder den tegn for tegn.
`helpers` valgfritt i settings string	string	Hvilke tegn som avsløres gratis som en vei inn: ingen, de vanligste, vokalene, eller de du lister opp selv. Én av `nonemost_commonvowelscustom` Standard: "none"
`character_list` valgfritt i settings string	string	Alfabetet krypteringen bygges fra. La det stå tomt, så velger krypteringen sitt eget.
`extra_letters` valgfritt i settings string	string	Tegnene som avsløres når helpers er "custom". Ignoreres for de andre hjelpemodusene.
`hide_unused_characters` valgfritt i settings boolean	boolean	Utelater tegn setningen aldri bruker, fra nøkkelen. Standard: false

Felt	Type	Hva det gjør
`sentence` obligatorisk string	string	Setningen spillerne avdekker ved å løse regnestykkene.
`difficulty_level` valgfritt i settings number	number	Det høyeste svaret et regnestykke har lov til å ha. Én av `20501001000` Standard: "100"
`operators` valgfritt i settings string[]	string[]	Hvilke regneoperasjoner som kan forekomme. x er gange, : er dele. Én av `+-x:` Standard: ["+", "-", "x", ":"]
`max_operations` valgfritt i settings number	number	Hvor mange operasjoner ett regnestykke kan kjede sammen. Én av `123` Standard: 1
`number_difficulty` valgfritt i settings number	number	Setter et tak på enkelttallene inni et regnestykke. Fra 5 til 1000. Standard: 100

Felt	Type	Hva det gjør
`size` valgfritt i settings string	string	Størrelsen på én blokk, skrevet som rader ganger kolonner — 3x3 gir det klassiske 9x9-rutenettet. Endepunktet sjekker bare at det kan tolkes som to tall, så hold deg til størrelsene editoren tilbyr. Én av `2x22x33x33x44x4` Standard: "3x3"
`difficulty_level` valgfritt i settings string	string	Hvor mange tall som blir stående igjen i rutenettet som utgangspunkt. Én av `easynormalhard` Standard: "normal"

Felt	Type	Hva det gjør
`sentence` obligatorisk string	string	Frasen som skal skjules: et sitat, et ordtak, en nøkkelsetning. Høyst 120 bokstaver og sifre.
`columns` valgfritt i settings number	number	Hvor bredt brettet er, fra 8 til 18. Smalere gir flere bokstaver i hver kolonne og er vanskeligere. Standard: 14
`helpers` valgfritt i settings string	string	Hvilke bokstaver som blir liggende i rutenettet som en vei inn: ingen, de vanligste, vokalene, eller de du lister opp selv. Én av `nonemost_commonvowelscustom` Standard: "none"
`extra_letters` valgfritt i settings string	string	Bokstavene som gis bort når helpers er "custom".

Felt	Type	Hva det gjør
`tables` valgfritt i settings number[]	number[]	Tabellene som skal øves på. Utelater du den, er det 1 til 10. Tar du med 11 eller 12, blir rutenettet 12 ganger 12. Én av `123456789101112`
`order` valgfritt i settings string	string	Om radene og kolonnene går i rekkefølge eller er stokket om. Én av `ascendingshuffled` Standard: "ascending"
`picture` valgfritt i settings string	string	Bildet riktige svar maler. Én av `sailboatheartrockettreecatfishflowerhouse` Standard: "sailboat"
`players_choose_tables` valgfritt i settings boolean	boolean	La hver spiller velge hvilke av tabellene de vil øve på. Standard: false
`fill_same_sums` valgfritt i settings boolean	boolean	Ett riktig svar fyller alle rutene med samme regnestykke. Standard: true

Felt	Type	Hva det gjør
`story` valgfritt i settings string	string	Bakgrunnshistorien som vises over ledetrådene.
`difficulty` valgfritt i settings string	string	Hvilke typer ledetråder generatoren kan bruke. Én av `easymediumhard` Standard: "easy"
`hints` valgfritt i settings boolean	boolean	Viser en knapp som viser neste steg. Standard: true
`auto_cross` valgfritt i settings boolean	boolean	Når du markerer et treff, krysses resten av raden og kolonnen ut. Standard: true
`clue_mode` valgfritt i settings string	string	Hvem som skriver ledetrådene spillerne ser: generert fra tabellen, dine egne setninger i free_clues, eller ingen. Én av `generatedfreenone` Standard: "generated"
`free_clues` valgfritt i settings string[]	string[]	Dine egne ledetrådsetninger, vist slik de er skrevet, med clue_mode "free". Ingenting sjekker dem.

Felt	Type	Hva det gjør
`clue_mode` valgfritt i settings string	string	Regler vist som bilder eller som setninger. Én av `visualtext` Standard: "visual"
`unique_object_picks` valgfritt i settings boolean	boolean	Hver form kan bare plasseres én gang. Standard: false
`hide_color_picker` valgfritt i settings boolean	boolean	Spillerne kan ikke endre fargen på formene. Standard: false

Bygg aktiviteter fra ditt eget system

Din første forespørsel

Autentisering

Forespørselsteksten

Hva du får tilbake

Opprette vs. oppdatere

Hastighetsgrense

Feil

Endepunkter

Noe som ikke oppfører seg?