Tools

Entity reads

Nine read tools over the core catalog: three lean list tools for browsing, one full-detail power-read, three single-item reads, and two reads over per-store versions. All require pim:read and touch only Peak PIM's own rows — never Shopify.

list_products_v1 · list_collections_v1 · list_variants_v1

list_products_v1 · list_collections_v1 · list_variants_v1pim:read

List entities of one type as lean rows — the fast way to browse. All three share the same argument shape, and every argument is optional:

Argument	Type	Description
`channel_id`	string	Restrict to a single store (connected Shopify store).
`page`	integer	1-based page number.
`page_size`	integer	Rows per page; values above 100 are clamped with a visible `[note]`.
`search`	string	Free-text search.
`sort`	string	Sort field.
`sort_source`	string	`master` to sort by the canonical item's values, `projection` to sort by the per-store version's.
`order`	string	`asc` or `desc`.
`exclude_default_variants`	boolean	Exclude auto-created default variants from the list (meaningful for variants, accepted everywhere).

list_masters_v1

list_masters_v1pim:read

The power-read: full-detail items of any type — products, collections, variants, metafield definitions, media — with extra filters. Prefer the lean list tools above for simple browsing; use this when you need full attribute detail, the parent_master_id relation, or a server-side filter. All arguments are optional:

Argument	Type	Description
`type`	string	Item type filter (product, collection, variant, metafield definition, media).
`channel_id`	string	Store filter (connected Shopify store).
`parent_master_id`	string	Restrict to children of this parent item — e.g. the variants of a product.
`filter`	string	Server-side filter expression.
`page`	integer	1-based page number.
`page_size`	integer	Rows per page (clamped at 100 with a visible note).
`search`	string	Free-text search.

get_master_v1

get_master_v1pim:read

Get a single item (product, collection, variant, metafield definition, or media) by id.

Argument	Type	Description
`id`	string, required	The item id. Must belong to the token's account; cross-account ids return "not found".

get_master_with_projections_v1

get_master_with_projections_v1pim:read

Get an item plus its per-store versions — one per connected Shopify store. The one-call way to compare what each store publishes. Single required argument id, as above.

get_master_related_v1pim:read

Get an item with its related entities: its variants, the default_variant, and linked collections/products. Single required argument id, as above.

list_projections_v1

list_projections_v1pim:read

List per-store versions directly. All arguments are optional:

Argument	Type	Description
`master_id`	string	Restrict to per-store versions of this item.
`channel_id`	string	Store filter (connected Shopify store).
`type`	string	Item type filter.

get_projection_v1

get_projection_v1pim:read

Get one per-store version by its id (required), same shape as get_master_v1's argument.

Which read should an assistant reach for?

Browsing → the lean list tools. Comparing stores → get_master_with_projections_v1. Navigating structure (a product's variants, its collections) → get_master_related_v1 or list_masters_v1 with parent_master_id. Editing next? Read first — the draft writes want the current revision.