planning

Generate a weekly content plan

POST

https://mcp.socialneuron.com/v1

/tools/plan_content_week

Generate a weekly content plan › Request Body

topic

string · required

Main topic or content theme

platforms

string[] · minItems: 1 · required

Target platforms

Enum values:

youtube

tiktok

instagram

twitter

facebook

threads

bluesky

source_url

string

URL to extract content from (YouTube, article)

posts_per_day

number · min: 1 · max: 5

Posts per platform per day

Default: 1

days

number · min: 1 · max: 7

Number of days to plan

Default: 5

start_date

string

ISO date, defaults to tomorrow

brand_voice

string

Override brand voice description

project_id

string

Project ID for brand/insights context

response_format

string · enum

Enum values:

text

json

Default: json

Generate a weekly content plan › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

POST/tools/plan_content_week

curl https://mcp.socialneuron.com/v1/tools/plan_content_week \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "topic": "topic",
  "source_url": "source_url",
  "platforms": [
    "youtube"
  ],
  "posts_per_day": 1,
  "days": 5,
  "start_date": "start_date",
  "brand_voice": "brand_voice",
  "project_id": "project_id",
  "response_format": "json"
}'

Example Request Body

{
  "topic": "topic",
  "source_url": "source_url",
  "platforms": [
    "youtube"
  ],
  "posts_per_day": 1,
  "days": 5,
  "start_date": "start_date",
  "brand_voice": "brand_voice",
  "project_id": "project_id",
  "response_format": "json"
}

json

Example Responses

{
  "content": [
    {
      "type": "type",
      "text": "text"
    }
  ],
  "structuredContent": {},
  "isError": true
}

json

application/json

Save a content plan

POST

https://mcp.socialneuron.com/v1

/tools/save_content_plan

Save a content plan › Request Body

object · required

project_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

status

string · enum

Enum values:

draft

in_review

approved

scheduled

completed

Default: draft

response_format

string · enum

Enum values:

text

json

Default: json

Save a content plan › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

POST/tools/save_content_plan

curl https://mcp.socialneuron.com/v1/tools/save_content_plan \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "plan": {
    "topic": "topic",
    "posts": [
      {
        "key": {}
      }
    ]
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "status": "draft",
  "response_format": "json"
}'

Example Request Body

{
  "plan": {
    "topic": "topic",
    "posts": [
      {
        "key": {}
      }
    ]
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "status": "draft",
  "response_format": "json"
}

json

Example Responses

{
  "content": [
    {
      "type": "type",
      "text": "text"
    }
  ],
  "structuredContent": {},
  "isError": true
}

json

application/json

Get a specific content plan by ID

POST

https://mcp.socialneuron.com/v1

/tools/get_content_plan

Get a specific content plan by ID › Request Body

plan_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

Persisted content plan ID

response_format

string · enum

Enum values:

text

json

Default: json

Get a specific content plan by ID › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

Update an existing content plan

POST

https://mcp.socialneuron.com/v1

/tools/update_content_plan

Update an existing content plan › Request Body

plan_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

object[] · minItems: 1 · required

response_format

string · enum

Enum values:

text

json

Default: json

Update an existing content plan › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

POST/tools/update_content_plan

curl https://mcp.socialneuron.com/v1/tools/update_content_plan \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "plan_id": "00000000-0000-0000-0000-000000000000",
  "post_updates": [
    {
      "post_id": "post_id",
      "caption": "caption",
      "title": "title",
      "hashtags": [
        "string"
      ],
      "hook": "hook",
      "angle": "angle",
      "visual_direction": "visual_direction",
      "media_url": "media_url",
      "schedule_at": "schedule_at",
      "platform": "platform",
      "status": "approved"
    }
  ],
  "response_format": "json"
}'

Example Request Body

{
  "plan_id": "00000000-0000-0000-0000-000000000000",
  "post_updates": [
    {
      "post_id": "post_id",
      "caption": "caption",
      "title": "title",
      "hashtags": [
        "string"
      ],
      "hook": "hook",
      "angle": "angle",
      "visual_direction": "visual_direction",
      "media_url": "media_url",
      "schedule_at": "schedule_at",
      "platform": "platform",
      "status": "approved"
    }
  ],
  "response_format": "json"
}

json

Example Responses

{
  "content": [
    {
      "type": "type",
      "text": "text"
    }
  ],
  "structuredContent": {},
  "isError": true
}

json

application/json

Submit a content plan for team approval

POST

https://mcp.socialneuron.com/v1

/tools/submit_content_plan_for_approval

Submit a content plan for team approval › Request Body

plan_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

response_format

string · enum

Enum values:

text

json

Default: json

Submit a content plan for team approval › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

Schedule all posts in an approved content plan

POST

https://mcp.socialneuron.com/v1

/tools/schedule_content_plan

Schedule all posts in an approved content plan › Request Body

object

project_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Exact brand/project ID. Defaults only when the authenticated user has one project.

object

Exact connected-account ID per platform for every post in the plan.

plan_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Persisted content plan ID from content_plans table

auto_slot

boolean

Auto-assign time slots for posts without schedule_at

Default: true

dry_run

boolean

Preview without actually scheduling

Default: false

response_format

string · enum

Enum values:

text

json

Default: text

enforce_quality

boolean

When true, block scheduling for posts that fail quality checks.

Default: true

quality_threshold

integer · min: 0 · max: 35

Optional quality threshold override. Defaults to project setting or 26.

batch_size

integer · min: 1 · max: 10

Concurrent schedule calls per platform batch.

Default: 4

idempotency_seed

string · maxLength: 128

Optional stable seed used when building idempotency keys.

Schedule all posts in an approved content plan › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

POST/tools/schedule_content_plan

curl https://mcp.socialneuron.com/v1/tools/schedule_content_plan \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "plan": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "account_ids": {
      "key": "00000000-0000-0000-0000-000000000000"
    },
    "posts": [
      {
        "id": "id",
        "caption": "caption",
        "platform": "platform",
        "connected_account_id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "media_url": "media_url",
        "schedule_at": "schedule_at",
        "hashtags": [
          "string"
        ]
      }
    ]
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "account_ids": {
    "key": "00000000-0000-0000-0000-000000000000"
  },
  "plan_id": "00000000-0000-0000-0000-000000000000",
  "auto_slot": true,
  "dry_run": false,
  "response_format": "text",
  "enforce_quality": true,
  "quality_threshold": 0,
  "batch_size": 4,
  "idempotency_seed": "idempotency_seed"
}'

Example Request Body

{
  "plan": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "account_ids": {
      "key": "00000000-0000-0000-0000-000000000000"
    },
    "posts": [
      {
        "id": "id",
        "caption": "caption",
        "platform": "platform",
        "connected_account_id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "media_url": "media_url",
        "schedule_at": "schedule_at",
        "hashtags": [
          "string"
        ]
      }
    ]
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "account_ids": {
    "key": "00000000-0000-0000-0000-000000000000"
  },
  "plan_id": "00000000-0000-0000-0000-000000000000",
  "auto_slot": true,
  "dry_run": false,
  "response_format": "text",
  "enforce_quality": true,
  "quality_threshold": 0,
  "batch_size": 4,
  "idempotency_seed": "idempotency_seed"
}

json

Example Responses

{
  "content": [
    {
      "type": "type",
      "text": "text"
    }
  ],
  "structuredContent": {},
  "isError": true
}

json

application/json

Find next available scheduling slots

POST

https://mcp.socialneuron.com/v1

/tools/find_next_slots

Find next available scheduling slots › Request Body

platforms

string[] · minItems: 1 · required

Enum values:

youtube

tiktok

instagram

twitter

facebook

threads

bluesky

project_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Brand/project ID used for conflict detection. Defaults to the authenticated key's project or the account default.

count

number · min: 1 · max: 20

Number of slots to find

Default: 7

start_after

string

ISO datetime, defaults to now

min_gap_hours

number · min: 1 · max: 24

Minimum gap between posts on same platform

Default: 4

response_format

string · enum

Enum values:

text

json

Default: text

Find next available scheduling slots › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

POST/tools/find_next_slots

curl https://mcp.socialneuron.com/v1/tools/find_next_slots \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "platforms": [
    "youtube"
  ],
  "count": 7,
  "start_after": "start_after",
  "min_gap_hours": 4,
  "response_format": "text"
}'

Example Request Body

{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "platforms": [
    "youtube"
  ],
  "count": 7,
  "start_after": "start_after",
  "min_gap_hours": 4,
  "response_format": "text"
}

json

Example Responses

{
  "content": [
    {
      "type": "type",
      "text": "text"
    }
  ],
  "structuredContent": {},
  "isError": true
}

json

application/json

plan-approvals quality

Social Neuron REST API

planning

Generate a weekly content plan

POST

https://mcp.socialneuron.com/v1

/tools/plan_content_week

Generate a weekly content plan › Request Body

topic

string · required

Main topic or content theme

platforms

string[] · minItems: 1 · required

Target platforms

Enum values:

youtube

tiktok

instagram

twitter

facebook

threads

bluesky

source_url

string

URL to extract content from (YouTube, article)

posts_per_day

number · min: 1 · max: 5

Posts per platform per day

Default: 1

days

number · min: 1 · max: 7

Number of days to plan

Default: 5

start_date

string

ISO date, defaults to tomorrow

brand_voice

string

Override brand voice description

project_id

string

Project ID for brand/insights context

response_format

string · enum

Enum values:

text

json

Default: json

Generate a weekly content plan › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

POST/tools/plan_content_week

curl https://mcp.socialneuron.com/v1/tools/plan_content_week \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "topic": "topic",
  "source_url": "source_url",
  "platforms": [
    "youtube"
  ],
  "posts_per_day": 1,
  "days": 5,
  "start_date": "start_date",
  "brand_voice": "brand_voice",
  "project_id": "project_id",
  "response_format": "json"
}'

Example Request Body

{
  "topic": "topic",
  "source_url": "source_url",
  "platforms": [
    "youtube"
  ],
  "posts_per_day": 1,
  "days": 5,
  "start_date": "start_date",
  "brand_voice": "brand_voice",
  "project_id": "project_id",
  "response_format": "json"
}

json

Example Responses

{
  "content": [
    {
      "type": "type",
      "text": "text"
    }
  ],
  "structuredContent": {},
  "isError": true
}

json

application/json

Save a content plan

POST

https://mcp.socialneuron.com/v1

/tools/save_content_plan

Save a content plan › Request Body

object · required

project_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

status

string · enum

Enum values:

draft

in_review

approved

scheduled

completed

Default: draft

response_format

string · enum

Enum values:

text

json

Default: json

Save a content plan › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

POST/tools/save_content_plan

curl https://mcp.socialneuron.com/v1/tools/save_content_plan \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "plan": {
    "topic": "topic",
    "posts": [
      {
        "key": {}
      }
    ]
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "status": "draft",
  "response_format": "json"
}'

Example Request Body

{
  "plan": {
    "topic": "topic",
    "posts": [
      {
        "key": {}
      }
    ]
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "status": "draft",
  "response_format": "json"
}

json

Example Responses

{
  "content": [
    {
      "type": "type",
      "text": "text"
    }
  ],
  "structuredContent": {},
  "isError": true
}

json

application/json

Get a specific content plan by ID

POST

https://mcp.socialneuron.com/v1

/tools/get_content_plan

Get a specific content plan by ID › Request Body

plan_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

Persisted content plan ID

response_format

string · enum

Enum values:

text

json

Default: json

Get a specific content plan by ID › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

Update an existing content plan

POST

https://mcp.socialneuron.com/v1

/tools/update_content_plan

Update an existing content plan › Request Body

plan_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

object[] · minItems: 1 · required

response_format

string · enum

Enum values:

text

json

Default: json

Update an existing content plan › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

POST/tools/update_content_plan

curl https://mcp.socialneuron.com/v1/tools/update_content_plan \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "plan_id": "00000000-0000-0000-0000-000000000000",
  "post_updates": [
    {
      "post_id": "post_id",
      "caption": "caption",
      "title": "title",
      "hashtags": [
        "string"
      ],
      "hook": "hook",
      "angle": "angle",
      "visual_direction": "visual_direction",
      "media_url": "media_url",
      "schedule_at": "schedule_at",
      "platform": "platform",
      "status": "approved"
    }
  ],
  "response_format": "json"
}'

Example Request Body

{
  "plan_id": "00000000-0000-0000-0000-000000000000",
  "post_updates": [
    {
      "post_id": "post_id",
      "caption": "caption",
      "title": "title",
      "hashtags": [
        "string"
      ],
      "hook": "hook",
      "angle": "angle",
      "visual_direction": "visual_direction",
      "media_url": "media_url",
      "schedule_at": "schedule_at",
      "platform": "platform",
      "status": "approved"
    }
  ],
  "response_format": "json"
}

json

Example Responses

{
  "content": [
    {
      "type": "type",
      "text": "text"
    }
  ],
  "structuredContent": {},
  "isError": true
}

json

application/json

Submit a content plan for team approval

POST

https://mcp.socialneuron.com/v1

/tools/submit_content_plan_for_approval

Submit a content plan for team approval › Request Body

plan_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-… · required

response_format

string · enum

Enum values:

text

json

Default: json

Submit a content plan for team approval › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

Schedule all posts in an approved content plan

POST

https://mcp.socialneuron.com/v1

/tools/schedule_content_plan

Schedule all posts in an approved content plan › Request Body

object

project_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Exact brand/project ID. Defaults only when the authenticated user has one project.

object

Exact connected-account ID per platform for every post in the plan.

plan_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Persisted content plan ID from content_plans table

auto_slot

boolean

Auto-assign time slots for posts without schedule_at

Default: true

dry_run

boolean

Preview without actually scheduling

Default: false

response_format

string · enum

Enum values:

text

json

Default: text

enforce_quality

boolean

When true, block scheduling for posts that fail quality checks.

Default: true

quality_threshold

integer · min: 0 · max: 35

Optional quality threshold override. Defaults to project setting or 26.

batch_size

integer · min: 1 · max: 10

Concurrent schedule calls per platform batch.

Default: 4

idempotency_seed

string · maxLength: 128

Optional stable seed used when building idempotency keys.

Schedule all posts in an approved content plan › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

POST/tools/schedule_content_plan

curl https://mcp.socialneuron.com/v1/tools/schedule_content_plan \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "plan": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "account_ids": {
      "key": "00000000-0000-0000-0000-000000000000"
    },
    "posts": [
      {
        "id": "id",
        "caption": "caption",
        "platform": "platform",
        "connected_account_id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "media_url": "media_url",
        "schedule_at": "schedule_at",
        "hashtags": [
          "string"
        ]
      }
    ]
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "account_ids": {
    "key": "00000000-0000-0000-0000-000000000000"
  },
  "plan_id": "00000000-0000-0000-0000-000000000000",
  "auto_slot": true,
  "dry_run": false,
  "response_format": "text",
  "enforce_quality": true,
  "quality_threshold": 0,
  "batch_size": 4,
  "idempotency_seed": "idempotency_seed"
}'

Example Request Body

{
  "plan": {
    "project_id": "00000000-0000-0000-0000-000000000000",
    "account_ids": {
      "key": "00000000-0000-0000-0000-000000000000"
    },
    "posts": [
      {
        "id": "id",
        "caption": "caption",
        "platform": "platform",
        "connected_account_id": "00000000-0000-0000-0000-000000000000",
        "title": "title",
        "media_url": "media_url",
        "schedule_at": "schedule_at",
        "hashtags": [
          "string"
        ]
      }
    ]
  },
  "project_id": "00000000-0000-0000-0000-000000000000",
  "account_ids": {
    "key": "00000000-0000-0000-0000-000000000000"
  },
  "plan_id": "00000000-0000-0000-0000-000000000000",
  "auto_slot": true,
  "dry_run": false,
  "response_format": "text",
  "enforce_quality": true,
  "quality_threshold": 0,
  "batch_size": 4,
  "idempotency_seed": "idempotency_seed"
}

json

Example Responses

{
  "content": [
    {
      "type": "type",
      "text": "text"
    }
  ],
  "structuredContent": {},
  "isError": true
}

json

application/json

Find next available scheduling slots

POST

https://mcp.socialneuron.com/v1

/tools/find_next_slots

Find next available scheduling slots › Request Body

platforms

string[] · minItems: 1 · required

Enum values:

youtube

tiktok

instagram

twitter

facebook

threads

bluesky

project_id

string · uuid · pattern: ^([0-9a-fA-F]{8}-[0-…

Brand/project ID used for conflict detection. Defaults to the authenticated key's project or the account default.

count

number · min: 1 · max: 20

Number of slots to find

Default: 7

start_after

string

ISO datetime, defaults to now

min_gap_hours

number · min: 1 · max: 24

Minimum gap between posts on same platform

Default: 4

response_format

string · enum

Enum values:

text

json

Default: text

Find next available scheduling slots › Responses

Tool executed. isError:true in the body indicates a tool-level error.

MCP CallToolResult. `content` carries text/structured blocks; `structuredContent` is present when the tool declares structured output.

ToolResult

object[]

object

isError

boolean

POST/tools/find_next_slots

curl https://mcp.socialneuron.com/v1/tools/find_next_slots \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "platforms": [
    "youtube"
  ],
  "count": 7,
  "start_after": "start_after",
  "min_gap_hours": 4,
  "response_format": "text"
}'

Example Request Body

{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "platforms": [
    "youtube"
  ],
  "count": 7,
  "start_after": "start_after",
  "min_gap_hours": 4,
  "response_format": "text"
}

json

Example Responses

{
  "content": [
    {
      "type": "type",
      "text": "text"
    }
  ],
  "structuredContent": {},
  "isError": true
}

json

application/json

plan-approvals quality