> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superlaunch.pro/llms.txt
> Use this file to discover all available pages before exploring further.
# Launcher launch tools
> Discover exact provider assets and targets before preparing a launch.
Discover exact provider assets and targets before preparing a launch. Preview reserves nothing. Submission uses one stable request key and returns work to track. Read operation results before retrying; corrected replacement inputs require a new request key.
The tables list arguments and common nested fields. Expand **Full input schema** for all fields and allowed values. Workspace and account permissions apply to every tool.
## launcher\_promotion\_sources\_list
Find ads created by earlier tests that are available for promotion.
**Access:** `mcp:read`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `limit` | integer | `50` | minimum: `1`. maximum: `100`. |
| `after_id` | uuid or null | `null` | Pagination cursor from the preceding result. |
```json theme={null}
{
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"limit": {
"default": 50,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"after_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"ad_account_id"
],
"type": "object"
}
```
## launcher\_assets\_list
Find Meta Pages, Instagram accounts, pixels, audiences, and other assets by name.
Pages, apps, pixels, and audiences use the selected ad account. Forms, Instagram accounts, and catalogs require a Page ID in `parent_id`. Product sets require a catalog ID in `parent_id` plus a `page_id`.
Pages and Instagram accounts use imported data; check `sync_status` and `synced_at`. Other asset types use live Meta reads. Follow `next_cursor` for more results. Launch validation checks whether the selected assets can be used.
**Access:** `mcp:read`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `kind` | pages, instagram\_accounts, pixels, applications, lead\_forms, product\_catalogs, product\_sets, custom\_audiences | Required | Supported discovery edges, never arbitrary Graph paths. |
| `parent_id` | string or null | `null` | |
| `page_id` | string or null | `null` | |
| `limit` | integer | `50` | minimum: `1`. maximum: `100`. |
| `cursor` | string or null | `null` | |
```json theme={null}
{
"$defs": {
"AssetKind": {
"description": "Supported discovery edges, never arbitrary Graph paths.",
"enum": [
"pages",
"instagram_accounts",
"pixels",
"applications",
"lead_forms",
"product_catalogs",
"product_sets",
"custom_audiences"
],
"type": "string"
}
},
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"kind": {
"$ref": "#/$defs/AssetKind"
},
"parent_id": {
"anyOf": [
{
"pattern": "^[0-9]{1,32}$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"type": [
"string",
"null"
]
},
"page_id": {
"anyOf": [
{
"pattern": "^[0-9]{1,32}$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"type": [
"string",
"null"
]
},
"limit": {
"default": 50,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"cursor": {
"anyOf": [
{
"maxLength": 4096,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"ad_account_id",
"kind"
],
"type": "object"
}
```
## launcher\_targets\_list
List current ad sets for the account. Read the chosen target before previewing a launch.
**Access:** `mcp:read`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `limit` | integer | `50` | minimum: `1`. maximum: `100`. |
| `cursor` | string or null | `null` | |
```json theme={null}
{
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"limit": {
"default": 50,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"cursor": {
"anyOf": [
{
"maxLength": 4096,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"ad_account_id"
],
"type": "object"
}
```
## launcher\_targets\_get
Read an ad set's account, parent campaign, current settings, and validation fingerprint.
**Access:** `mcp:read`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `adset_id` | string | Required | pattern: `^[0-9]{1,32}$`. |
| `campaign_id` | string or null | `null` | |
```json theme={null}
{
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"adset_id": {
"pattern": "^[0-9]{1,32}$",
"type": "string"
},
"campaign_id": {
"anyOf": [
{
"pattern": "^[0-9]{1,32}$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"ad_account_id",
"adset_id"
],
"type": "object"
}
```
## launcher\_launches\_preview
Check approved content, planned Meta objects, and estimated usage. A preview does not reserve capacity.
**Access:** `mcp:read`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `request` | object | Required | Launch inputs, including the account, content selection, template, and timing. |
### request fields
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `schema_version` | 1 | `1` | Input format version. |
| `name` | string | `"Launch"` | minLength: `1`. maxLength: `200`. |
| `request_key` | string | Required | minLength: `1`. maxLength: `200`. |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `operation` | test, promote, refresh | Required | Launch type: test, promote, or refresh. |
| `purpose` | test, scale | Required | Purpose recorded for the launch. |
| `template_version_id` | uuid | Required | Exact saved template version to use. |
| `selection` | object | Required | Direct or pinned collection selection with explicit exclusions. |
| `repeat_across_groups` | boolean | `false` | |
| `manual_groups` | array of object | `[]` | maxItems: `100`. |
| `requested_status` | PAUSED, ACTIVE | `"PAUSED"` | Requested provider status, distinct from actual delivery. |
| `scheduled_at` | date-time or null | `null` | Launch date and time, including the UTC offset. |
| `source_launch_item_ids` | array of uuid | `[]` | Earlier launch items selected for promotion. |
| `target` | object or null | `null` | |
| `retest_reason` | string or null | `null` | Reason for testing previously used content again. |
| `replacement` | object or null | `null` | Failed-item replacement details from the replacement-candidates tool. |
```json theme={null}
{
"$defs": {
"BudgetConfig": {
"additionalProperties": false,
"description": "One budget owner and period using integer currency minor units.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"owner": {
"enum": [
"campaign",
"adset"
],
"type": "string"
},
"period": {
"enum": [
"daily",
"lifetime"
],
"type": "string"
},
"amount_minor": {
"exclusiveMinimum": 0,
"maximum": 9223372036854775807,
"type": "integer"
},
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
}
},
"required": [
"owner",
"period",
"amount_minor",
"currency"
],
"type": "object"
},
"ExistingTargetSpec": {
"additionalProperties": false,
"description": "Exact provider target chosen from fresh account reads.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"campaign_id": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"adset_id": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"settings_fingerprint": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
}
},
"required": [
"campaign_id",
"adset_id",
"settings_fingerprint"
],
"type": "object"
},
"FilterCondition": {
"additionalProperties": false,
"description": "Conditions combine with AND; their values combine with OR.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"field": {
"enum": [
"name",
"concept",
"language",
"format",
"tags",
"source",
"imported_at"
],
"type": "string"
},
"operator": {
"enum": [
"eq",
"contains",
"in",
"gte",
"lte"
],
"type": "string"
},
"values": {
"items": {
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"operator",
"values"
],
"type": "object"
},
"FilterSpec": {
"additionalProperties": false,
"description": "Versioned server filter definition.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"conditions": {
"default": [],
"items": {
"$ref": "#/$defs/FilterCondition"
},
"maxItems": 30,
"type": "array"
}
},
"type": "object"
},
"ManualGroup": {
"additionalProperties": false,
"description": "One stable user-assigned group over explicit creative families.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"group_key": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"creative_ids": {
"default": [],
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 1000,
"type": "array"
},
"targeting": {
"anyOf": [
{
"$ref": "#/$defs/TargetingConfig"
},
{
"type": "null"
}
],
"default": null
},
"budget": {
"anyOf": [
{
"$ref": "#/$defs/BudgetConfig"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"group_key"
],
"type": "object"
},
"ProviderLocation": {
"additionalProperties": false,
"description": "Exact location-search reference with optional city radius.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"kind": {
"enum": [
"region",
"city",
"zip"
],
"type": "string"
},
"key": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"radius": {
"anyOf": [
{
"exclusiveMinimum": 0,
"maximum": 1000,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"distance_unit": {
"anyOf": [
{
"enum": [
"kilometer",
"mile"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"kind",
"key"
],
"type": "object"
},
"ReplacementItem": {
"additionalProperties": false,
"description": "Fence one failed assignment and the exact approved corrected version.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"source_item_id": {
"format": "uuid",
"type": "string"
},
"creative_version_id": {
"format": "uuid",
"type": "string"
},
"expected_ad_attempt": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"source_item_id",
"creative_version_id",
"expected_ad_attempt"
],
"type": "object"
},
"ReplacementSpec": {
"additionalProperties": false,
"description": "A new request links a bounded corrected subset to retained source history.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"launch_id": {
"format": "uuid",
"type": "string"
},
"expected_version": {
"minimum": 1,
"type": "integer"
},
"items": {
"items": {
"$ref": "#/$defs/ReplacementItem"
},
"maxItems": 1000,
"minItems": 1,
"type": "array"
}
},
"required": [
"launch_id",
"expected_version",
"items"
],
"type": "object"
},
"RequestedStatus": {
"description": "Requested provider status, distinct from actual delivery.",
"enum": [
"PAUSED",
"ACTIVE"
],
"type": "string"
},
"SelectionSpec": {
"additionalProperties": false,
"description": "Direct or pinned collection selection with explicit exclusions.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"kind": {
"enum": [
"direct",
"fixed",
"smart"
],
"type": "string"
},
"creative_ids": {
"default": [],
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 1000,
"type": "array"
},
"excluded_ids": {
"default": [],
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 1000,
"type": "array"
},
"collection_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_lock_version": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"filter_spec": {
"anyOf": [
{
"$ref": "#/$defs/FilterSpec"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"kind"
],
"type": "object"
},
"TargetingConfig": {
"additionalProperties": false,
"description": "Country and audience controls with independent exclusions.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"countries": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"excluded_countries": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"included_locations": {
"default": [],
"items": {
"$ref": "#/$defs/ProviderLocation"
},
"maxItems": 100,
"type": "array"
},
"excluded_locations": {
"default": [],
"items": {
"$ref": "#/$defs/ProviderLocation"
},
"maxItems": 100,
"type": "array"
},
"genders": {
"default": [],
"items": {
"enum": [
1,
2
],
"type": "integer"
},
"type": "array"
},
"user_os": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 10,
"type": "array"
},
"user_device": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"advantage_audience": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"custom_audiences": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"excluded_custom_audiences": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"locales": {
"default": [],
"items": {
"type": "integer"
},
"type": "array"
},
"age_min": {
"anyOf": [
{
"maximum": 65,
"minimum": 13,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"age_max": {
"anyOf": [
{
"maximum": 65,
"minimum": 13,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"audience_semantics": {
"default": "control",
"enum": [
"control",
"suggestion"
],
"type": "string"
}
},
"type": "object"
},
"WorkspaceLaunchSubmit": {
"additionalProperties": false,
"description": "Brandless public schema with legacy receipt parsing for exact retries.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"name": {
"default": "Launch",
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"request_key": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"operation": {
"enum": [
"test",
"promote",
"refresh"
],
"type": "string"
},
"purpose": {
"enum": [
"test",
"scale"
],
"type": "string"
},
"template_version_id": {
"format": "uuid",
"type": "string"
},
"selection": {
"$ref": "#/$defs/SelectionSpec"
},
"repeat_across_groups": {
"default": false,
"type": "boolean"
},
"manual_groups": {
"default": [],
"items": {
"$ref": "#/$defs/ManualGroup"
},
"maxItems": 100,
"type": "array"
},
"requested_status": {
"$ref": "#/$defs/RequestedStatus",
"default": "PAUSED"
},
"scheduled_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_launch_item_ids": {
"default": [],
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
},
"target": {
"anyOf": [
{
"$ref": "#/$defs/ExistingTargetSpec"
},
{
"type": "null"
}
],
"default": null
},
"retest_reason": {
"anyOf": [
{
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"replacement": {
"anyOf": [
{
"$ref": "#/$defs/ReplacementSpec"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"request_key",
"ad_account_id",
"operation",
"purpose",
"template_version_id",
"selection"
],
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"request": {
"$ref": "#/$defs/WorkspaceLaunchSubmit",
"type": "object"
}
},
"required": [
"request"
],
"type": "object"
}
```
## launcher\_launches\_submit
Submit a launch with one stable `request_key`, then track its result.
To replace a failed item with corrected content, include the replacement details, approved creative version IDs, exact target, and a new request key.
**Access:** `mcp:read` and `mcp:write`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `request` | object | Required | Launch inputs, including the account, content selection, template, and timing. |
### request fields
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `schema_version` | 1 | `1` | Input format version. |
| `name` | string | `"Launch"` | minLength: `1`. maxLength: `200`. |
| `request_key` | string | Required | minLength: `1`. maxLength: `200`. |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `operation` | test, promote, refresh | Required | Launch type: test, promote, or refresh. |
| `purpose` | test, scale | Required | Purpose recorded for the launch. |
| `template_version_id` | uuid | Required | Exact saved template version to use. |
| `selection` | object | Required | Direct or pinned collection selection with explicit exclusions. |
| `repeat_across_groups` | boolean | `false` | |
| `manual_groups` | array of object | `[]` | maxItems: `100`. |
| `requested_status` | PAUSED, ACTIVE | `"PAUSED"` | Requested provider status, distinct from actual delivery. |
| `scheduled_at` | date-time or null | `null` | Launch date and time, including the UTC offset. |
| `source_launch_item_ids` | array of uuid | `[]` | Earlier launch items selected for promotion. |
| `target` | object or null | `null` | |
| `retest_reason` | string or null | `null` | Reason for testing previously used content again. |
| `replacement` | object or null | `null` | Failed-item replacement details from the replacement-candidates tool. |
**Retries:** reuse the same `request_key` with unchanged inputs for the same operation.
```json theme={null}
{
"$defs": {
"BudgetConfig": {
"additionalProperties": false,
"description": "One budget owner and period using integer currency minor units.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"owner": {
"enum": [
"campaign",
"adset"
],
"type": "string"
},
"period": {
"enum": [
"daily",
"lifetime"
],
"type": "string"
},
"amount_minor": {
"exclusiveMinimum": 0,
"maximum": 9223372036854775807,
"type": "integer"
},
"currency": {
"pattern": "^[A-Z]{3}$",
"type": "string"
}
},
"required": [
"owner",
"period",
"amount_minor",
"currency"
],
"type": "object"
},
"ExistingTargetSpec": {
"additionalProperties": false,
"description": "Exact provider target chosen from fresh account reads.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"campaign_id": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"adset_id": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"settings_fingerprint": {
"pattern": "^[0-9a-f]{64}$",
"type": "string"
}
},
"required": [
"campaign_id",
"adset_id",
"settings_fingerprint"
],
"type": "object"
},
"FilterCondition": {
"additionalProperties": false,
"description": "Conditions combine with AND; their values combine with OR.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"field": {
"enum": [
"name",
"concept",
"language",
"format",
"tags",
"source",
"imported_at"
],
"type": "string"
},
"operator": {
"enum": [
"eq",
"contains",
"in",
"gte",
"lte"
],
"type": "string"
},
"values": {
"items": {
"type": "string"
},
"maxItems": 100,
"minItems": 1,
"type": "array"
}
},
"required": [
"field",
"operator",
"values"
],
"type": "object"
},
"FilterSpec": {
"additionalProperties": false,
"description": "Versioned server filter definition.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"conditions": {
"default": [],
"items": {
"$ref": "#/$defs/FilterCondition"
},
"maxItems": 30,
"type": "array"
}
},
"type": "object"
},
"ManualGroup": {
"additionalProperties": false,
"description": "One stable user-assigned group over explicit creative families.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"group_key": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"creative_ids": {
"default": [],
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 1000,
"type": "array"
},
"targeting": {
"anyOf": [
{
"$ref": "#/$defs/TargetingConfig"
},
{
"type": "null"
}
],
"default": null
},
"budget": {
"anyOf": [
{
"$ref": "#/$defs/BudgetConfig"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"group_key"
],
"type": "object"
},
"ProviderLocation": {
"additionalProperties": false,
"description": "Exact location-search reference with optional city radius.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"kind": {
"enum": [
"region",
"city",
"zip"
],
"type": "string"
},
"key": {
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"radius": {
"anyOf": [
{
"exclusiveMinimum": 0,
"maximum": 1000,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"distance_unit": {
"anyOf": [
{
"enum": [
"kilometer",
"mile"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"kind",
"key"
],
"type": "object"
},
"ReplacementItem": {
"additionalProperties": false,
"description": "Fence one failed assignment and the exact approved corrected version.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"source_item_id": {
"format": "uuid",
"type": "string"
},
"creative_version_id": {
"format": "uuid",
"type": "string"
},
"expected_ad_attempt": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"source_item_id",
"creative_version_id",
"expected_ad_attempt"
],
"type": "object"
},
"ReplacementSpec": {
"additionalProperties": false,
"description": "A new request links a bounded corrected subset to retained source history.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"launch_id": {
"format": "uuid",
"type": "string"
},
"expected_version": {
"minimum": 1,
"type": "integer"
},
"items": {
"items": {
"$ref": "#/$defs/ReplacementItem"
},
"maxItems": 1000,
"minItems": 1,
"type": "array"
}
},
"required": [
"launch_id",
"expected_version",
"items"
],
"type": "object"
},
"RequestedStatus": {
"description": "Requested provider status, distinct from actual delivery.",
"enum": [
"PAUSED",
"ACTIVE"
],
"type": "string"
},
"SelectionSpec": {
"additionalProperties": false,
"description": "Direct or pinned collection selection with explicit exclusions.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"kind": {
"enum": [
"direct",
"fixed",
"smart"
],
"type": "string"
},
"creative_ids": {
"default": [],
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 1000,
"type": "array"
},
"excluded_ids": {
"default": [],
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 1000,
"type": "array"
},
"collection_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_lock_version": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"filter_spec": {
"anyOf": [
{
"$ref": "#/$defs/FilterSpec"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"kind"
],
"type": "object"
},
"TargetingConfig": {
"additionalProperties": false,
"description": "Country and audience controls with independent exclusions.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"countries": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"excluded_countries": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"included_locations": {
"default": [],
"items": {
"$ref": "#/$defs/ProviderLocation"
},
"maxItems": 100,
"type": "array"
},
"excluded_locations": {
"default": [],
"items": {
"$ref": "#/$defs/ProviderLocation"
},
"maxItems": 100,
"type": "array"
},
"genders": {
"default": [],
"items": {
"enum": [
1,
2
],
"type": "integer"
},
"type": "array"
},
"user_os": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 10,
"type": "array"
},
"user_device": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 100,
"type": "array"
},
"advantage_audience": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"custom_audiences": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"excluded_custom_audiences": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"locales": {
"default": [],
"items": {
"type": "integer"
},
"type": "array"
},
"age_min": {
"anyOf": [
{
"maximum": 65,
"minimum": 13,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"age_max": {
"anyOf": [
{
"maximum": 65,
"minimum": 13,
"type": "integer"
},
{
"type": "null"
}
],
"default": null
},
"audience_semantics": {
"default": "control",
"enum": [
"control",
"suggestion"
],
"type": "string"
}
},
"type": "object"
},
"WorkspaceLaunchSubmit": {
"additionalProperties": false,
"description": "Brandless public schema with legacy receipt parsing for exact retries.",
"properties": {
"schema_version": {
"const": 1,
"default": 1,
"type": "integer"
},
"name": {
"default": "Launch",
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"request_key": {
"maxLength": 200,
"minLength": 1,
"type": "string"
},
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"operation": {
"enum": [
"test",
"promote",
"refresh"
],
"type": "string"
},
"purpose": {
"enum": [
"test",
"scale"
],
"type": "string"
},
"template_version_id": {
"format": "uuid",
"type": "string"
},
"selection": {
"$ref": "#/$defs/SelectionSpec"
},
"repeat_across_groups": {
"default": false,
"type": "boolean"
},
"manual_groups": {
"default": [],
"items": {
"$ref": "#/$defs/ManualGroup"
},
"maxItems": 100,
"type": "array"
},
"requested_status": {
"$ref": "#/$defs/RequestedStatus",
"default": "PAUSED"
},
"scheduled_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_launch_item_ids": {
"default": [],
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
},
"target": {
"anyOf": [
{
"$ref": "#/$defs/ExistingTargetSpec"
},
{
"type": "null"
}
],
"default": null
},
"retest_reason": {
"anyOf": [
{
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"replacement": {
"anyOf": [
{
"$ref": "#/$defs/ReplacementSpec"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"request_key",
"ad_account_id",
"operation",
"purpose",
"template_version_id",
"selection"
],
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"request": {
"$ref": "#/$defs/WorkspaceLaunchSubmit",
"type": "object"
}
},
"required": [
"request"
],
"type": "object"
}
```
## launcher\_launches\_list
List launches with the newest first. For the next page, pass the returned `next_cursor` as `after_id` and keep the same account.
**Access:** `mcp:read`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `limit` | integer | `50` | minimum: `1`. maximum: `100`. |
| `after_id` | uuid or null | `null` | Pagination cursor from the preceding result. |
```json theme={null}
{
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"limit": {
"default": 50,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"after_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"ad_account_id"
],
"type": "object"
}
```
## launcher\_launches\_get
Read launch status and links to the operation results.
**Access:** `mcp:read`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `launch_id` | uuid | Required | Launch UUID from submission or `launcher_launches_list`. |
```json theme={null}
{
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"launch_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"ad_account_id",
"launch_id"
],
"type": "object"
}
```
## launcher\_launches\_change\_status
Hold or resume an unstarted run; a missed time requires Run now or a new time.
**Access:** `mcp:read` and `mcp:write`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `launch_id` | uuid | Required | Launch UUID from submission or `launcher_launches_list`. |
| `enabled` | boolean | Required | |
| `expected_version` | integer | Required | minimum: `1`. |
| `scheduled_at` | date-time or null | `null` | Launch date and time, including the UTC offset. |
| `run_now` | boolean | `false` | Run a held launch now rather than wait for a new time. |
**Retries:** read the current state after a timeout. If the change has already applied, do not submit it again with an old version.
```json theme={null}
{
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"launch_id": {
"format": "uuid",
"type": "string"
},
"enabled": {
"type": "boolean"
},
"expected_version": {
"minimum": 1,
"type": "integer"
},
"scheduled_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"type": [
"string",
"null"
]
},
"run_now": {
"default": false,
"type": "boolean"
}
},
"required": [
"ad_account_id",
"launch_id",
"enabled",
"expected_version"
],
"type": "object"
}
```
## launcher\_launches\_cancel
Request cancellation of a launch. Existing Meta objects remain, and a write already in progress may still finish. Read the result to confirm what stopped.
**Access:** `mcp:read` and `mcp:write`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `launch_id` | uuid | Required | Launch UUID from submission or `launcher_launches_list`. |
| `expected_version` | integer | Required | minimum: `1`. |
**Retries:** read the current state after a timeout. If the change has already applied, do not submit it again with an old version.
```json theme={null}
{
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"launch_id": {
"format": "uuid",
"type": "string"
},
"expected_version": {
"minimum": 1,
"type": "integer"
}
},
"required": [
"ad_account_id",
"launch_id",
"expected_version"
],
"type": "object"
}
```
## launcher\_launches\_replacement\_candidates
Find failed items eligible for replacement with corrected content. Approve the new version, check the target, then preview and submit with the returned replacement details and a new request key. Leave successful items and items with uncertain outcomes unchanged.
**Access:** `mcp:read`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `launch_id` | uuid | Required | Launch UUID from submission or `launcher_launches_list`. |
| `limit` | integer | `50` | minimum: `1`. maximum: `100`. |
| `after_id` | uuid or null | `null` | Pagination cursor from the preceding result. |
```json theme={null}
{
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"launch_id": {
"format": "uuid",
"type": "string"
},
"limit": {
"default": 50,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"after_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"ad_account_id",
"launch_id"
],
"type": "object"
}
```
## launcher\_run\_operations
Read the result and attempt history of each launch operation.
**Access:** `mcp:read`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `launch_id` | uuid | Required | Launch UUID from submission or `launcher_launches_list`. |
| `limit` | integer | `50` | minimum: `1`. maximum: `100`. |
| `after_id` | uuid or null | `null` | Pagination cursor from the preceding result. |
```json theme={null}
{
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"launch_id": {
"format": "uuid",
"type": "string"
},
"limit": {
"default": 50,
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"after_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"type": [
"string",
"null"
]
}
},
"required": [
"ad_account_id",
"launch_id"
],
"type": "object"
}
```
## launcher\_launches\_retry
Retry eligible failed operations with their original inputs. Superlaunch blocks retries when it cannot confirm whether Meta already changed. For operations that failed before any attempt, use attempt `0` in `expected_attempts`.
**Access:** `mcp:read` and `mcp:write`.
| Parameter | Type | Required / default | Details |
| - | - | - | - |
| `ad_account_id` | uuid | Required | Superlaunch account UUID from `ad_accounts_list`. |
| `launch_id` | uuid | Required | Launch UUID from submission or `launcher_launches_list`. |
| `expected_version` | integer | Required | minimum: `1`. |
| `expected_attempts` | object | Required | Current attempt number for each operation selected for retry. |
**Retries:** read the current state after a timeout. If the change has already applied, do not submit it again with an old version.
```json theme={null}
{
"additionalProperties": false,
"properties": {
"ad_account_id": {
"format": "uuid",
"type": "string"
},
"launch_id": {
"format": "uuid",
"type": "string"
},
"expected_version": {
"minimum": 1,
"type": "integer"
},
"expected_attempts": {
"additionalProperties": {
"minimum": 0,
"type": "integer"
},
"maxProperties": 5000,
"minProperties": 1,
"propertyNames": {
"format": "uuid"
},
"type": "object"
}
},
"required": [
"ad_account_id",
"launch_id",
"expected_version",
"expected_attempts"
],
"type": "object"
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.