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

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 \x3Capi_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)

List Leads

Query Parameters:

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": "[email protected]",
      "phone": "+6281234567890",
      "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

Path Parameters:

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": "[email protected]",
    "phone": "+6281234567890",
    "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

Request Body (JSON):

Example:

curl -X POST -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Andi","email":"[email protected]","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": "[email protected]",
    "status": "new",
    "priority": "medium",
    "source": "ads",
    "adPlatform": "meta",
    "createdAt": "2025-01-16T08:00:00.000Z",
    "updatedAt": "2025-01-16T08:00:00.000Z"
  }
}

Update Lead

Path Parameters:

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

Query Parameters:

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

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

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

Query Parameters:

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

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

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

Request Body (JSON):

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:

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

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:

Scopes Reference

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