AdCP 3.1.13 · Creative

build_creative

build_creative request fields

The required column reflects the top-level required array only. One of the 35 request fields carries a top-level required flag: idempotency_key. A top-level if, anyOf, oneOf or dependencies block can make an unmarked field mandatory in the mode being called, and a flat table cannot render a rule that fires in one mode only. Those branches are visible in the request schema itself.

build_creative writes state. Its request schema is one of the 30 in the 64-entry registry flagged x-mutates-state: true. A repeated call is deduplicated only by idempotency_key, which this request requires. AdCP's release notes describe x-mutates-state as a non-normative tooling hint that agents do not validate, so it is the registry's classification of the operation rather than a contract, and it is the only machine-readable answer in the registry to whether an operation is safe to retry.

build_creative response fields

The response schema for build_creative declares the envelope and keeps its result in a top-level oneOf, anyOf or if, which a table of flat rows cannot represent. The branch names are in the response schema. 29 of the 64 operations are shaped that way.

The first 13 rows are the shared protocol envelope from core/version-envelope.json and core/protocol-envelope.json. Not one of the 13 rows below belongs to build_creative itself. One field in the whole response is marked required: status.

The shared protocol envelope

62 of AdCP's 64 registered operations carry every one of the 13 envelope fields. report_plan_outcome and check_governance compose core/version-envelope.json only, so they carry the version pair and none of the task fields.

status resolves to enums/task-status.json, which admits nine values: submitted, working, input-required, completed, canceled, failed, rejected, auth-required, unknown. The envelope marks it required on every response, and a synchronous call emits completed rather than omitting it. When it returns submitted or working instead, task_id is the polling handle and push_notification_config is the webhook the agent echoes back to confirm the callback. Webhooks are A2A and REST only: MCP sends progress notifications and defines no webhook.

payload appears in the response field table typed object. core/protocol-envelope.json describes it as a documentary construct and states that it is not a required wire field. Body fields are siblings of the envelope fields: on MCP at the root of the tool response, on A2A in task.artifacts[0].parts[].DataPart, on REST at the root of the JSON body. An accessor that reads response.payload finds nothing there.

Field lists are not published over the wire

AdCP's integration guide, docs/protocol/calling-an-agent.mdx, states that its MCP servers no longer publish per-tool parameter schemas: a tools/list call returns an empty properties object for every tool, and the guide directs clients not to infer shape from it. A client author reads the schema registry instead of the tool list.

Example build_creative calls

The field tables above come from the 3.1.13 schema release and these blocks come from the documentation tree, which is versioned separately, so the two can disagree.

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
  "message": "Create a banner promoting our winter sale with a warm, inviting feel",
  "target_capability_id": "display_300x250_generative",
  "brand": {
    "domain": "mybrand.com"
  },
  "creative_manifest": {
    "format_kind": "image",
    "assets": {
      "offering_catalog": {
        "asset_type": "catalog",
        "type": "offering",
        "items": [
          {
            "offering_id": "winter-sale",
            "name": "Winter Sale Collection",
            "description": "50% off all winter items"
          }
        ]
      }
    }
  }
}

{
  "$schema": "/schemas/media-buy/build-creative-request.json",
  "idempotency_key": "b2c3d4e5-f6a7-4890-b123-456789abcdef",
  "message": "Adapt this creative for mobile, making the text larger and CTA more prominent",
  "creative_manifest": {
    "format_kind": "image",
    "assets": {
      "banner_image": {
        "asset_type": "image",
        "url": "https://cdn.example.com/original-banner.png",
        "width": 300,
        "height": 250
      },
      "headline": {
        "asset_type": "text",
        "content": "Winter Sale - 50% Off"
      }
    }
  },
  "target_capability_id": "display_mobile_320x50"
}

{
  "creative_manifest": {
    "format_kind": "image",
    "assets": { /* complete assets */ }
  },
  "target_capability_id": "display_300x250"
}

Other operations in Creative

• get_creative_delivery
• list_creative_formats
• list_creatives
• list_transformers
• preview_creative
• sync_creatives
• validate_input

Related

• The full Creative reference
• All 64 entries in the AdCP 3.1.13 registry
• Does AAMP have an equivalent operation?