{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/schemas/3.1.0-rc.4/creative/list-creatives-request.json",
  "title": "List Creatives Request",
  "description": "Request parameters for querying creative assets from a creative library with filtering, sorting, and pagination. Implemented by any agent that hosts a creative library — creative agents (ad servers, creative platforms) and sales agents that manage creatives.",
  "type": "object",
  "allOf": [
    {
      "$ref": "/schemas/3.1.0-rc.4/core/version-envelope.json"
    },
    {
      "if": {
        "properties": {
          "include_pricing": {
            "const": true
          }
        },
        "required": [
          "include_pricing"
        ]
      },
      "then": {
        "required": [
          "account"
        ]
      }
    }
  ],
  "properties": {
    "filters": {
      "$ref": "/schemas/3.1.0-rc.4/core/creative-filters.json"
    },
    "sort": {
      "type": "object",
      "description": "Sorting parameters",
      "properties": {
        "field": {
          "$ref": "/schemas/3.1.0-rc.4/enums/creative-sort-field.json",
          "default": "created_date",
          "description": "Field to sort by"
        },
        "direction": {
          "$ref": "/schemas/3.1.0-rc.4/enums/sort-direction.json",
          "default": "desc",
          "description": "Sort direction"
        }
      },
      "additionalProperties": true
    },
    "pagination": {
      "$ref": "/schemas/3.1.0-rc.4/core/pagination-request.json"
    },
    "include_assignments": {
      "type": "boolean",
      "default": true,
      "description": "Include package assignment information in response"
    },
    "include_snapshot": {
      "type": "boolean",
      "default": false,
      "description": "Include a lightweight delivery snapshot per creative (lifetime impressions and last-served date). For detailed performance analytics, use get_creative_delivery."
    },
    "include_items": {
      "type": "boolean",
      "default": false,
      "description": "Include items for multi-asset formats like carousels and native ads"
    },
    "include_variables": {
      "type": "boolean",
      "default": false,
      "description": "Include dynamic content variable definitions (DCO slots) for each creative"
    },
    "include_pricing": {
      "type": "boolean",
      "default": false,
      "description": "Include pricing_options on each creative. Requires account to be provided. When false or omitted, pricing is not computed."
    },
    "include_purged": {
      "type": "boolean",
      "default": false,
      "description": "Include soft-purged creative tombstones in the result set. When true, creatives destroyed via `creative.purged` with `purge_kind: soft` surface as tombstone records carrying `purged: true`, `purged_at`, and the purge reason — within the seller's webhook activity retention window (30 days from `purged_at`, MUST match `webhook-activity-record` retention). Hard-purged creatives MUST NOT appear regardless of this flag. When false or omitted, the result set excludes all purged creatives — same default as today."
    },
    "include_webhook_activity": {
      "type": "boolean",
      "default": false,
      "description": "Include recent webhook activity per creative. When true, each returned creative carries a `webhook_activity[]` array of the most recent fires scoped to that creative — `creative.status_changed` and `creative.purged` deliveries. Adoption of the `webhook_activity[]` pattern per `snapshot-and-log.mdx § Webhook activity log pattern`. Retention is 30 days from `completed_at` (MUST). Three-state presence applies: omitted = seller does not surface; `[]` = persists but no recent fires; non-empty = actual records."
    },
    "webhook_activity_limit": {
      "type": "integer",
      "default": 50,
      "minimum": 1,
      "maximum": 200,
      "description": "Maximum number of `webhook_activity[]` records to return per creative. Only meaningful when `include_webhook_activity: true`. Sellers MUST respect the cap; structural enforcement is provided by the response schema's `maxItems: 200` on the array."
    },
    "account": {
      "$ref": "/schemas/3.1.0-rc.4/core/account-ref.json",
      "description": "Account reference for pricing and access. When provided with include_pricing, the agent returns pricing_options from this account's rate card on each creative."
    },
    "fields": {
      "type": "array",
      "description": "Specific fields to include in response (omit for all fields). The 'concept' value returns both concept_id and concept_name.",
      "minItems": 1,
      "items": {
        "type": "string",
        "enum": [
          "creative_id",
          "name",
          "format_id",
          "status",
          "created_date",
          "updated_date",
          "tags",
          "assignments",
          "snapshot",
          "items",
          "variables",
          "concept",
          "pricing_options"
        ]
      }
    },
    "context": {
      "$ref": "/schemas/3.1.0-rc.4/core/context.json"
    },
    "ext": {
      "$ref": "/schemas/3.1.0-rc.4/core/ext.json"
    }
  },
  "additionalProperties": true,
  "examples": [
    {
      "description": "List all approved creatives",
      "data": {
        "filters": {
          "statuses": [
            "approved"
          ]
        }
      }
    },
    {
      "description": "List creatives in a specific concept matching a format",
      "data": {
        "filters": {
          "concept_ids": [
            "concept_holiday_2026"
          ],
          "format_ids": [
            {
              "agent_url": "https://creative.example.com",
              "id": "display_static",
              "width": 300,
              "height": 250
            }
          ]
        },
        "include_variables": true
      }
    },
    {
      "description": "Find DCO creatives for dynamic campaigns",
      "data": {
        "filters": {
          "has_variables": true,
          "statuses": [
            "approved"
          ]
        },
        "include_variables": true
      }
    },
    {
      "description": "Lightweight list with minimal fields",
      "data": {
        "fields": [
          "creative_id",
          "name",
          "status"
        ],
        "include_assignments": false
      }
    },
    {
      "description": "List creatives with account-specific pricing",
      "data": {
        "account": {
          "account_id": "acct_acme_creative"
        },
        "include_pricing": true,
        "filters": {
          "statuses": [
            "approved"
          ]
        }
      }
    },
    {
      "description": "List approved creatives plus recent webhook activity, including purged tombstones",
      "data": {
        "filters": {
          "statuses": [
            "approved"
          ]
        },
        "include_purged": true,
        "include_webhook_activity": true,
        "webhook_activity_limit": 25
      }
    }
  ]
}