Developer

Code Examples

Ready-to-use examples for the Social Neuron REST API. Every tool is called via POST /v1/tools/{tool_name} with your API key in the x-api-key header.

Generate your API key at socialneuron.com/settings/developer. Keys start with snk_ and are tied to your plan's scopes.

cURL

Generate Content

curl -X POST https://api.socialneuron.com/v1/tools/generate_content \
  -H "Content-Type: application/json" \
  -H "x-api-key: snk_your_api_key" \
  -d '{
    "prompt": "Write a LinkedIn post about the benefits of AI in marketing",
    "platform": "linkedin",
    "tone": "professional"
  }'

bash

Response:

{
  "ok": true,
  "result": {
    "content": "The marketing teams winning today aren't working harder -- they're working smarter with AI.\n\nHere's what I've seen change in the last 12 months:\n\n1. Content creation time dropped by 60%\n2. Engagement rates up 2.3x with personalized messaging\n3. A/B testing cycles shortened from weeks to hours\n\nThe shift isn't about replacing creativity. It's about removing the bottlenecks that keep good ideas from reaching the right audience.\n\n#AIMarketing #ContentStrategy #MarTech",
    "platform": "linkedin",
    "creditsUsed": 2
  }
}

json

Schedule a Post

curl -X POST https://api.socialneuron.com/v1/tools/schedule_post \
  -H "Content-Type: application/json" \
  -H "x-api-key: snk_your_api_key" \
  -d '{
    "platforms": ["instagram", "tiktok"],
    "caption": "Behind the scenes of our new product launch",
    "mediaUrl": "https://yourstorage.com/video.mp4",
    "scheduledFor": "2026-04-15T14:00:00Z"
  }'

bash

Response:

{
  "ok": true,
  "result": {
    "postIds": ["post_8f3a2b1c", "post_9d4e5f6a"],
    "scheduledFor": "2026-04-15T14:00:00Z",
    "platforms": ["instagram", "tiktok"],
    "status": "scheduled"
  }
}

json

Check Credit Balance

curl -X POST https://api.socialneuron.com/v1/tools/get_credit_balance \
  -H "Content-Type: application/json" \
  -H "x-api-key: snk_your_api_key" \
  -d '{}'

bash

Response:

{
  "ok": true,
  "result": {
    "creditsRemaining": 1420,
    "monthlyAllocation": 2000,
    "spendingCap": 5000,
    "plan": "pro",
    "resetsAt": "2026-05-01T00:00:00Z"
  }
}

json

Fetch Analytics

curl -X POST https://api.socialneuron.com/v1/tools/fetch_analytics \
  -H "Content-Type: application/json" \
  -H "x-api-key: snk_your_api_key" \
  -d '{
    "platform": "instagram",
    "timeframe": "7d"
  }'

bash

Response:

{
  "ok": true,
  "result": {
    "platform": "instagram",
    "timeframe": "7d",
    "summary": {
      "totalPosts": 12,
      "totalImpressions": 48200,
      "totalEngagements": 3150,
      "engagementRate": 6.53,
      "followerChange": 340
    },
    "topPost": {
      "caption": "Behind the scenes of our new product launch",
      "impressions": 12400,
      "engagements": 890
    }
  }
}

json

JavaScript (Node.js)

All examples use the built-in fetch() API -- no external dependencies required.

Generate Content

const response = await fetch(
  "https://api.socialneuron.com/v1/tools/generate_content",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "snk_your_api_key",
    },
    body: JSON.stringify({
      prompt: "Write a Twitter thread about remote work productivity tips",
      platform: "twitter",
      tone: "conversational",
    }),
  }
);

const data = await response.json();
console.log(data.result.content);

javascript

Response:

{
  "ok": true,
  "result": {
    "content": "Remote work changed how we think about productivity. Here are 5 things that actually moved the needle for our team:\n\n1/ Block your calendar ruthlessly. If it's not on the calendar, it doesn't exist.\n\n2/ Async by default. Not every question needs a meeting.\n\n3/ Document decisions, not just discussions.\n\n4/ Take real breaks. Walking away from the screen is not slacking.\n\n5/ End each day with a 2-minute brain dump. Tomorrow-you will thank you.",
    "platform": "twitter",
    "creditsUsed": 2
  }
}

json

Schedule a Post

const response = await fetch(
  "https://api.socialneuron.com/v1/tools/schedule_post",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "snk_your_api_key",
    },
    body: JSON.stringify({
      platforms: ["linkedin", "twitter"],
      caption: "Excited to announce our Series A funding!",
      mediaUrl: "https://yourstorage.com/announcement.png",
      scheduledFor: "2026-04-20T09:00:00Z",
    }),
  }
);

const data = await response.json();
console.log(`Scheduled ${data.result.postIds.length} posts`);

javascript

Response:

{
  "ok": true,
  "result": {
    "postIds": ["post_a1b2c3d4", "post_e5f6g7h8"],
    "scheduledFor": "2026-04-20T09:00:00Z",
    "platforms": ["linkedin", "twitter"],
    "status": "scheduled"
  }
}

json

Check Credit Balance

const response = await fetch(
  "https://api.socialneuron.com/v1/tools/get_credit_balance",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "snk_your_api_key",
    },
    body: JSON.stringify({}),
  }
);

const { result } = await response.json();
console.log(`${result.creditsRemaining} / ${result.monthlyAllocation} credits remaining`);

javascript

Fetch Analytics

const response = await fetch(
  "https://api.socialneuron.com/v1/tools/fetch_analytics",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "snk_your_api_key",
    },
    body: JSON.stringify({
      platform: "tiktok",
      timeframe: "30d",
    }),
  }
);

const { result } = await response.json();
console.log(`Engagement rate: ${result.summary.engagementRate}%`);

javascript

Response:

{
  "ok": true,
  "result": {
    "platform": "tiktok",
    "timeframe": "30d",
    "summary": {
      "totalPosts": 28,
      "totalImpressions": 215000,
      "totalEngagements": 18400,
      "engagementRate": 8.56,
      "followerChange": 1280
    },
    "topPost": {
      "caption": "Day in the life running a SaaS startup",
      "impressions": 42000,
      "engagements": 5100
    }
  }
}

json

Python

All examples use the requests library. Install it with pip install requests.

Generate Content

import requests

response = requests.post(
    "https://api.socialneuron.com/v1/tools/generate_content",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "snk_your_api_key",
    },
    json={
        "prompt": "Write an Instagram caption for a coffee brand product photo",
        "platform": "instagram",
        "tone": "playful",
    },
)

data = response.json()
print(data["result"]["content"])

python

Response:

{
  "ok": true,
  "result": {
    "content": "Your morning called. It wants an upgrade.\n\nOur new single-origin blend from Colombia hits different -- smooth, bright, and just enough sweetness to make you forget you're awake at 6 AM.\n\nAvailable now. Your taste buds can thank us later.\n\n#CoffeeLovers #SingleOrigin #MorningRitual #NewBlend",
    "platform": "instagram",
    "creditsUsed": 2
  }
}

json

Schedule a Post

import requests

response = requests.post(
    "https://api.socialneuron.com/v1/tools/schedule_post",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "snk_your_api_key",
    },
    json={
        "platforms": ["instagram", "facebook"],
        "caption": "New collection dropping this Friday. Set your alarms.",
        "mediaUrl": "https://yourstorage.com/teaser.mp4",
        "scheduledFor": "2026-04-18T18:00:00Z",
    },
)

data = response.json()
for post_id in data["result"]["postIds"]:
    print(f"Scheduled: {post_id}")

python

Check Credit Balance

import requests

response = requests.post(
    "https://api.socialneuron.com/v1/tools/get_credit_balance",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "snk_your_api_key",
    },
    json={},
)

result = response.json()["result"]
print(f"{result['creditsRemaining']} credits remaining (resets {result['resetsAt']})")

python

Fetch Analytics

import requests

response = requests.post(
    "https://api.socialneuron.com/v1/tools/fetch_analytics",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "snk_your_api_key",
    },
    json={
        "platform": "youtube",
        "timeframe": "30d",
    },
)

result = response.json()["result"]
summary = result["summary"]
print(f"Posts: {summary['totalPosts']}")
print(f"Impressions: {summary['totalImpressions']:,}")
print(f"Engagement rate: {summary['engagementRate']}%")

python

Response:

{
  "ok": true,
  "result": {
    "platform": "youtube",
    "timeframe": "30d",
    "summary": {
      "totalPosts": 8,
      "totalImpressions": 94500,
      "totalEngagements": 7200,
      "engagementRate": 7.62,
      "followerChange": 520
    },
    "topPost": {
      "caption": "How we grew from 0 to 10K subscribers in 90 days",
      "impressions": 31000,
      "engagements": 2800
    }
  }
}

json

Error Handling

All error responses follow a consistent format:

{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "This operation requires 5 credits but you have 2 remaining."
  }
}

json

Common error codes:

Code	HTTP Status	Meaning
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Your plan does not include this scope
`RATE_LIMITED`	429	Too many requests -- check `X-RateLimit-Reset` header
`INSUFFICIENT_CREDITS`	402	Not enough credits for this operation
`VALIDATION_ERROR`	400	Missing or invalid parameters

Always check response.ok or the ok field in the JSON body before using the result. Network errors, expired keys, and insufficient credits can all cause failures.

Ready to try this? Sign up free and get 100 credits to start.

CLI Reference MCP Quickstart

Developer

Code Examples

Ready-to-use examples for the Social Neuron REST API. Every tool is called via POST /v1/tools/{tool_name} with your API key in the x-api-key header.

Generate your API key at socialneuron.com/settings/developer. Keys start with snk_ and are tied to your plan's scopes.

cURL

Generate Content

curl -X POST https://api.socialneuron.com/v1/tools/generate_content \
  -H "Content-Type: application/json" \
  -H "x-api-key: snk_your_api_key" \
  -d '{
    "prompt": "Write a LinkedIn post about the benefits of AI in marketing",
    "platform": "linkedin",
    "tone": "professional"
  }'

bash

Response:

{
  "ok": true,
  "result": {
    "content": "The marketing teams winning today aren't working harder -- they're working smarter with AI.\n\nHere's what I've seen change in the last 12 months:\n\n1. Content creation time dropped by 60%\n2. Engagement rates up 2.3x with personalized messaging\n3. A/B testing cycles shortened from weeks to hours\n\nThe shift isn't about replacing creativity. It's about removing the bottlenecks that keep good ideas from reaching the right audience.\n\n#AIMarketing #ContentStrategy #MarTech",
    "platform": "linkedin",
    "creditsUsed": 2
  }
}

json

Schedule a Post

curl -X POST https://api.socialneuron.com/v1/tools/schedule_post \
  -H "Content-Type: application/json" \
  -H "x-api-key: snk_your_api_key" \
  -d '{
    "platforms": ["instagram", "tiktok"],
    "caption": "Behind the scenes of our new product launch",
    "mediaUrl": "https://yourstorage.com/video.mp4",
    "scheduledFor": "2026-04-15T14:00:00Z"
  }'

bash

Response:

{
  "ok": true,
  "result": {
    "postIds": ["post_8f3a2b1c", "post_9d4e5f6a"],
    "scheduledFor": "2026-04-15T14:00:00Z",
    "platforms": ["instagram", "tiktok"],
    "status": "scheduled"
  }
}

json

Check Credit Balance

curl -X POST https://api.socialneuron.com/v1/tools/get_credit_balance \
  -H "Content-Type: application/json" \
  -H "x-api-key: snk_your_api_key" \
  -d '{}'

bash

Response:

{
  "ok": true,
  "result": {
    "creditsRemaining": 1420,
    "monthlyAllocation": 2000,
    "spendingCap": 5000,
    "plan": "pro",
    "resetsAt": "2026-05-01T00:00:00Z"
  }
}

json

Fetch Analytics

curl -X POST https://api.socialneuron.com/v1/tools/fetch_analytics \
  -H "Content-Type: application/json" \
  -H "x-api-key: snk_your_api_key" \
  -d '{
    "platform": "instagram",
    "timeframe": "7d"
  }'

bash

Response:

{
  "ok": true,
  "result": {
    "platform": "instagram",
    "timeframe": "7d",
    "summary": {
      "totalPosts": 12,
      "totalImpressions": 48200,
      "totalEngagements": 3150,
      "engagementRate": 6.53,
      "followerChange": 340
    },
    "topPost": {
      "caption": "Behind the scenes of our new product launch",
      "impressions": 12400,
      "engagements": 890
    }
  }
}

json

JavaScript (Node.js)

All examples use the built-in fetch() API -- no external dependencies required.

Generate Content

const response = await fetch(
  "https://api.socialneuron.com/v1/tools/generate_content",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "snk_your_api_key",
    },
    body: JSON.stringify({
      prompt: "Write a Twitter thread about remote work productivity tips",
      platform: "twitter",
      tone: "conversational",
    }),
  }
);

const data = await response.json();
console.log(data.result.content);

javascript

Response:

{
  "ok": true,
  "result": {
    "content": "Remote work changed how we think about productivity. Here are 5 things that actually moved the needle for our team:\n\n1/ Block your calendar ruthlessly. If it's not on the calendar, it doesn't exist.\n\n2/ Async by default. Not every question needs a meeting.\n\n3/ Document decisions, not just discussions.\n\n4/ Take real breaks. Walking away from the screen is not slacking.\n\n5/ End each day with a 2-minute brain dump. Tomorrow-you will thank you.",
    "platform": "twitter",
    "creditsUsed": 2
  }
}

json

Schedule a Post

const response = await fetch(
  "https://api.socialneuron.com/v1/tools/schedule_post",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "snk_your_api_key",
    },
    body: JSON.stringify({
      platforms: ["linkedin", "twitter"],
      caption: "Excited to announce our Series A funding!",
      mediaUrl: "https://yourstorage.com/announcement.png",
      scheduledFor: "2026-04-20T09:00:00Z",
    }),
  }
);

const data = await response.json();
console.log(`Scheduled ${data.result.postIds.length} posts`);

javascript

Response:

{
  "ok": true,
  "result": {
    "postIds": ["post_a1b2c3d4", "post_e5f6g7h8"],
    "scheduledFor": "2026-04-20T09:00:00Z",
    "platforms": ["linkedin", "twitter"],
    "status": "scheduled"
  }
}

json

Check Credit Balance

const response = await fetch(
  "https://api.socialneuron.com/v1/tools/get_credit_balance",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "snk_your_api_key",
    },
    body: JSON.stringify({}),
  }
);

const { result } = await response.json();
console.log(`${result.creditsRemaining} / ${result.monthlyAllocation} credits remaining`);

javascript

Fetch Analytics

const response = await fetch(
  "https://api.socialneuron.com/v1/tools/fetch_analytics",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "snk_your_api_key",
    },
    body: JSON.stringify({
      platform: "tiktok",
      timeframe: "30d",
    }),
  }
);

const { result } = await response.json();
console.log(`Engagement rate: ${result.summary.engagementRate}%`);

javascript

Response:

{
  "ok": true,
  "result": {
    "platform": "tiktok",
    "timeframe": "30d",
    "summary": {
      "totalPosts": 28,
      "totalImpressions": 215000,
      "totalEngagements": 18400,
      "engagementRate": 8.56,
      "followerChange": 1280
    },
    "topPost": {
      "caption": "Day in the life running a SaaS startup",
      "impressions": 42000,
      "engagements": 5100
    }
  }
}

json

Python

All examples use the requests library. Install it with pip install requests.

Generate Content

import requests

response = requests.post(
    "https://api.socialneuron.com/v1/tools/generate_content",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "snk_your_api_key",
    },
    json={
        "prompt": "Write an Instagram caption for a coffee brand product photo",
        "platform": "instagram",
        "tone": "playful",
    },
)

data = response.json()
print(data["result"]["content"])

python

Response:

{
  "ok": true,
  "result": {
    "content": "Your morning called. It wants an upgrade.\n\nOur new single-origin blend from Colombia hits different -- smooth, bright, and just enough sweetness to make you forget you're awake at 6 AM.\n\nAvailable now. Your taste buds can thank us later.\n\n#CoffeeLovers #SingleOrigin #MorningRitual #NewBlend",
    "platform": "instagram",
    "creditsUsed": 2
  }
}

json

Schedule a Post

import requests

response = requests.post(
    "https://api.socialneuron.com/v1/tools/schedule_post",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "snk_your_api_key",
    },
    json={
        "platforms": ["instagram", "facebook"],
        "caption": "New collection dropping this Friday. Set your alarms.",
        "mediaUrl": "https://yourstorage.com/teaser.mp4",
        "scheduledFor": "2026-04-18T18:00:00Z",
    },
)

data = response.json()
for post_id in data["result"]["postIds"]:
    print(f"Scheduled: {post_id}")

python

Check Credit Balance

import requests

response = requests.post(
    "https://api.socialneuron.com/v1/tools/get_credit_balance",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "snk_your_api_key",
    },
    json={},
)

result = response.json()["result"]
print(f"{result['creditsRemaining']} credits remaining (resets {result['resetsAt']})")

python

Fetch Analytics

import requests

response = requests.post(
    "https://api.socialneuron.com/v1/tools/fetch_analytics",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "snk_your_api_key",
    },
    json={
        "platform": "youtube",
        "timeframe": "30d",
    },
)

result = response.json()["result"]
summary = result["summary"]
print(f"Posts: {summary['totalPosts']}")
print(f"Impressions: {summary['totalImpressions']:,}")
print(f"Engagement rate: {summary['engagementRate']}%")

python

Response:

{
  "ok": true,
  "result": {
    "platform": "youtube",
    "timeframe": "30d",
    "summary": {
      "totalPosts": 8,
      "totalImpressions": 94500,
      "totalEngagements": 7200,
      "engagementRate": 7.62,
      "followerChange": 520
    },
    "topPost": {
      "caption": "How we grew from 0 to 10K subscribers in 90 days",
      "impressions": 31000,
      "engagements": 2800
    }
  }
}

json

Error Handling

All error responses follow a consistent format:

{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "This operation requires 5 credits but you have 2 remaining."
  }
}

json

Common error codes:

Code	HTTP Status	Meaning
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Your plan does not include this scope
`RATE_LIMITED`	429	Too many requests -- check `X-RateLimit-Reset` header
`INSUFFICIENT_CREDITS`	402	Not enough credits for this operation
`VALIDATION_ERROR`	400	Missing or invalid parameters

Always check response.ok or the ok field in the JSON body before using the result. Network errors, expired keys, and insufficient credits can all cause failures.

Ready to try this? Sign up free and get 100 credits to start.

CLI Reference MCP Quickstart

​cURL

​Generate Content

​Schedule a Post

​Check Credit Balance

​Fetch Analytics

​JavaScript (Node.js)

​Generate Content

​Schedule a Post

​Check Credit Balance

​Fetch Analytics

​Python

​Generate Content

​Schedule a Post

​Check Credit Balance

​Fetch Analytics

​Error Handling

​cURL

​Generate Content

​Schedule a Post

​Check Credit Balance

​Fetch Analytics

​JavaScript (Node.js)

​Generate Content

​Schedule a Post

​Check Credit Balance

​Fetch Analytics

​Python

​Generate Content

​Schedule a Post

​Check Credit Balance

​Fetch Analytics

​Error Handling

cURL

Generate Content

Schedule a Post

Check Credit Balance

Fetch Analytics

JavaScript (Node.js)

Generate Content

Schedule a Post

Check Credit Balance

Fetch Analytics

Python

Generate Content

Schedule a Post

Check Credit Balance

Fetch Analytics

Error Handling

cURL

Generate Content

Schedule a Post

Check Credit Balance

Fetch Analytics

JavaScript (Node.js)

Generate Content

Schedule a Post

Check Credit Balance

Fetch Analytics

Python

Generate Content

Schedule a Post

Check Credit Balance

Fetch Analytics

Error Handling