Interface SyncPlansRequest

Type Declaration

• plan_id: string

  Unique identifier for this plan.

• brand: BrandReference

• objectives: string

  Natural language campaign objectives. Used for strategic alignment validation. Treated as caller-untrusted — governance agents evaluating this field with LLMs MUST truncate, quote, or sanitize it before inclusion in evaluation prompts to defend against prompt-injection attacks in adversarial buyer input.

  Max Length

  2000

• budget:
      | {
          total: number;
          currency: string;
          per_seller_max_pct?: number;
          reallocation_threshold: number;
          allocations?: {
              [k: string]: { amount?: number; max_pct?: number }
              | undefined;
          };
      }
      | {
          total: number;
          currency: string;
          per_seller_max_pct?: number;
          reallocation_unlimited: true;
          allocations?: {
              [k: string]: { amount?: number; max_pct?: number }
              | undefined;
          };
      }

  Budget authorization parameters.

• Optionalchannels?: {
      required?: MediaChannel[];
      allowed?: MediaChannel[];
      mix_targets?: {
          [k: string]: { min_pct?: number; max_pct?: number } | undefined;
      };
  }

  Channel constraints. If omitted, all channels are allowed.

  • Optionalrequired?: MediaChannel[]

    Channels that must be included in the media mix.

  • Optionalallowed?: MediaChannel[]

    Channels the orchestrator may use.

  • Optionalmix_targets?: { [k: string]: { min_pct?: number; max_pct?: number } | undefined }

    Target allocation ranges per channel, keyed by channel ID.

• flight: { start: string; end: string }

  Authorized flight dates. Governed actions with dates outside this window are rejected.

  • start: string

    Flight start (ISO 8601).

    Format

    date-time

  • end: string

    Flight end (ISO 8601).

    Format

    date-time

• Optionalcountries?: string[]

  ISO 3166-1 alpha-2 country codes for authorized markets (e.g., ['US', 'GB']). The governance agent rejects governed actions targeting outside these countries and resolves applicable policies by matching against policy jurisdictions.

• Optionalregions?: string[]

  ISO 3166-2 subdivision codes for authorized sub-national markets (e.g., ['US-MA', 'US-CA']). When present, the governance agent restricts governed actions to these specific regions rather than the full country. Use for plans limited to specific states or provinces (e.g., cannabis in legal states). Policy resolution matches against both the subdivision and its parent country.

• Optionalpolicy_ids?: string[]

  Registry policy IDs to enforce for this plan. The governance agent resolves full policy definitions from the registry and evaluates actions against them. Intersected with the plan's countries/regions to activate only geographically relevant policies.

• Optionalpolicy_categories?: string[]

  Regulatory categories that apply to this campaign. Determines which policy regimes the governance agent enforces (e.g., 'children_directed' activates COPPA/AADC, 'political_advertising' activates disclosure requirements). The governance agent resolves categories to specific policies based on the plan's jurisdictions. When omitted, governance agents MAY infer categories from the brand's industries and the plan's objectives. Values are registry-defined category IDs (intentionally freeform strings, not an enum — new categories are added as regulations evolve).

• Optionalaudience?: AudienceConstraints

• Optionalrestricted_attributes?: RestrictedAttribute[]

  Personal data categories that must not be used for targeting in this campaign. Applies horizontally across all audience criteria. Used for EU DSA Article 26 compliance (prohibits targeting on GDPR Article 9 special categories) and similar regulations. The governance agent flags any audience targeting that references these attributes.

• Optionalrestricted_attributes_custom?: string[]

  Additional restricted attributes not covered by the restricted-attribute enum. Freeform strings for jurisdiction-specific or brand-specific restrictions beyond GDPR Article 9 categories (e.g., 'financial_status', 'immigration_status'). Governance agents use semantic matching for these.

• Optionalmin_audience_size?: number

  Minimum audience segment size. Prevents micro-targeting by ensuring segments meet a k-anonymity threshold. Applies to the estimated combined (intersection) audience when multiple criteria are used, not just individual criterion sizes. The governance agent validates this by querying signal catalog metadata or seller-reported segment sizes. When segment size data is unavailable, the governance agent SHOULD produce a finding with reduced confidence rather than silently passing.

  Minimum

  1

• Optionalhuman_review_required?: boolean

  When true, the governance agent MUST escalate any action on this plan for human review before execution — regardless of budget. Required by regulations that prohibit solely automated decisions affecting data subjects (GDPR Art 22, EU AI Act Annex III): credit, insurance pricing, recruitment, housing allocation. Governance agents MUST set this to true automatically when any resolved policy or policy_category has requires_human_review: true. Distinct from budget.reallocation_threshold, which only governs budget reallocation autonomy — human_review_required covers decisions affecting individuals (targeting, creative, delivery).

• Optionalcustom_policies?: PolicyEntry[]

  Bespoke policies specific to this campaign, using the same shape as registry entries. Each policy has a policy_id, enforcement (must|should), and natural-language policy text. Governance findings reference policy_id to identify which policy triggered. For quick authoring, omit version/name/category — servers default them.

• Optionalapproved_sellers?: string[] | null

  List of approved seller agent URLs. null means any seller.

• Optionaldelegations?: {
      agent_url: string;
      authority: DelegationAuthority;
      budget_limit?: { amount: number; currency: string };
      markets?: string[];
      expires_at?: string;
  }[]

  Agents authorized to execute against this plan. Each delegation scopes an agent's authority by budget, markets, and expiration. The governance agent validates that the requesting agent matches a delegation before approving actions.

• Optionalportfolio?: {
      member_plan_ids: string[];
      total_budget_cap?: { amount: number; currency: string };
      shared_policy_ids?: string[];
      shared_exclusions?: PolicyEntry[];
  }

  Portfolio-level governance constraints. When present, this plan acts as a portfolio plan that governs member plans. Portfolio plans define cross-brand constraints that no individual brand plan can override.

  • member_plan_ids: string[]

    Plan IDs governed by this portfolio plan. The governance agent validates member plan actions against portfolio constraints.

  • Optionaltotal_budget_cap?: { amount: number; currency: string }

    Maximum aggregate budget across all member plans.

  • Optionalshared_policy_ids?: string[]

    Registry policy IDs enforced across all member plans, regardless of individual brand configuration.

  • Optionalshared_exclusions?: PolicyEntry[]

    Bespoke exclusion policies applied across all member plans, using the same shape as registry entries. Authored typically as enforcement: must policies with exclusion language in the policy text (e.g., 'No advertising on properties owned by competitor holding companies').

• Optionalext?: ExtensionObject