media

Upload local file or external URL to R2 storage

POST

https://mcp.socialneuron.com/v1

/tools/upload_media

Execute the upload_media Social Neuron tool. Upload local file or external URL to R2 storage. Required OAuth scope: mcp:write.

Upload local file or external URL to R2 storage › Request Body

source

string

Local file path (e.g. "/Users/me/image.png") or public URL (e.g. "https://example.com/photo.jpg"). Leave empty when passing file_data instead.

file_data

string

Base64-encoded file bytes, with or without a "data:;base64," prefix. Use this from remote agents (Claude Web/Desktop) that cannot provide a filesystem path. Max 10MB decoded.

file_name

string

Optional filename for the upload (e.g. "hero.png"). Path components are stripped — only the basename is used.

content_type

string

MIME type (e.g. "image/png", "video/mp4"). Auto-detected from file extension for paths/URLs, or from the data: prefix on file_data. Required when passing raw base64 with no prefix.

project_id

string

Project ID used to verify ownership and associate the upload. Effectively REQUIRED — the service rejects requests with no verified project/organization scope. Omit only if you are certain the account has exactly one project.

response_format

string · enum

Response format. Default: text.

Enum values:

text

json

Upload local file or external URL to R2 storage › 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/upload_media

curl https://mcp.socialneuron.com/v1/tools/upload_media \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "source": "source",
  "file_data": "file_data",
  "file_name": "file_name",
  "content_type": "content_type",
  "project_id": "project_id",
  "response_format": "text"
}'

Example Request Body

{
  "source": "source",
  "file_data": "file_data",
  "file_name": "file_name",
  "content_type": "content_type",
  "project_id": "project_id",
  "response_format": "text"
}

json

Example Responses

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

json

application/json

Sign an R2 key to get a fresh download URL

POST

https://mcp.socialneuron.com/v1

/tools/get_media_url

Execute the get_media_url Social Neuron tool. Sign an R2 key to get a fresh download URL. Required OAuth scope: mcp:read.

Sign an R2 key to get a fresh download URL › Request Body

r2_key

string

Durable media key returned by upload_media or check_status.

job_id

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

An async job ID from check_status. The server resolves the job to its stored media key — use this when the raw key fails to sign (legacy key formats).

response_format

string · enum

Response format. Default: text.

Enum values:

text

json

Sign an R2 key to get a fresh download URL › 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

Request an owner-bound browser upload link for an ordered set of image, video or audio files

POST

https://mcp.socialneuron.com/v1

/tools/request_upload_session

Execute the request_upload_session Social Neuron tool. Request an owner-bound browser upload link for an ordered set of image, video or audio files. Required OAuth scope: mcp:write.

Request an owner-bound browser upload link for an ordered set of image, video or audio files › Request Body

object[] · minItems: 1 · maxItems: 10 · required

Ordered image, video or audio slots.

project_id

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

Project to own these files; required when multiple projects are accessible.

ttl_minutes

integer · min: 1 · max: 30

Session lifetime, at most 30 minutes; default 20.

request_id

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

Reuse this ID when retrying the same creation request.

Request an owner-bound browser upload link for an ordered set of image, video or audio files › 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/request_upload_session

curl https://mcp.socialneuron.com/v1/tools/request_upload_session \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slots": [
    {
      "label": "label",
      "kind": "image",
      "max_bytes": 1
    }
  ],
  "ttl_minutes": 1,
  "request_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slots": [
    {
      "label": "label",
      "kind": "image",
      "max_bytes": 1
    }
  ],
  "ttl_minutes": 1,
  "request_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

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

json

application/json

Wait for verified upload completion and return ordered durable media keys

POST

https://mcp.socialneuron.com/v1

/tools/wait_for_upload

Execute the wait_for_upload Social Neuron tool. Wait for verified upload completion and return ordered durable media keys. Required OAuth scope: mcp:read.

Wait for verified upload completion and return ordered durable media keys › Request Body

session_id

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

Upload session returned by request_upload_session.

project_id

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

Optional project attestation; must match the session.

timeout_s

integer · min: 5 · max: 600

Maximum wait in seconds; default 120.

poll_interval_s

integer · min: 2 · max: 30

Status poll interval in seconds; default 5.

Wait for verified upload completion and return ordered durable media keys › 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

Create signed media-domain PUT URLs for a session slot or multipart batch

POST

https://mcp.socialneuron.com/v1

/tools/create_upload_url

Execute the create_upload_url Social Neuron tool. Create signed media-domain PUT URLs for a session slot or multipart batch. Required OAuth scope: mcp:write.

Create signed media-domain PUT URLs for a session slot or multipart batch › Request Body

session_id

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

Upload session returned by request_upload_session.

slot_index

integer · min: 0 · max: 9 · required

content_type

string · minLength: 1 · maxLength: 120 · required

Actual file MIME type; the server validates uploaded bytes.

size_bytes

integer · max: 524288000 · required

Actual file length in bytes.

project_id

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

Optional project attestation; must match the session.

request_id

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

attempt_id

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

Existing upload attempt when requesting another part batch.

part_numbers

integer[] · minItems: 1 · maxItems: 20

Create signed media-domain PUT URLs for a session slot or multipart batch › 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/create_upload_url

curl https://mcp.socialneuron.com/v1/tools/create_upload_url \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slot_index": 0,
  "content_type": "content_type",
  "size_bytes": 1,
  "request_id": "00000000-0000-0000-0000-000000000000",
  "attempt_id": "00000000-0000-0000-0000-000000000000",
  "part_numbers": [
    1
  ]
}'

Example Request Body

{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slot_index": 0,
  "content_type": "content_type",
  "size_bytes": 1,
  "request_id": "00000000-0000-0000-0000-000000000000",
  "attempt_id": "00000000-0000-0000-0000-000000000000",
  "part_numbers": [
    1
  ]
}

json

Example Responses

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

json

application/json

Verify one upload slot and finish the session when every file is ready

POST

https://mcp.socialneuron.com/v1

/tools/complete_upload_session

Execute the complete_upload_session Social Neuron tool. Verify one upload slot and finish the session when every file is ready. Required OAuth scope: mcp:write.

Verify one upload slot and finish the session when every file is ready › Request Body

session_id

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

Upload session returned by request_upload_session.

slot_index

integer · min: 0 · max: 9 · required

attempt_id

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

project_id

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

Optional project attestation; must match the session.

Verify one upload slot and finish the session when every file is ready › 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/complete_upload_session

curl https://mcp.socialneuron.com/v1/tools/complete_upload_session \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slot_index": 0,
  "attempt_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slot_index": 0,
  "attempt_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

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

json

application/json

loop-summary pipeline

Social Neuron REST API

media

Upload local file or external URL to R2 storage

POST

https://mcp.socialneuron.com/v1

/tools/upload_media

Execute the upload_media Social Neuron tool. Upload local file or external URL to R2 storage. Required OAuth scope: mcp:write.

Upload local file or external URL to R2 storage › Request Body

source

string

Local file path (e.g. "/Users/me/image.png") or public URL (e.g. "https://example.com/photo.jpg"). Leave empty when passing file_data instead.

file_data

string

Base64-encoded file bytes, with or without a "data:;base64," prefix. Use this from remote agents (Claude Web/Desktop) that cannot provide a filesystem path. Max 10MB decoded.

file_name

string

Optional filename for the upload (e.g. "hero.png"). Path components are stripped — only the basename is used.

content_type

string

MIME type (e.g. "image/png", "video/mp4"). Auto-detected from file extension for paths/URLs, or from the data: prefix on file_data. Required when passing raw base64 with no prefix.

project_id

string

response_format

string · enum

Response format. Default: text.

Enum values:

text

json

Upload local file or external URL to R2 storage › 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/upload_media

curl https://mcp.socialneuron.com/v1/tools/upload_media \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "source": "source",
  "file_data": "file_data",
  "file_name": "file_name",
  "content_type": "content_type",
  "project_id": "project_id",
  "response_format": "text"
}'

Example Request Body

{
  "source": "source",
  "file_data": "file_data",
  "file_name": "file_name",
  "content_type": "content_type",
  "project_id": "project_id",
  "response_format": "text"
}

json

Example Responses

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

json

application/json

Sign an R2 key to get a fresh download URL

POST

https://mcp.socialneuron.com/v1

/tools/get_media_url

Execute the get_media_url Social Neuron tool. Sign an R2 key to get a fresh download URL. Required OAuth scope: mcp:read.

Sign an R2 key to get a fresh download URL › Request Body

r2_key

string

Durable media key returned by upload_media or check_status.

job_id

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

An async job ID from check_status. The server resolves the job to its stored media key — use this when the raw key fails to sign (legacy key formats).

response_format

string · enum

Response format. Default: text.

Enum values:

text

json

Sign an R2 key to get a fresh download URL › 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

Request an owner-bound browser upload link for an ordered set of image, video or audio files

POST

https://mcp.socialneuron.com/v1

/tools/request_upload_session

Execute the request_upload_session Social Neuron tool. Request an owner-bound browser upload link for an ordered set of image, video or audio files. Required OAuth scope: mcp:write.

Request an owner-bound browser upload link for an ordered set of image, video or audio files › Request Body

object[] · minItems: 1 · maxItems: 10 · required

Ordered image, video or audio slots.

project_id

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

Project to own these files; required when multiple projects are accessible.

ttl_minutes

integer · min: 1 · max: 30

Session lifetime, at most 30 minutes; default 20.

request_id

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

Reuse this ID when retrying the same creation request.

Request an owner-bound browser upload link for an ordered set of image, video or audio files › 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/request_upload_session

curl https://mcp.socialneuron.com/v1/tools/request_upload_session \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slots": [
    {
      "label": "label",
      "kind": "image",
      "max_bytes": 1
    }
  ],
  "ttl_minutes": 1,
  "request_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slots": [
    {
      "label": "label",
      "kind": "image",
      "max_bytes": 1
    }
  ],
  "ttl_minutes": 1,
  "request_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

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

json

application/json

Wait for verified upload completion and return ordered durable media keys

POST

https://mcp.socialneuron.com/v1

/tools/wait_for_upload

Execute the wait_for_upload Social Neuron tool. Wait for verified upload completion and return ordered durable media keys. Required OAuth scope: mcp:read.

Wait for verified upload completion and return ordered durable media keys › Request Body

session_id

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

Upload session returned by request_upload_session.

project_id

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

Optional project attestation; must match the session.

timeout_s

integer · min: 5 · max: 600

Maximum wait in seconds; default 120.

poll_interval_s

integer · min: 2 · max: 30

Status poll interval in seconds; default 5.

Wait for verified upload completion and return ordered durable media keys › 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

Create signed media-domain PUT URLs for a session slot or multipart batch

POST

https://mcp.socialneuron.com/v1

/tools/create_upload_url

Execute the create_upload_url Social Neuron tool. Create signed media-domain PUT URLs for a session slot or multipart batch. Required OAuth scope: mcp:write.

Create signed media-domain PUT URLs for a session slot or multipart batch › Request Body

session_id

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

Upload session returned by request_upload_session.

slot_index

integer · min: 0 · max: 9 · required

content_type

string · minLength: 1 · maxLength: 120 · required

Actual file MIME type; the server validates uploaded bytes.

size_bytes

integer · max: 524288000 · required

Actual file length in bytes.

project_id

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

Optional project attestation; must match the session.

request_id

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

attempt_id

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

Existing upload attempt when requesting another part batch.

part_numbers

integer[] · minItems: 1 · maxItems: 20

Create signed media-domain PUT URLs for a session slot or multipart batch › 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/create_upload_url

curl https://mcp.socialneuron.com/v1/tools/create_upload_url \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slot_index": 0,
  "content_type": "content_type",
  "size_bytes": 1,
  "request_id": "00000000-0000-0000-0000-000000000000",
  "attempt_id": "00000000-0000-0000-0000-000000000000",
  "part_numbers": [
    1
  ]
}'

Example Request Body

{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slot_index": 0,
  "content_type": "content_type",
  "size_bytes": 1,
  "request_id": "00000000-0000-0000-0000-000000000000",
  "attempt_id": "00000000-0000-0000-0000-000000000000",
  "part_numbers": [
    1
  ]
}

json

Example Responses

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

json

application/json

Verify one upload slot and finish the session when every file is ready

POST

https://mcp.socialneuron.com/v1

/tools/complete_upload_session

Execute the complete_upload_session Social Neuron tool. Verify one upload slot and finish the session when every file is ready. Required OAuth scope: mcp:write.

Verify one upload slot and finish the session when every file is ready › Request Body

session_id

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

Upload session returned by request_upload_session.

slot_index

integer · min: 0 · max: 9 · required

attempt_id

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

project_id

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

Optional project attestation; must match the session.

Verify one upload slot and finish the session when every file is ready › 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/complete_upload_session

curl https://mcp.socialneuron.com/v1/tools/complete_upload_session \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slot_index": 0,
  "attempt_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "session_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "slot_index": 0,
  "attempt_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

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

json

application/json

loop-summary pipeline