MCP tool

Create a research project

sosoapi_research_projects_create

Create a Research project with untrusted team text and explicit scope; reuse mutation_id on retry. Requires agent:research.

Read as Markdown

Profiles and transports

Profiles: full · Transports: stdio, http

Choose core or full to control which tools your client sees; this does not change its permissions. Local file upload requires stdio and is unavailable over HTTP. Set SOSOAPI_OUTPUT_SCHEMAS=1 to include output schemas in discovery. Tools return structured results with or without that setting.

Permissions and side effects

Annotations help clients describe a tool. Each call still checks the user’s authentication, role, resource access and capability grants.

{
  "readOnlyHint": false,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}

/research-api/projects/create: agent:research · committed Research resource version; no provider action

Input fields

Required means required inside its parent object and selected branch. A required child does not make an optional parent required. Rules and field names below are copied from the contract.

Input fields
Field / branch	Type / required	Constraints
`$`	`object`Required in parent	`additionalProperties: false`
`workspace_id`	`string`Required in parent	`format: "uuid"`
`mutation_id`	`string`Required in parent	`format: "uuid"`
`content`	`object`Required in parent	`additionalProperties: false`
`content.title`	`string`Required in parent	`minLength: 1` `maxLength: 200`
`content.question`	`string`Required in parent	`minLength: 1` `maxLength: 2000`
`content.purpose`	`string`Required in parent	`maxLength: 1000`
`content.audience`	`string`Required in parent	`maxLength: 2000`
`content.brands`	`array`Required in parent	`maxItems: 20`
`content.brands[]`	`object`Optional / item	`additionalProperties: false`
`content.brands[].id`	`string`Required in parent	`format: "uuid"`
`content.brands[].name`	`string`Required in parent	`minLength: 1` `maxLength: 100`
`content.brands[].terms`	`array`Required in parent	`minItems: 1` `maxItems: 20`
`content.brands[].terms[]`	`string`Optional / item	`minLength: 1` `maxLength: 100`
`content.scope`	`object`Required in parent	`additionalProperties: false`
`content.scope.query`	`string`Required in parent	`maxLength: 2000`
`content.scope.excluded_terms`	`array`Required in parent	`maxItems: 50`
`content.scope.excluded_terms[]`	`string`Optional / item	`minLength: 1` `maxLength: 100`
`content.scope.platforms`	`array`Required in parent	`maxItems: 7`
`content.scope.platforms[]`	`string`Optional / item	`enum: ["threads","instagram","facebook","youtube","x","reddit","web"]`
`content.scope.source_categories`	`array`Required in parent	`minItems: 1` `maxItems: 3`
`content.scope.source_categories[]`	`string`Optional / item	`enum: ["your_accounts","public_posts","team_notes"]`
`content.scope.languages`	`array`Required in parent	`maxItems: 18`
`content.scope.languages[]`	`string`Optional / item	`minLength: 1` `maxLength: 35`
`content.scope.since`	`string \| null`Required in parent	—
`content.scope.since`anyOf 1	`string`Required in parent	`format: "date-time"` `pattern: "^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z\|([+-](?:[01]\\d\|2[0-3]):[0-5]\\d)))$"`
`content.scope.since`anyOf 2	`null`Required in parent	—
`content.scope.until`	`string \| null`Required in parent	—
`content.scope.until`anyOf 1	`string`Required in parent	`format: "date-time"` `pattern: "^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z\|([+-](?:[01]\\d\|2[0-3]):[0-5]\\d)))$"`
`content.scope.until`anyOf 2	`null`Required in parent	—

Complete JSON Schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "format": "uuid"
    },
    "mutation_id": {
      "type": "string",
      "format": "uuid"
    },
    "content": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "question": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "purpose": {
          "type": "string",
          "maxLength": 1000
        },
        "audience": {
          "type": "string",
          "maxLength": 2000
        },
        "brands": {
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "$ref": "#/$defs/s1"
              },
              "terms": {
                "minItems": 1,
                "maxItems": 20,
                "type": "array",
                "items": {
                  "$ref": "#/$defs/s1"
                }
              }
            },
            "required": [
              "id",
              "name",
              "terms"
            ],
            "additionalProperties": false
          }
        },
        "scope": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "maxLength": 2000
            },
            "excluded_terms": {
              "maxItems": 50,
              "type": "array",
              "items": {
                "$ref": "#/$defs/s1"
              }
            },
            "platforms": {
              "maxItems": 7,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "threads",
                  "instagram",
                  "facebook",
                  "youtube",
                  "x",
                  "reddit",
                  "web"
                ]
              }
            },
            "source_categories": {
              "minItems": 1,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "your_accounts",
                  "public_posts",
                  "team_notes"
                ]
              }
            },
            "languages": {
              "maxItems": 18,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 35
              }
            },
            "since": {
              "$ref": "#/$defs/s0"
            },
            "until": {
              "$ref": "#/$defs/s0"
            }
          },
          "required": [
            "query",
            "excluded_terms",
            "platforms",
            "source_categories",
            "languages",
            "since",
            "until"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "title",
        "question",
        "purpose",
        "audience",
        "brands",
        "scope"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "workspace_id",
    "mutation_id",
    "content"
  ],
  "additionalProperties": false,
  "$defs": {
    "s0": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "s1": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    }
  }
}

Structured output

This schema describes structuredContent in a successful tool result. The MCP response also includes content and may set isError when a call fails. For publishing, read the post’s final result rather than treating an accepted request or text response as confirmation. The linked API operation explains permissions and retry rules.

Required means required inside its parent object and selected branch. A required child does not make an optional parent required. Rules and field names below are copied from the contract.

Structured output
Field / branch	Type / required	Constraints
`$`	`object`Required in parent	`additionalProperties: false`
`project`	`object`Required in parent	`additionalProperties: false`
`project.id`	`string`Required in parent	`format: "uuid"`
`project.workspace_id`	`string`Required in parent	`format: "uuid"`
`project.revision`	`integer`Required in parent	`maximum: 9007199254740991` `exclusiveMinimum: 0`
`project.archived`	`boolean`Required in parent	—
`project.created_at`	`string`Required in parent	`format: "date-time"` `pattern: "^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z\|([+-](?:[01]\\d\|2[0-3]):[0-5]\\d)))$"`
`project.updated_at`	`string`Required in parent	`format: "date-time"` `pattern: "^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z\|([+-](?:[01]\\d\|2[0-3]):[0-5]\\d)))$"`
`project.content`	`object`Required in parent	`additionalProperties: false`
`project.content.title`	`string`Required in parent	`minLength: 1` `maxLength: 200`
`project.content.question`	`string`Required in parent	`minLength: 1` `maxLength: 2000`
`project.content.purpose`	`string`Required in parent	`maxLength: 1000`
`project.content.audience`	`string`Required in parent	`maxLength: 2000`
`project.content.brands`	`array`Required in parent	`maxItems: 20`
`project.content.brands[]`	`object`Optional / item	`additionalProperties: false`
`project.content.brands[].id`	`string`Required in parent	`format: "uuid"`
`project.content.brands[].name`	`string`Required in parent	`minLength: 1` `maxLength: 100`
`project.content.brands[].terms`	`array`Required in parent	`minItems: 1` `maxItems: 20`
`project.content.brands[].terms[]`	`string`Optional / item	`minLength: 1` `maxLength: 100`
`project.content.scope`	`object`Required in parent	`additionalProperties: false`
`project.content.scope.query`	`string`Required in parent	`maxLength: 2000`
`project.content.scope.excluded_terms`	`array`Required in parent	`maxItems: 50`
`project.content.scope.excluded_terms[]`	`string`Optional / item	`minLength: 1` `maxLength: 100`
`project.content.scope.platforms`	`array`Required in parent	`maxItems: 7`
`project.content.scope.platforms[]`	`string`Optional / item	`enum: ["threads","instagram","facebook","youtube","x","reddit","web"]`
`project.content.scope.source_categories`	`array`Required in parent	`minItems: 1` `maxItems: 3`
`project.content.scope.source_categories[]`	`string`Optional / item	`enum: ["your_accounts","public_posts","team_notes"]`
`project.content.scope.languages`	`array`Required in parent	`maxItems: 18`
`project.content.scope.languages[]`	`string`Optional / item	`minLength: 1` `maxLength: 35`
`project.content.scope.since`	`string \| null`Required in parent	—
`project.content.scope.since`anyOf 1	`string`Required in parent	`format: "date-time"` `pattern: "^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z\|([+-](?:[01]\\d\|2[0-3]):[0-5]\\d)))$"`
`project.content.scope.since`anyOf 2	`null`Required in parent	—
`project.content.scope.until`	`string \| null`Required in parent	—
`project.content.scope.until`anyOf 1	`string`Required in parent	`format: "date-time"` `pattern: "^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z\|([+-](?:[01]\\d\|2[0-3]):[0-5]\\d)))$"`
`project.content.scope.until`anyOf 2	`null`Required in parent	—

Complete JSON Schema

{
  "type": "object",
  "properties": {
    "project": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "workspace_id": {
          "type": "string",
          "format": "uuid"
        },
        "revision": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "archived": {
          "type": "boolean"
        },
        "created_at": {
          "type": "string",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
          "format": "date-time"
        },
        "content": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "question": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2000
            },
            "purpose": {
              "type": "string",
              "maxLength": 1000
            },
            "audience": {
              "type": "string",
              "maxLength": 2000
            },
            "brands": {
              "maxItems": 20,
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "terms": {
                    "minItems": 1,
                    "maxItems": 20,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100
                    }
                  }
                },
                "required": [
                  "id",
                  "name",
                  "terms"
                ],
                "additionalProperties": false
              }
            },
            "scope": {
              "type": "object",
              "properties": {
                "query": {
                  "type": "string",
                  "maxLength": 2000
                },
                "excluded_terms": {
                  "maxItems": 50,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  }
                },
                "platforms": {
                  "maxItems": 7,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "threads",
                      "instagram",
                      "facebook",
                      "youtube",
                      "x",
                      "reddit",
                      "web"
                    ]
                  }
                },
                "source_categories": {
                  "minItems": 1,
                  "maxItems": 3,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "your_accounts",
                      "public_posts",
                      "team_notes"
                    ]
                  }
                },
                "languages": {
                  "maxItems": 18,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 35
                  }
                },
                "since": {
                  "anyOf": [
                    {
                      "type": "string",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
                      "format": "date-time"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "until": {
                  "anyOf": [
                    {
                      "type": "string",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
                      "format": "date-time"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "query",
                "excluded_terms",
                "platforms",
                "source_categories",
                "languages",
                "since",
                "until"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "title",
            "question",
            "purpose",
            "audience",
            "brands",
            "scope"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "workspace_id",
        "revision",
        "archived",
        "created_at",
        "updated_at",
        "content"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "project"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Example tool call

These examples use fictional values checked against the schemas. Replace the IDs with ones you are authorized to use, the media with ready assets and the dates with your confirmed publishing time. Check the account’s eligibility before submitting a write. This page sends no API requests.

{
  "name": "sosoapi_research_projects_create",
  "arguments": {
    "workspace_id": "11111111-1111-4111-8111-111111111111",
    "mutation_id": "11111111-1111-4111-8111-111111111111",
    "content": {
      "title": "example",
      "question": "example",
      "purpose": "example",
      "audience": "example",
      "brands": [],
      "scope": {
        "query": "example",
        "excluded_terms": [],
        "platforms": [],
        "source_categories": [
          "your_accounts"
        ],
        "languages": [],
        "since": null,
        "until": null
      }
    }
  }
}

structuredContent

{
  "project": {
    "id": "11111111-1111-4111-8111-111111111111",
    "workspace_id": "11111111-1111-4111-8111-111111111111",
    "revision": 1,
    "archived": false,
    "created_at": "2099-01-15T09:00:00Z",
    "updated_at": "2099-01-15T09:00:00Z",
    "content": {
      "title": "example",
      "question": "example",
      "purpose": "example",
      "audience": "example",
      "brands": [],
      "scope": {
        "query": "example",
        "excluded_terms": [],
        "platforms": [],
        "source_categories": [
          "your_accounts"
        ],
        "languages": [],
        "since": null,
        "until": null
      }
    }
  }
}

/research-api/projects/create

Install or connect MCP

Privacy preferences

Necessary features

Optional usage analytics

Also allow session replay on this public website

Create a research project

Profiles and transports

Permissions and side effects

Input fields

Structured output

Example tool call

structuredContent

Create a research project

Profiles and transports

Permissions and side effects

Input fields

Structured output

Example tool call

structuredContent

Underlying API operations