Batch requests and item outcomes
Send one through ten explicit item selectors and handle one ordered outcome per entry.
Use one read-only POST for one or several items
The details, price and labor, and labor-hours operations accept one through ten entries in a JSON body. The same contract therefore serves a human developer, an MCP adapter, and a batch client without duplicating a single-item GET and a multi-item POST.
- These POST operations are read-only and idempotent; they do not create or change catalog items or mappings.
- They require no public idempotency key.
- A valid response preserves request order and returns exactly one result for every accepted entry.
- An optional request_key can correlate an input entry with its result, but it is never item identity or authority.
- Malformed JSON, an invalid batch size, or a structurally invalid entry rejects the request rather than silently dropping work.
Name exactly one selector per entry
Each entry contains exactly one item_skey, company_item_identifier, or hph_item_code selector. The selector type is explicit and is never guessed from punctuation, length, UUID shape, or prefix.
- company_item_identifier is the normal customer input and is checked against the represented Company's approved primary and alternate identifier fields.
- item_skey is an optional stable Company catalog reference for clients that received it earlier.
- hph_item_code is accepted only by operations and represented-company contexts that have current code-capable authority.
- HPH Item Code lookup remains limited to the represented Company's current catalog relationships where the operation requires that boundary.
- An ambiguous selector returns an item-level ambiguous outcome; the service never chooses one item arbitrarily.
Handle closed item-level outcomes
A structurally valid batch can contain different item-level outcomes. Only available carries the requested content; other outcomes contain only the safe fields defined by their public schema.
- available means the authorized projection was returned for that entry.
- not_found_or_concealed does not reveal whether an item exists outside the caller's current authority.
- mapping_required means the Company catalog item needs an HPH association before this projection can be produced.
- ambiguous means the submitted selector resolved to more than one permitted Company item.
- temporarily_unavailable identifies a bounded dependency failure and does not authorize a broader retry or alternate source.
- A protected field can be omitted from an available result without changing the whole item outcome to an error.
Choose the narrowest operation
Use the operation whose response matches the task instead of sending an include list or retrieving every field and discarding most of it. All three projections reuse the same authorization and disclosure policy.
- Details returns the bounded product representation.
- Price/labor returns Manufacturer list price and at most one authorized Company-applicable default labor hour.
- Labor hours returns the requested all, item-default, or Company-default labor-hour selection, with at most 256 complete entries per item and no silent truncation.
- The batch operations have no public continuation cursor. Split work into additional bounded requests when more than ten items are needed.
- Restricted HPH Item Code and unlicensed labor are omitted while safe notices explain requested optional content that was not returned.