Skip to main content
POST
Create vehicle comparison
Creates and generates a vehicle comparison for 2–5 vehicles. Each vehicle must declare an explicit source: Free-text YMMT without cascade validation is rejected. Supports the same create options as Composer (tone/voice, depth, geo, Layouts, featured vehicle + bias). Generation is asynchronous; use GET /content/{id} to check status. Scope required: content:write

Request body

array
required
Array of 2-5 vehicles. Each item requires source plus either inventory (vin or stock_number) or catalog YMMT fields. Optional per-vehicle selected_trims.
string
Brand voice profile id (sets tone to BrandVoice:{id}).
string
Enum tone when not using a brand voice. Defaults to the site’s first brand voice, otherwise Informative.
string
default:"English"
Language for generated content.
string
Custom title. Defaults to “Vehicle A vs Vehicle B vs …”.
string
default:"balanced"
Content depth preset. One of concise, steady, balanced, substantial, or in-depth.
boolean
Optional override. Defaults to false only when content_depth is concise.
object[]
Optional geo targeting: [{ element_id, priority }] from GET /site/target-geography.
string
default:"standard"
standard (Rich Text) or visual (Layouts). Visual requires Layouts plan entitlement.
string
When visual: custom (AI Design), user-template (My Template), or template.
uuid
Required when visual + user-template. Use GET /layouts?content_type=comparison.
Zero-based index of the vehicle to favor (0–2). Defaults to 0.
integer
Bias intensity toward the featured vehicle (0–100). Defaults to 50.

Example

Authorizations

X-API-Key
string
header
required

Your Hrizn API key (prefix hzk_)

Body

application/json
vehicles
object[]
required
Required array length: 2 - 5 elements
brand_voice_id
string

Brand voice profile id (sets tone to BrandVoice:{id})

tone
enum<string>

Enum tone when not using brand_voice_id. Default first brand voice or Informative.

Available options:
Informative,
Authoritative,
Persuasive,
Confident,
Analytical,
Empathetic,
Witty,
Enthusiastic,
Inspiring,
Motivating,
Creative
language
enum<string>
default:English
Available options:
English,
Spanish,
Mandarin Chinese,
Japanese,
Korean,
Arabic,
Farsi,
Hebrew,
French,
Tagalog,
Vietnamese,
Portuguese,
Russian
title
string
Maximum string length: 500
content_length
integer
deprecated
Required range: 200 <= x <= 5000
content_depth
enum<string>

Defaults to balanced

Available options:
concise,
steady,
balanced,
substantial,
in-depth
include_tables
boolean

Defaults to false only when content_depth is concise

selected_trims
string[]

Model landing only — multi-trim selection (omit when empty)

target_geo_overrides
object[]

Included geos from GET /site/target-geography with priority order

output_format
enum<string>
default:standard

Rich Text (standard) or Layouts (visual). Visual requires Layouts plan entitlement.

Available options:
standard,
visual
visual_design_mode
enum<string>

When visual — custom=AI Design (default), user-template=My Template

Available options:
template,
custom,
user-template
selected_template_id
string<uuid>

Required when visual + user-template; from GET /layouts

Zero-based index of the vehicle to favor. Defaults to 0.

Required range: 0 <= x <= 2
bias_level
integer

Bias intensity toward the featured vehicle (0-100). Defaults to 50.

Required range: 0 <= x <= 100

Response

Comparison generation started

data
object
Last modified on July 26, 2026