> ## Documentation Index > Fetch the complete documentation index at: https://docs.shareofmodel.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create campaign optimization > Create a new campaign optimization. Required permission: `write:analysis`. **Top-level optional field (Google Ads only):** - `promotion_type` (optional): Optimisation intent. Values: `Product`, `Service`, `Brand` (case-insensitive). Stored as `campaign.intent` (lowercase). Ignored for TikTok. **Google Ads enrichment:** On creation, Jarvis fetches live metadata from Google Ads for each asset group and stores it in `campaign.asset_group_info` (ad strength, status, search themes count, campaign name). The client only needs to send `asset_group_info` with `name`; the backend fills the rest. **Campaign Field Structure (`campaign` JSON)** The `campaign` field is a free-form JSON object whose structure depends on the platform. **Google Ads (PMax):** ```json { "customer_id": "1447066043/8965287694", "asset_group_ids": ["6476435676", "6481074503"], "intent": "product", "asset_group_info": { "6476435676": { "name": "Animalerie", "ad_strength": "POOR", "ad_strength_score": 10, "ad_strength_max": 25, "search_themes_count": 0, "campaign_name": "PMax: IKOM - Smart Shopping CSS", "status": "ENABLED" } } } ``` Fields: - `customer_id` (string): Google Ads customer ID, format `"manager_id/account_id"` or `"account_id"`. - `asset_group_ids` (string[]): Asset group IDs selected for optimization. - `intent` (string, optional): Optimization intent (`product`, `service`, `brand`). Set from `promotion_type`. - `asset_group_info` (object): Mapping of asset group ID to metadata. Enriched with live Google Ads data at creation: - `name` (string): Asset group name. - `ad_strength` (string): Google Ads enum — `EXCELLENT`, `GOOD`, `AVERAGE`, `POOR`, `PENDING`, `UNKNOWN`, `UNSPECIFIED`, `NO_ADS`. - `ad_strength_score` (int): Numeric score — EXCELLENT=25, GOOD=20, AVERAGE=15, POOR=10, all others=0. - `ad_strength_max` (int): Always 25 (max possible score). - `search_themes_count` (int): Number of search theme signals currently on the asset group in Google Ads. - `campaign_name` (string): Parent PMax campaign name. - `status` (string): Asset group status — `ENABLED`, `PAUSED`, `REMOVED`, etc. Use `POST .../refresh` to re-fetch `asset_group_info` from Google Ads without re-running the optimization pipeline. **TikTok:** ```json { "advertiser_id": "7052316759499587586", "campaign_id": "1850667377518002", "ad_group_ids": ["1850939823278113", "1850667437045906"], "ad_group_names": { "1850939823278113": "Ad Group Name 1", "1850667437045906": "Ad Group Name 2" } } ``` Fields: - `advertiser_id` (string): TikTok advertiser account ID. - `campaign_id` (string): TikTok campaign ID. - `ad_group_ids` (string[]): Ad group IDs to optimize (non-empty). - `ad_group_names` (object, optional): Mapping of ad group ID to ad group name. Supply this at creation time so the activation page can display names without making additional TikTok API calls. TikTok campaign objects do **not** include `asset_group_info` or enrichment fields. ## OpenAPI ````yaml https://openapi.shareofmodel.ai/swagger.json post /v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations openapi: 3.0.3 info: title: Share Of Model API version: v1 description: >- ## Model Context Protocol (MCP) In addition to this REST API, Share of Model exposes a **Model Context Protocol** server that lets AI assistants (Claude Desktop, Claude Code, MCP Inspector, custom agents…) call our endpoints directly as tools. Any MCP-compatible client can interact with Share of Model without writing custom integration code — connect once with your usual login and start asking the assistant to query the data for you. ### Connecting from Claude Desktop Open **Settings → Connectors**, scroll to the bottom and click **Add custom connector**, then paste `https://mcp.shareofmodel.ai/mcp/`. A browser window opens for you to log in with your Share of Model account (same login as the web app), and the assistant gains access to the tools. ### Connecting from Claude Code ```bash claude mcp add --transport http share-of-model https://mcp.shareofmodel.ai/mcp/ ``` The first time you call a tool, Claude Code opens your browser to complete the login. ### Connecting from MCP Inspector ```bash npx @modelcontextprotocol/inspector ``` In the Inspector UI, pick **Streamable HTTP** as transport, paste `https://mcp.shareofmodel.ai/mcp/`, and click **Connect**. The first connection prompts you to log in. ### Available tools Only endpoints tagged `mcp` in this OpenAPI spec are exposed as MCP tools, and only read-only (`GET`) routes are exposed. Everything tagged `mcp` below is callable from any compliant MCP client. ### Example prompts Once connected, try asking your assistant things like: - _"List the workspaces I have access to."_ - _"Show me the latest searches in workspace X."_ - _"Compare the share of model between brand A and brand B over the last 30 days."_ For more details on the protocol itself, see the [Model Context Protocol specification](https://modelcontextprotocol.io/). servers: - description: Production API url: https://api.shareofmodel.ai/ - description: Development API url: https://api.dev.shareofmodel.ai/ security: [] tags: - name: Auth description: Endpoints needed for API authentication. - name: Organizations description: Endpoints related to organizations, to list all available organizations. - name: Workspaces description: Endpoints related to workspaces, to list all available workspaces. - name: Analyses description: Endpoints related to analyses and analyses management. - name: Asset Evaluations description: Endpoints related to assets and asset evaluations. - name: Brand Catalog description: Endpoints related to general brand information. - name: Content Briefs description: Endpoints related to content briefs generation and optimisation. - name: Metrics description: >+ Endpoints related to brand metrics. **LEXICON** **Brand Awareness**: What opinion the LLMs have concerning specific brands, related to certain categories. **Brand Perception**: The general sentiment of the LLMs towards a brand, based on the pros and cons they mention. paths: /v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations: post: tags: - Campaign Optimizations summary: Create campaign optimization description: >- Create a new campaign optimization. Required permission: `write:analysis`. **Top-level optional field (Google Ads only):** - `promotion_type` (optional): Optimisation intent. Values: `Product`, `Service`, `Brand` (case-insensitive). Stored as `campaign.intent` (lowercase). Ignored for TikTok. **Google Ads enrichment:** On creation, Jarvis fetches live metadata from Google Ads for each asset group and stores it in `campaign.asset_group_info` (ad strength, status, search themes count, campaign name). The client only needs to send `asset_group_info` with `name`; the backend fills the rest. **Campaign Field Structure (`campaign` JSON)** The `campaign` field is a free-form JSON object whose structure depends on the platform. **Google Ads (PMax):** ```json { "customer_id": "1447066043/8965287694", "asset_group_ids": ["6476435676", "6481074503"], "intent": "product", "asset_group_info": { "6476435676": { "name": "Animalerie", "ad_strength": "POOR", "ad_strength_score": 10, "ad_strength_max": 25, "search_themes_count": 0, "campaign_name": "PMax: IKOM - Smart Shopping CSS", "status": "ENABLED" } } } ``` Fields: - `customer_id` (string): Google Ads customer ID, format `"manager_id/account_id"` or `"account_id"`. - `asset_group_ids` (string[]): Asset group IDs selected for optimization. - `intent` (string, optional): Optimization intent (`product`, `service`, `brand`). Set from `promotion_type`. - `asset_group_info` (object): Mapping of asset group ID to metadata. Enriched with live Google Ads data at creation: - `name` (string): Asset group name. - `ad_strength` (string): Google Ads enum — `EXCELLENT`, `GOOD`, `AVERAGE`, `POOR`, `PENDING`, `UNKNOWN`, `UNSPECIFIED`, `NO_ADS`. - `ad_strength_score` (int): Numeric score — EXCELLENT=25, GOOD=20, AVERAGE=15, POOR=10, all others=0. - `ad_strength_max` (int): Always 25 (max possible score). - `search_themes_count` (int): Number of search theme signals currently on the asset group in Google Ads. - `campaign_name` (string): Parent PMax campaign name. - `status` (string): Asset group status — `ENABLED`, `PAUSED`, `REMOVED`, etc. Use `POST .../refresh` to re-fetch `asset_group_info` from Google Ads without re-running the optimization pipeline. **TikTok:** ```json { "advertiser_id": "7052316759499587586", "campaign_id": "1850667377518002", "ad_group_ids": ["1850939823278113", "1850667437045906"], "ad_group_names": { "1850939823278113": "Ad Group Name 1", "1850667437045906": "Ad Group Name 2" } } ``` Fields: - `advertiser_id` (string): TikTok advertiser account ID. - `campaign_id` (string): TikTok campaign ID. - `ad_group_ids` (string[]): Ad group IDs to optimize (non-empty). - `ad_group_names` (object, optional): Mapping of ad group ID to ad group name. Supply this at creation time so the activation page can display names without making additional TikTok API calls. TikTok campaign objects do **not** include `asset_group_info` or enrichment fields. operationId: create_campaign_optimization parameters: - in: query name: format schema: type: string enum: - csv - json - in: path name: organization_id schema: type: string required: true - in: path name: workspace_id schema: type: string format: uuid required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/CampaignOptimizationInput' examples: GoogleAdsCampaignOptimization: value: workspace_id: 311ee332-4594-4549-a8c4-df7f21f67751 organization_id: 804daa6c-8c04-4e95-a6c6-1ad37296815b platform_integration_id: 42b25fbd-02e0-4252-a75d-3632b8d80a86 analysis_id: 8b4b3b1b-0b3b-4b3b-8b3b-0b3b4b3b8b3b platform: google_ads campaign: customer_id: 9088979976/9088979976 asset_group_ids: - '6574388623' asset_group_info: '6574388623': name: 'Asset Group : Test Campaign (PMAX)' name: Google Ads Campaign Optimization language: en promotion_type: Product summary: Example request for Google Ads platform TikTokCampaignOptimization: value: workspace_id: 311ee332-4594-4549-a8c4-df7f21f67751 organization_id: 804daa6c-8c04-4e95-a6c6-1ad37296815b platform_integration_id: 4c601196-aa58-4f61-87ec-7acd9c49fbdc analysis_id: 8b4b3b1b-0b3b-4b3b-8b3b-0b3b4b3b8b3b platform: tiktok campaign: advertiser_id: '7052316759499587586' campaign_id: '1850667377518002' ad_group_ids: - '1850939823278113' - '1850667437045906' ad_group_names: '1850939823278113': Ad Group Name 1 '1850667437045906': Ad Group Name 2 name: TikTok Campaign Optimization language: en summary: Example request for TikTok platform application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CampaignOptimizationInput' examples: GoogleAdsCampaignOptimization: value: workspace_id: 311ee332-4594-4549-a8c4-df7f21f67751 organization_id: 804daa6c-8c04-4e95-a6c6-1ad37296815b platform_integration_id: 42b25fbd-02e0-4252-a75d-3632b8d80a86 analysis_id: 8b4b3b1b-0b3b-4b3b-8b3b-0b3b4b3b8b3b platform: google_ads campaign: customer_id: 9088979976/9088979976 asset_group_ids: - '6574388623' asset_group_info: '6574388623': name: 'Asset Group : Test Campaign (PMAX)' name: Google Ads Campaign Optimization language: en promotion_type: Product summary: Example request for Google Ads platform TikTokCampaignOptimization: value: workspace_id: 311ee332-4594-4549-a8c4-df7f21f67751 organization_id: 804daa6c-8c04-4e95-a6c6-1ad37296815b platform_integration_id: 4c601196-aa58-4f61-87ec-7acd9c49fbdc analysis_id: 8b4b3b1b-0b3b-4b3b-8b3b-0b3b4b3b8b3b platform: tiktok campaign: advertiser_id: '7052316759499587586' campaign_id: '1850667377518002' ad_group_ids: - '1850939823278113' - '1850667437045906' ad_group_names: '1850939823278113': Ad Group Name 1 '1850667437045906': Ad Group Name 2 name: TikTok Campaign Optimization language: en summary: Example request for TikTok platform multipart/form-data: schema: $ref: '#/components/schemas/CampaignOptimizationInput' examples: GoogleAdsCampaignOptimization: value: workspace_id: 311ee332-4594-4549-a8c4-df7f21f67751 organization_id: 804daa6c-8c04-4e95-a6c6-1ad37296815b platform_integration_id: 42b25fbd-02e0-4252-a75d-3632b8d80a86 analysis_id: 8b4b3b1b-0b3b-4b3b-8b3b-0b3b4b3b8b3b platform: google_ads campaign: customer_id: 9088979976/9088979976 asset_group_ids: - '6574388623' asset_group_info: '6574388623': name: 'Asset Group : Test Campaign (PMAX)' name: Google Ads Campaign Optimization language: en promotion_type: Product summary: Example request for Google Ads platform TikTokCampaignOptimization: value: workspace_id: 311ee332-4594-4549-a8c4-df7f21f67751 organization_id: 804daa6c-8c04-4e95-a6c6-1ad37296815b platform_integration_id: 4c601196-aa58-4f61-87ec-7acd9c49fbdc analysis_id: 8b4b3b1b-0b3b-4b3b-8b3b-0b3b4b3b8b3b platform: tiktok campaign: advertiser_id: '7052316759499587586' campaign_id: '1850667377518002' ad_group_ids: - '1850939823278113' - '1850667437045906' ad_group_names: '1850939823278113': Ad Group Name 1 '1850667437045906': Ad Group Name 2 name: TikTok Campaign Optimization language: en summary: Example request for TikTok platform '*/*': schema: $ref: '#/components/schemas/CampaignOptimizationInput' examples: GoogleAdsCampaignOptimization: value: workspace_id: 311ee332-4594-4549-a8c4-df7f21f67751 organization_id: 804daa6c-8c04-4e95-a6c6-1ad37296815b platform_integration_id: 42b25fbd-02e0-4252-a75d-3632b8d80a86 analysis_id: 8b4b3b1b-0b3b-4b3b-8b3b-0b3b4b3b8b3b platform: google_ads campaign: customer_id: 9088979976/9088979976 asset_group_ids: - '6574388623' asset_group_info: '6574388623': name: 'Asset Group : Test Campaign (PMAX)' name: Google Ads Campaign Optimization language: en promotion_type: Product summary: Example request for Google Ads platform TikTokCampaignOptimization: value: workspace_id: 311ee332-4594-4549-a8c4-df7f21f67751 organization_id: 804daa6c-8c04-4e95-a6c6-1ad37296815b platform_integration_id: 4c601196-aa58-4f61-87ec-7acd9c49fbdc analysis_id: 8b4b3b1b-0b3b-4b3b-8b3b-0b3b4b3b8b3b platform: tiktok campaign: advertiser_id: '7052316759499587586' campaign_id: '1850667377518002' ad_group_ids: - '1850939823278113' - '1850667437045906' ad_group_names: '1850939823278113': Ad Group Name 1 '1850667437045906': Ad Group Name 2 name: TikTok Campaign Optimization language: en summary: Example request for TikTok platform required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CampaignOptimization' text/csv: schema: $ref: '#/components/schemas/CampaignOptimization' description: The created campaign optimization. '400': description: Invalid input data. security: - Bearer: [] components: schemas: CampaignOptimizationInput: type: object properties: workspace_id: type: string format: uuid organization_id: type: string format: uuid platform_integration_id: type: string format: uuid analysis_id: type: string format: uuid platform: enum: - google_ads - tiktok type: string description: |- * `google_ads` - google ads * `tiktok` - tiktok x-spec-enum-id: 56e9e914e95b1bf9 campaign: type: object additionalProperties: {} name: type: string default: '' language: enum: - ar - da - de - en - es - eu - fi - fil - fr - he - hi - hu - id - it - ja - ko - nl - pl - pt - ro - sv - th - tr - ur - vi - zh - zh-TW type: string description: |- * `ar` - ar * `da` - da * `de` - de * `en` - en * `es` - es * `eu` - eu * `fi` - fi * `fil` - fil * `fr` - fr * `he` - he * `hi` - hi * `hu` - hu * `id` - id * `it` - it * `ja` - ja * `ko` - ko * `nl` - nl * `pl` - pl * `pt` - pt * `ro` - ro * `sv` - sv * `th` - th * `tr` - tr * `ur` - ur * `vi` - vi * `zh` - zh * `zh-TW` - zh TW x-spec-enum-id: eb433b6ba098186f default: en promotion_type: enum: - Product - Service - Brand - null type: string x-spec-enum-id: 2c23e5a868396ea4 nullable: true description: >- Optimisation intent. Only used for Google Ads (PMax); ignored for other platforms. Allowed values: Product, Service, Brand. Stored as campaign.intent (lowercase). * `Product` - Product * `Service` - Service * `Brand` - Brand required: - analysis_id - campaign - organization_id - platform - platform_integration_id - workspace_id CampaignOptimization: type: object properties: id: type: string format: uuid readOnly: true created_at: type: string format: date-time readOnly: true title: Created workspace_id: type: string format: uuid platform_integration_id: type: string format: uuid status: enum: - pending - in_progress - completed - failed - suggestions_applied type: string description: |- * `pending` - pending * `in_progress` - in progress * `completed` - completed * `failed` - failed * `suggestions_applied` - suggestions applied x-spec-enum-id: eae3ee0747a684c4 platform: enum: - google_ads - tiktok type: string description: |- * `google_ads` - google ads * `tiktok` - tiktok x-spec-enum-id: 56e9e914e95b1bf9 campaign: {} language: enum: - ar - da - de - en - es - eu - fi - fil - fr - he - hi - hu - id - it - ja - ko - nl - pl - pt - ro - sv - th - tr - ur - vi - zh - zh-TW - '' type: string description: |- * `ar` - ar * `da` - da * `de` - de * `en` - en * `es` - es * `eu` - eu * `fi` - fi * `fil` - fil * `fr` - fr * `he` - he * `hi` - hi * `hu` - hu * `id` - id * `it` - it * `ja` - ja * `ko` - ko * `nl` - nl * `pl` - pl * `pt` - pt * `ro` - ro * `sv` - sv * `th` - th * `tr` - tr * `ur` - ur * `vi` - vi * `zh` - zh * `zh-TW` - zh TW x-spec-enum-id: eb433b6ba098186f name: type: string maxLength: 255 analysis: type: string format: uuid required: - analysis - campaign - created_at - id - name - platform - platform_integration_id - workspace_id securitySchemes: Bearer: type: apiKey in: header name: Authorization ````