Przejdź do treści
To podgląd nowej wersji Puzzel.org Wróć do obecnej strony
API dla programistów

Twórz aktywności z własnego systemu

Jeden POST na typ aktywności. Wyślij swoją treść jako JSON, a w zamian dostaniesz aktywność na koncie Puzzel.org i adres URL, który przekażesz graczom albo wstawisz do iframe.

Bazowy URL
https://puzzel.org/api/public/v1
Uwierzytelnianie
Klucz + e-mail w treści żądania
Endpointy
20 typów aktywności
Limit
10 aktywności dziennie

Twoje pierwsze żądanie

Nic nie instalujesz i nie ma żadnej wstępnej wymiany tokenów: wyślij metodą POST treść JSON ze swoim kluczem, adresem e-mail i zawartością. W odpowiedzi wracają klucz nowej aktywności i adres URL, pod którym się w nią gra.

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

Każdy przykład na tej stronie to kompletne, gotowe do uruchomienia żądanie. Podstaw własny klucz i własną treść, a zadziała bez żadnych zmian.

Uwierzytelnianie

Nie ma żadnych nagłówków ani tokenu bearer. Oba dane uwierzytelniające jadą w treści JSON każdego żądania, a klucz jest akceptowany tylko dla konta, do którego należy ten adres e-mail.

PoleTypDo czego służy
account_api_key
wymagane
string
stringKlucz API twojego konta. Trafia do treści żądania, a nie do nagłówka.
email
wymagane
string
stringAdres, którym logujesz się na swoje konto Puzzel.org. Klucz jest ważny tylko razem z nim.

Twój klucz znajdziesz w sekcji konta w panelu, pod przyciskiem Pokaż.

Zaloguj się

Klucze API przyznajemy w chwili rozpoczęcia subskrypcji, więc bezpłatne konto jeszcze go nie ma.

Zobacz plany

Traktuj klucz jak hasło. Tworzy i nadpisuje aktywności na twoim koncie, więc trzymaj go po stronie serwera, z dala od wszystkiego, co może odczytać przeglądarka.

Treść żądania

Każdy endpoint przyjmuje te same pięć pól. Różni się tylko pole z zawartością pod nimi: większość przyjmuje tablicę items, kilka jedno zdanie albo jeden obraz, a sudoku nie przyjmuje niczego.

PoleTypDo czego służy
account_api_key
wymagane
string
stringKlucz API twojego konta. Trafia do treści żądania, a nie do nagłówka.
email
wymagane
string
stringAdres, którym logujesz się na swoje konto Puzzel.org. Klucz jest ważny tylko razem z nim.
title
opcjonalne
string
stringNazwa, jaką aktywność dostanie w twoim panelu. Pomiń je, a endpoint użyje własnej nazwy zapasowej.
language
opcjonalne
string
stringDecyduje tylko o języku w zwracanym adresie URL — nie tłumaczy niczego, co wysyłasz. Wykreślanka dodatkowo z niego korzysta, by przełączyć litery wypełniające na arabskie, gdy ma wartość "ar".
Domyślnie: "en"
activity_key
opcjonalne
string
stringPomiń je, aby utworzyć nową aktywność. Podaj klucz aktywności, którą już masz, a zostanie ona przebudowana.

settings to obiekt z opcjami danego endpointu. Które z nich endpoint odczytuje, wypisane jest przy nim niżej; wszystko inne, co tam umieścisz, jest ignorowane.

Co wraca w odpowiedzi

Udane wywołanie odpowiada kodem 200 z kluczem nowej aktywności i adresem URL, pod którym się w nią gra. Wszystko inne odpowiada polem success ustawionym na false i jednym tekstem błędu.

Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Niepowodzenie 
{
  "success": false,
  "error": "Invalid Email or API Key"
}

Zwracany url to widok osadzony. Zamień embed na play, aby otworzyć go na całej stronie, albo na build, aby otworzyć go w edytorze — klucz po p= pozostaje ten sam.

Tworzenie a aktualizacja

Wyślij activity_key, a stojąca za nim aktywność zostanie przebudowana na miejscu: jej zawartość jest zastępowana, nazwa i znacznik wersji odświeżane, a sam klucz pozostaje ten sam — więc udostępnione już linki i osadzenia działają dalej. Wyniki, umieszczenie w folderze i wszystkie ustawienia, których endpoint sam nie zapisuje, zostają bez zmian.

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 jest stosowane przy każdej aktualizacji, razem z wartością domyślną — pomiń je, a aktywność zostanie przemianowana na nazwę zapasową tego endpointu.
  • Bloki ustawień, które endpoint zapisuje sam, są pisane od zera, więc aktualizacja resetuje je do wartości, które wyślesz, albo do wartości domyślnych endpointu.
  • Aktualizować możesz tylko aktywności należące do twojego konta. Cudzy klucz kończy się odpowiedzią 403.
  • Aktualizacja kosztuje tyle samo co utworzenie: jedno wywołanie z dziennego limitu.

Limit żądań

10
10 aktywności na konto dziennie

Liczy się każde udane wywołanie, zarówno tworzenie, jak i aktualizacja. Po przekroczeniu limitu kolejne żądanie odpowiada kodem 429, dopóki licznik nie zostanie wyzerowany.

Licznik jest zerowany raz dziennie przez zaplanowane zadanie, a nie w ruchomym oknie 24 godzin.

Błędy

Błędy zawsze przychodzą jako JSON z tymi samymi dwoma polami, nigdy jako strona HTML. Tekst błędu jest napisany tak, by przeczytał go człowiek — nazywa pole albo limit, na którym coś się wysypało.

StatusCo oznacza
400
Bad Request
Czegoś w treści żądania brakuje, coś jest źle zbudowane albo poza zakresem. Komunikat wskazuje pole.
401
Unauthorized
Adres e-mail jest nieznany albo klucz nie należy do tego konta.
403
Forbidden
Wysłany activity_key należy do innego konta.
429
Too Many Requests
Dzisiejszy limit został wyczerpany. Zeruje się raz dziennie.
500
Server Error
Generator nie zdołał zbudować łamigłówki z tego, co wysłano — zwykle za mało słów albo słowa, których nie da się ze sobą dopasować.

Endpointy

Jedna ścieżka na typ aktywności, wszystkie POST, wszystkie pod tym samym bazowym URL. Przy każdej wypisana jest treść, której potrzebuje, ustawienia, które odczytuje, i żądanie, które możesz uruchomić.

Słowa i litery

Krzyżówka

Splata twoje odpowiedzi w siatkę i sam numeruje definicje.

#
POST /api/public/v1/crossword Co najmniej 2 elementów w items
Treść

Tablica słów. Każdy wpis łączy odpowiedź z definicją, która na nią wskazuje.

W razie braku używa nazwy “Crossword API”

Warto wiedzieć
  • Odpowiedzi krótsze niż dwa znaki są odrzucane przed zbudowaniem siatki i co najmniej dwie muszą to przetrwać.
  • Odpowiedzi są zamieniane na wielkie litery, a generator ma dwadzieścia prób, żeby je dopasować. Jeśli nie zdoła umieścić ani jednego słowa, wywołanie odpowiada kodem 500.
Przykładowe żądanie
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": "pl",
  "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"
    }
  ]
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/crossword/embed?p=-Nq8sample_activity_key",
  "message": "Crossword created successfully"
}
Otwórz edytor Powrót na górę

Wykreślanka

Ukrywa twoje słowa w siatce liter, w wybranych przez ciebie kierunkach i kształcie.

#
POST /api/public/v1/wordseeker Co najmniej 2 elementów w items
Treść

Tablica słów. Tekst definicji staje się listą słów, z której korzystają gracze.

W razie braku używa nazwy “Wordseeker API”

Warto wiedzieć
  • Odpowiedzi krótsze niż dwa znaki są odrzucane, a każda odpowiedź trafia do siatki zamieniona na wielkie litery.
  • Siatka jest wypełniana literami łacińskimi, chyba że language ma wartość "ar" — wtedy litery wypełniające przełączają się na arabskie.
Odczytywane ustawienia
PoleTypDo czego służy
hidden_solution
opcjonalne w settings
string
stringPozostałe litery układają się w to rozwiązanie. Ustawienie go mówi też generatorowi, żeby najpierw dopasował rozwiązanie, zamiast upchnąć jak najwięcej słów.
directions
opcjonalne w settings
string[]
string[]W których kierunkach może biec słowo. Pomiń je, a słowa pobiegną tylko na wschód, na południowy wschód i na południe.
Jedna z wartości westeastnorthsouthnorthwestnortheastsouthwestsoutheast
Domyślnie: ["east", "southeast", "south"]
template
opcjonalne w settings
string
stringWycina siatkę w kształt, zamiast zostawiać ją kwadratową.
Jedna z wartości squarecirclecrossdiamondpyramidsmileystarcross_plus
Przykładowe żądanie
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": "pl",
  "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"
  }
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordseeker/embed?p=-Nq8sample_activity_key",
  "message": "Wordseeker created successfully"
}
Otwórz edytor Powrót na górę

Akrostych

Układa twoje odpowiedzi jedna pod drugą tak, by jedna kolumna tworzyła ukryte słowo.

#
POST /api/public/v1/acrostic Co najmniej 1 elementów w items
Treść

Tablica słów. Razem muszą dostarczyć wszystkie litery ukrytego słowa.

W razie braku używa nazwy “Acrostic API”

Warto wiedzieć
  • Jeśli odpowiedzi nie dostarczą liter potrzebnych do rozwiązania, wywołanie odpowiada kodem 500, zamiast zapisać niedokończoną siatkę.
  • Generator zmienia kolejność twoich odpowiedzi, żeby kolumna zadziałała, więc kolejność, którą wysyłasz, nie jest tą, którą widzą gracze.
Odczytywane ustawienia
PoleTypDo czego służy
hidden_solution
wymagane w settings
string
stringSłowo, które układa się w wyróżnionej kolumnie. Bez niego ten endpoint nie zadziała.
Przykładowe żądanie
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": "pl",
  "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"
  }
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/acrostic/embed?p=-Nq8sample_activity_key",
  "message": "Acrostic created successfully"
}
Otwórz edytor Powrót na górę

Pomieszane litery

api_e_word_scramble

#
POST /api/public/v1/word-scramble Co najmniej 1 elementów w items
Treść

api_c_word_scramble

W razie braku używa nazwy “Word Scramble API”

Warto wiedzieć
  • Aktywności tworzone przez API zawsze mają włączone losowanie kolejności, więc kolejność, którą wysyłasz, nie jest tą, którą dostają gracze.
Odczytywane ustawienia
PoleTypDo czego służy
hidden_solution
opcjonalne w settings
string
stringOpcjonalne słowo bonusowe, które gracze wpisują po rozwiązaniu reszty.
Przykładowe żądanie
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": "pl",
  "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"
  }
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/word-scramble/embed?p=-Nq8sample_activity_key",
  "message": "Word Scramble created successfully"
}
Otwórz edytor Powrót na górę

Wisielec

Zamienia twoje słowa lub zwroty w rundy zgadywania liter.

#
POST /api/public/v1/hangman Co najmniej 1 elementów w items
Treść

Tablica słów lub krótkich zwrotów. Wskazówka jest podpowiedzią, którą widzą gracze.

W razie braku używa nazwy “Hangman API”

Przykładowe żądanie
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": "pl",
  "items": [
    {
      "answer": "BANANA",
      "description": "A long yellow fruit",
      "type": "text"
    }
  ]
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/hangman/embed?p=-Nq8sample_activity_key",
  "message": "Hangman created successfully"
}
Otwórz edytor Powrót na górę

Wordle

Z każdego wysłanego słowa robi grę w zgadywanie słowa.

#
POST /api/public/v1/wordle Co najmniej 1 elementów w items
Treść

Tablica słów. Gracze dostają jedną rundę na każde słowo.

W razie braku używa nazwy “Wordle API”

Warto wiedzieć
  • Tworzone z włączonym sprawdzaniem, czy zgadywane słowa naprawdę istnieją. Wyłącz je w edytorze, jeśli twoje słowa to nazwy własne albo wyrazy wymyślone.
Przykładowe żądanie
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": "pl",
  "items": [
    {
      "answer": "MELON",
      "description": "Sweet and green",
      "type": "text"
    },
    {
      "answer": "PEACH",
      "description": "Fuzzy and orange",
      "type": "text"
    }
  ]
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/wordle/embed?p=-Nq8sample_activity_key",
  "message": "Wordle created successfully"
}
Otwórz edytor Powrót na górę

Nauka pisania na klawiaturze

api_e_typing_practice

#
POST /api/public/v1/typing-practice Co najmniej 1 elementów w items
Treść

api_c_typing_practice

W razie braku używa nazwy “Typing Practice API”

Przykładowe żądanie
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": "pl",
  "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"
    }
  ]
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/typing-practice/embed?p=-Nq8sample_activity_key",
  "message": "Typing Practice created successfully"
}
Otwórz edytor Powrót na górę

Koło fortuny

api_e_wheel_of_fortune

#
POST /api/public/v1/wheel-of-fortune Co najmniej 1 elementów w items
Treść

api_c_wheel_of_fortune

W razie braku używa nazwy “Wheel of Fortune API”

Warto wiedzieć
  • Tworzone z ustawieniem “pokaż wynik tylko w kole”, więc rezultat odczytuje się z koła, zamiast być ogłaszanym obok.
Przykładowe żądanie
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": "pl",
  "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"
    }
  ]
}'
Sukces 
{
  "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"
}
Otwórz edytor Powrót na górę
Karty i pary

Memory

Karty odwrócone rewersem do góry, które odkrywa się i dobiera w pary.

#
POST /api/public/v1/memory Co najmniej 2 elementów w items
Treść

Tablica par. Każda para zawiera dwie karty, które do siebie pasują.

W razie braku używa nazwy “Memory Game API”

Warto wiedzieć
  • Karta to obiekt z polami type i value. Użyj "text" dla słów albo "image", "audio", "youtube" czy "link" z adresem URL w value i dodaj alt z opisem.
Przykładowe żądanie
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": "pl",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/memory/embed?p=-Nq8sample_activity_key",
  "message": "Memory game created successfully"
}
Otwórz edytor Powrót na górę

Gra w pary

api_e_matching_pairs

#
POST /api/public/v1/matching-pairs Co najmniej 2 elementów w items
Treść

api_c_matching_pairs

W razie braku używa nazwy “Matching Game API”

Warto wiedzieć
  • Karta to obiekt z polami type i value. Użyj "text" dla słów albo "image", "audio", "youtube" czy "link" z adresem URL w value i dodaj alt z opisem.
Przykładowe żądanie
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": "pl",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/matching-pairs/embed?p=-Nq8sample_activity_key",
  "message": "Matching pairs game created successfully"
}
Otwórz edytor Powrót na górę

Fiszki

api_e_flash_cards

#
POST /api/public/v1/flash-cards Co najmniej 1 elementów w items
Treść

api_c_flash_cards

W razie braku używa nazwy “Flash Cards API”

Warto wiedzieć
  • Endpoint zapisuje tyle kart, ile wyślesz, więc wysyłaj dokładnie dwie na wpis — najpierw przód, potem tył.
  • Karta to obiekt z polami type i value. Użyj "text" dla słów albo "image", "audio", "youtube" czy "link" z adresem URL w value i dodaj alt z opisem.
Przykładowe żądanie
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": "pl",
  "items": [
    {
      "cards": [
        {
          "type": "text",
          "value": "Apple"
        },
        {
          "type": "text",
          "value": "A red fruit"
        }
      ]
    },
    {
      "cards": [
        {
          "type": "text",
          "value": "Banana"
        },
        {
          "type": "text",
          "value": "A yellow fruit"
        }
      ]
    }
  ]
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/flash-cards/embed?p=-Nq8sample_activity_key",
  "message": "Flash Cards created successfully"
}
Otwórz edytor Powrót na górę

Podział na kategorie

Karty do rozdzielenia do kategorii, do których należą.

#
POST /api/public/v1/categorize Co najmniej 2 elementów w items
Treść

Tablica kategorii, każda z nazwą i kartami, które do niej należą.

W razie braku używa nazwy “Categorize Game API”

Warto wiedzieć
  • Kategoria wysłana bez nazwy zapisuje się jako “Untitled Category”, więc zawsze podawaj nazwę.
  • Karta to obiekt z polami type i value. Użyj "text" dla słów albo "image", "audio", "youtube" czy "link" z adresem URL w value i dodaj alt z opisem.
Przykładowe żądanie
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": "pl",
  "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"
        }
      ]
    }
  ]
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/categorize/embed?p=-Nq8sample_activity_key",
  "message": "Categorize game created successfully"
}
Otwórz edytor Powrót na górę

Porządkowanie

Sekwencja, którą gracze muszą ułożyć z powrotem w kolejności.

#
POST /api/public/v1/reorder Co najmniej 1 elementów w items
Treść

Tablica sekwencji. Każda zawiera swoje karty w poprawnej kolejności.

W razie braku używa nazwy “Reorder Game API”

Warto wiedzieć
  • Kolejność, którą wysyłasz, jest zapisywana jako poprawna — pozycja numer jeden na początku.
  • Karta to obiekt z polami type i value. Użyj "text" dla słów albo "image", "audio", "youtube" czy "link" z adresem URL w value i dodaj alt z opisem.
Przykładowe żądanie
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": "pl",
  "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"
        }
      ]
    }
  ]
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/reorder/embed?p=-Nq8sample_activity_key",
  "message": "Reorder game created successfully"
}
Otwórz edytor Powrót na górę
Pytania i odpowiedzi

Quiz

Pytania wielokrotnego wyboru i otwarte, punktowane na bieżąco.

#
POST /api/public/v1/quiz Co najmniej 1 elementów w items
Treść

Tablica pytań. Pytania wielokrotnego wyboru niosą swoje odpowiedzi, pytania otwarte — odpowiedź, którą akceptujesz.

W razie braku używa nazwy “Quiz API”

Warto wiedzieć
  • question_type to albo "multiple_choice", gdzie poprawna opcja ma isCorrect ustawione na true, albo "open_answer", które zamiast tego korzysta z correct_answer. Pominięte, jest traktowane jako pytanie wielokrotnego wyboru.
  • Endpoint quizu przekazuje settings prosto jako bloki ustawień aktywności, więc nie jest to miejsce na luźne opcje — quiz dopracuj potem w edytorze.
Przykładowe żądanie
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": "pl",
  "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."
    }
  ]
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/quiz/embed?p=-Nq8sample_activity_key",
  "message": "Quiz created successfully"
}
Otwórz edytor Powrót na górę

Gra planszowa

api_e_board_game

#
POST /api/public/v1/board-game Co najmniej 1 elementów w items
Treść

api_c_board_game

W razie braku używa nazwy “Board Game API”

Warto wiedzieć
  • question_type to albo "multiple_choice", gdzie poprawna opcja ma isCorrect ustawione na true, albo "open_answer", które zamiast tego korzysta z correct_answer. Pominięte, jest traktowane jako pytanie wielokrotnego wyboru.
Odczytywane ustawienia
PoleTypDo czego służy
number_of_tiles
opcjonalne w settings
number
numberIle pól ma plansza. Od 10 do 75.
Domyślnie: 30
game_mode
opcjonalne w settings
string
stringCzy gracze ścigają się do mety, czy zbierają po drodze przedmioty.
Jedna z wartości race_to_finishcollect_items
Domyślnie: "race_to_finish"
Przykładowe żądanie
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": "pl",
  "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"
  }
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/board-game/embed?p=-Nq8sample_activity_key",
  "message": "Board Game created successfully"
}
Otwórz edytor Powrót na górę
Zdania i liczby

Kryptogram

Zamienia zdanie w szyfr do złamania, znak po znaku.

#
POST /api/public/v1/cryptogram Nie przyjmuje items
Treść

Jedno zdanie, w polu sentence. Ten endpoint nie przyjmuje items.

W razie braku używa nazwy “Cryptogram API”

Warto wiedzieć
  • Wszystko, co wyślesz w items, jest ignorowane — łamigłówka powstaje z samego zdania.
Odczytywane ustawienia
PoleTypDo czego służy
sentence
wymagane
string
stringZdanie do zaszyfrowania. Gracze rozszyfrowują je znak po znaku.
helpers
opcjonalne w settings
string
stringKtóre znaki są odsłaniane za darmo na wejście: żadne, najczęstsze, samogłoski albo te, które wypiszesz samodzielnie.
Jedna z wartości nonemost_commonvowelscustom
Domyślnie: "none"
character_list
opcjonalne w settings
string
stringAlfabet, z którego budowany jest szyfr. Zostawiony pusty, szyfrowanie wybierze go samo.
extra_letters
opcjonalne w settings
string
stringZnaki odsłaniane, gdy helpers ma wartość "custom". Przy pozostałych trybach ignorowane.
hide_unused_characters
opcjonalne w settings
boolean
booleanPomija w kluczu znaki, których zdanie w ogóle nie używa.
Domyślnie: false
Przykładowe żądanie
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": "pl",
  "sentence": "An apple a day keeps the doctor away",
  "settings": {
    "helpers": "vowels",
    "hide_unused_characters": false
  }
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/cryptogram/embed?p=-Nq8sample_activity_key",
  "message": "Cryptogram created successfully"
}
Otwórz edytor Powrót na górę

Ćwiczenie rachunkowe

Ukrywa zdanie za działaniami — rozwiąż działanie, odsłoń literę.

#
POST /api/public/v1/calculation Nie przyjmuje items
Treść

Jedno zdanie, w polu sentence. Ten endpoint nie przyjmuje items.

W razie braku używa nazwy “Calculation Game API”

Warto wiedzieć
  • Jeśli ograniczenia są zbyt ciasne, by zakodować zdanie, wywołanie odpowiada kodem 400 z prośbą o ich poluzowanie, zamiast zapisać niepełną łamigłówkę.
Odczytywane ustawienia
PoleTypDo czego służy
sentence
wymagane
string
stringZdanie, które gracze odkrywają, rozwiązując działania.
difficulty_level
opcjonalne w settings
number
numberNajwyższy wynik, jaki może dać działanie.
Jedna z wartości 20501001000
Domyślnie: "100"
operators
opcjonalne w settings
string[]
string[]Które operacje mogą się pojawić. x to mnożenie, : to dzielenie.
Jedna z wartości +-x:
Domyślnie: ["+", "-", "x", ":"]
max_operations
opcjonalne w settings
number
numberIle operacji może połączyć w sobie jedno działanie.
Jedna z wartości 123
Domyślnie: 1
number_difficulty
opcjonalne w settings
number
numberOgranicza pojedyncze liczby w działaniu. Od 5 do 1000.
Domyślnie: 100
Przykładowe żądanie
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": "pl",
  "sentence": "Fruit salad for everyone",
  "settings": {
    "difficulty_level": "100",
    "operators": [
      "+",
      "-",
      "x",
      ":"
    ],
    "max_operations": 1,
    "number_difficulty": 100
  }
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/calculation/embed?p=-Nq8sample_activity_key",
  "message": "Calculation game created successfully"
}
Otwórz edytor Powrót na górę

Sudoku

Generuje rozwiązaną siatkę, a potem wyjmuje z niej liczby.

#
POST /api/public/v1/sudoku Nie przyjmuje items
Treść

Nic. Cała łamigłówka powstaje z dwóch ustawień.

W razie braku używa nazwy “Sudoku API”

Warto wiedzieć
  • Nie wysyłaj ani items, ani sentence — rozmiar i poziom trudności to całe wejście.
  • Edytor oferuje poziom trudności tylko dla 2x3, 3x3 i 3x4. API stosuje go do każdego rozmiaru, w tym 2x2 i 4x4.
Odczytywane ustawienia
PoleTypDo czego służy
size
opcjonalne w settings
string
stringRozmiar jednego bloku, zapisany jako wiersze na kolumny — 3x3 daje klasyczną siatkę 9x9. Endpoint sprawdza tylko, czy da się to odczytać jako dwie liczby, więc trzymaj się rozmiarów, które oferuje edytor.
Jedna z wartości 2x22x33x33x44x4
Domyślnie: "3x3"
difficulty_level
opcjonalne w settings
string
stringIle liczb zostaje w siatce na start.
Jedna z wartości easynormalhard
Domyślnie: "normal"
Przykładowe żądanie
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": "pl",
  "settings": {
    "size": "3x3",
    "difficulty_level": "normal"
  }
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/sudoku/embed?p=-Nq8sample_activity_key",
  "message": "Sudoku created successfully"
}
Otwórz edytor Powrót na górę
Obrazy

Puzzle

Tnie obraz na elementy, które trzeba z powrotem złożyć.

#
POST /api/public/v1/jigsaw Nie przyjmuje items
Treść

Jeden adres URL obrazu, w polu image. Ten endpoint nie przyjmuje items.

W razie braku używa nazwy “Jigsaw Game API”

Warto wiedzieć
  • API zawsze tworzy puzzle 4 na 4. Liczba elementów, nieregularne kształty i proste krawędzie to ustawienia edytora — wysyłanie tutaj rows albo columns nic nie daje.
  • Adres URL jest zapisywany dokładnie tak, jak go wyślesz, a plik nigdy nie jest kopiowany, więc musi pozostać publicznie dostępny tak długo, jak długo gra się w tę aktywność.
Odczytywane ustawienia
PoleTypDo czego służy
image
wymagane
string
stringBezwzględny adres URL obrazu do pocięcia. Wysyłany na najwyższym poziomie, nie w settings.
Przykładowe żądanie
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": "pl",
  "image": "https://example.com/orchard.jpg"
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/jigsaw/embed?p=-Nq8sample_activity_key",
  "message": "Jigsaw game created successfully"
}
Otwórz edytor Powrót na górę

Przesuwanka

Rozsypuje obraz na kafelki, które wsuwa się na miejsce.

#
POST /api/public/v1/slidingpuzzle Nie przyjmuje items
Treść

Jeden adres URL obrazu, w settings. Ten endpoint nie przyjmuje items.

W razie braku używa nazwy “Sliding Puzzle API”

Warto wiedzieć
  • W odróżnieniu od puzzli, ten endpoint czyta obraz z settings.image. Pole image na najwyższym poziomie jest ignorowane, a wywołanie odpowiada kodem 400.
  • Adres URL jest zapisywany dokładnie tak, jak go wyślesz, a plik nigdy nie jest kopiowany, więc musi pozostać publicznie dostępny tak długo, jak długo gra się w tę aktywność.
Odczytywane ustawienia
PoleTypDo czego służy
image
wymagane w settings
string
stringBezwzględny adres URL obrazu do wymieszania. W odróżnieniu od puzzli, ten trafia do settings.
Przykładowe żądanie
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": "pl",
  "settings": {
    "image": "https://example.com/orchard.jpg"
  }
}'
Sukces 
{
  "success": true,
  "id": "-Nq8sample_activity_key",
  "url": "https://puzzel.org/en/slidingpuzzle/embed?p=-Nq8sample_activity_key",
  "message": "Sliding puzzle created successfully"
}
Otwórz edytor Powrót na górę

Coś nie działa jak trzeba?

Wyślij swoje żądanie i błąd, który wrócił, a dostaniesz konkretną odpowiedź — od osoby, która napisała ten endpoint.

Napisz do pomocy