API pengembang

Buat aktivitas dari sistemmu sendiri

Satu POST per jenis aktivitas. Kirim kontenmu sebagai JSON, lalu kamu mendapat satu aktivitas di akun Puzzel.org milikmu beserta URL yang bisa kamu berikan ke pemain atau kamu sematkan di iframe.

URL dasar: https://puzzel.org/api/public/v1
Autentikasi: Kunci + email di body
Endpoint: 38 jenis aktivitas
Kuota: 10 aktivitas per hari

Permintaan pertamamu

Tidak ada yang perlu dipasang dan tidak ada handshake: kirim body JSON berisi kuncimu, emailmu, dan kontenmu. Responsnya membawa kunci aktivitas baru itu dan URL tempat aktivitas itu dimainkan.

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

Berhasil

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

Setiap contoh di halaman ini adalah permintaan lengkap yang bisa langsung dijalankan. Ganti dengan kunci dan kontenmu sendiri, dan contoh itu langsung berfungsi.

Autentikasi

Tidak ada header dan tidak ada bearer token. Kedua kredensial dikirim di body JSON setiap permintaan, dan kunci hanya diterima untuk akun yang memiliki email tersebut.

Kolom	Tipe	Fungsinya
`account_api_key` wajib string	string	Kunci API akunmu. Dikirim di body, bukan di header.
`email` wajib string	string	Alamat email yang kamu pakai untuk masuk ke akun Puzzel.org. Kunci hanya berlaku bersama alamat itu.

Kuncimu ada di bagian akun pada dasbormu, di balik tombol Tampilkan.

Masuk

Kunci API diberikan saat langganan dimulai, jadi akun gratis belum punya kunci.

Lihat paket

Perlakukan kunci itu seperti kata sandi. Kunci itu membuat dan menimpa aktivitas di akunmu, jadi simpan di sisi server dan jauhkan dari apa pun yang bisa dibaca peramban.

Body permintaan

Setiap endpoint menerima lima kolom yang sama. Yang berbeda adalah kolom konten di bawahnya: sebagian besar menerima array items, beberapa menerima satu sentence atau satu image, dan Sudoku tidak menerima apa pun.

Kolom	Tipe	Fungsinya
`account_api_key` wajib string	string	Kunci API akunmu. Dikirim di body, bukan di header.
`email` wajib string	string	Alamat email yang kamu pakai untuk masuk ke akun Puzzel.org. Kunci hanya berlaku bersama alamat itu.
`title` opsional string	string	Nama yang didapat aktivitas di dasbormu. Kosongkan dan endpoint memakai nama cadangannya sendiri.
`language` opsional string	string	Hanya menentukan lokal di URL yang kamu terima — kolom ini tidak menerjemahkan apa pun yang kamu kirim. Pencarian kata juga membacanya untuk mengganti huruf pengisinya menjadi huruf Arab bila nilainya "ar". Bawaan: "en"
`activity_key` opsional string	string	Kosongkan untuk membuat aktivitas baru. Kirim kunci aktivitas yang sudah kamu miliki, dan aktivitas itulah yang dibangun ulang.

settings adalah objek berisi opsi per endpoint. Opsi mana yang dibaca sebuah endpoint dicantumkan bersamanya di bawah; apa pun lain yang kamu taruh di sana diabaikan.

Apa yang dikembalikan

Panggilan yang berhasil menjawab 200 dengan kunci aktivitas baru itu dan URL tempat aktivitas itu dimainkan. Selain itu, jawabannya berisi success bernilai false dan satu string error.

Berhasil

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

Gagal

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

url yang kamu terima adalah tampilan sematan. Ganti embed dengan play untuk membukanya satu halaman penuh, atau dengan build untuk membukanya di editor — kunci setelah p= tetap sama.

Membuat vs. memperbarui

Kirim activity_key dan aktivitas di baliknya dibangun ulang di tempat: kontennya diganti, nama dan cap versinya disegarkan, dan kuncinya sendiri tetap sama — jadi tautan dan sematan yang sudah kamu bagikan tetap berfungsi. Hasil, penempatan folder, dan setiap pengaturan yang tidak ditulis sendiri oleh endpoint dibiarkan apa adanya.

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 diterapkan pada setiap pembaruan, termasuk nilai bawaannya — kosongkan dan aktivitas itu akan diganti namanya menjadi nama cadangan endpoint tersebut.
Blok pengaturan yang ditulis sendiri oleh sebuah endpoint ditulis ulang dari nol, jadi pembaruan juga mengembalikan blok itu ke nilai yang kamu kirim, atau ke nilai bawaan endpoint.
Kamu hanya bisa memperbarui aktivitas yang dimiliki akunmu sendiri. Kunci milik orang lain dijawab 403.
Pembaruan berbiaya sama dengan pembuatan: satu panggilan dari kuota hari ini.

Batas permintaan

10 aktivitas per akun per hari

Setiap panggilan yang berhasil ikut dihitung, baik pembuatan maupun pembaruan. Lewati batasnya dan permintaan berikutnya dijawab 429 sampai penghitungnya dinolkan.

Penghitung dikosongkan sekali sehari oleh tugas terjadwal, bukan pada jendela 24 jam berjalan.

Kesalahan

Kesalahan selalu datang sebagai JSON dengan dua kolom yang sama, tidak pernah sebagai halaman HTML. String error ditulis untuk dibaca manusia — string itu menyebut kolom atau batas yang gagal.

Status	Artinya
`400` Bad Request	Ada isi body yang hilang, salah bentuk, atau di luar jangkauan. Pesannya menyebut kolom yang bermasalah.
`401` Unauthorized	Email tidak dikenal, atau kunci bukan milik akun itu.
`403` Forbidden	activity_key yang kamu kirim milik akun lain.
`429` Too Many Requests	Kuota hari ini sudah habis. Kuota dikosongkan sekali sehari.
`500` Server Error	Generator tidak bisa membangun teka-teki dari yang kamu kirim — biasanya karena katanya terlalu sedikit, atau kata yang tidak bisa disusun bersama.

Endpoint

Satu path per jenis aktivitas, semuanya POST, semuanya di bawah URL dasar yang sama. Masing-masing mencantumkan konten yang dibutuhkan, pengaturan yang dibaca, dan satu permintaan yang bisa kamu jalankan.

Kata & huruf

Teka-teki silang

Menautkan jawabanmu menjadi satu kisi dan menomori deskripsinya untukmu.

POST /api/public/v1/crossword 2 hingga 80 di items

Konten

Array kata. Setiap entri memasangkan jawaban dengan deskripsi yang menunjuk ke jawaban itu.

Memakai nama cadangan “Crossword API”

Perlu diketahui

Jawaban yang lebih pendek dari dua karakter dibuang sebelum kisi dibangun, dan minimal dua jawaban harus lolos dari penyaringan itu.
Jawaban diubah menjadi huruf kapital dan generator mendapat dua puluh percobaan untuk memuatnya. Kalau satu kata pun tidak bisa ditempatkan, panggilan dijawab 500.

Pengaturan yang dibaca

Kolom	Tipe	Fungsinya
`hidden_solution` opsional di settings string	string	Kata bonus opsional. Huruf-hurufnya ditandai di kotak-kotak kisi yang sudah jadi, untuk dikumpulkan pemain setelah teka-teki silang terpecahkan, jadi setiap hurufnya harus muncul di jawaban.

Contoh permintaan

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

Berhasil

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

Kolom	Tipe	Fungsinya
`hidden_solution` opsional di settings string	string	Huruf yang tersisa mengeja kata ini. Mengisinya juga memberi tahu generator untuk memuat solusinya lebih dulu, alih-alih menjejalkan sebanyak mungkin kata.
`directions` opsional di settings string[]	string[]	Ke arah mana saja sebuah kata boleh membentang. Kosongkan dan kata hanya membentang ke timur, tenggara, dan selatan. Salah satu dari `westeastnorthsouthnorthwestnortheastsouthwestsoutheast` Bawaan: ["east", "southeast", "south"]
`template` opsional di settings string	string	Memotong kisi menjadi sebuah bentuk alih-alih membiarkannya persegi. Salah satu dari `squarecirclecrossdiamondpyramidsmileystarcross_plus`

Kolom	Tipe	Fungsinya
`theme` opsional di settings string	string	Teka-teki yang ditampilkan di atas kisi. Kalau dikosongkan, pemain melihat judulnya.
`spangram` opsional di settings string	string	Kata atau frasa yang menyebutkan tema dan melintasi papan dari satu tepi ke tepi lainnya.

Kolom	Tipe	Fungsinya
`list_match_mode` opsional di settings string	string	Apakah sebuah nama dihitung begitu diketik, atau hanya setelah menekan tombol Enter. Salah satu dari `while_typingon_enter` Bawaan: "while_typing"
`list_slot_hint` opsional di settings string	string	Apa yang dibocorkan sebuah slot kosong: tidak ada, panjang nama, huruf pertamanya, atau petunjuk yang kamu tulis. Salah satu dari `nonelengthfirst_letterhint` Bawaan: "none"
`list_arrange` opsional di settings string	string	Satu kolom per kelompok, atau satu daftar. Salah satu dari `groupsone_list` Bawaan: "groups"
`list_allow_give_up` opsional di settings boolean	boolean	Menampilkan tombol menyerah yang mengakhiri putaran dan menunjukkan apa yang terlewat. Bawaan: false

Kolom	Tipe	Fungsinya
`mode` opsional di settings string	string	Apa yang mengisi kotak: items milikmu, items milikmu yang dipanggil lewat petunjuknya, atau angka biasa (yang tidak butuh items). Salah satu dari `itemscluesnumbers` Bawaan: "items"
`rows` opsional di settings number	number	Jumlah baris di setiap kartu, 2 sampai 5. Bawaan: 3
`columns` opsional di settings number	number	Jumlah kolom di setiap kartu, 2 sampai 5. Bawaan: 3
`highest_number` opsional di settings number	number	Dalam mode angka, kartu diisi dari 1 sampai angka ini, paling besar 100. Fitur paket: tanpa paket nilainya tetap 50. Bawaan: 50

Kolom	Tipe	Fungsinya
`instructions` opsional di settings string	string	Pertanyaan atau teka-teki yang dijawab oleh kode, ditampilkan bersama papan tombolnya.
`force_solution_in_correct_order` opsional di settings boolean	boolean	Tombol harus ditekan secara berurutan. Kalau dimatikan, urutan apa pun dari tombol yang benar membuka gemboknya. Bawaan: false
`randomize_order` opsional di settings boolean	boolean	Setiap pemain mendapat tombol dalam susunan yang diacak. Bawaan: true

Kolom	Tipe	Fungsinya
`number_of_tiles` opsional di settings number	number	Berapa banyak petak yang dimiliki papan. Antara 10 dan 75. Bawaan: 30
`game_mode` opsional di settings string	string	Apakah pemain berlomba ke garis akhir atau mengumpulkan benda di sepanjang jalan. Salah satu dari `race_to_finishcollect_items` Bawaan: "race_to_finish"

Kolom	Tipe	Fungsinya
`maze_width` opsional di settings string	string	Bagaimana ruang-ruangnya ditata: satu kolom, persegi, atau lebih lebar. Salah satu dari `narrownormalwide` Bawaan: "normal"
`maze_corridors` opsional di settings string	string	Seberapa banyak labirin yang terbentang di antara dua pertanyaan. Salah satu dari `shortnormallong` Bawaan: "normal"
`maze_fog` opsional di settings string	string	Tampilkan seluruh labirin, atau hanya yang pernah didekati pemain. Salah satu dari `offnear` Bawaan: "off"
`maze_wrong_door_pause` opsional di settings string	string	Berapa lama pintu tetap tertutup setelah pemain memilih pintu yang salah. Salah satu dari `noneshortlong` Bawaan: "short"
`maze_walk_there` opsional di settings boolean	boolean	Menampilkan tombol yang membawa bidak berjalan ke ruang berikutnya. Bawaan: false
`maze_seed` opsional di settings string	string	Seed yang menjadi dasar pembuatan labirin. Seed dan pertanyaan yang sama menghasilkan labirin yang sama; kalau dikosongkan, labirin baru dibuat.

Kolom	Tipe	Fungsinya
`jeopardy_buzzer_mode` opsional di settings string	string	Siapa bermain bagaimana: pemandu menjalankannya dari konsol, pemain menekan bel dari ponsel, atau setiap pemain mengerjakan papan sendirian. Salah satu dari `hostphonessolo` Bawaan: "host"
`jeopardy_contestants` opsional di settings string	string	Apakah konsol menyebut tim atau pemain. Salah satu dari `teamsplayers` Bawaan: "teams"
`jeopardy_value_step` opsional di settings number	number	Nilai sebuah baris: sebuah deskripsi bernilai angka ini dikali nomor barisnya. Dari 50 sampai 500, dengan kelipatan 50. Bawaan: 100
`jeopardy_answer_time` opsional di settings number	number	Detik untuk menjawab setelah sebuah deskripsi dibuka, paling lama 300. 0 berarti tanpa jam. Bawaan: 20
`jeopardy_wrong_answer_costs` opsional di settings boolean	boolean	Jawaban yang salah mengurangi skor sebesar nilai deskripsinya. Bawaan: false
`jeopardy_reveal_on_timeout` opsional di settings boolean	boolean	Papan sendiri menampilkan jawabannya saat waktu habis. Bawaan: false
`jeopardy_require_question_form` opsional di settings boolean	boolean	Mengingatkan pemain untuk menjawab dalam bentuk pertanyaan. Bawaan: false

Kolom	Tipe	Fungsinya
`video_url` wajib di settings string	string	Videonya: halaman YouTube, Vimeo atau Bunny Stream, atau tautan langsung ke berkas mp4, webm atau mov.
`video_duration` opsional di settings number	number	Panjang video dalam detik. Kalau diisi, pop-up yang melewati akhir video ditolak.

Kolom	Tipe	Fungsinya
`sentence` wajib string	string	Kalimat yang akan dienkripsi. Pemain memecahkannya karakter demi karakter.
`helpers` opsional di settings string	string	Karakter mana yang langsung dibagikan gratis sebagai jalan masuk: tidak ada, yang paling sering muncul, huruf vokal, atau yang kamu tentukan sendiri. Salah satu dari `nonemost_commonvowelscustom` Bawaan: "none"
`character_list` opsional di settings string	string	Abjad yang menjadi dasar sandinya. Kalau dibiarkan kosong, enkripsinya memilih sendiri.
`extra_letters` opsional di settings string	string	Karakter yang dibagikan ketika helpers bernilai "custom". Diabaikan untuk mode bantuan lainnya.
`hide_unused_characters` opsional di settings boolean	boolean	Menghilangkan karakter yang tidak pernah dipakai kalimat itu dari kuncinya. Bawaan: false

Kolom	Tipe	Fungsinya
`sentence` wajib string	string	Kalimat yang tersingkap saat pemain menyelesaikan soal hitungnya.
`difficulty_level` opsional di settings number	number	Jawaban tertinggi yang boleh dimiliki sebuah soal hitung. Salah satu dari `20501001000` Bawaan: "100"
`operators` opsional di settings string[]	string[]	Operasi mana saja yang boleh muncul. x adalah kali, : adalah bagi. Salah satu dari `+-x:` Bawaan: ["+", "-", "x", ":"]
`max_operations` opsional di settings number	number	Berapa banyak operasi yang boleh dirangkai dalam satu soal hitung. Salah satu dari `123` Bawaan: 1
`number_difficulty` opsional di settings number	number	Membatasi setiap angka di dalam satu soal hitung. Antara 5 sampai 1000. Bawaan: 100

Kolom	Tipe	Fungsinya
`size` opsional di settings string	string	Ukuran satu blok, ditulis sebagai baris kali kolom — 3x3 menghasilkan kisi 9x9 yang klasik. Endpoint hanya memeriksa bahwa nilainya terbaca sebagai dua angka, jadi gunakan saja ukuran yang disediakan editor. Salah satu dari `2x22x33x33x44x4` Bawaan: "3x3"
`difficulty_level` opsional di settings string	string	Berapa banyak angka yang ditinggalkan di papan sebagai titik awal. Salah satu dari `easynormalhard` Bawaan: "normal"

Kolom	Tipe	Fungsinya
`sentence` wajib string	string	Frasa yang akan disembunyikan: kutipan, peribahasa, kalimat kunci. Paling banyak 120 huruf dan angka.
`columns` opsional di settings number	number	Selebar apa papannya, dari 8 sampai 18. Yang lebih sempit menumpuk lebih banyak huruf di setiap kolom dan lebih sulit. Bawaan: 14
`helpers` opsional di settings string	string	Huruf mana yang tetap di kisi sebagai jalan masuk: tidak ada, yang paling sering muncul, huruf vokal, atau yang kamu tentukan sendiri. Salah satu dari `nonemost_commonvowelscustom` Bawaan: "none"
`extra_letters` opsional di settings string	string	Huruf yang dibagikan gratis ketika helpers bernilai "custom".

Kolom	Tipe	Fungsinya
`tables` opsional di settings number[]	number[]	Tabel yang dilatih. Kalau dikosongkan, nilainya 1 sampai 10; jika ada 11 atau 12, kisinya menjadi 12 kali 12. Salah satu dari `123456789101112`
`order` opsional di settings string	string	Apakah baris dan kolom berjalan berurutan atau diacak. Salah satu dari `ascendingshuffled` Bawaan: "ascending"
`picture` opsional di settings string	string	Gambar yang diwarnai oleh jawaban yang benar. Salah satu dari `sailboatheartrockettreecatfishflowerhouse` Bawaan: "sailboat"
`players_choose_tables` opsional di settings boolean	boolean	Membiarkan setiap pemain memilih tabel mana yang dilatih. Bawaan: false
`fill_same_sums` opsional di settings boolean	boolean	Satu jawaban yang benar mengisi setiap kotak dengan soal yang sama. Bawaan: true

Kolom	Tipe	Fungsinya
`story` opsional di settings string	string	Cerita latar yang ditampilkan di atas deskripsi.
`difficulty` opsional di settings string	string	Jenis deskripsi apa saja yang boleh dipakai generator. Salah satu dari `easymediumhard` Bawaan: "easy"
`hints` opsional di settings boolean	boolean	Menampilkan tombol yang menunjukkan langkah berikutnya. Bawaan: true
`auto_cross` opsional di settings boolean	boolean	Menandai satu pasangan mencoret sisa baris dan kolomnya. Bawaan: true
`clue_mode` opsional di settings string	string	Siapa yang menulis deskripsi yang dilihat pemain: dibuat dari tabel, kalimatmu sendiri di free_clues, atau tidak ada. Salah satu dari `generatedfreenone` Bawaan: "generated"
`free_clues` opsional di settings string[]	string[]	Kalimat deskripsimu sendiri, ditampilkan apa adanya, dengan clue_mode "free". Tidak ada yang memeriksanya.

Kolom	Tipe	Fungsinya
`clue_mode` opsional di settings string	string	Aturan ditampilkan sebagai gambar atau sebagai kalimat. Salah satu dari `visualtext` Bawaan: "visual"
`unique_object_picks` opsional di settings boolean	boolean	Setiap bentuk hanya boleh ditempatkan satu kali. Bawaan: false
`hide_color_picker` opsional di settings boolean	boolean	Pemain tidak bisa mengganti warna bentuk. Bawaan: false

Buat aktivitas dari sistemmu sendiri

Permintaan pertamamu

Autentikasi

Body permintaan

Apa yang dikembalikan

Membuat vs. memperbarui

Batas permintaan

Kesalahan

Endpoint

Ada yang tidak beres?