Agent API v2 — API untuk AI Agent

Agent API v2 adalah namespace API khusus yang dirancang untuk AI Agent, LLM, dan automation tool. Dengan Agent API, AI Agent Anda dapat mengakses dan mengelola data lead, menarik analytics, memantau conversion tracking, dan mendapatkan informasi workspace — semuanya melalui endpoint yang aman dan terstruktur.

Apa itu SKILL.md?

SKILL.md adalah dokumen machine-readable yang menjelaskan seluruh kemampuan Agent API Konektor. AI Agent membaca file ini untuk memahami endpoint apa saja yang tersedia, parameter yang dibutuhkan, dan format response yang dikembalikan.

URL SKILL.md Anda:

https://konektor.id/api/v2/agent/SKILL.md

SKILL.md bersifat publik dan tidak memerlukan autentikasi. AI Agent manapun dapat mengaksesnya langsung.

Hubungkan melalui MCP

Untuk integrasi Claude yang baca-saja dengan persetujuan pengguna, gunakan connector Konektor untuk Claude. Panduan di bawah menjelaskan endpoint MCP lanjutan berbasis API key.

Gunakan endpoint Streamable HTTP berikut jika agent Anda mendukung MCP:

https://mcp.konektor.id/mcp

Kirim API key workspace sebagai Bearer token:

Authorization: Bearer <api_key_anda>

MCP hanya menampilkan tool yang diizinkan oleh scope pada API key. Workspace ditentukan dari key, jadi agent tidak dapat memilih workspace lain melalui parameter tool.

Konfigurasi umum klien MCP berbasis HTTP:

{
  "url": "https://mcp.konektor.id/mcp",
  "headers": {
    "Authorization": "Bearer ${KONEKTOR_API_KEY}"
  }
}

Setelah terhubung, jalankan List Tools. Koneksi berhasil jika klien menampilkan tool yang sesuai dengan scope key.

Setiap hasil List Tools memuat inputSchema dan outputSchema. Schema tersebut menandai field wajib, enum, panjang teks, batas angka, ukuran batch, dan bentuk response agar agent tidak perlu menebak kontrak tool.

lead_delete membutuhkan confirm=true, scope terpisah leads.delete, dan paket yang mengaktifkan Management API. leads_bulk_upsert juga membutuhkan Management API. Data dihapus secara soft-delete, bukan dipurge. Jangan berikan scope tulis, hapus, atau bulk jika agent hanya perlu membaca data.

Billing di MCP bersifat baca-saja. Agent dapat melihat paket, harga, retensi, dan batas melalui billing_plans, serta melihat paket workspace dan penggunaan lead harian melalui workspace_get. Checkout, invoice, upgrade, pembatalan, refund, kredensial pembayaran, dan detail rekening tetap dilakukan melalui halaman billing member.

Nilai usage.leadsPerDay.current memakai zona waktu workspace dan hanya menghitung lead aktual yang belum dihapus. Baris visitor berstatus pageview tidak memakai kuota lead harian.

Atasi masalah koneksi MCP

Jangan mengirim API key melalui prompt, URL, atau log. Simpan key di secret manager atau konfigurasi rahasia klien agent.

Cara Menghubungkan AI Agent

Untuk menghubungkan AI Agent (seperti OpenClaw, ChatGPT, Claude, atau tool automation lainnya) ke workspace Konektor Anda:

1. Buat API Key dengan Scope Agent

Buka Settings → API Keys di dashboard workspace Anda, lalu buat API key baru dengan scope yang dibutuhkan:

Paket Starter dapat membuat key dengan scope agent.*. Scope Management API leads.* hanya dapat dipilih jika paket Anda mengaktifkan Management API.

2. Berikan SKILL.md ke AI Agent Anda

Berikan URL berikut ke AI Agent Anda:

https://konektor.id/api/v2/agent/SKILL.md

AI Agent akan membaca dokumen ini dan memahami cara berinteraksi dengan API Konektor. Setiap AI Agent yang mendukung format SKILL.md dapat langsung terhubung.

3. Konfigurasi API Key di AI Agent

Masukkan API key yang sudah dibuat ke konfigurasi AI Agent Anda. AI Agent akan menggunakan key ini untuk autentikasi setiap request:

Authorization: Bearer <api_key_anda>

Apa yang Bisa Dilakukan AI Agent?

Setelah terhubung, AI Agent Anda dapat:

• Analisa data lead — Menarik summary, funnel, dan performa campaign secara real-time
• Manage lead — Membuat lead baru, mengupdate status, melakukan scoring
• Monitor conversion — Memantau status sync conversion ke Meta, Google, TikTok
• Cek workspace — Melihat info subscription, usage, dan konfigurasi workspace
• Cek paket — Membandingkan harga, retensi, dan batas paket yang aktif
• Buat support ticket — Mengirim support ticket langsung dari AI Agent

Contoh Penggunaan

Berikut beberapa contoh perintah yang bisa Anda berikan ke AI Agent:

• "Berapa total lead baru minggu ini?"
• "Tampilkan funnel conversion bulan ini"
• "Campaign mana yang paling banyak menghasilkan lead?"
• "Update status lead CRM-1024 ke qualified"
• "Buat lead baru dari form submission ini"
• "Ada berapa conversion yang gagal sync?"
• "Buat support ticket tentang tracking pixel yang tidak jalan"
• "Berapa batas lead harian paket saya dan paket apa yang tersedia?"

Endpoint yang Tersedia

Catatan Tool Iklan

Tool iklan membaca data yang sudah tersinkron di Konektor, bukan Meta Ads Manager langsung.

• ads_campaign_set_status dan ads_campaign_set_budget membutuhkan confirm=true.
• Satu perubahan budget tidak boleh menaikkan nilai lebih dari 3x budget berjalan.
• Aksi tulis iklan dibatasi 10 kali per workspace per jam.
• Koneksi Meta harus punya izin kelola iklan. Jika kurang, response menyebut meta_scope_missing dan Anda perlu menghubungkan ulang Meta.

Catatan Query from dan to

Untuk endpoint analytics (summary, funnel, campaigns) dan conversion status:

• Jika from atau to diisi, filter custom range akan override timeframe
• Jika hanya from yang diisi, range dianggap terbuka sampai waktu sekarang
• Jika hanya to yang diisi, range dianggap terbuka dari data paling awal
• Jika from > to, API mengembalikan VALIDATION_ERROR

Rate Limit

Rate limit berbasis plan dan berlaku per workspace (shared antar semua API key):

Setiap response terautentikasi menyertakan header rate limit (termasuk saat auth-throttle):

• X-RateLimit-Limit — Maksimum request per menit
• X-RateLimit-Remaining — Sisa request di window saat ini
• X-RateLimit-Reset — Timestamp reset window (Unix seconds)

Panggilan tool MCP memakai kuota workspace yang sama. Jika kuota habis, MCP mengembalikan tool error RATE_LIMITED beserta limit, resetAt, dan retryAfter.

Format Error

Semua error menggunakan format JSON yang konsisten:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid lead data",
    "details": {
      "firstName": "Required"
    }
  }
}

Kode error yang mungkin: UNAUTHORIZED, FORBIDDEN, VALIDATION_ERROR, NOT_FOUND, RATE_LIMITED, INTERNAL_ERROR.

Keamanan

• Semua data PII (nama, email, phone) dienkripsi at-rest
• API key mendukung IP allowlist untuk membatasi akses
• Scope-based access control memastikan AI Agent hanya bisa mengakses data yang diizinkan
• Analytics endpoint hanya mengembalikan data agregat, tanpa PII

Persyaratan Plan

Agent API dan MCP tersedia untuk langganan Starter ke atas yang berstatus active atau trialing. Plan Trial, Free, kedaluwarsa, dibatalkan, atau past_due tidak dapat mengakses Agent API.

Referensi Lengkap

Untuk dokumentasi teknis lengkap (parameter, contoh request/response, dan nilai enum), baca langsung SKILL.md:

https://konektor.id/api/v2/agent/SKILL.md