Social API

The Social API provides programmatic access to the creator's connected social accounts, post scheduling queue, published content, and automation rules.

Endpoints#

Method	Path	Scope	Description
GET	/social/connections	social:read	List connected social accounts
GET	/social/insights	social:read	Get cross-platform social insights
POST	/social/posts	social:write	Schedule or publish a post
GET	/social/posts	social:read	List scheduled and published posts
GET	/social/posts/:id	social:read	Get a single post
DELETE	/social/posts/:id	social:write	Delete a scheduled post
GET	/social/automations	social:read	List automation rules
POST	/social/automations	social:write	Create an automation rule
PUT	/social/automations/:id	social:write	Update an automation rule
DELETE	/social/automations/:id	social:write	Delete an automation rule

---

GET /social/connections#

Returns all connected social media accounts.

curl https://api.nodukan.com/v1/social/connections \
  -H "Authorization: Bearer NDK_live_..."

Response#

{
  "data": [
    {
      "id": "conn_01j9x4km2v",
      "platform": "linkedin",
      "accountType": "personal",
      "displayName": "Priya Sharma",
      "profileUrl": "https://linkedin.com/in/priyasharma",
      "avatarUrl": "https://media.licdn.com/...",
      "followers": 12400,
      "isActive": true,
      "tokenExpiresAt": "2026-11-06T00:00:00Z"
    },
    {
      "id": "conn_01j9y7mp3k",
      "platform": "instagram",
      "accountType": "business",
      "displayName": "priyasharma.creates",
      "profileUrl": "https://instagram.com/priyasharma.creates",
      "followers": 28900,
      "isActive": true,
      "tokenExpiresAt": null
    }
  ],
  "requestId": "req_01j9xabc..."
}

---

GET /social/insights#

Returns aggregated social performance metrics across all connected accounts.

Query parameters#

Parameter	Type	Description
from	ISO date	Start of date range
to	ISO date	End of date range
platform	string	Filter by platform: linkedin, instagram, facebook

curl "https://api.nodukan.com/v1/social/insights?from=2026-05-01&to=2026-05-31" \
  -H "Authorization: Bearer NDK_live_..."

Response#

{
  "data": {
    "period": { "from": "2026-05-01", "to": "2026-05-31" },
    "summary": {
      "totalPosts": 14,
      "totalImpressions": 84230,
      "totalEngagements": 6710,
      "totalFollowerGrowth": 340,
      "averageEngagementRate": 0.0796
    },
    "byPlatform": {
      "linkedin": {
        "posts": 9,
        "impressions": 51000,
        "engagements": 4200,
        "followerGrowth": 180
      },
      "instagram": {
        "posts": 5,
        "impressions": 33230,
        "engagements": 2510,
        "followerGrowth": 160
      }
    },
    "topPost": {
      "id": "post_01j9x...",
      "platform": "linkedin",
      "content": "After 2 years of creator journey, here's what I wish I knew on day 1...",
      "impressions": 12400,
      "engagements": 980
    }
  },
  "requestId": "req_01j9xabc..."
}

---

POST /social/posts#

Schedules a post (or publishes immediately if scheduledAt is omitted).

Request body#

Field	Type	Required	Description
platform	string	✅	linkedin, instagram, or facebook
connectionId	string	✅	ID of the social connection to post from
content	string	✅	Post text (max 3000 chars for LinkedIn, 2200 for Instagram)
scheduledAt	ISO datetime		When to publish. Omit to publish immediately.
mediaUrls	string[]		Up to 10 image/video URLs to attach
firstComment	string		LinkedIn only: auto-post a first comment immediately after publication

curl -X POST https://api.nodukan.com/v1/social/posts \
  -H "Authorization: Bearer NDK_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "connectionId": "conn_01j9x4km2v",
    "content": "3 lessons from 1000 days as an independent creator in India 🧵\n\n1. Your niche is not your prison...",
    "scheduledAt": "2026-05-07T06:30:00+05:30",
    "firstComment": "Full blog post here 👇 https://ndk.in/1000-days"
  }'

const res = await fetch('https://api.nodukan.com/v1/social/posts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NODUKAN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    platform: 'linkedin',
    connectionId: 'conn_01j9x4km2v',
    content: '3 lessons from 1000 days as an independent creator in India 🧵',
    scheduledAt: '2026-05-07T06:30:00+05:30',
  }),
});
const { data } = await res.json();

Response 201 Created#

{
  "data": {
    "id": "post_01j9znew00",
    "platform": "linkedin",
    "connectionId": "conn_01j9x4km2v",
    "status": "scheduled",
    "content": "3 lessons from 1000 days as an independent creator in India 🧵\n\n1. ...",
    "scheduledAt": "2026-05-07T01:00:00Z",
    "publishedAt": null,
    "mediaUrls": [],
    "metrics": null,
    "createdAt": "2026-05-06T11:00:00Z"
  },
  "requestId": "req_01j9xabc..."
}

---

GET /social/posts#

Lists all posts (scheduled, published, and failed).

Query parameters#

Parameter	Description
status	Filter by scheduled, published, failed, cancelled
platform	Filter by platform
from / to	Date range on scheduledAt or publishedAt
limit / offset	Pagination

---

GET /social/posts/:id#

Returns a single post with full metrics (available once published).

curl https://api.nodukan.com/v1/social/posts/post_01j9x4km2v \
  -H "Authorization: Bearer NDK_live_..."

Response (published post)#

{
  "data": {
    "id": "post_01j9x4km2v",
    "platform": "linkedin",
    "status": "published",
    "publishedAt": "2026-05-05T01:00:00Z",
    "metrics": {
      "impressions": 8420,
      "likes": 312,
      "comments": 48,
      "shares": 29,
      "clicks": 180,
      "engagementRate": 0.0702
    }
  },
  "requestId": "req_01j9xabc..."
}

---

DELETE /social/posts/:id#

Cancels and deletes a scheduled post. Cannot delete already-published posts.

curl -X DELETE https://api.nodukan.com/v1/social/posts/post_01j9x4km2v \
  -H "Authorization: Bearer NDK_live_..."

Returns 204 No Content on success.

---

POST /social/automations#

Creates an automation rule (e.g., auto-engage with posts matching certain keywords).

Request body#

{
  "name": "Engage with creator economy content",
  "connectionId": "conn_01j9x4km2v",
  "trigger": {
    "type": "keyword",
    "keywords": ["creator economy", "indie creator", "creator monetization"],
    "excludeKeywords": ["crypto", "NFT"]
  },
  "action": {
    "type": "comment",
    "templates": [
      "Great perspective! The creator economy in India is booming 🚀",
      "Totally agree — sustainable monetization is the key.",
      "This resonates deeply. What's your take on the Indian market specifically?"
    ]
  },
  "schedule": {
    "dailyLimit": 15,
    "intervalMinutes": 60
  },
  "isActive": true
}

curl -X POST https://api.nodukan.com/v1/social/automations \
  -H "Authorization: Bearer NDK_live_..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'