# Hubungkan Agen AI ke APIPedia via Token API

> Buat token API di console APIPedia, tempel ke prompt atau env agen AI, lalu agen memanggil api.apipedia.id/v1 dengan header Bearer.

- Base URL: `https://api.apipedia.id/v1`
- Header: `Authorization: Bearer apk_...`
- Buat token: https://console.apipedia.id/api/token
- Halaman: https://apipedia.id/docs/prompt-token
- Panduan umum (autentikasi, format respons, kode error): https://apipedia.id/docs.md

## Kapan memakai cara ini

Pakai token di prompt bila agenmu **bisa melakukan HTTP request** tetapi tidak (atau belum) mendukung MCP: ChatGPT dengan code interpreter, Claude Code atau Cursor yang menjalankan `curl`, n8n AI Agent, Make, agen kustom di server, dan sejenisnya.

- Agen memanggil REST API APIPedia langsung di base URL `https://api.apipedia.id/v1`.
- Token dikirim di header `Authorization: Bearer apk_...`, sama persis dengan [panduan autentikasi](https://apipedia.id/docs#autentikasi).
- Kamu yang mengatur cakupan (scope) dan masa berlaku token, jadi aksesnya bisa dibuat sesempit mungkin.

Tidak ingin menyalin token? Pakai [Via kode](https://apipedia.id/docs/device-code). Klienmu mendukung MCP? Pakai [Via MCP](https://apipedia.id/docs/mcp).

## Langkah-langkah

1. Masuk ke console, buka halaman [Token API](https://console.apipedia.id/api/token), lalu klik buat token baru.
2. Beri nama yang jelas (mis. `Agent ChatGPT`), pilih **hanya API yang dibutuhkan** sebagai cakupan, dan isi masa berlaku. Simpan.
3. Salin nilai token (diawali `apk_`). Nilai lengkapnya hanya tampil sekali.
4. Berikan token ke agen: tempel di prompt (lihat contoh di bawah) atau simpan sebagai environment variable `APIPEDIA_TOKEN`.
5. Agar agen tahu endpoint dan parameter yang benar, pasang [Skill APIPedia](https://apipedia.id/docs/skill) (berkas [SKILL.md](https://apipedia.id/skills/apipedia/SKILL.md)) atau minta agen membaca [https://apipedia.id/llms.txt](https://apipedia.id/llms.txt).
6. Tulis tugasmu. Agen memanggil API dengan header `Authorization: Bearer apk_...` dan membaca amplop `{ is_success, message, data }`.
7. Setelah selesai, cabut atau rotasi token itu di halaman [Token API](https://console.apipedia.id/api/token).

## Contoh prompt

Prompt singkat untuk satu tugas:

```text
Gunakan token apk_xxxxxxxxxxxxxxxx untuk memanggil https://api.apipedia.id/v1/libur/tahun/2026 dengan header "Authorization: Bearer <token>", lalu ringkas hari libur nasional bulan depan.
```

Prompt lengkap yang bisa dipakai ulang. Ganti token dan tugasnya, lalu tempel ke agenmu:

```text
Kamu membantu saya memakai APIPedia, gateway API Indonesia.

- Base URL: https://api.apipedia.id/v1
- Token API saya: apk_xxxxxxxxxxxxxxxx
  Kirim di header "Authorization: Bearer <token>". Anggap token ini rahasia: jangan tampilkan ulang, jangan tulis ke berkas atau log.

Sebelum memanggil apa pun:
1. Baca https://apipedia.id/llms.txt untuk daftar API dan tautan dokumentasinya.
2. Baca panduan umum https://apipedia.id/docs.md, lalu dokumentasi Markdown API yang relevan (https://apipedia.id/docs/<slug>.md, mis. https://apipedia.id/docs/cek-ongkir.md).
3. Kalau kamu mendukung Agent Skill, baca juga https://apipedia.id/skills/apipedia/SKILL.md.

Aturan:
- Panggil HANYA endpoint, parameter, dan field yang tertulis di dokumentasi itu. Jangan mengarang endpoint. Kalau tidak ada di dokumentasi, katakan tidak tersedia.
- Setiap respons berbentuk {"is_success": boolean, "message": string, "data": ...}. Periksa is_success dulu; kalau false, sampaikan message apa adanya.
- 401 = token salah/kedaluwarsa, 403 = di luar cakupan token, 429 = kuota habis, 502 = sumber data hulu gagal. Jangan mengulang request yang gagal berkali-kali.
- Setiap panggilan memakai kuota/saldo akun saya. Minta konfirmasi saya sebelum aksi yang mengirim sesuatu atas nama saya atau memakai saldo (email, postingan, isi saldo).

Tugas saya: <tulis tugasmu di sini>
```

Contoh tugas lain yang bisa ditulis di baris terakhir:

- "Cek ongkir 1 kg dari Jakarta Selatan ke Bandung, bandingkan tiga kurir termurah."
- "Ambil daftar kecamatan di Kota Yogyakarta lalu simpan sebagai CSV."
- "Baca teks dari foto KTP ini dengan OCR, lalu tampilkan field yang terbaca."

## Lewat environment variable

Untuk agen yang berjalan di terminal atau server (Claude Code, Cursor, skrip, n8n self-hosted), simpan token di environment variable supaya tidak muncul di riwayat chat:

```bash
# macOS / Linux (shell yang menjalankan agen)
export APIPEDIA_TOKEN="apk_xxxxxxxxxxxxxxxx"

# atau berkas .env di proyek (pastikan .env ada di .gitignore)
APIPEDIA_TOKEN=apk_xxxxxxxxxxxxxxxx
```

Lalu cukup tulis di prompt: "Pakai token di `$APIPEDIA_TOKEN` untuk memanggil APIPedia." Nama `APIPEDIA_TOKEN` juga dipakai oleh [Skill APIPedia](https://apipedia.id/docs/skill) dan contoh kode di setiap halaman API.

## Contoh curl

Request yang dikirim agen sama dengan request biasa:

```bash
curl "https://api.apipedia.id/v1/libur/tahun/2026" \
  -H "Authorization: Bearer apk_xxxxxxxxxxxxxxxx"
```

Respons selalu dibungkus amplop yang sama:

```json
{
  "is_success": true,
  "message": "Daftar hari libur 2026 berhasil diambil",
  "data": { }
}
```

Untuk memastikan token terbaca dengan benar, minta agen mengecek sisa kuota:

```bash
curl "https://api.apipedia.id/v1/me/quota" \
  -H "Authorization: Bearer $APIPEDIA_TOKEN"
```

## Keamanan token

- **Pakai token khusus berlingkup sempit.** Satu token per agen, cakupan hanya API yang dibutuhkan, dan masa berlaku pendek. Request di luar cakupan ditolak dengan **403**.
- **Jangan bagikan di chat publik.** Jangan menempel token di grup, forum, issue, percakapan yang dibagikan (share link), atau tangkapan layar. Siapa pun yang memegangnya bisa memakai kuota dan saldo akunmu.
- **Jangan commit token.** Simpan di environment variable atau secret manager, bukan di kode, SKILL.md, atau berkas konfigurasi yang ikut ke repositori.
- **Rotasi atau cabut kapan saja** di halaman [Token API](https://console.apipedia.id/api/token). Perubahan berlaku paling lambat sekitar 30 detik kemudian.
- **Pantau pemakaian.** Setiap panggilan dihitung ke kuota dan saldo akunmu; log request terlihat di console.
- **Minta konfirmasi untuk aksi penting.** Prompt di atas meminta agen bertanya dulu sebelum mengirim email, membuat postingan, atau memakai saldo.

## Pemecahan masalah

| Gejala | Penyebab dan solusi |
|---|---|
| **401 Unauthorized** | Token salah, kedaluwarsa, atau sudah dicabut. Pastikan diawali `apk_`, ditulis setelah `Bearer `, tanpa spasi atau tanda kutip berlebih. |
| **403 Forbidden** | Token sah tetapi cakupannya tidak mencakup API itu. Tambah cakupan token di halaman [Token API](https://console.apipedia.id/api/token). |
| **429** | Kuota harian atau batas request habis. Cek dengan `GET /v1/me/quota`. |
| Agen mengarang endpoint | Pasang [Skill APIPedia](https://apipedia.id/docs/skill) atau minta agen membaca dokumentasi Markdown di `https://apipedia.id/docs/<slug>.md` lebih dulu. |
| Agen tidak bisa melakukan HTTP request | Pakai [Via MCP](https://apipedia.id/docs/mcp) bila klien mendukung MCP. |

## Cara lain menghubungkan agen

- **[Via MCP](https://apipedia.id/docs/mcp)**: tempel URL server MCP `https://api.apipedia.id/v1/mcp` ke Claude, ChatGPT, Cursor, atau VS Code lalu login OAuth. Cocok untuk klien yang mendukung MCP.
- **[Via kode](https://apipedia.id/docs/device-code)**: ketik "hubungkan platformku ke apipedia.id", buka link dari agen, lalu tekan **Setujui**. Tanpa menyalin API key.

Ketiga cara berujung pada kredensial yang sama jenisnya: API key `apk_` dengan kuota, penagihan, dan amplop respons yang sama. Tambahkan [Skill APIPedia](https://apipedia.id/docs/skill) supaya agen mengenal setiap endpoint.