Inventory Fragment
When to use it
The vehicle search modules render in the browser and are the right choice for almost every site. Reach for the fragment when the markup has to exist in the server response: a CMS plugin producing crawlable listing pages, a static build, or a template that has to work without JavaScript.
It carries the same data as the widget, in HTML you own and style yourself.
The endpoint
GET /inventory/{companySlug}/fragment?mode=index&limit=50&offset=0
GET /inventory/{companySlug}/fragment?mode=detail&vehicle={slug}{companySlug} is the dealer's Carposé slug — the same one the vehicle sitemap is published under.
Response
Content-Type: text/html; charset=UTF-8
Cache-Control: public, max-age=3600
X-Carpose-Total: 1109
X-Robots-Tag: noindexThe body is a run of <article> elements and nothing around them — no doctype, no <html>, <head>, <body> or <footer>, no <style> block, no class attributes, and no template indentation. Drop it into your own container and style it with your own selectors.
X-Carpose-Total is the dealer's whole active inventory, not the number of articles in this response. Page count, the boundary where your listing should answer 404, and a meta description that names a number all come from this header rather than from counting rows.
Query parameters
mode
index | detail
index
A page of the inventory, or one vehicle in full. Any other value is a 400.
limit
integer
50
Articles per response, clamped to 1…500.
offset
integer
0
How many articles to skip. Negative values are read as 0.
vehicle
string
—
Required for mode=detail; missing is a 400, unknown is a 404.
limit and offset page over the whole inventory, in one order spanning every location. You never have to map a page number onto a location.
What the two modes carry
mode=index
mode=detail
Images
the lead image only
the whole gallery
Equipment description
omitted
included, sanitized
JSON-LD image
the lead image only
every image
Images arrive in gallery order — _1 before _10, numerically.
Addressing a vehicle
vehicle accepts every form a deep link can carry, so you can hand back whatever your listing already holds:
All three resolve to the same article. The token is also the article's id, so a listing can hand its own anchor straight back as the detail request. See URL Structure for how the token is formed and when an account is set to slug-only addressing.
Links inside the fragment
Every article already points where it should. The <a> in the article and the url in the JSON-LD both carry the dealer's own vehicle URL, built from their account settings — URL form, slug-only, base page. There is nothing to rewrite on your side.
The account needs a vehicle-search page URL. Without it Carposé does not know where the dealer's vehicles live, so articles come back with no link and the JSON-LD omits url rather than pointing somewhere wrong. Set the search page URL on the account before you integrate.
Elements you will see
article h2 h3 p div span a img dl dt dd ul ol li strong em br, plus one script[type="application/ld+json"] per article.
Shape of one article:
Sanitize it anyway. The equipment description is dealer-authored text imported from mobile.de, and Carposé already restricts it to the elements listed above. Running your own allowlist over the response before you print it is still the right call — it is the only check that survives a change on our side, and it costs a single pass.
Caching
Responses are cached for an hour and rebuilt the moment the dealer's inventory or link settings change, so a fresh import shows up without waiting out the TTL. Cache-Control: public, max-age=3600 is safe to honour in your own cache or CDN.
Errors
400
mode is neither index nor detail, or mode=detail without vehicle
404
unknown company slug, or vehicle names a vehicle this dealer does not have
An offset past the end of the inventory is not an error — it answers 200 with an empty body. Compare offset against X-Carpose-Total to decide where your own listing stops.
Last updated