Inventory Service

The Inventory service exposes read access to the vehicle inventory managed on the OpenHive platform: the vehicles, the publication contracts they come from, and the field mappings used to publish listings.

info

To activate the Inventory service for your software, please contact us at https://openhive.eu/contact.

Available endpoints

Every path lives under /v1/inventory on the platform host (see Base URLs).

Endpoint	Description
GET /v1/inventory/vehicles	List the vehicles available in the inventory, with their full representation.
GET /v1/inventory/vehicles/{uid}	Retrieve a single vehicle with its full representation.
GET /v1/inventory/vehicle-partials	List lightweight (partial) vehicle representations, optimised for pagination and search.
GET /v1/inventory/mappings	List the field mappings configured for your customer.
GET /v1/inventory/mappings-available	List the vehicle properties a mapping can translate.
GET /v1/inventory/publication-contracts	List your publication contracts, the provider feeds your vehicles come from.

See the API section for the full request and response reference of each endpoint.

Publication contracts

Before fetching vehicles, you might want to filter them by contract. A publication contract is a feed your vehicles come from, and every vehicle belongs to at least one of yours.

1. GET /v1/inventory/publication-contracts returns your contracts, each with its slug. Narrow it with slug (partial, case-insensitive) or active.
2. GET /v1/inventory/vehicles with publicationContract.slug=<slug> returns only the vehicles of that contract. not_in[publicationContract.slug] excludes a contract instead.

curl "https://api.openhive.eu/v1/inventory/publication-contracts?active=true" \
  -H "Authorization: Bearer <access_token>"

curl "https://api.openhive.eu/v1/inventory/vehicles?publicationContract.slug=my-dealer-vo&itemsPerPage=50" \
  -H "Authorization: Bearer <access_token>"

Both filters only ever match your own contracts: a slug you do not own matches nothing rather than erroring. Contracts are read-only through the API.

Filters and pagination

The vehicle collections accept the same filters: exact matches (make, model, fuel, vehicleType, frameNumber, …), a priceInc range (priceInc[gte], priceInc[lte], …) and updatedAt / entryInStock date windows. publicationContract.slug narrows the result to one of your own publication contracts.

Every filter is declared on its operation. A filter name the operation does not declare, or a value outside its allowed set, answers 400 rather than being ignored, so a mistyped filter never returns the whole catalogue silently.

Collection	itemsPerPage default	Maximum
/vehicles, /vehicle-partials	10	50
/mappings	25	50
/publication-contracts	30	fixed, page only

Authentication

All endpoints require a bearer access token, passed in the Authorization header:

Authorization: Bearer <token>

Vehicles and mappings are scoped to your own customer subscription: you only ever see the publication contracts attached to it.

Migrating from the legacy host

The service used to be served on its own host, https://inventory.preprod.openhive.eu/api. It now shares the platform host and the /v1 prefix with every other service, and identifiers are uids. One path is renamed along the way:

Legacy	New
GET /api/vehicle_partials	GET /v1/inventory/vehicle-partials

See the API v1 — single host changelog for the full migration checklist.