Read MaterialGraph over REST, MCP and the CLI.

Extract a named color palette from an uploaded image

Upload→palette for the "match the colors" image path: send image bytes (a data URI or bare base64) and get back the colorscope-extracted named palette. Node-only (sharp-backed). Not cached (best-effort, per-request analysis). Requires the `mg:read` bearer scope.

curl -X POST 'https://beta.materialgraph.com/api/v1/search/palettes/extract' \  -H "Authorization: Bearer $MG_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "image": "…"}'

Resolve a color name to a hex

Resolve a color name or phrase to a hex via the colorscope brand libraries (exact + Fuse.js fuzzy) with a semantic fallback, and say whether the named paint is a variant in the catalogue (`match.variant`). Node-only. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/search/colors/resolve?name=text' \  -H "Authorization: Bearer $MG_API_KEY"

Nearest Samplize catalogue paints for several hexes

Normalises hexes to #RRGGBB and removes duplicates in input order. One indexed statement retrieves the nearest 100 settled paints per hex by OKLab cube KNN, within the eligible samplizeCatalogue subset including out-of-stock paints. ColorScope CIEDE2000 reorders those candidates and supplies the closeness bands. Cards, hex and LRV come from resolved_variants. Requires mg:read.

curl 'https://beta.materialgraph.com/api/v1/colors/nearest-paints?hex=text' \  -H "Authorization: Bearer $MG_API_KEY"

Get the representative color palette of one or more categories

The colors a product category actually comes in, for up to 8 categories in ONE call, at either taxonomy tier. Each profile carries the category's display `name`/`path`, its total colored variants, its variant-weighted mean OKLab lightness and chroma, and its representative colors as hex + OKLab + variant count + proportion. `groupBy=group` accepts product-type GROUP keys and merges every leaf type under a group into one bucket histogram BEFORE ranking, so a group's palette is the group's palette rather than the union of its leaves' heads. `groupBy=merged` merges across the KEYS as well and returns a SINGLE profile over the union of their leaves — the palette of a caller-defined facet such as "Wood" (`wood_surface,wood_flooring`) that the taxonomy carries no single node for; its keys may sit at either tier, `categoryKey` is those keys sorted and joined with `+`, and `members` hands them back so nothing has to split that key. `select=diverse` runs a greedy max-min OKLab sampler (0.02 minimum separation, backfilled by frequency if fewer survive) so the swatches are visually spread — the one thing a client cannot reconstruct from a truncated frequency list. A category with no color data returns a zero-count profile, not a missing key. Counts are read live at request time from `resolved_variant_bands` (the dominant color of each searchable variant), so they are as current as the last write to a variant. This is a category-level aggregate, not a per-material read, so responses carry the shared vocabulary window, `Cache-Control: no-store`. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/colors/profiles?productTypeIds=text' \  -H "Authorization: Bearer $MG_API_KEY"

Get per-brand paint color provenance

Which paint brands publish a color value and which do not. Per brand: the paint variants MaterialGraph holds (`paintVariants`, the denominator), how many carry a color DECLARED by the manufacturer (`declared`), how many carry one DERIVED from product imagery (`derived`), how many carry neither, and `declaredCoverage` — the number that matters. The population is paint and coating product types only, because a declared color is not expected of a stone slab and counting its absence would be a slur rather than a measurement. `declared` and `derived` OVERLAP and are not a split: most declared paints also carry a derived query interpretation, and only `neither` is exclusive. There is deliberately no corpus average in the response — a single rate is the one shape that hides the finding, since a handful of publishing brands would mask every brand that publishes nothing. `totals` therefore carries counts, including `brandsPublishingNothing`. No query parameters. This is a corpus-level aggregate, not a per-material read, so responses carry the shared vocabulary window, `Cache-Control: no-store`. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/colors/provenance' \  -H "Authorization: Bearer $MG_API_KEY"

Audit whether a brand's declared color hex agrees with its declared light reflectance

Compares each variant's DECLARED color hex against its DECLARED light reflectance value and reports the residual — `lrv` minus the sRGB relative luminance of the hex, both on 0–100. The instrument CANNOT say which side of a divergence is wrong: the hex, the LRV, the sheen (LRV is finish-specific), the observer/geometry mismatch between BS 8493 and sRGB, and legitimate gamut clipping all land in the same number. The signal is declared-color INCONSISTENCY, never "the LRV is wrong". Read `verdict` before any number. A brand whose LRV was COMPUTED from its hex piles every residual inside two-decimal rounding and would otherwise read as a clean bill of health for data carrying no independent information; two screens run first — the zero spike, and whether median |Δ| rises with chroma as optical error must — and such a brand comes back `circular` and MUST be excluded from any consistency claim. `verdict.reason` states which screen fired. `bands` splits the residuals into ≤1 / 1–5 / 5–20 / >20; a |Δ| of 1–5 is expected optical residual, not fault, and only |Δ| above `thresholds.defect` is a candidate defect. `brand` is optional and scopes the audit, because the corpus-wide join is the heavy one; omit it and `report` is null while `brands` still lists every auditable brand with its pair count, so no caller has to guess a name. `worst` bounds the offender list — a page of examples, never the raw pairs. `thresholds` carries the kernel's own constants so no client restates them. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/colors/consistency' \  -H "Authorization: Bearer $MG_API_KEY"

Get one variant, compact, with only the detail asked for

Reads one variant by id: name, code, product, brand, category, image and page. Name canonical attribute or block ids in `attributes` and `blocks` (comma-separated) to add their values under `specifications`; `null` means unknown, never false or zero. Selectors the variant's product type lacks come back in `notApplicable`. Variant ids are opaque tokens: pass back exactly what a `list_variants` or `find_variants_by_vector` result gave you. One indexed statement reads the Resolved Variant with Brand and product joined by key. Ineligible and untyped variants still open by id; a superseded id returns its final surviving variant. The response includes eligibility, channels, the stored palette and selected attributes with their Value Source and exact wording. Success responses carry `Cache-Control: no-store`. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/variants/{variantId}' \  -H "Authorization: Bearer $MG_API_KEY"

List a variant's images and files

Returns one bounded, filtered, cursor-paged page of a variant's images and files: images first (primary image leading), then documents, then other files. `imageRoles` narrows only images and `documentTypes` narrows only documents, so each implies its own kind; asking for both, or pairing one with other kinds, is a 400 rather than a silently widened page. Raw PIM URLs and internal storage/provider metadata are excluded. A variant's assets change when an ingest lands, so success responses carry `Cache-Control: no-store`. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/variants/{variantId}/assets' \  -H "Authorization: Bearer $MG_API_KEY"

List variants by hard filter, ranked and cursor-paged

Eligible variants, hard-filtered by `filters`, ranked by `optionalFilters` and `orderBy`, cursor-paged. This is the successor to the retired `catalog_by_spec`/`search_browse`/materials-batch/siblings surface: a hard specification across every brand, a category or brand browse, a product's other colorways and a batch lookup by id are all a kind-grouped `filters` object now — `{terms, numbers, presence, anyField}`, every condition across all four ANDed (OR within one field is `in`). `filters`, `optionalFilters`, `orderBy` and `colors` are URL-encoded JSON; `attributes`, `include` and `words` are comma-separated lists; `limit`, `cursor` and `name` are plain values. `optionalFilters` RANK only — they never exclude, and each entry's `weight` (1–10, required) sums into `preference.score` on a matched item. Responses carry `Cache-Control: no-store`. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/variants' \  -H "Authorization: Bearer $MG_API_KEY"

Count variants per attribute value under a filter tree

Contextual facet values and exact variant counts over the eligible variants `filters` admits: the options a filter UI shows next to a `list_variants` page. `filters` is the same kind-grouped `{terms, numbers, presence, anyField}` tree `list_variants` takes, less its `orText` and `unstated` additions, validated by the same code. `attributeIds` names 1–10 facetable attributes (see `list_attributes`). A categorical or boolean facet returns its top `valuesPerFacet` values (default 10) with `hasMoreValues`; a numeric facet returns its observed `min`/`max`. `missingVariantCount` counts variants recording no value: unknown, never false or zero. Requires the `mg:read` bearer scope.

curl -X POST 'https://beta.materialgraph.com/api/v1/variants/facets' \  -H "Authorization: Bearer $MG_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "attributeIds": [    "…"  ]}'

Find variants from plain words

Reads `query` into filters, runs them through `list_variants` and answers with what was understood beside a page of variants. `understood` says what each phrase became: a hard `filter`, a ranking `preference`, or `not_applied` when nothing could serve it. `filters`, `optionalFilters` and `name` are exactly what ran, so the three can be sent to `list_variants` to narrow or widen the same search. A phrase with more than one meaning is answered with one and listed in `choices`: send its `handle` with an alternative's `group` and `id` in `selections` to switch it. `unresolved` lists words nothing in the vocabulary could read. A query that applies nothing returns no items, never the whole catalogue; a preference alone still ranks it. `cursor` is the previous page's `pageInfo.endCursor`, tied to the vocabulary version the query was read against; it pages this operation only, not `list_variants`. Requires the `mg:read` bearer scope.

curl -X POST 'https://beta.materialgraph.com/api/v1/variants/search' \  -H "Authorization: Bearer $MG_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "query": "…"}'

Find variants by color — contains, palette or rerank

Flat query encoding: zero-based `color0` through `color5`, each with optional `.share`, `.shareMax`, `.dominant` and `.role` fields, e.g. `color0=%23aabbcc&color0.share=0.6`. Lists use repeated query keys; image fields are `imageAssetId`, `imageSourceId`, `imageUrl`, `imageVariantId`. The canonical color-discovery operation, one required `mode`: `contains` (variants holding a swatch for every REQUIRED `colors[]` condition, ordered by preferred conditions held then ColorVec cosine), `palette` (variants whose FULL palette resembles `colors[]`'s target shares, an image's extracted palette, or `targetVariantId`'s own palette, ordered by ColorVec cosine) or `rerank` (reorder a caller-held `variantIds` set by color closeness to `colors[0]` or `targetVariantId`). A color that fails to resolve is reported in `unresolvedColors` with actionable alternatives, never guessed. CONTAINS/PALETTE candidates are gated through `list_variants`' own eligibility and hard filters first. The page is a cursor over that gated, ranked pool, bound to the exact request that minted it — a cursor from different criteria is refused. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/variants/by-color?mode=text' \  -H "Authorization: Bearer $MG_API_KEY"

Find variants by semantic or visual similarity

Eligible variants ranked by similarity in the image-lane embedding space (voyage-multimodal-3.5). `query.mode` is `text` (mood words, unanchored), `image` (`query.images`: one to six references, each a catalogue variant or asset, an external URL, or an upload) or `text_and_image` (each image is embedded fused with the text). Several images are combined into one query vector, the mean of their normalised vectors, normalised again; every seed image's variant is left out of the results, and the vector is never returned. `references` echoes the images used, in order. `filters` is the `{terms, numbers, presence, anyField}` grammar `list_variants` takes, less its `orText` and `unstated` additions; a category, brand or variant-id condition rides Pinecone's native metadata, any other condition builds the eligible set in Postgres first and hands it to Pinecone as an allowlist. Every returned id is re-checked through `list_variants` itself with the caller's filters — what that re-check rejects is counted in `scan.rejected`, never hidden. An upload is embedded once and its vector is kept, so a later image-only query on the same upload reads it and spends nothing; with `text` the image is embedded fused with the words, and a URL is embedded on every request. Each image that has to be embedded consumes one request of the key's own `embed` limit, 10 a minute unless the key has another; a catalogue variant seed or a kept upload vector consumes none. Requires the `mg:read` bearer scope.

curl -X POST 'https://beta.materialgraph.com/api/v1/variants/by-vector' \  -H "Authorization: Bearer $MG_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "query": {    "mode": "text"  }}'

Find sampled together — what designers sampled together with your seeds

The materials designers sampled together with one or more seeds in real Material Bank projects (a sample order shows sampling, not specification), other brands first, then the most projects. Give `variantIds` and/or `materials` (free-text names, resolved to one variant each; the resolved seeds come back in `seeds`, and any reference that matched nothing in `unresolved`), at most 12 together. Each row carries `lift` (the mean over the seeds it pairs with; above 1 is above average), `seedMatchCount` (how many seeds it pairs with), `relation` (`other_brand` is another brand, `brand_sibling` and `colorway` share a seed's) and a one-line `reason`. Ranking is other brands first, then `seedMatchCount`, then lift weighted by the projects behind it, one row per product. `projectType` reads one sector from the closed project-type vocabulary; an unknown sector is refused by name. A page is lean: `include` adds `image` (`imageUrl`) and `color` (`swatches`, `colorFit`, which annotates and never reorders). Sample cards are left out unless `includeSamplingArtifacts` is true, an ops and audit switch. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/variants/sampled-together' \  -H "Authorization: Bearer $MG_API_KEY"

Resolve a manufacturer page URL or code to a stored variant

Resolves a manufacturer page URL, or a manufacturer code qualified by that URL or a brandId, to a stored variant, its brand, bounded candidates or a named unresolved reason. Exact and scoreless; the submitted URL is never persisted. The body is the `resolve_variant` tool's own output.

curl -X POST 'https://beta.materialgraph.com/api/v1/variants/resolve' \  -H "Authorization: Bearer $MG_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "brandId": "…",  "code": "…"}'

List a material's canonical blocks

Returns the canonical block completeness and status projection for one variant: canonical block ids and names, field values and statuses, and missing attribute ids. A variant's detail changes when an ingest lands, so success responses carry `Cache-Control: no-store`. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/materials/{variantId}/blocks' \  -H "Authorization: Bearer $MG_API_KEY"

List an owning Product's technical documents

Returns a paginated, URL-deduplicated union of Product- and Variant-grained technical documents. Every Variant declaration retains its contributing Variant ids and states whether it applies to the requested Variant. Coverage distinguishes an explicit empty source collection from a collection not yet ingested, and unavailable documents never carry a usable URL. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/materials/{variantId}/documents' \  -H "Authorization: Bearer $MG_API_KEY"

List retained catalog documents

Lists immutable catalog editions with their source, page, render, extraction, and failure receipts. `availability=source_unavailable` keeps a known edition visible without inventing a document; `document.contentScope` distinguishes a retained full publication from cover-only evidence. Live registry truth carries `Cache-Control: no-store`. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/catalogs' \  -H "Authorization: Bearer $MG_API_KEY"

List stable pages in a catalog edition

Returns stable one-based page identities and explicit representation coverage. A page whose derived WebP is not retained carries `status=unavailable`, the required representation version and media type, and no URL or fabricated object key. A known edition with no retained source returns `source_unavailable`. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/catalogs/{catalogId}/pages' \  -H "Authorization: Bearer $MG_API_KEY"

List verified products in a retained catalog

Returns either every reviewed product/page relationship for one available catalog or an explicit `source_unavailable` result. Each verified reference carries the exact manufacturer code printed in the publication and a normalized anchor for that printed label. `productRegion` is present only when a distinct product-image rectangle has its own explicit review receipt; it is never inferred from the label anchor. Live registry truth carries `Cache-Control: no-store`. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/catalogs/{catalogId}/references' \  -H "Authorization: Bearer $MG_API_KEY"

Read a catalog page representation receipt

Returns a retained page artifact when available, the exact expected artifact without a URL when absent, or `unresolved_page` for an unknown page id. Requires the `mg:read` bearer scope.

curl 'https://beta.materialgraph.com/api/v1/catalog-pages/{pageId}/representation' \  -H "Authorization: Bearer $MG_API_KEY"

Find verified catalogue pages for material variants

Returns exact, human-reviewed relationships between opaque variant ids and pages in immutable brand publications. Every requested id receives an explicit result: `verified`, `no_verified_reference`, `unresolved_variant`, `unavailable`, or `upstream_failure`. A `no_verified_reference` result carries a closed `reason` (`no_publication_on_record`, `publication_source_unavailable`, `publication_not_reviewed`, `product_not_yet_referenced`) and, for every reason but the first, the brand `publication` it was judged against. `no_publication_on_record` means only that the registry holds no publication for the brand, not that the brand publishes none, and no reason says the product is absent from the printed book. A generic brand PDF is never treated as page evidence, and an unreviewed relationship is never guessed. `coverage` reconciles exactly with the deduplicated results. The read reflects the current product graph and therefore carries `Cache-Control: no-store`. Requires the `mg:read` bearer scope.

curl -X POST 'https://beta.materialgraph.com/api/v1/catalogues/references' \  -H "Authorization: Bearer $MG_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "variantIds": [    "…"  ]}'

List product collections in the catalogue channel

Returns a flat, paginated shelf of product collections whose variants have governed catalogue-channel membership. Each collection includes exact current product and variant counts plus a bounded representative sample. Requires the `mg:read` bearer scope.