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

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.

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

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:

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
• 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"

Endpoint yang Tersedia

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)

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 tersedia untuk plan Starter ke atas. Plan Trial dan Free 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