Konektor - CAPI & Lead Management

Access and manage marketing leads, update lead details, and retrieve analytics for lead performance and conversion tracking via Konektor API.

Security Scan

The skill's documentation describes a normal lead-management API and requires a KONEKTOR_API_KEY, but the registry metadata claims no credentials or env vars are required — this mismatch is a material inconsistency that warrants caution.

Purpose & Capability

The SKILL.md describes a Konektor lead-management API (listing leads, creating leads, analytics) that legitimately requires an API key. However, the registry metadata for the skill declares no required environment variables or primary credential. That discrepancy (documentation requiring KONEKTOR_API_KEY vs metadata claiming none) is unexpected and incoherent.

Instruction Scope

The runtime instructions in SKILL.md are scoped to HTTP API calls to https://konektor.id and require a Bearer token and specific scopes. The document does not instruct reading unrelated system files or secrets beyond the KONEKTOR_API_KEY. The main issue is SKILL.md itself expects an env var that the registry did not declare.

Install Mechanism

This is an instruction-only skill with no install spec and no code files — it does not write files or download packages, which is lower-risk from an install perspective.

Credentials

Requesting a KONEKTOR_API_KEY (scoped bearer token) is proportionate to a lead-management integration. The problem is the metadata omission: the skill claims to require no env vars while the documentation requires a secret. This mismatch could be an honest metadata error but also makes it unclear what credentials the skill will ask the agent to provide at runtime.

Persistence & Privilege

The skill is not always-enabled and uses default autonomous invocation settings. There is no indication it requests persistent system-wide changes or other skills' credentials.

What to consider before installing

Do not provide any real or high-privilege API keys to this skill until the metadata mismatch is resolved. Ask the publisher (or registry) to: 1) update the registry metadata to declare KONEKTOR_API_KEY as a required env var and specify the primaryEnv and exact minimal scopes; 2) provide a homepage or contact to verify authenticity. If you must test it, create a limited-scope, revocable API key (least privilege), use a test workspace or sandbox account, and run the agent in an isolated environment while monitoring outbound network traffic to verify it only contacts https://konektor.id. Revoke the test key immediately if behavior is unexpected. If the publisher cannot verify identity or fix the metadata, treat the skill as untrusted.

Konektor Agent API

Version: 2.2.0 Last updated: 2026-03-11

Machine-readable API documentation for AI agents, LLMs, and automation tools.

Base URL: https://konektor.id

Documentation: https://konektor.id/docs/api/agent-api

Requirements

Key	Value
Authentication	Bearer token (API key)
Environment Variable	KONEKTOR_API_KEY
Minimum Scopes	Depends on endpoint (see Scopes Reference)
Base URL	https://konektor.id
Transport	HTTPS only
Content-Type	application/json

To use this API, set the KONEKTOR_API_KEY environment variable with a valid API key. Keys are created in the Konektor dashboard under Workspace Settings → API Keys. Each key must be assigned the minimum scopes required for the intended operations.

Authentication

All endpoints (except SKILL.md) require a Bearer token:

Authorization: Bearer <api_key>

API keys are scoped. Available scopes: agent.leads.read, agent.leads.write, agent.analytics.read, agent.conversions.read, agent.workspace.read, agent.support.write

Each endpoint requires a specific scope — requests without the required scope receive HTTP 403.

Endpoints

SKILL.md (this document)

Method	GET
Path	/api/v2/agent/SKILL.md
Auth	None (public)
Scope	—

---

List Leads

Method	GET
Path	/api/v2/agent/leads
Scope	agent.leads.read

Query Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number (min: 1)
limit	integer	No	Items per page (1–100, default: 50)
cursor	string	No	Cursor for cursor-based pagination
status	string	No	Filter by status: pageview, new, contacted, responded, qualified, hot, proposal, negotiation, invoice, won, lost
priority	string	No	Filter by priority: low, medium, high, urgent
source	string	No	Filter by source: website, whatsapp, phone, email, referral, social, ads, event, other
adPlatform	string	No	Filter by ad platform: meta, google, tiktok, linkedin, posthog, other
assignedTo	string (UUID)	No	Filter by assigned team member
createdFrom	string (ISO 8601)	No	Filter leads created after this date
createdTo	string (ISO 8601)	No	Filter leads created before this date
search	string	No	Search by name, email, phone, uniqueCode, or externalRef (max 200 chars)
sortBy	string	No	Sort field: createdAt, updatedAt (default: createdAt)
sortOrder	string	No	Sort order: asc, desc (default: desc)

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://konektor.id/api/v2/agent/leads?status=new&limit=10"

{
  "success": true,
  "data": [
    {
      "id": "lead_abc123",
      "uniqueCode": "KNK-001",
      "firstName": "Budi",
      "lastName": "Santoso",
      "email": "[e-mail]",
      "phone": "[phone]",
      "status": "new",
      "priority": "medium",
      "source": "ads",
      "adPlatform": "meta",
      "assignedTo": null,
      "estimatedValue": 5000000,
      "actualValue": null,
      "notes": null,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5,
    "nextCursor": "eyJpZCI6ImxlYWRfYWJjMTIzIn0"
  }
}

---

Get Lead

Method	GET
Path	/api/v2/agent/leads/:id
Scope	agent.leads.read

Path Parameters:

Parameter	Type	Description
id	string	Lead ID

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://konektor.id/api/v2/agent/leads/lead_abc123"

{
  "success": true,
  "data": {
    "id": "lead_abc123",
    "uniqueCode": "KNK-001",
    "firstName": "Budi",
    "lastName": "Santoso",
    "email": "[e-mail]",
    "phone": "[phone]",
    "status": "new",
    "priority": "medium",
    "source": "ads",
    "adPlatform": "meta",
    "assignedTo": null,
    "estimatedValue": 5000000,
    "actualValue": null,
    "notes": null,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

---

Create Lead

Method	POST
Path	/api/v2/agent/leads
Scope	agent.leads.write

Request Body (JSON):

Field	Type	Required	Description
firstName	string	Yes	First name (1–100 chars)
lastName	string	No	Last name (max 100 chars)
email	string	No	Email address
phone	string	No	Phone number (max 20 chars)
status	string	No	Lead status (default: new)
priority	string	No	Priority: low, medium, high, urgent
source	string	No	Source: website, whatsapp, phone, email, referral, social, ads, event, other
adPlatform	string	No	Ad platform: meta, google, tiktok, linkedin, posthog, other
notes	string	No	Notes (max 5000 chars)
uniqueCode	string	No	Custom unique code (max 100 chars)
externalRef	string	No	External reference ID (max 150 chars)
assignedTo	string (UUID)	No	Assign to team member
estimatedValue	number	No	Estimated deal value
actualValue	number	No	Actual deal value

Example:

curl -X POST -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Andi","email":"[e-mail]","status":"new","source":"ads","adPlatform":"meta"}' \
  "https://konektor.id/api/v2/agent/leads"

{
  "success": true,
  "data": {
    "id": "lead_xyz789",
    "uniqueCode": "KNK-002",
    "firstName": "Andi",
    "email": "[e-mail]",
    "status": "new",
    "priority": "medium",
    "source": "ads",
    "adPlatform": "meta",
    "createdAt": "2025-01-16T08:00:00.000Z",
    "updatedAt": "2025-01-16T08:00:00.000Z"
  }
}

---

Update Lead

Method	PATCH
Path	/api/v2/agent/leads/:id
Scope	agent.leads.write

Path Parameters:

Parameter	Type	Description
id	string	Lead ID

Request Body (JSON): Same fields as Create Lead, all optional.

Example:

curl -X PATCH -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"contacted","notes":"Called via WhatsApp"}' \
  "https://konektor.id/api/v2/agent/leads/lead_xyz789"

{
  "success": true,
  "data": {
    "id": "lead_xyz789",
    "uniqueCode": "KNK-002",
    "firstName": "Andi",
    "status": "contacted",
    "notes": "Called via WhatsApp",
    "updatedAt": "2025-01-16T09:15:00.000Z"
  }
}

---

Analytics Summary

Method	GET
Path	/api/v2/agent/analytics/summary
Scope	agent.analytics.read

Query Parameters:

Parameter	Type	Required	Description
timeframe	string	No	Preset timeframe: today, last_7_days, last_30_days, current_week, current_month, all_time (default: last_30_days)
from	string (ISO 8601)	No	Custom start date (overrides timeframe)
to	string (ISO 8601)	No	Custom end date (overrides timeframe)

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://konektor.id/api/v2/agent/analytics/summary?timeframe=last_7_days"

{
  "success": true,
  "data": {
    "totalLeads": 156,
    "newLeads": 42,
    "contactedLeads": 38,
    "totalConversions": 12,
    "totalConversionValue": 45000000,
    "timeframe": "last_7_days",
    "period": {
      "from": "2025-01-09T00:00:00.000Z",
      "to": "2025-01-16T00:00:00.000Z"
    }
  }
}

---

Analytics Funnel

Method	GET
Path	/api/v2/agent/analytics/funnel
Scope	agent.analytics.read

Query Parameters: Same as Analytics Summary.

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://konektor.id/api/v2/agent/analytics/funnel?timeframe=current_month"

{
  "success": true,
  "data": [
    { "status": "new", "count": 42, "percentage": 26.92 },
    { "status": "contacted", "count": 38, "percentage": 24.36 },
    { "status": "qualified", "count": 25, "percentage": 16.03 },
    { "status": "proposal", "count": 20, "percentage": 12.82 },
    { "status": "won", "count": 12, "percentage": 7.69 },
    { "status": "lost", "count": 19, "percentage": 12.18 }
  ]
}

---

Campaign Performance

Method	GET
Path	/api/v2/agent/analytics/campaigns
Scope	agent.analytics.read

Query Parameters: Same as Analytics Summary.

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://konektor.id/api/v2/agent/analytics/campaigns?timeframe=last_30_days"

{
  "success": true,
  "data": [
    {
      "campaignName": "Promo Januari",
      "adPlatform": "meta",
      "leads": 85,
      "conversions": 8,
      "conversionValue": 32000000
    },
    {
      "campaignName": "Brand Awareness",
      "adPlatform": "google",
      "leads": 45,
      "conversions": 3,
      "conversionValue": 12000000
    }
  ]
}

---

Conversion Sync Status

Method	GET
Path	/api/v2/agent/conversions/status
Scope	agent.conversions.read

Query Parameters:

Parameter	Type	Required	Description
timeframe	string	No	Preset timeframe: today, last_7_days, last_30_days, current_week, current_month, all_time (default: last_30_days)
from	string (ISO 8601)	No	Custom start date
to	string (ISO 8601)	No	Custom end date
platform	string	No	Filter by ad platform: meta, google, tiktok, linkedin, posthog, other

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://konektor.id/api/v2/agent/conversions/status?timeframe=last_7_days"

{
  "success": true,
  "data": {
    "pending": 5,
    "synced": 42,
    "partial": 2,
    "failed": 1,
    "none": 106
  }
}

---

Pending Conversions

Method	GET
Path	/api/v2/agent/conversions/pending
Scope	agent.conversions.read

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://konektor.id/api/v2/agent/conversions/pending"

{
  "success": true,
  "data": [
    {
      "leadId": "lead_abc123",
      "uniqueCode": "KNK-001",
      "status": "won",
      "adPlatform": "meta",
      "conversionSyncStatus": "pending",
      "lastConversionSyncAt": null
    },
    {
      "leadId": "lead_def456",
      "uniqueCode": "KNK-005",
      "status": "won",
      "adPlatform": "google",
      "conversionSyncStatus": "failed",
      "lastConversionSyncAt": "2025-01-15T12:00:00.000Z"
    }
  ]
}

---

Workspace Info

Method	GET
Path	/api/v2/agent/workspace
Scope	agent.workspace.read

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://konektor.id/api/v2/agent/workspace"

{
  "success": true,
  "data": {
    "displayName": "Toko Budi Online",
    "timezone": "Asia/Jakarta",
    "currency": "IDR",
    "language": "id",
    "dateFormat": "DD/MM/YYYY",
    "trackingCode": "KNK-abc123",
    "subscription": {
      "plan": "pro",
      "status": "active",
      "interval": "monthly",
      "currentPeriodEnd": "2025-02-15T00:00:00.000Z"
    },
    "usage": {
      "leadsPerDay": { "limit": 500, "current": 23 },
      "teamMembers": 5,
      "activeRotators": 2
    }
  }
}

---

Create Support Ticket

Method	POST
Path	/api/v2/agent/support/tickets
Scope	agent.support.write

Request Body (JSON):

Field	Type	Required	Description
subject	string	Yes	Ticket subject (3–180 chars)
message	string	Yes	Ticket body (1–10000 chars)
priority	string	No	Priority: ${ticketPriorities} (default: normal)

Example:

curl -X POST -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Tracking pixel not firing","message":"Our Meta pixel events stopped syncing since yesterday. Workspace ID: ws_abc123.","priority":"high"}' \
  "https://konektor.id/api/v2/agent/support/tickets"

{
  "success": true,
  "data": {
    "ticketId": "t_abc123",
    "ticketRef": "A1B2C-3D4E",
    "subject": "Tracking pixel not firing",
    "status": "new",
    "priority": "high",
    "createdAt": "2026-03-10T08:00:00.000Z"
  }
}

Ticket Statuses: ${ticketStatuses}

Ticket Priorities: ${ticketPriorities}

Rate Limits

Rate limits are per workspace (shared across all API keys) and vary by plan:

Plan	Limit
starter	60 req/min
pro	200 req/min
enterprise	600 req/min
custom	200 req/min

Rate limit headers are included in every response:

• X-RateLimit-Limit: Maximum requests per minute
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Unix timestamp when the window resets

When rate limited, the response includes a Retry-After header (seconds).

Error Handling

All errors follow a consistent JSON format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": null
  }
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing, invalid, expired, or revoked API key
FORBIDDEN	403	Insufficient scope or plan does not support Agent API
VALIDATION_ERROR	400	Invalid request parameters (details contains field-level errors)
NOT_FOUND	404	Resource not found or soft-deleted
RATE_LIMITED	429	Rate limit exceeded
INTERNAL_ERROR	500	Unexpected server error

Validation Error Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "firstName": "Required",
      "email": "Invalid email"
    }
  }
}

Response Headers

Every response (except SKILL.md) includes:

Header	Description
X-Request-Id	Unique request ID (UUID) for debugging
X-RateLimit-Limit	Max requests per minute
X-RateLimit-Remaining	Remaining requests
X-RateLimit-Reset	Window reset timestamp (Unix seconds)

Scopes Reference

Scope	Description
agent.leads.read	Read leads (list, get)
agent.leads.write	Create and update leads
agent.analytics.read	Read analytics (summary, funnel, campaigns)
agent.conversions.read	Read conversion sync status and pending conversions
agent.workspace.read	Read workspace info and subscription
agent.support.write	Create support tickets

Values Reference

Lead Statuses: pageview, new, contacted, responded, qualified, hot, proposal, negotiation, invoice, won, lost

Lead Priorities: low, medium, high, urgent

Lead Sources: website, whatsapp, phone, email, referral, social, ads, event, other

Ad Platforms: meta, google, tiktok, linkedin, posthog, other

Timeframes: today, last_7_days, last_30_days, current_week, current_month, all_time

Error Codes: UNAUTHORIZED, FORBIDDEN, VALIDATION_ERROR, NOT_FOUND, RATE_LIMITED, INTERNAL_ERROR