Dokumentasi API

Dokumentasi Wisepage

Semua yang Anda butuhkan untuk memanggil Wisepage dari kode Anda: autentikasi, setiap endpoint beserta parameternya, penagihan kredit dan kode error.

Mulai cepat

Semua endpoint ada di https://api.wisepage.dev. Kirim JSON lewat POST dengan API key Anda di header. Selama beta privat, API key dikirim lewat email setelah Anda mendaftar.

curl https://api.wisepage.dev/v1/scrape \
  -H "Authorization: Bearer $WISEPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Mau langsung dipakai di Claude Code, Cursor atau VS Code? Lihat panduan MCP. Kredit, batas dan log pemakaiannya sama dengan REST.

Autentikasi

Kirim API key di header Authorization: Bearer wsp_live_..., atau di header x-api-key. Simpan key di variabel lingkungan atau secret manager, jangan di kode yang dibagikan. Kalau key bocor, kirim email ke hello@wisepage.dev dan kami ganti.

Format respons

Respons yang berhasil selalu berbentuk {"success": true, "credits_used": ..., "data": ...}. Respons error memakai status HTTP yang sesuai dan bentuk berikut:

{ "error": { "code": "url_not_allowed", "message": "Private and reserved IP addresses are not allowed" } }

Pakai code di kode Anda; message ditujukan untuk manusia dan bisa berubah. Daftar lengkapnya ada di Kode error.

Kredit dan harga

Sebelum request dijalankan, biaya maksimumnya ditahan dari saldo. Setelah selesai, Anda hanya membayar yang benar-benar terpakai dan sisanya langsung kembali. Request yang gagal tidak ditagih sama sekali.

Setiap respons mencantumkan credits_used. Kalau saldo tidak cukup, API membalas 402 insufficient_credits tanpa menjalankan request.

Batas pemakaian

• 60 request per menit per API key. Sisa kuotanya ada di header X-RateLimit-Remaining. Lewat dari itu, API membalas 429 rate_limited.
• Batas per domain untuk gabungan semua pelanggan, supaya situs yang dibaca tidak terbebani. Kalau tercapai, API membalas 429 domain_rate_limited dengan details.retry_after_ms. batch/scrape dan crawl sudah mencobanya ulang otomatis.
• Ukuran: halaman web maksimal 5 MB, PDF maksimal 20 MB dan 100 halaman.
• Waktu: satu halaman maksimal 60 detik (timeout_ms, default 20 detik); batch/scrape dan crawl punya anggaran sekitar 60 detik per panggilan.

Cache

Halaman yang baru diambil disimpan sebentar, jadi request yang sama lebih cepat dan situs tidak diambil ulang. Atur umur salinan yang Anda terima dengan max_age (detik, default 3600, maksimal 86400). Pakai "max_age": 0 untuk selalu mengambil versi terbaru. Respons menyertakan cached dan fetched_at, dan salinan dari cache ditagih sama seperti pengambilan baru.

Endpoint

POST/v1/scrape

Mengambil satu halaman web atau file PDF dan mengembalikannya sebagai markdown bersih beserta metadata. Halaman yang butuh JavaScript dirender otomatis.

{
  "success": true,
  "credits_used": 1,
  "data": {
    "url": "https://example.com/",
    "status_code": 200,
    "rendered": false,
    "markdown": "# Example Domain\n\nThis domain is for use in ...",
    "metadata": { "title": "Example Domain", "language": "en", "description": null, ... },
    "cached": false,
    "fetched_at": "2026-09-28T04:12:00.000Z"
  }
}

POST/v1/batch/scrape

Mengambil hingga 50 URL dalam satu panggilan dengan opsi yang sama. Hasil kembali sesuai urutan input; URL yang gagal mendapat kode error tanpa menggagalkan yang lain.

"data": {
  "results": [
    { "url": "https://a.example/", "success": true, "data": { "markdown": "...", ... } },
    { "url": "https://b.example/", "success": false, "error": "fetch_timeout" }
  ],
  "stats": { "succeeded": 1, "failed": 1, "stopped_reason": "done" }
}

POST/v1/crawl

Mengikuti tautan dalam satu situs mulai dari satu halaman, dan mengembalikan hingga 50 halaman sebagai markdown.

Respons berisi pages (url, markdown, metadata), failed (url dan kode error) dan stats. Kredit untuk limit halaman ditahan di awal; halaman yang gagal atau tidak sempat diambil dikembalikan.

POST/v1/map

Mendaftar URL sebuah situs dari sitemap dan tautan di halamannya, tanpa membuka setiap halaman. Cocok untuk memilih halaman sebelum batch/scrape.

POST/v1/search

Mencari di web (hasil Google) dan mengembalikan judul, URL dan cuplikan. Aktifkan scrape_results untuk sekalian mendapat isi setiap halaman sebagai markdown.

POST/v1/extract

Mengambil data terstruktur dari satu halaman atau PDF sesuai JSON Schema Anda. Responsnya selalu cocok dengan skema.

curl https://api.wisepage.dev/v1/extract \
  -H "Authorization: Bearer $WISEPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://toko.example/produk/123",
    "schema": {
      "type": "object",
      "properties": {
        "nama": { "type": "string" },
        "harga": { "type": "number" },
        "tersedia": { "type": "boolean" }
      },
      "required": ["nama", "harga"]
    }
  }'

Respons berisi data (hasil sesuai skema), source (url, judul, dan truncated kalau halaman lebih dari 60.000 karakter dipotong) dan usage (token yang dipakai). Anda perlu minimal 5 kredit untuk memulai; setelah halaman diambil, biaya maksimum untuk halaman itu ditahan lalu sisanya dikembalikan.

GET/v1/usage

Sisa kredit dan daftar panggilan terakhir beserta biaya dan statusnya. Parameter query limit 1–200, default 50. Gratis.

"data": {
  "credits_remaining": 4812,
  "recent": [ { "operation": "scrape", "credits": 1, "success": true, "duration_ms": 412, ... } ]
}

PDF

Semua endpoint yang mengambil halaman juga bisa membaca PDF, termasuk file yang dikirim server sebagai unduhan biasa. Isinya dikembalikan sebagai markdown yang rapi: judul, paragraf, daftar dan tabel disusun ulang dari tata letaknya, sedangkan header, footer dan nomor halaman yang berulang dibuang. Penanda <!-- page N --> memisahkan halaman, dan respons menyertakan pdf: { pages, pages_parsed, truncated }.

Hingga 100 halaman dan 20 MB dibaca per file, dengan biaya 1 kredit per 10 halaman. PDF hasil scan tanpa lapisan teks dibalas 422 pdf_no_text, dan PDF berpassword 422 pdf_encrypted.

Spesifikasi OpenAPI

Semua endpoint di halaman ini juga tersedia sebagai file OpenAPI (YAML). File itu ditujukan untuk program, bukan untuk dibaca langsung: impor ke Postman atau Insomnia untuk mencoba setiap endpoint, buka di Swagger UI atau Redoc untuk dokumentasi interaktif, atau pakai generator kode untuk membuat library di bahasa Anda.

https://wisepage.dev/openapi.yaml

Kode error

Semua error di atas tidak ditagih. Masih ada pertanyaan? Tulis ke hello@wisepage.dev.