Dokumentasi
Panduan teknis dan spesifikasi lengkap endpoint publik Xez REST API gateway (GET & POST) beserta parameter query, skema body JSON, dan kode status.
Arahkan semua request ke https://api.xez.my.id. Prefix /api/* dan shortcut langsung (mis. /ip, /cf/waf, /recaptcha) sama-sama valid.
Gunakan GET dengan query string untuk lookup cepat, atau POST dengan header Content-Type: application/json untuk batch / solver.
Jika sukses, HTTP 200 mengembalikan payload JSON. Jika gagal, gateway mengembalikan status: "error" lengkap dengan code dan pesan error.
curl -s "https://api.xez.my.id/ip?ip=1.1.1.1"
Host dan alias
rute /api/* wajib mengarah ke api.xez.my.id| Host / Alias | Tujuan & Deskripsi | Protokol / Metode |
|---|---|---|
| api.xez.my.id | Host JSON API khusus untuk konsumsi programatis (GET & POST) | HTTP/3, TLS 1.3 |
| xez.my.id | Antarmuka web publik, dokumentasi, dan playground | HTTP/3, TLS 1.3 |
| /health (alias https://api.xez.my.id/health) | Alias ringkas untuk /api/health | GET |
| /ip (alias https://api.xez.my.id/ip) | Alias ringkas untuk /api/ip (mendukung query GET maupun body POST tunggal/batch) | GET · POST |
Referensi Endpoint
Spesifikasi lengkap parameter query & body JSON, deskripsi field, contoh pemanggilan, dan skema respons.
/api/health
Memeriksa status operasional layanan REST API, versi rilis gateway, dan stempel waktu server UTC secara real-time.
| Field | Tipe | Keterangan |
|---|---|---|
| status | string | Indikator ketersediaan gateway (selalu bernilai "online" saat node sehat). |
| service, version | string | Identitas layanan ("xez.my.id REST API") dan versi spesifikasi aktif ("1.0.0"). |
| timestamp | string (ISO-8601) | Waktu evaluasi respons di sisi server dalam format UTC ISO-8601. |
curl -s https://api.xez.my.id/api/health
{
"status": "online",
"service": "xez.my.id REST API",
"version": "1.0.0",
"timestamp": "2026-11-13T14:30:00.000Z"
}/api/ip
Mengambil detail GeoIP tunggal (kota, wilayah, negara, kode pos, koordinat, timezone), informasi jaringan (ISP, organisasi, ASN), serta hasil parsing User-Agent klien melalui query string URL.
| Parameter | Tipe | Status | Keterangan |
|---|---|---|---|
| ip | string | opsional | Alamat IPv4 atau IPv6 publik target. Jika dikosongkan, otomatis menggunakan IP pemanggil. |
| fields | string | opsional | Filter bagian output dipisahkan koma: geo, network, client (mis. ?fields=geo,network). Default menampilkan semua. |
| Field | Tipe | Keterangan |
|---|---|---|
| status, ip, version | string | Status permintaan, alamat IP target, dan versi protokol (IPv4 / IPv6). |
| geo.* | object | Kota, wilayah, negara, kode ISO, kode pos, koordinat (latitude/longitude), dan timezone. |
| network.* | object | Metadata penyedia jaringan: isp, org, dan asn. |
| client.* | object | Hasil parsing User-Agent pemanggil: device_type, os, browser, is_mobile, is_tablet, is_bot. |
curl -s "https://api.xez.my.id/api/ip?ip=1.1.1.1&fields=geo,network"
{
"status": "success",
"ip": "1.1.1.1",
"version": "IPv4",
"geo": {
"city": "South Brisbane",
"region": "Queensland",
"country": "Australia",
"country_code": "AU",
"postal_code": "4101",
"latitude": -27.4766,
"longitude": 153.0166,
"timezone": "Australia/Brisbane"
},
"network": {
"isp": "Cloudflare, Inc",
"org": "APNIC and Cloudflare DNS Resolver project",
"asn": "AS13335 Cloudflare, Inc."
},
"client": {
"raw": "curl/8.5.0",
"device_type": "Desktop",
"device_name": "Desktop",
"os": "Unknown OS",
"browser": "Unknown Browser",
"is_mobile": false,
"is_tablet": false,
"is_bot": true
}
}/api/ip
Menjalankan lookup GeoIP via HTTP POST body JSON: cocok untuk menyembunyikan IP target dari log URL, memproses batch paralel hingga 10 alamat IPv4/IPv6 sekaligus, memilih field tertentu, atau menguji string User-Agent kustom.
| Field Body | Tipe | Status | Keterangan |
|---|---|---|---|
| ips | string[] | opsional | Array berisi 1–10 alamat IPv4/IPv6 untuk diproses secara batch paralel. Menghasilkan mode: "batch" & array results[]. |
| ip | string | opsional | Satu alamat IPv4/IPv6 target (mode: "single"). Jika ip & ips kosong, menggunakan IP pemanggil. |
| fields | string[] | string | opsional | Daftar bagian yang disertakan: ["geo", "network", "client"]. Memperkecil ukuran payload respons. |
| user_agent | string | opsional | Override string User-Agent (maks 512 karakter) untuk dianalisis pada objek client.*. |
| Field | Tipe | Keterangan |
|---|---|---|
| status, mode | string | Status eksekusi ("success") dan mode pemrosesan ("single" atau "batch"). |
| count, results[] | number, array | Jumlah IP yang diproses beserta daftar objek hasil GeoIP/network/client pada mode batch. |
curl -s -X POST "https://api.xez.my.id/api/ip" \
-H "Content-Type: application/json" \
-d '{"ips":["1.1.1.1","8.8.8.8"],"fields":["geo","network"]}'
{
"status": "success",
"mode": "batch",
"count": 2,
"results": [
{
"status": "success",
"ip": "1.1.1.1",
"version": "IPv4",
"geo": { "city": "South Brisbane", "country": "Australia", "country_code": "AU" },
"network": { "isp": "Cloudflare, Inc", "asn": "AS13335 Cloudflare, Inc." }
},
{
"status": "success",
"ip": "8.8.8.8",
"version": "IPv4",
"geo": { "city": "Ashburn", "country": "United States", "country_code": "US" },
"network": { "isp": "Google LLC", "asn": "AS15169 Google LLC" }
}
]
}/api/kuku/domains
Mengambil daftar domain email sementara aktif m.kuku.lu secara real-time (dengan cache ringan 5 menit).
GET https://api.xez.my.id/kuku/domainsTidak memerlukan parameter query atau body. Menggunakan cache ringan 5 menit.
curl -s "https://api.xez.my.id/api/kuku/domains"
{
"status": "success",
"provider": "m.kuku.lu",
"count": 50,
"default_domain": "nekosan.uk",
"cached": false,
"domains": [
"adadad.uk",
"addrin.uk",
"bangban.uk",
"nekosan.uk"
]
}/api/kuku/create
Membuat alamat email sementara baru di m.kuku.lu (mode random, custom, atau onetime) beserta token session stateless.
POST https://api.xez.my.id/kuku/create| Field | Tipe | Keterangan |
|---|---|---|
| mode | string | Mode alokasi opsional: "random" (default), "custom", atau "onetime". |
| user | string | Handle kustom (1–32 karakter alfanumerik, ".", "_", "-"); wajib saat mode="custom". |
| domain | string | Domain tujuan dari /api/kuku/domains (default: nekosan.uk). |
| session | string | Token session opsional jika ingin menggabungkan alamat baru ke sesi yang sudah ada. |
curl -s -X POST "https://api.xez.my.id/api/kuku/create" \
-H "Content-Type: application/json" \
-d '{"mode":"onetime"}'
{
"status": "success",
"email": "shehitray@petchi.uk",
"mode": "onetime",
"expiry": "Friday 18th of December 2026",
"session": "eyJ2IjoxLCJjc3JmIjoiLi4uIn0"
}/api/kuku/inbox
Mengambil daftar email masuk untuk alamat m.kuku.lu memakai token session dari /api/kuku/create.
POST https://api.xez.my.id/kuku/inbox| Field | Tipe | Keterangan |
|---|---|---|
| string* | Alamat email m.kuku.lu yang ingin diperiksa. | |
| session | string* | Token session dari respons /api/kuku/create. |
curl -s -X POST "https://api.xez.my.id/api/kuku/inbox" \
-H "Content-Type: application/json" \
-d '{"email":"contoh@nekosan.uk","session":"TOKEN"}'
{
"status": "success",
"email": "contoh@nekosan.uk",
"count": 1,
"messages": [
{
"num": 49193676,
"key": "cdb742dc73913211e6962aa7ec6804ee",
"subject": "Verification Code",
"from": "noreply@example.com",
"time": "05/31, 18:50"
}
],
"session": "eyJ2IjoxLCJjc3JmIjoiLi4uIn0"
}/api/kuku/read
Membaca isi pesan email, membersihkan tag HTML, dan mengekstrak kode OTP 4–8 digit serta tautan bersih.
POST https://api.xez.my.id/kuku/read| Field | Tipe | Keterangan |
|---|---|---|
| num | number* | ID numerik pesan dari daftar messages[] /api/kuku/inbox. |
| key | string* | Kunci heksadesimal pesan dari daftar messages[] /api/kuku/inbox. |
| session | string* | Token session aktif dari /api/kuku/create atau /api/kuku/inbox. |
curl -s -X POST "https://api.xez.my.id/api/kuku/read" \
-H "Content-Type: application/json" \
-d '{"num":49193676,"key":"MAIL_KEY","session":"TOKEN"}'
{
"status": "success",
"num": 49193676,
"key": "cdb742dc73913211e6962aa7ec6804ee",
"text": "Your verification code is 482910",
"otp_codes": [
"482910"
],
"links": [
{
"text": "Confirm Account",
"url": "https://example.com/verify?code=482910"
}
],
"session": "eyJ2IjoxLCJjc3JmIjoiLi4uIn0"
}/api/kuku/delete
Menghapus alokasi alamat email sementara dari sesi aktif di server m.kuku.lu.
POST https://api.xez.my.id/kuku/delete| Field | Tipe | Keterangan |
|---|---|---|
| string* | Alamat email m.kuku.lu yang ingin dihapus. | |
| session | string* | Token session aktif dari /api/kuku/create. |
curl -s -X POST "https://api.xez.my.id/api/kuku/delete" \
-H "Content-Type: application/json" \
-d '{"email":"contoh@nekosan.uk","session":"TOKEN"}'
{
"status": "success",
"deleted": true,
"email": "contoh@nekosan.uk",
"session": "eyJ2IjoxLCJjc3JmIjoiLi4uIn0"
}/api/genmail/create
Menghasilkan alamat email sementara acak baru via generator.email tanpa token session.
GET https://api.xez.my.id/genmail/createTidak memerlukan parameter query atau body. Menggunakan cache ringan 5 menit.
curl -s "https://api.xez.my.id/api/genmail/create"
{
"status": "success",
"provider": "generator.email",
"email": "elduro213@calvarystreetisa.org",
"user": "elduro213",
"domain": "calvarystreetisa.org",
"inbox_url": "https://generator.email/calvarystreetisa.org/elduro213"
}/api/genmail/inbox
Membaca pesan masuk generator.email beserta ekstraksi kode OTP 4–8 digit dan tautan bersih.
GET https://api.xez.my.id/genmail/inbox| Field | Tipe | Keterangan |
|---|---|---|
| string* | Alamat email generator.email target (contoh: elduro213@calvarystreetisa.org). |
curl -s "https://api.xez.my.id/api/genmail/inbox?email=elduro213@calvarystreetisa.org"
{
"status": "success",
"provider": "generator.email",
"email": "elduro213@calvarystreetisa.org",
"count": 1,
"messages": [
{
"from": "noreply@example.com",
"subject": "Verification Code",
"time": "2026-11-16 15:00:00",
"text": "Your OTP is 482910",
"otp_codes": [
"482910"
],
"links": []
}
]
}/api/genmail/inbox
Versi POST JSON untuk membaca kotak masuk generator.email tanpa menaruh alamat email di query URL.
POST https://api.xez.my.id/genmail/inbox| Field | Tipe | Keterangan |
|---|---|---|
| string* | Alamat email generator.email target. |
curl -s -X POST "https://api.xez.my.id/api/genmail/inbox" \
-H "Content-Type: application/json" \
-d '{"email":"elduro213@calvarystreetisa.org"}'
{
"status": "success",
"provider": "generator.email",
"email": "elduro213@calvarystreetisa.org",
"count": 0,
"messages": []
}/api/tiktok/info
Mengambil metadata dan informasi embed resmi video TikTok publik via oEmbed API dengan proteksi anti-SSRF.
GET https://api.xez.my.id/tiktok/info| Field | Tipe | Keterangan |
|---|---|---|
| url | string* | URL video TikTok publik (domain tiktok.com, vm.tiktok.com, atau vt.tiktok.com). |
curl -s "https://api.xez.my.id/api/tiktok/info?url=https://www.tiktok.com/@tiktok/video/7106594312292453675"
{
"status": "success",
"provider": "tiktok.oembed",
"url": "https://www.tiktok.com/@tiktok/video/7106594312292453675",
"video_id": "7106594312292453675",
"type": "video",
"embed": {
"width": 325,
"height": 578,
"player_url": "https://www.tiktok.com/player/v1/7106594312292453675"
}
}/api/tiktok/info
Versi POST JSON untuk mengambil metadata dan embed resmi video TikTok publik.
POST https://api.xez.my.id/tiktok/info| Field | Tipe | Keterangan |
|---|---|---|
| url | string* | URL video TikTok publik. |
curl -s -X POST "https://api.xez.my.id/api/tiktok/info" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.tiktok.com/@tiktok/video/7106594312292453675"}'
{
"status": "success",
"provider": "tiktok.oembed",
"url": "https://www.tiktok.com/@tiktok/video/7106594312292453675",
"video_id": "7106594312292453675",
"type": "video",
"embed": {
"width": 325,
"height": 578,
"player_url": "https://www.tiktok.com/player/v1/7106594312292453675"
}
}/api/cloudflare
Satu endpoint untuk semua jalur: cache, WAF, Turnstile, lalu proxy VPS bila direct gagal. Mengembalikan hasil pertama yang benar-benar bisa dipakai, lengkap dengan attempts[].
POST https://api.xez.my.id/cloudflare
| Field | Tipe | Keterangan |
|---|---|---|
| url | string* | URL publik target. |
| sitekey | string | Opsional, dipakai kalau widget butuh sitekey eksplisit. |
| async | boolean | Kembalikan taskId, poll /api/cloudflare/status. |
| timeout | integer | Batas waktu ms (default 30000). |
curl -s -X POST "https://api.xez.my.id/api/cloudflare" -H "Content-Type: application/json" -d '{"url":"https://nowsecure.nl/","async":true,"timeout":30000}'
{
"status": "success",
"mode": "waf",
"attempts": ["waf"],
"data": {
"cfClearance": "AbCd123...",
"cookieString": "cf_clearance=AbCd123...",
"userAgent": "Mozilla/5.0..."
}
}/api/cf/turnstile
Menyelesaikan widget Cloudflare Turnstile (managed checkbox, non-interactive, maupun invisible) pada URL publik target dan mengembalikan token cf-turnstile-response.
Browser selalu dijalankan headed (Xvfb + Chromium asli). Mode headless tidak pernah menerbitkan token, jadi field headless diabaikan server dan response selalu berisi "headless": false.
POST https://api.xez.my.id/cf/turnstile
| Field | Tipe | Keterangan |
|---|---|---|
| url | string* | URL publik halaman yang memuat widget (http/https, dilindungi anti-SSRF + resolusi DNS). |
| sitekey | string | Opsional. Solver mendeteksi widget sendiri; isi hanya kalau widget dirender dinamis. |
| timeout | integer | Batas waktu tunggu ms (5000–13000, default: 10000). |
| proxy | object | Opsional { host, port, username?, password? }. |
| headless | boolean | Diabaikan · selalu false. |
curl -s -X POST "https://api.xez.my.id/api/cf/turnstile" \
-H "Content-Type: application/json" \
-d '{"url":"https://2captcha.com/demo/cloudflare-turnstile","timeout":10000}'
{
"status": "success",
"mode": "turnstile",
"url": "https://2captcha.com/demo/cloudflare-turnstile",
"token": "0.AbCdEf...",
"headless": false,
"elapsedMs": 3370
}
Kirim token sebagai field form cf-turnstile-response bersama request kamu sendiri · biasanya divalidasi sekali per submit dan kedaluwarsa dalam ~5 menit.
/api/cf/waf
Melewati halaman tantangan Cloudflare WAF ("Just a moment...") pada URL publik target dan mengembalikan cookie cf_clearance, cookieString, daftar cookies lengkap, serta userAgent.
Halaman demo widget Turnstile bukan gate WAF · tidak menerbitkan cookie apa pun. Contoh target yang valid: https://nowsecure.nl. Browser headed, timeout 5000–13000 ms.
POST https://api.xez.my.id/cf/waf
| Field | Tipe | Keterangan |
|---|---|---|
| url | string* | URL publik di balik challenge Cloudflare (http/https, anti-SSRF + resolusi DNS). |
| timeout | integer | Batas waktu tunggu ms (5000–13000, default: 10000). |
| proxy | object | Opsional { host, port, username?, password? } · pakai proxy residensial kalau IP datacenter langsung diblok. |
| headless | boolean | Diabaikan · selalu false. |
curl -s -X POST "https://api.xez.my.id/api/cf/waf" \
-H "Content-Type: application/json" \
-d '{"url":"https://nowsecure.nl","timeout":10000}'
{
"status": "success",
"mode": "waf",
"url": "https://nowsecure.nl/",
"cfClearance": "Cj4nqL08xR04ux...",
"cookieString": "cf_clearance=Cj4nqL08xR04ux...",
"cookies": [{ "name": "cf_clearance", "value": "..." }],
"userAgent": "Mozilla/5.0 ...",
"elapsedMs": 5120
}
cf_clearance terikat pada IP + User-Agent pemanggil. Reuse cookie dari mesin/IP yang sama, kalau tidak Cloudflare langsung menantang ulang. Tanpa clearance → 502; solver kehabisan waktu → 504.
/api/recaptcha
Solver reCAPTCHA multi-mode yang menggabungkan dua engine independen: Engine v2 (HTTP Stateless) untuk checkbox, invisible, dan enterprise tanpa overhead browser; serta Engine v3 (Headed Browser) untuk challenge berbasis skor (score-based) lewat Chromium Xvfb asli.
Stateless anchor & reload token protocol. Menyelesaikan reCAPTCHA v2 Checkbox ("I'm not a robot"), v2 Invisible, dan v2 Enterprise dalam ~200–500 ms tanpa browser. Jika Google mendeteksi reputasi IP buruk dan meminta interaksi gambar, gateway mengembalikan status CHALLENGE_REQUIRED secara jujur.
Mengeksekusi skrip client resmi target di lingkungan browser asli (grecaptcha.execute(sitekey, { action })). Menghasilkan token skor v3 valid yang terikat langsung pada origin target.
POST https://api.xez.my.id/api/recaptcha (shortcut: /recaptcha)POST https://api.xez.my.id/api/recaptcha/v2POST https://api.xez.my.id/api/recaptcha/v3GET https://api.xez.my.id/api/recaptcha/types| Tipe | Path Endpoint | Engine | Keterangan |
|---|---|---|---|
| auto | /api/recaptcha | Fallback | Coba v2 HTTP dulu, lalu beralih ke v3 browser |
| v2 | /api/recaptcha/v2 | Pure HTTP | Checkbox standar "I'm not a robot" |
| v2-invisible | /api/recaptcha/v2-invisible | Pure HTTP | Badge invisible tanpa interaksi pengguna |
| v2-enterprise | /api/recaptcha/v2-enterprise | Pure HTTP | Google Cloud reCAPTCHA Enterprise |
| v3 | /api/recaptcha/v3 | Browser headed | Score-based evaluation (opsional param action) |
| v3-enterprise | /api/recaptcha/v3-enterprise | Browser headed | Enterprise score-based evaluation |
| Field | Tipe | Keterangan |
|---|---|---|
| url | string* | URL halaman target (wajib; sitekey, versi Enterprise, & mode otomatis terdeteksi dari HTML target). |
| sitekey | string | Opsional: override manual jika sitekey dirender dinamis lewat JS eksternal dan tidak ada di HTML awal. |
| type / mode | string | Pilihan varian: auto (default), v2, v2-invisible, v2-enterprise, v3, v3-enterprise. |
| action | string | Khusus v3: nama action yang dipantau (mis. verify, login, default: verify). |
| timeout | integer | Batas waktu tunggu engine browser v3 dalam ms (5000–30000, default: 15000). |
| anchorUrl | string | Khusus v2: alternatif URL anchor lengkap dari inspect browser. |
| size | string | Ukuran widget v2: normal, invisible, atau compact. |
| isEnterprise | boolean | Pakai endpoint Google Cloud Enterprise jika true. |
# [1] Mode Auto (cukup kirim URL, sitekey & versi terdeteksi otomatis)
curl -s -X POST "https://api.xez.my.id/api/recaptcha" -H "Content-Type: application/json" -d '{
"url": "https://www.google.com/recaptcha/api2/demo"
}'
# [2] Engine v3 Browser Headed (Score-based)
curl -s -X POST "https://api.xez.my.id/api/recaptcha/v3" -H "Content-Type: application/json" -d '{
"url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
"action": "examples/v3scores",
"timeout": 15000
}'
{
"status": "success",
"type": "v2",
"token": "03AFcWeA7Z-x19k...",
"attempts": ["v2"],
"elapsedMs": 265
}
Kirim nilai token sebagai field form g-recaptcha-response bersama request POST form target kamu. Backend target akan memverifikasi token ini ke Google siteverify.
Jika Google mewajibkan tantangan gambar manual (akibat skor reputasi IP pemanggil rendah), server v2 HTTP akan membalas CHALLENGE_REQUIRED secara jujur tanpa menggantung koneksi. Mode auto atau direct /api/recaptcha/v3 otomatis mencoba jalur solver browser.
Kode status & error
Semua respons dan error gateway dikembalikan dalam format JSON terstruktur beserta kode status HTTP standar:
| Kode | Arti & Penyebab |
|---|---|
| 200 OK | Permintaan GET atau POST berhasil diproses dan payload JSON dikembalikan dengan header Cache-Control: no-store. |
| 400 Bad Request | Format alamat IP tidak valid, JSON request body rusak, filter fields tidak dikenali, atau array ips melebihi batas 10 item. |
| 404 Not Found | Rute tidak terdaftar, atau endpoint /api/* dipanggil ke domain web xez.my.id (wajib memakai https://api.xez.my.id). |
| 405 Method Not Allowed | Metode HTTP tidak didukung oleh rute target (mis. memanggil POST pada /api/health). |
| 413 Payload Too Large | Ukuran body permintaan POST melebihi batas maksimum gateway (16 KB). |
| 429 Too Many Requests | Batas laju (rate limit) per IP terlampaui. Tunggu sesuai header Retry-After atau pantau X-RateLimit-Reset sebelum mengulang permintaan. |
| 502 Bad Gateway | Solver Cloudflare tidak mendapat cf_clearance dalam batas waktu, atau target membalas challenge yang tidak bisa dilewati. |
| 503 Service Unavailable | Runtime browser di node belum siap (instalasi dependensi). Coba ulang beberapa detik lagi. |
| 504 Gateway Timeout | Widget Turnstile tidak menerbitkan token, atau solver kehabisan waktu (timeout 5000–13000 ms). |
Format respons & body
Semua endpoint REST xez.my.id menerima dan menyajikan data JSON berformat UTF-8 standar:
Digunakan untuk seluruh respons /api/* serta body permintaan POST di api.xez.my.id dengan dukungan penuh Access-Control-Allow-Origin: *.
{
"status": "ok",
"method": "GET",
...
}
{
"status": "error",
"code": 400,
"error": "Deskripsi penyebab error"
}