sync_creatives

Overview

Uploads new creatives, updates existing ones, or removes creatives no longer needed. Every creative is validated against the format specification returned by list_creative_formats. Supports dry-run mode for pre-flight validation.

Category: Creative Authentication: Required REST equivalent: POST /api/v1/media-buys/{id}/creatives

Parameters

Parameter Type Required Default Description
creatives list[dict] or None No None Creatives to create or update. See Creative fields below.
assignments dict or None No None Map of media buy IDs to lists of creative IDs to assign.
creative_ids list[str] or None No None When used with delete_missing, the canonical set of creative IDs. Any creative not in this list is deleted.
delete_missing bool No false Delete creatives owned by the caller that are not in creative_ids.
dry_run bool No false Validate inputs without persisting changes.
validation_mode str No "strict" "strict" rejects any format mismatch; "lenient" allows minor deviations.

Creative Fields

Field Type Required Default Description
creative_id str Yes – Caller-supplied unique identifier.
format_id FormatId Yes – Format spec reference (agent_url, id).
name str Yes – Human-readable creative name.
status str or None No None Initial status override (typically left as None).
assets dict Yes – Asset payload. Structure depends on format (e.g., {"url": "...", "width": 300, "height": 250} for display, {"vast_url": "..."} for video).
provenance Provenance or None No None Content provenance metadata for EU AI Act compliance. See below.

Provenance Fields

Field Type Required Description
digital_source_type str Yes How the creative was produced. See DigitalSourceType enum below.
ai_tool str or None No AI tool used (e.g., "DALL-E 3", "Midjourney v6").
human_oversight str or None No Description of human oversight during production.
declared_by str or None No Entity declaring provenance.
created_time str (ISO 8601) or None No When the creative was originally produced.
c2pa dict or None No C2PA manifest data.
disclosure str or None No Human-readable disclosure about AI involvement.
verification dict or None No Third-party verification data.

DigitalSourceType Enum

Value Description
digital_capture Captured by a digital device.
digital_creation Created by a human using digital tools.
composite_capture Composite of captured sources.
composite_synthetic Composite with fully synthetic elements.
composite_with_trained_model Composite with AI model output.
trained_algorithmic_model Generated entirely by an AI model.
algorithmic_media Generated by a non-ML algorithm.
human_edits AI-generated with significant human modifications.
minor_human_edits AI-generated with minor human edits (cropping, colour correction).

Creative Lifecycle

sync_creatives → processing → pending_review → approved → live
                     │              │
                     ▼              ▼
                  rejected       rejected

Tenants can configure automatic approval thresholds. When the content-standards score meets creative_auto_approve_threshold (default 0.9), the creative is approved without human review. Below creative_auto_reject_threshold (default 0.1), it is automatically rejected.

Response

Field Type Description
created int Number of creatives created.
updated int Number of creatives updated.
deleted int Number of creatives deleted.
results list[object] Per-creative results with creative_id, status, and errors.

Errors

Error Cause
AdCPValidationError (400) Format mismatch, missing required asset fields, or invalid format_id.
AdCPNotFoundError (404) Referenced format_id does not exist at the specified agent_url.
AdCPAuthorizationError (403) Attempting to modify creatives owned by another principal.

Example

Request:

{
  "creatives": [
    {
      "creative_id": "cr_video_001",
      "format_id": {"agent_url": "https://creative.example.com", "id": "video_30s"},
      "name": "Acme Sports CTV 30s",
      "assets": {
        "vast_url": "https://cdn.example.com/vast/acme_sports_30s.xml",
        "duration_seconds": 30,
        "resolution": "1920x1080"
      },
      "provenance": {
        "digital_source_type": "human_edits",
        "ai_tool": "RunwayML Gen-3",
        "human_oversight": "Creative director reviewed and approved final cut",
        "disclosure": "This advertisement contains AI-generated visual effects."
      }
    }
  ],
  "assignments": {
    "mb_a1b2c3d4": ["cr_video_001"]
  },
  "dry_run": false,
  "validation_mode": "strict"
}

Response:

{
  "created": 1,
  "updated": 0,
  "deleted": 0,
  "results": [
    {
      "creative_id": "cr_video_001",
      "status": "processing",
      "errors": []
    }
  ]
}

Further Reading