Public API v1

Authentication

Create a key under /app/settings/api-keys. Send it as x-api-key or Authorization: Bearer kmn_.... Write routes require the public_api_write feature flag (on by default) plus campaigns:write scope.

curl https://your-app/api/v1/campaigns \
  -H "Authorization: Bearer kmn_..."

Scopes

• campaigns:read / campaigns:write
• accounts:read
• listeners:read / listeners:write (listeners also accept campaigns:read/write)
• leads:read / leads:write
• activity:read
• analytics:read
• competitors:read
• templates:read

GET /api/v1/campaigns

List campaigns for the API key workspace.

POST /api/v1/campaigns

Create a campaign. Optional listenerQuery creates a keyword listener. Optional socialAccountIds must belong to the workspace.

{
  "name": "IG keyword pilot",
  "platform": "instagram",
  "mode": "approval_required",
  "goal": "Helpful product replies",
  "listenerQuery": "social ops automation",
  "clientId": "optional_client_profile_id",
  "dailyLimit": 30
}

GET/POST /api/v1/listeners

List or create keyword/competitor/trend listeners. POST requires campaigns:write.

{
  "platform": "instagram",
  "type": "keyword",
  "query": "ai agent",
  "campaignId": "optional_campaign_id"
}

GET/POST /api/v1/leads

List or create engagement leads. Query params for GET: status, clientId, q. Requires lead_capture feature flag. POST uses leads:write and fires outbound lead.captured with structured CRM fields on generic webhooks.

{
  "handle": "prospect_ig",
  "platform": "instagram",
  "intent": "Asked for pricing",
  "contactEmail": "ops@brand.com",
  "clientId": "optional_client_id",
  "source": "api"
}

Other read endpoints

• GET /api/v1/accounts
• GET /api/v1/activity
• GET /api/v1/analytics

Outbound workspace webhooks

Configure Slack/Discord/generic endpoints under Settings → Webhooks. Events include approval.new, lead.captured (extra: handle/email/client/campaign/status), account.degraded, account.reauth_required, account.proxy_rotated, comment.failed, usage.warning.