Upgrade Guide

Versions 1 and 2 of the Content API will be deprecated on February 1, 2027. Please refer to this upgrade guide for a detailed understanding of how to convert your code to work with v3.

1. Update POST /preflights request parameters

---

The request body has significant changes:

Brand — v1 and v2 both accept a single string brand. v3 replaces this with two mutually exclusive options; you must provide exactly one:

• brand_id (Integer) — the internal CreativeX brand ID
• brand_name (String) — the brand name

Use GET /dimensions (see section 5) to look up valid brand_id and brand_name values for your account.

Market — v1 and v2 both accept a single string market. v3 replaces this with two mutually exclusive options; you must provide exactly one:

• market_name (String)
• market_code (String) — ISO 3166 two-letter country code

Once again, you can use GET /dimensions (see section 5) to look up valid market_name and market_code values.

Assets → Creatives — the assets array is replaced by a creatives array with a different shape:

assets field (v1 & v2)	v3 creatives field
url	source_url
content_type	(removed from asset level — now a top-level param)
filename	(removed)
(not present)	external_label (optional)

Placement — v3 uses top-level scalar fields for both:

• placement (String, optional)
• publisher (String, optional)

How this differs by starting version:

• From v1: placements was an array of { publisher, placement } objects with no top-level publisher. Both fields move to top-level scalars in v3.
• From v2: placements was the same array, but publisher could also be sent as a top-level string. In v3 the array is removed entirely; only the top-level strings remain.

New optional top-level fields in v3:

• ad_format (String)
• content_type (String) — moved from per-asset to top-level; values: brand | creator | ugc; defaults to brand (or partner default if configured)

---

2. Update GET /preflights to handle paginated responses

Both v1 and v2 return a flat array of all preflights. v3 returns paginated results. Update your client to pass pagination parameters and iterate pages rather than expecting a single complete list. For a more detailed explanation, see our pagination reference.

---

3. Replace GET /preflights/assets/:id with GET /preflights/:id

The GET /preflights/assets/:id endpoint (which accepted a CreativeX audit_post ID) was removed in v3. Use GET /preflights/:id with the preflight request ID returned when you created the preflight.

Note: v3 preflights can only be retrieved through v3 of the API. Attempts to fetch a v3 preflight through v1 or v2 will return a 400 error.

---

4. Replace GET /preflights/brands with GET /dimensions

The GET /preflights/brands endpoint was removed. Use the new GET /dimensions endpoint instead, which returns all valid values for preflight creation in a single call — brands (now including both id and name), markets (including ISO 3166 country codes), channels, publishers, placements, ad formats, and campaign objectives.

---

5. Update GET /preflights/:id response parsing

The v3 preflight response shape has changed dramatically. This table describes how the old and new fields are related:

v1/v2 field	v3 field	Notes
id	request_id
state	status
brand (String)	brand (Object)	Now { id, name }
market (String)	market (Object)	Now { name, code } — code is ISO 3166
placements[0].placement	placement (String)	Top-level scalar
placements[0].publisher	publisher (String)	Top-level scalar
assets[].content_type	content_type (String)	Moved to top-level
assets	creatives	Each item now includes post_id, source_url, external_label, scores
(not present)	scores[].default	Boolean — whether this is the company default score
(not present)	completed_at	Datetime when scoring finished

Additionally, we made some changes to enhance the clarity of the responses:

• Error details are now returned as structured objects with code and message fields (see our error codes reference for more details)
• Fields not applicable to a given preflight (e.g. ad_format when not submitted) are omitted rather than returned as null — please update your parsing to handle missing fields gracefully

---

6. Handle rate limiting on POST /preflights

v3 introduces a daily rate limit. The default is 2,500 creatives/day, resetting at UTC midnight but a higher rate limit can be negotiated on a case-by-case basis. Exceeding the limit returns HTTP 429. We return the following response headers to help you determine usage patterns:

• X-RateLimit-Limit
• X-RateLimit-CreativesSubmittedInRequest
• X-RateLimit-Remaining
• X-RateLimit-Reset (Unix timestamp of next reset)