---
title: "Creative assets upload"
method: POST
path: "/creative_upload"
tags: ["Atomic Creatives"]
---

# Creative assets upload

`POST /creative_upload`

## Request

- Base URL: `https://api.mediamath.com/api/v3.0`
- URL: `https://api.mediamath.com/api/v3.0/creative_upload`
- Auth: OAuth 2
  - Authorization code: `https://auth.mediamath.com/authorize`
  - Token URL: `https://auth.mediamath.com/oauth/token` scopes: `offline_access`, `manage:services`
- TypeScript: <https://skmtc.dev/mediamath/apis/campaigns-api/docs/creative_upload/post.ts> (a function with typed inputs; its response is checked against the schema)

Upload creative assets and create first-party atomic creatives. This endpoint
validates files and metadata, stores assets, and returns the atomic creatives
that were created.

Creative upload limits:

| Creative upload shape | Limit |
| --- | --- |
| Plain/non-ZIP uploaded files | 500KB per uploaded file |
| Uploaded ZIP package | 10MB per ZIP file |
| Direct files in the uploaded outer ZIP | 500KB per direct file |
| Assets inside an inner HTML5 package ZIP | 500KB recommended maximum; warning only |
| Uploaded filename form parts | 10 files max |

Send all files in a request with either the `filename` multipart field name
or the legacy `filename[]` multipart field name; do not mix both field names
in the same request. The OpenAPI
`x-max-file-size: 10485760` value is the transport/schema ceiling for uploaded
ZIP parts. Non-ZIP 500KB and direct outer-ZIP file 500KB limits are endpoint
validation rules. Assets inside an inner HTML5 package ZIP over 500KB are
accepted with a `meta.warnings` entry unless the `html5-file-too-large` sub_code
is promoted to an error by configuration. If multiple ZIP files are uploaded,
ZIP structural/content validation preserves the legacy behavior of validating
the first ZIP selected by the request.

Top-level uploads may use image extensions (`.gif`, `.jpg`, `.jpeg`, `.png`,
`.tiff`, `.tif`, `.svg`), the legacy `.swf` extension, loose HTML/CSS/JS/font
extensions (`.html`, `.htm`, `.css`, `.js`, `.woff`, `.woff2`, `.ttf`, `.otf`),
or ZIP packages. ZIP-inner HTML5 assets may use image extensions plus `.html`,
`.htm`, `.css`, `.js`, `.woff`, `.woff2`, `.ttf`, `.otf`, `.mp4`, and `.webm`.

HTML5 packages must use a two-level ZIP structure: the outer ZIP contains one
or more inner ZIP files, each inner ZIP contains the HTML5 creative assets, and
backup images are included in the outer ZIP. Loose files must not be uploaded
alongside an HTML5 ZIP package. Nested ZIPs beyond two levels are rejected.

HTML5 validation errors and warnings use these stable `sub_code` values:

| `sub_code` | Default disposition | Scope | Trigger |
| --- | --- | --- | --- |
| `html5-missing-click-tracker` | Error | Inner package | No HTML/JS file contains a MediaMath click-tracker macro |
| `html5-noscript-tag` | Warning | Inner package | Root HTML contains a `<noscript>` tag |
| `html5-storage-api` | Warning | Inner package | HTML/JS file uses `localStorage` or `sessionStorage` |
| `html5-external-reference` | Warning | Inner package | Root HTML references an external asset |
| `html5-invalid-filename-chars` | Warning | Inner package | File name contains spaces, non-ASCII, or other non-standard characters |
| `html5-missing-file-extension` | Warning | Inner package | Extensionless file is recognized by content signature or root HTML reference |
| `html5-unsafe-filename-path` | Error | Inner package | File path is absolute, contains `.`/`..`, drive-letter, or UNC path components |
| `html5-filename-too-long` | Error | Inner package | File path exceeds 255 characters |
| `html5-unsupported-file-type` | Error | Outer ZIP and inner package | File extension is not allowed |
| `html5-file-too-large` | Warning | Inner package | Inner package asset exceeds the recommended 500KB maximum |
| `html5-file-too-large` | Error | Outer ZIP direct entry | Direct entry in uploaded outer ZIP exceeds 500KB |
| `html5-file-read-error` | Error | Inner package | Extracted HTML/JS file cannot be read |
| `html5-backup-mismatch` | Warning | HTML5 package auto-discovery | Backup image matches the package name only by letter case |
| `html5-backup-mismatch` | Error | HTML5 package auto-discovery | No backup metadata and no matching backup image exists |
| `html5-backup-mismatch` | Error | HTML5 package manual backup | Specified backup file is absent from the ZIP |
| `html5-invalid-package-structure` | Error | Outer ZIP | HTML appears directly in the outer ZIP |
| `html5-nested-zip-too-deep` | Error | Outer ZIP | ZIP nesting exceeds two levels |
| `html5-separate-files` | Error | Multipart request | Loose files are uploaded alongside an HTML5 ZIP package |
| `html5-submission-name-mismatch` | Error | Outer ZIP (HTML5) | Inner ZIP name is missing from `metadata.submissions[].name` |
| `submission-name-mismatch` | Error | Outer ZIP (non-HTML5) | Plain ZIP file is missing from `metadata.submissions[].name` |
| `zip-too-large` | Error | Uploaded ZIP | Uploaded ZIP exceeds 10MB |
| `html5-validation-error` | Error | Fallback | Internal fallback for an unmapped HTML5 validation rule |

## Request body `multipart/form-data`

- CreativeUploadRequest
  - `filename` string[], required: Creative files to upload. Send all files in a request as either `filename` or the legacy `filename[]` field name; do not mix both field names in the same request. Loose/non-ZIP uploads are limited to 500KB per file. Uploaded ZIP packages are limited to 10MB per ZIP. Direct files in the uploaded outer ZIP are limited to 500KB. Assets inside an inner HTML5 package ZIP over 500KB are accepted with a warning unless the `html5-file-too-large` sub_code is promoted to an error. If multiple ZIP files are uploaded, ZIP structural/content validation preserves the legacy behavior of validating the first ZIP selected by the request.
  - `metadata` CreativeUploadMetadataUpload, required: JSON metadata for the upload request.
    - `advertiser_id` integer, required
    - `is_https` boolean
    - `submissions` CreativeAssetSubmissionUpload[], required: Submission details for files being uploaded or ZIP/HTML5 package entries.
      - `name` string, required: The creative file name. For loose/non-ZIP uploads this is the uploaded filename. For regular ZIPs this is a file inside the ZIP. For HTML5 packages this is the inner ZIP filename, such as `interactive_ad.zip`.
      - `click_through_url` string, uri, required
      - `landing_page` string, uri
      - `concept_id` integer, required
      - `backup` string: Optional backup image filename for HTML5 creatives. Backup images must be inside the HTML5 ZIP package. If omitted, the API attempts to find an image with the same base filename as the HTML5 package.
      - `mraid_type` 'static' | 'expandable' | 'interstitial': Optional MRAID type. `expandable` requires the `expandable` image field; `expandable` must not be supplied for other MRAID types.
      - `expandable` string: Required when `mraid_type` is `expandable`; otherwise invalid.
      - `creative_name` string: Optional display name for the created atomic creative. When provided, this overrides the default name derived from the submission filename.

## Response `201`

Upload completed successfully

- object
  - `data` AtomicCreativeResponse[]
    - `id` integer, required
    - `version` integer, required
    - `entity_type` string, required
    - `advertiser_id` integer, required
    - `concept_id` integer
    - `concept_name` string
    - `name` string, required
    - `width` integer, required
    - `height` integer, required
    - `creative_import_file_id` integer
    - `file_type` string, required
    - `is_https` boolean, required
    - `is_multi_creative` boolean, required
    - `has_sound` boolean, required
    - `rich_media` boolean, required
    - `rich_media_provider` string
    - `status` boolean
    - `archived` boolean
    - `built` boolean, required
    - `build_date` string
    - `built_by_user_id` integer, nullable
    - `build_errors` string
    - `created_on` string, date-time, required
    - `last_modified` string, required
    - `external_identifier` string
    - `tpas_ad_tag_name` string, required
    - `updated_on` string, date-time, required
    - `expand` string
    - `click_url` string
    - `ad_format` string, required
    - `expansion_direction` string, required
    - `expansion_trigger` 'AUTOMATIC' | 'MOUSEOVER' | 'CLICK', required
    - `ad_server_type` string
    - `t1as` boolean, required
    - `tpas_ad_tag` string
    - `edited_tag` string
    - `click_through_url` string
    - `rejected_reason` string
    - `approval_status` string, required
    - `start_date` string
    - `end_date` string
    - `media_type` string, required
    - `is_mraid` boolean, required
    - `vast_version` number, float, nullable
    - `sizmek_tag_status` string, required
    - `sizmek_creative_status` string, required
    - `last_payload_modified` string
    - `is_audio` boolean
    - `tag` string
    - `tag_type` string
  - `meta` CreativeCollectionCreatedMetadata
    - `status` string, required
    - `count` integer, required
    - `warnings` CreativeWarning[]
      - `code` string
      - `sub_code` string
      - `message` string
      - `field` string

## Other responses

- `400`: Bad request
- `401`: Error response
- `403`: Not authorized

---

[API](https://skmtc.dev/mediamath/apis/campaigns-api.md) - [All operations](https://skmtc.dev/mediamath/apis/campaigns-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mediamath/apis/campaigns-api/revisions/408743891def?raw)