> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amber.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity relationships

> Traverse source records, history, files, and reference libraries

All paths below start at `/api/public/v1/brands/{brand}`. Collection filters
return the full matching set through [pagination](/pagination). A detail read
returns a bare object. Composite assignments use collections and filters.

## Products and libraries

| Starting record | Follow these references |
| - | - |
| Parent Product | `product-options?productId=`, `skus?productId=`, `product-versions?productId=`, `product-relations?productId=` |
| Version | `boms?productVersionId=`, `measurement-tables?productVersionId=` |
| BOM | `bom-components?bomId=`, `bom-skus?bomId=` |
| Product Option | `product-option-values?productOptionId=`, `product-option-dimension-values?productOptionId=`, `product-option-prices?productOptionId=`, `product-option-collections?productOptionId=` |
| SKU | `sku-dimension-values?skuId=`, `bom-skus?skuId=`, `measurement-table-skus?skuId=` |

Materials are the `/materials` library; BOM components are instances in a BOM.
Resolve `componentId` through `/materials/{id}`, and `componentVariantId` through
`/material-variants/{id}`. Resolve colors, units, and BOM sections through their
library resources.

Dimension groups, curves, axes, axis values, and cells have separate collections.
A curve's `groupId` resolves to `/dimension-groups/{id}`. Query
`dimension-curve-axes?curveId=`, then `dimension-curve-axis-values?axisId=`;
`dimension-curve-cells?curveId=` returns the sparse matrix. Product-specific
curves can also be listed with `dimension-curves?productId=`.

## Quotes and samples

`/quotes` are the sourcing requests shown as **Quotes** in Amber. Use `/quotes`
for the collection and `/quotes/{id}` for a single quote.
Use `quoteNumber` for the display number and `id` for relationships.
A quote detail's `details` preserves the source header. Its existing price
summary represents one revision and band; use child collections for history:

```text theme={null}
/quotes/{quote.id}/revisions
/quote-revisions/{revision.id}/items
/quote-items/{item.id}/price-bands
```

A revision's stored `rfqId` means the public Quote ID. An item's stored `quoteId`
means the **revision** ID. These identifiers are distinct. Brand-side visibility
includes submitted revisions and brand drafts. It excludes supplier-private
drafts and canceled revisions, matching the application.

Samples expose source status and costs. Follow `/sample-rounds?protoId=` and
`/sample-checklist-results?protoRoundId=` for rounds, structured measurements,
and checklist outcomes. The stored `protoId` means Sample ID.
Samples, rounds, and checklist results are available only while their parent
product is visible in the authorized brand, including on direct detail reads.

## Orders, logistics, and finance

An order detail keeps its existing summary and line items, adds stable line/SKU
references, and exposes its source header in `details`. Use `/order-items?orderId=`,
`/order-amendments?orderId=`, `/production-runs?orderId=`, and the related production
run items/revisions for complete source history.

Follow order shipment links into shipments, shipment items, cartons and carton
contents, charges, legs, bookings, packing lists, and item lineages. Each resource
retains its source foreign keys; the API Reference lists its exact filters.
Inventory positions retain SKU and location references. Goods receipts and
receipt lines remain separate from shipment plans.

Payment agreements and milestones describe planned terms. Payment obligations,
settlements, and receipts preserve their own identities and relationships.
Supplier invoices and invoice lines expose source amounts and order references.
Do not reconstruct these records from an order's summary total.

## Partners and locations

`/partners` returns active brand-linked partners with structured profile data and
the brand's relationship defaults. `/suppliers` retains the compact supplier
shape using the same partner IDs. Read `/contacts?partnerId=` and
`/partner-locations?partnerId=` for contacts and structured addresses.

Partner-location and brand-location records carry link identity, primary flags,
and an embedded `location`. Use these for address-book ownership; shared
locations can be owned through a link even when their original brand differs.
The `/locations` collection also resolves visible transport locations.

## Documents and downloads

`/documents` returns brand-owned native documents. To include documents shared
by a counterparty on an owned order or shipment, supply its subject:

```text theme={null}
/documents?subjectKind=ORDER&subjectKey={order.id}
/documents?subjectKind=SHIPMENT&subjectKey={shipment.id}
/documents?subjectKind=PARTNER&subjectKey={partner.id}
/documents?subjectKind=PRODUCT&subjectKey={product.id}
/documents?subjectKind=PRODUCT_OPTION&subjectKey={productOption.id}
```

Subject-filtered reads also include the existing legacy document mirrors. Keep
opaque document IDs exactly as returned. Use the same subject parameters on
`/documents/{id}` and `/documents/{id}/content` for shared documents. Content
returns a signed `url`, `expiresAt`, and optional file `extent`. Data-only
documents return `404` for content.

Legacy attachment metadata and downloads also check the attachment's own
parent. A known file ID returns `404` when that parent is unavailable, even
without subject parameters.

`subjects` lists open attachments to orders, shipments, and payments visible to
your brand. It includes asserted and derived links. Superseded records are hidden
by default; use `includeSuperseded=true` to follow their history. Resolve
`documentTypeId` through `/document-types/{id}`.

Custom field values remain on their entities. Read `/custom-field-definitions`
for definitions. Structured JSON retains its nested content. Notes, checklists,
and reference libraries have their own collections. Credentials, sessions,
private supplier drafts, and internal agent execution records are not exported.

Other supported file subjects include PRODUCT\_VERSION, SKU, SAMPLE, SAMPLE\_ROUND,
QUOTE, QUOTE\_NOTE, MATERIAL, BOM\_COMPONENT, and MEASUREMENT\_TABLE. Supply that
entity ID as `subjectKey`. `BRAND` returns the authenticated brand's own legacy
files; `subjectKey` must equal your brand ID. `subjectKind` is a closed set;
an unsupported value returns `400`.

## Quote discussions

`/quotes/{quote.id}/notes` returns a quote's discussion thread: root
notes and their replies together, so a client can reconstruct the tree from
each note's `parentNoteId`. Filter by `productId` or `parentNoteId` to narrow
further. Read a reply's attachments with
`/documents?subjectKind=QUOTE_NOTE&subjectKey={note.id}`.

## Business notes

Use `/notes?entityType=product&entityId={product.id}` for brand-owned notes.
Supported `entityType` values are `product`, `product_construction`, `order`,
`partner`, `rfq` (Quote), and `proto` (Sample). Construction notes use the Parent
Product ID. Your brand's note history remains readable when the referenced
entity is archived, deleted, or unlinked. Other entity types are excluded;
an unsupported `entityType` filter returns `400`.