Composway Docs
Tool reference

Create AI campaign

Create an AEO (AI) campaign in a workspace from one or more target prompts.

Tool name: create_ai_campaign

Cost: Counts against your plan's monthly campaign quota - the same allowance the web app draws on. Nothing is billed per call.

Writes data - confirmation required

This tool creates or changes data. It is not annotated readOnlyHint, so your MCP client prompts you before it runs, and the server asks for an explicit confirmation describing exactly what will change. Declining cancels the call cleanly.

Create an AEO (AI) campaign in a workspace from one or more target prompts. Counts against the monthly campaign quota and kicks off background analysis.

After creating, the campaign runs background analysis. Poll get_campaign with the returned campaign id about every 30 seconds until its status becomes "awaiting-pain-point-confirmation" AND it returns at least one pain point (pain_points) and at least one search intent. The search intents are in search_intents[].results[] - each entry is a SearchIntentDetail and its id is the search-intent id. Once that state is reached, present the returned pain points and search intents to the user and ask them to confirm which to keep, then call confirm_pain_points with the chosen pain points and the selected SearchIntentDetail ids (searchIntentIds). Do NOT call confirm_pain_points before the status is awaiting-pain-point-confirmation, and never with an empty search-intent list.

Parameters

ParameterTypeRequiredNotes
workspaceIdstring (uuid)Yes-
targetPrompts({ topic, location, language, llmProviderIds })[]Yes-
targetAudiences({ id, name })[]YesAt least one target audience is REQUIRED - the backend rejects the campaign otherwise. If the user did not specify an audience, do NOT invent one: call get_workspace first and ask the user to pick one of the workspace's target audiences to attach (pass its id + name to inherit it), or to provide a new audience name.
aiMode"ai" | "manual"NoDefaults to "ai".
Full input JSON Schema
{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"properties": {
		"workspaceId": {
			"type": "string",
			"format": "uuid",
			"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
		},
		"targetPrompts": {
			"minItems": 1,
			"type": "array",
			"items": {
				"type": "object",
				"properties": {
					"topic": {
						"type": "string",
						"description": "The prompt/topic to target."
					},
					"location": {
						"type": "object",
						"properties": {
							"id": {
								"type": "integer",
								"minimum": -9007199254740991,
								"maximum": 9007199254740991
							},
							"code": {
								"type": "string"
							},
							"isoCode": {
								"type": "string"
							},
							"name": {
								"type": "string"
							}
						},
						"required": ["id", "code", "isoCode", "name"],
						"description": "DataForSEO location reference. Do NOT invent these fields - call search_reference with type=\"location\" (e.g. query=\"United States\") and pass one returned result object here verbatim."
					},
					"language": {
						"type": "object",
						"properties": {
							"id": {
								"type": "integer",
								"minimum": -9007199254740991,
								"maximum": 9007199254740991
							},
							"code": {
								"type": "string"
							},
							"isoCode": {
								"type": "string"
							},
							"name": {
								"type": "string"
							}
						},
						"required": ["id", "code", "isoCode", "name"],
						"description": "DataForSEO language reference. Do NOT invent these fields - call search_reference with type=\"language\" (e.g. query=\"English\") and pass one returned result object here verbatim."
					},
					"llmProviderIds": {
						"default": [],
						"type": "array",
						"items": {
							"type": "string",
							"format": "uuid",
							"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
						}
					}
				},
				"required": ["topic", "location", "language"]
			}
		},
		"targetAudiences": {
			"minItems": 1,
			"type": "array",
			"items": {
				"type": "object",
				"properties": {
					"id": {
						"description": "Set only when inheriting a workspace audience.",
						"type": "string",
						"format": "uuid",
						"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
					},
					"name": {
						"type": "string"
					}
				},
				"required": ["name"]
			},
			"description": "At least one target audience is REQUIRED - the backend rejects the campaign otherwise. If the user did not specify an audience, do NOT invent one: call get_workspace first and ask the user to pick one of the workspace's target audiences to attach (pass its id + name to inherit it), or to provide a new audience name."
		},
		"aiMode": {
			"default": "ai",
			"type": "string",
			"enum": ["ai", "manual"]
		}
	},
	"required": ["workspaceId", "targetPrompts", "targetAudiences"]
}

Response

Full output JSON Schema
{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"properties": {
		"workspaceId": {
			"type": "string",
			"format": "uuid",
			"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
		},
		"targetPrompts": {
			"type": "array",
			"items": {
				"type": "object",
				"properties": {
					"topic": {
						"type": "string"
					},
					"location": {
						"type": "object",
						"properties": {
							"id": {
								"type": "integer",
								"minimum": -9007199254740991,
								"maximum": 9007199254740991
							},
							"code": {
								"type": "string"
							},
							"isoCode": {
								"type": "string"
							},
							"name": {
								"type": "string"
							}
						},
						"required": ["id", "code", "isoCode", "name"],
						"additionalProperties": {}
					},
					"language": {
						"type": "object",
						"properties": {
							"id": {
								"type": "integer",
								"minimum": -9007199254740991,
								"maximum": 9007199254740991
							},
							"code": {
								"type": "string"
							},
							"isoCode": {
								"type": "string"
							},
							"name": {
								"type": "string"
							}
						},
						"required": ["id", "code", "isoCode", "name"],
						"additionalProperties": {}
					},
					"llmProviderIds": {
						"type": "array",
						"items": {
							"type": "string",
							"format": "uuid",
							"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
						}
					},
					"campaignId": {
						"type": "string",
						"format": "uuid",
						"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
					},
					"promptId": {
						"type": "string",
						"format": "uuid",
						"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
					},
					"targetAudiences": {
						"type": "array",
						"items": {
							"type": "string",
							"format": "uuid",
							"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
						}
					},
					"painPointConnected": {
						"type": "boolean"
					},
					"painPointId": {
						"anyOf": [
							{
								"type": "string",
								"format": "uuid",
								"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
							},
							{
								"type": "null"
							}
						]
					}
				},
				"required": ["topic", "location", "language"],
				"additionalProperties": {}
			}
		},
		"aiMode": {
			"type": "string"
		}
	},
	"required": ["workspaceId", "targetPrompts", "aiMode"],
	"additionalProperties": false
}

Create workspace

Create a new workspace.

Confirm search intent

Confirm the chosen search-intent classification for a campaign.

On this page

ParametersResponse