MCP tool

sync_audience

Build an audience from the exposure ledger (households exposed on some channels and not others) and sync it to an adapter on the target channel as an inclusion or suppression audience — the sequencing primitive (e.g. billboard-exposed households retargeted on CTV). Returns the sync record with matched count and key-grade breakdown. Copy adapterKey and executionMode from the selected get_journeys suggestion exactly; the API rejects provider or mode drift.

Input

Pass fields from this schema as the tool arguments. Runtime ownership, product scope and readiness checks still apply.

Input JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "campaignId": {
      "type": "string",
      "description": "campaign id whose ledger to query"
    },
    "agentStepId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "pending execute-step id that consumed the exact approved action"
    },
    "expectedActionDigest": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "SHA-256 digest returned for the exact approved action"
    },
    "exposedOn": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "ctv",
          "audio",
          "tv",
          "cinema",
          "dooh",
          "search",
          "social"
        ]
      },
      "description": "channels the audience WAS exposed on"
    },
    "notExposedOn": {
      "default": [],
      "description": "channels the audience was NOT exposed on",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "ctv",
          "audio",
          "tv",
          "cinema",
          "dooh",
          "search",
          "social"
        ]
      }
    },
    "channel": {
      "type": "string",
      "enum": [
        "ctv",
        "audio",
        "tv",
        "cinema",
        "dooh",
        "search",
        "social"
      ],
      "description": "target channel to sync the audience to"
    },
    "purpose": {
      "type": "string",
      "enum": [
        "inclusion",
        "suppression"
      ],
      "description": "use the audience to include or suppress"
    },
    "adapterKey": {
      "type": "string",
      "description": "exact adapterKey returned by the selected get_journeys suggestion"
    },
    "executionMode": {
      "type": "string",
      "enum": [
        "sandbox",
        "live"
      ],
      "description": "exact executionMode returned with the selected get_journeys suggestion"
    }
  },
  "required": [
    "campaignId",
    "agentStepId",
    "expectedActionDigest",
    "exposedOn",
    "channel",
    "purpose",
    "adapterKey",
    "executionMode"
  ]
}

REST mapping and authority

The tool wraps this REST endpoint. The mapping identifies path/query/body transformations and approval or idempotency headers.

Request contract

{
  "method": "POST",
  "path": "/api/v1/campaigns/{campaignId}/sync-audience",
  "pathFields": [
    "campaignId"
  ],
  "pathSchema": {
    "type": "object",
    "properties": {
      "campaignId": {
        "type": "string",
        "description": "campaign id whose ledger to query"
      }
    },
    "additionalProperties": false,
    "required": [
      "campaignId"
    ]
  },
  "pathEncoding": "encodeURIComponent for each path field",
  "governedAction": "audience.sync",
  "headers": {
    "x-chorus-agent-step-id": "agentStepId",
    "x-chorus-agent-action-digest": "expectedActionDigest"
  },
  "bodySchema": {
    "type": "object",
    "properties": {
      "exposedOn": {
        "minItems": 1,
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "ctv",
            "audio",
            "tv",
            "cinema",
            "dooh",
            "search",
            "social"
          ]
        },
        "description": "channels the audience WAS exposed on"
      },
      "notExposedOn": {
        "default": [],
        "description": "channels the audience was NOT exposed on",
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "ctv",
            "audio",
            "tv",
            "cinema",
            "dooh",
            "search",
            "social"
          ]
        }
      },
      "channel": {
        "type": "string",
        "enum": [
          "ctv",
          "audio",
          "tv",
          "cinema",
          "dooh",
          "search",
          "social"
        ],
        "description": "target channel to sync the audience to"
      },
      "purpose": {
        "type": "string",
        "enum": [
          "inclusion",
          "suppression"
        ],
        "description": "use the audience to include or suppress"
      },
      "adapterKey": {
        "type": "string",
        "description": "exact adapterKey returned by the selected get_journeys suggestion"
      },
      "executionMode": {
        "type": "string",
        "enum": [
          "sandbox",
          "live"
        ],
        "description": "exact executionMode returned with the selected get_journeys suggestion"
      }
    },
    "additionalProperties": false,
    "required": [
      "exposedOn",
      "channel",
      "purpose",
      "adapterKey",
      "executionMode"
    ]
  },
  "responseMapping": "REST JSON is returned as MCP structuredContent and a compatibility text block; privacy-sensitive tools validate their output schema."
}

Output

This is the registered MCP output envelope. Nested fields are only modeled where the schema explicitly defines them.

Output JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "sync": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "sync"
  ],
  "additionalProperties": {}
}

Safety annotations

MCP annotations

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

Annotations help a client present the tool. The API independently enforces authorization and exact action approvals. Error and retry guidance →