Agent API v2 — API for AI Agents

Agent API v2 is a dedicated API namespace designed for AI Agents, LLMs, and automation tools. With Agent API, your AI Agent can access and manage lead data, pull analytics, monitor conversion tracking, and get workspace information — all through secure, structured endpoints.

What is SKILL.md?

SKILL.md is a machine-readable document that describes all capabilities of the Konektor Agent API. AI Agents read this file to understand what endpoints are available, what parameters are needed, and what response formats to expect.

Your SKILL.md URL:

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

SKILL.md is public and requires no authentication. Any AI Agent can access it directly.

Connect through MCP

Use this Streamable HTTP endpoint if your agent supports MCP:

https://mcp.konektor.id/mcp

Send the workspace API key as a Bearer token:

Authorization: Bearer <your_api_key>

MCP only lists tools permitted by the API key scopes. The key selects the workspace, so an agent cannot choose another workspace through a tool parameter.

Generic HTTP MCP client configuration:

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

After connecting, run List Tools. The connection is ready when the client shows the tools allowed by the key scopes.

Every List Tools result includes inputSchema and outputSchema. These schemas identify required fields, enum values, text lengths, numeric bounds, batch sizes, and response shapes so the agent does not need to infer a tool contract.

lead_delete requires confirm=true, the separate leads.delete scope, and a plan with Management API enabled. leads_bulk_upsert also requires Management API. Deletion is a soft-delete instead of a history purge. Do not grant write, delete, or bulk scopes when the agent only needs read access.

MCP billing access is read-only. An agent can read active plans, prices, retention, and limits through billing_plans, and read the workspace plan and daily lead usage through workspace_get. Checkout, invoices, upgrades, cancellations, refunds, payment credentials, and bank details remain in the member billing page.

usage.leadsPerDay.current uses the workspace timezone and counts only actual, non-deleted leads. Visitor rows with the pageview status do not consume the daily lead quota.

Troubleshoot an MCP connection

Never send an API key in a prompt, URL, or log. Store it in the agent client's secret manager or protected configuration.

How to Connect Your AI Agent

To connect an AI Agent (such as OpenClaw, ChatGPT, Claude, or other automation tools) to your Konektor workspace:

1. Create an API Key with Agent Scopes

Go to Settings → API Keys in your workspace dashboard and create a new API key with the required scopes:

Starter plans can create keys with agent.* scopes. Management API leads.* scopes are available only when your plan enables Management API.

2. Give SKILL.md to Your AI Agent

Provide the following URL to your AI Agent:

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

Your AI Agent will read this document and understand how to interact with the Konektor API. Any AI Agent that supports the SKILL.md format can connect immediately.

3. Configure the API Key

Enter the API key you created into your AI Agent's configuration. The agent will use this key to authenticate every request:

Authorization: Bearer <your_api_key>

What Can Your AI Agent Do?

Once connected, your AI Agent can:

• Analyze lead data — Pull summaries, funnels, and campaign performance in real-time
• Manage leads — Create new leads, update status, perform scoring
• Monitor conversions — Track conversion sync status to Meta, Google, TikTok
• Check workspace — View subscription info, usage, and workspace configuration
• Check plans — Compare active plan prices, retention, and limits
• Create support tickets — Submit support tickets directly from the AI Agent

Example Commands

Here are some example prompts you can give your AI Agent:

• "How many new leads this week?"
• "Show me the conversion funnel for this month"
• "Which campaign generated the most leads?"
• "Update lead CRM-1024 status to qualified"
• "Create a new lead from this form submission"
• "How many conversions failed to sync?"
• "Create a support ticket about our tracking pixel not firing"
• "What is my daily lead limit and which plans are available?"

Available Endpoints

from and to Query Notes

For analytics endpoints (summary, funnel, campaigns) and conversion status:

• If from or to is provided, custom range filtering overrides timeframe
• If only from is provided, range is open-ended up to current time
• If only to is provided, range is open-ended from earliest data
• If from > to, API returns VALIDATION_ERROR

Rate Limits

Rate limits are plan-based and apply per workspace (shared across all API keys):

Every authenticated response includes rate limit headers (including auth-throttle responses):

• X-RateLimit-Limit — Maximum requests per minute
• X-RateLimit-Remaining — Remaining requests in current window
• X-RateLimit-Reset — Window reset timestamp (Unix seconds)

MCP tool calls use the same workspace quota. When the quota is exhausted, MCP returns a RATE_LIMITED tool error with limit, resetAt, and retryAfter details.

Error Format

All errors use a consistent JSON format:

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

Possible error codes: UNAUTHORIZED, FORBIDDEN, VALIDATION_ERROR, NOT_FOUND, RATE_LIMITED, INTERNAL_ERROR.

Security

• All PII data (name, email, phone) is encrypted at rest
• API keys support IP allowlists to restrict access
• Scope-based access control ensures AI Agents can only access permitted data
• Analytics endpoints return aggregate data only, no PII

Plan Requirements

Agent API and MCP are available for Starter subscriptions and above with active or trialing status. Trial, Free, expired, cancelled, and past_due subscriptions cannot access Agent API.

Full Reference

For complete technical documentation (parameters, request/response examples, and enum values), read SKILL.md directly:

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