> For the complete documentation index, see [llms.txt](https://docs.durohub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.durohub.com/core-concepts/components.md).

# Components

Components are the fundamental building blocks in Duro. They represent parts, assemblies, documents, and other items that make up your products. This guide covers how to query, create, and update components through the API.

## Overview

Every component in Duro has:

* A unique identifier (`id`)
* A name and optional description
* A revision value (e.g., "1.A", "2.B") tracking design iterations
* A category defining its type (Part, Assembly, Document, etc.)
* A status indicating its lifecycle state
* Attributes specific to its category

## Required Headers

All component operations require these headers:

```bash
curl 'https://api.durohub.com/graphql' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'x-organization: @your-org' \
  -H 'x-library: @your-org/your-library' \
  -H 'Content-Type: application/json' \
  -d '{"query": "..."}'
```

{% hint style="info" %}
The `x-library` header is required for all component operations since components belong to a specific library.
{% endhint %}

***

## Querying Components

### Get a Single Component

Retrieve a component by its ID:

```graphql
query GetComponent {
  component {
    findOne(id: "550e8400-e29b-41d4-a716-446655440000") {
      id
      name
      description
      revisionValue
      version
      state
      status {
        name
        color
      }
      category {
        name
        type
      }
      createdAt
      updatedAt
    }
  }
}
```

`state` is a `String` whose value is `RELEASED` or `MODIFIED` — see [State](#state).

### Get a Component by CPN

When you hold a part number rather than an id, `findByCpn` returns the component that currently has that CPN in the library named by `x-library`:

```graphql
query GetComponentByCpn {
  component {
    findByCpn(cpn: "300-00042-01") {
      id
      name
      revisionValue
      identifier {
        displayValue
      }
    }
  }
}
```

The match is case-insensitive and uses the component's **current** CPN. It returns `null` when no live, non-archived component in the library has that CPN; it is not an error. It requires `components.read`.

### List Components

Query multiple components with optional filtering and pagination:

```graphql
query ListComponents {
  component {
    findAll(
      filter: {
        categoryType: PART
        isArchived: false
      }
      pagination: { first: 20 }
    ) {
      edges {
        node {
          id
          name
          revisionValue
          version
          status {
            name
          }
          category {
            name
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

### Filter Options

The `ComponentFilterInput` supports these fields:

| Field           | Type           | Description                                                                           |
| --------------- | -------------- | ------------------------------------------------------------------------------------- |
| `ids`           | `[ID!]`        | Filter by specific component IDs                                                      |
| `name`          | `String`       | Filter by name (partial match)                                                        |
| `names`         | `[String!]`    | Filter by multiple names                                                              |
| `exactNames`    | `[String!]`    | Filter by exact name matches                                                          |
| `cpns`          | `[String!]`    | Filter by Component Part Numbers                                                      |
| `statusId`      | `String`       | Filter by status ID                                                                   |
| `categoryId`    | `String`       | Filter by category ID                                                                 |
| `categoryType`  | `CategoryType` | Filter by category type (ASSEMBLY, PART, DOCUMENT)                                    |
| `isArchived`    | `Boolean`      | Include/exclude archived components                                                   |
| `eid`           | `String`       | Filter by external identifier                                                         |
| `hasVariants`   | `Boolean`      | `true` returns only components in a variant group, `false` only components not in one |
| `excludePinned` | `Boolean`      | Exclude components pinned in the library                                              |

### Advanced Filtering

For complex queries with AND/OR logic, use the `filter` method. String conditions take an operator object (`eq`, `neq`, `in`, `contains`, …), and a status is matched by the lifecycle stage it maps to — `DESIGN`, `DEVELOPMENT`, `PRODUCTION`, `MAINTENANCE` or `OBSOLETE` — or by its own `name`:

```graphql
query AdvancedFilter {
  component {
    filter(input: {
      and: [
        { status: { mapsTo: { eq: "PRODUCTION" } } }
        { category: { type: { eq: "PART" } } }
        { createdAt: { after: "2024-01-01" } }
      ]
      pagination: { first: 50 }
    }) {
      edges {
        node {
          id
          name
          revisionValue
        }
      }
    }
  }
}
```

See [Searching and Filtering](https://docs.durohub.com/advanced-topics/searching-and-filtering.md) for comprehensive filtering options.

### Organizing Components into Groups

Group components by category, lifecycle status, type, modified-by user, label, or variant group — server-side, in a single call:

```graphql
query GroupByCategory {
  component {
    componentGroups(groupBy: CATEGORY, pagination: { first: 10 }) {
      edges {
        node {
          key
          label
          totalCount
          components {
            edges { node { id name } }
            pageInfo { hasNextPage }
          }
        }
      }
      totalCount
    }
  }
}
```

Each group returns a preview of up to 50 components. Groups with more items signal overflow via `components.pageInfo.hasNextPage`, and the remaining items can be loaded incrementally with the `componentsInGroup` query.

Grouping works with both simple and advanced filters — pass `filter` or `advancedFilter` alongside `groupBy` to scope results before grouping.

See [Component Grouping](https://docs.durohub.com/advanced-topics/component-grouping.md) for the full guide, including sorting within groups, sentinel keys for uncategorized items, and the complete API reference.

***

## Validating Attributes

Before creating or updating components, you can check attribute values against the rules defined by their category. Validation is read-only — nothing is written, so it is safe to call as often as your UI needs.

### Validating One Component

```graphql
query ValidateAttributes {
  component {
    validateAttributes(
      categoryId: "category-uuid"
      attributeValues: [
        { attributeId: "attr-uuid-1", value: "12V" }
        { attributeId: "attr-uuid-2", value: "50W" }
      ]
    ) {
      success
      message
      errors {
        attributeId
        message
      }
    }
  }
}
```

`success` is `true` when every value passes. When it is `false`, `errors` names the offending attribute and explains why, and `message` carries an optional summary.

### Validating Many Components in One Call

`validateAttributesBatch` validates a set of components in a single round trip. Use it instead of looping over `validateAttributes` — a grid of rows, a CAD assembly's variants, or an import preview should cost one request, not one per item.

```graphql
query ValidateAttributesBatch {
  component {
    validateAttributesBatch(requests: [
      {
        key: "row-1"
        categoryId: "category-uuid"
        attributeValues: [{ attributeId: "attr-uuid-1", value: "12V" }]
      }
      {
        key: "row-2"
        categoryId: "category-uuid"
        attributeValues: [{ attributeId: "attr-uuid-1", value: "not-a-voltage" }]
      }
    ]) {
      success
      results {
        key
        success
        message
        errors {
          attributeId
          message
        }
      }
    }
  }
}
```

#### AttributeValidationRequestInput Fields

| Field             | Type                      | Required | Description                                                                                                                             |
| ----------------- | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `key`             | `ID!`                     | Yes      | Caller-supplied identifier echoed back on the matching result — a component id, file path, or row key, anything stable within the batch |
| `categoryId`      | `ID!`                     | Yes      | Category whose attribute rules to validate against                                                                                      |
| `attributeValues` | `[AttributeValueInput!]!` | Yes      | The values to validate                                                                                                                  |

#### Result

`validateAttributesBatch` returns a `BatchAttributeValidationResultDto` with two fields:

| Field     | Type                                    | Description                                                                                                                                                                              |
| --------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success` | `Boolean!`                              | `true` only when **every** request passed. Read this when the question is "may I proceed?" and skip the per-request scan.                                                                |
| `results` | `[KeyedAttributeValidationResultDto!]!` | One verdict per request, in submission order. Each carries the same `success`, `message`, and `errors` fields as `validateAttributes`, plus the `key` from the request that produced it. |

Results are returned in submission order, so you can zip them against your requests positionally. Prefer matching on `key` anyway — it keeps your code correct if a request is reordered or dropped upstream, and it is the only reliable join when the same category appears many times in one batch.

A batch accepts up to **10,000** requests. A larger one is rejected whole with a `400` (`Cannot validate more than 10000 components in one request`) — split it before sending.

{% hint style="info" %}
Each request is validated independently. One failing request does not fail the batch — expect a mix of `success: true` and `success: false` entries in a single response.
{% endhint %}

{% hint style="warning" %}
**`success: false` with an empty `errors` list means the check could not run, not that the values are bad.** When validation itself fails for a request — a malformed rule on the category, for example — its result is `success: false`, `errors: []`, and a `message` starting `Validation could not be completed`. Treat that entry as unknown rather than valid; a client that only inspects `errors` would wave it through.
{% endhint %}

{% hint style="warning" %}
Validation reflects the category rules at the time of the call. It is a pre-flight check, not a guarantee: the create or update mutation validates again server-side, and that result is authoritative.
{% endhint %}

***

## Creating Components

Create one or more components using the `create` mutation:

```graphql
mutation CreateComponent {
  component {
    create(inputs: [{
      name: "Motor Assembly"
      description: "Primary drive motor assembly"
      categoryId: "category-uuid"
      attributeValues: [
        { attributeId: "attr-uuid-1", value: "12V" }
        { attributeId: "attr-uuid-2", value: "50W" }
      ]
    }]) {
      id
      name
      revisionValue
      version
      createdAt
    }
  }
}
```

### CreateComponentInput Fields

| Field                     | Type                     | Required | Description                                                                                                                                                                                                                                |
| ------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                    | `String!`                | Yes      | Component name                                                                                                                                                                                                                             |
| `description`             | `String`                 | No       | Detailed description                                                                                                                                                                                                                       |
| `categoryId`              | `String`                 | No       | Category/type for this component                                                                                                                                                                                                           |
| `statusId`                | `ID`                     | No       | Initial status                                                                                                                                                                                                                             |
| `revisionValue`           | `String`                 | No       | Initial revision (defaults based on library config)                                                                                                                                                                                        |
| `eid`                     | `String`                 | No       | External identifier for integrations                                                                                                                                                                                                       |
| `attributeValues`         | `[AttributeValueInput!]` | No       | Category-specific attribute values                                                                                                                                                                                                         |
| `fileId`                  | `ID`                     | No       | Attached file ID                                                                                                                                                                                                                           |
| `imageFileId`             | `ID`                     | No       | Component image file ID                                                                                                                                                                                                                    |
| `producedFromComponentId` | `ID`                     | No       | For a document, the component it was produced from — see [Producer tracking](#producer-tracking-for-documents)                                                                                                                             |
| `depictsComponentId`      | `ID`                     | No       | For a document, the component it depicts, such as the part a drawing shows — see [Documents](https://docs.durohub.com/core-concepts/documents.md#which-component-produced-a-document)                                                      |
| `identifierOverride`      | `IdOverrideInput`        | No       | Supply the CPN yourself: `freeform` replaces the whole CPN (the scheme must allow freeform), `elements` overrides individual scheme elements (the scheme must allow overrides) — see [Validating CPN Overrides](#validating-cpn-overrides) |
| `idInput`                 | `JSON`                   | No       | Element values for a multi-element CPN scheme, as key-value pairs, used with `categoryId` — for example `{ "product_code": "P", "suffix": "Battery" }`                                                                                     |
| `labelIds`                | `[ID!]`                  | No       | Labels to apply. Every label must belong to the component's library                                                                                                                                                                        |

### Example Response

```json
{
  "data": {
    "component": {
      "create": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "Motor Assembly",
          "revisionValue": "1.A",
          "version": 1,
          "createdAt": "2024-01-15T10:30:00Z"
        }
      ]
    }
  }
}
```

***

## Validating CPN Overrides

When a caller supplies its own values for the elements of a [CPN scheme](https://docs.durohub.com/library-configuration/cpn-schema-reference.md) — a category, a prefix, a variant — the `identifier` queries validate those values before a component is created. The question these queries answer is **"can a CPN be generated from what I have supplied?"**, not "here is the CPN this component will get."

Duro builds the CPN from the scheme, filling in whatever the caller supplied. Anything not supplied — in practice an **auto-counter**, whose value is only allocated at creation time — is rendered in `displayValue` as a run of `X` characters:

```
433-XXXXX
```

The number of `X`s is the width of the counter, which is the digit/character count of its `format.max_value` (see [Numeric Counter](https://docs.durohub.com/library-configuration/cpn-schema-reference.md#numeric-counter)). Treat `X`s as "unresolved counter", the same way the Duro web app renders them.

{% hint style="warning" %}
Do not parse a validation `displayValue` as the component's final CPN. The counter value is allocated only when the component is created.
{% endhint %}

### Determinism and uniqueness

`ValidateIdentifierOverrideResponse` exposes a determinism signal alongside the preview:

| Field             | Type       | Description                                                                                                                                                 |
| ----------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `valid`           | `Boolean!` | Whether the supplied overrides are valid. `message` carries an overall explanation, and `elementValidations` the result for each element.                   |
| `displayValue`    | `String!`  | The CPN preview, with unresolved counters rendered as `X`s.                                                                                                 |
| `isDeterministic` | `Boolean!` | `true` only when **every** element resolved from the supplied values — i.e. the preview contains no `X` placeholders and is the CPN the component will get. |
| `isUnique`        | `Boolean!` | Whether the previewed CPN is unique. **Only meaningful when `isDeterministic` is `true`.**                                                                  |

When `isDeterministic` is `false`, uniqueness is not applicable rather than false: the pending counter guarantees uniqueness by construction. `isUnique` is non-nullable on this response and will still carry a value in that case — **disregard it** and branch on `isDeterministic` instead.

```graphql
query ValidateCpnOverride($overrides: [IdElementOverrideInput!]!) {
  identifier {
    validateCompleteOverride(overrides: $overrides) {
      valid
      message
      displayValue
      isDeterministic
      isUnique
    }
  }
}
```

When re-validating an existing component's CPN, pass its id as the optional `componentId` argument so the component's own CPN is not counted as a duplicate.

A non-deterministic result is the normal, healthy case for a scheme that ends in an auto-counter — it is not an error, and it does not mean the component cannot be created.

{% hint style="info" %}
Because an unresolved counter always renders as a fixed-width run of `X`s, a non-deterministic preview is derivable from the scheme and the element values you already hold. Clients validating many rows at once — a CAD plugin pulling an assembly, for example — can render the preview locally and skip the round trip, calling the API only when they need a uniqueness answer for a fully specified CPN.
{% endhint %}

For the exact response shape and the `IdElementOverrideInput` fields, introspect the schema in [Apollo Explorer](https://api.durohub.com/graphql).

### Looking Up Identifiers

`identifier.get(ids: [String!], filter: IdsFilterInput): [Identifier!]` reads the identifier records of the library in the `x-library` header. It requires `components.read` and has **no pagination**: the whole result comes back in one response. It runs in one of two modes, chosen by the `ids` argument.

| Mode      | When                              | Behavior                                                                                                                                                                                                                                                                                      |
| --------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **By ID** | `ids` is a nonempty list          | Returns the identifier records with those IDs. `filter` is ignored, and the result cap below does not apply.                                                                                                                                                                                  |
| **List**  | `ids` is omitted, `null`, or `[]` | Returns every identifier that matches `filter`, up to a cap of **10,000**. If more than 10,000 match, the query fails with [`IDENTIFIER_LIST_TOO_LARGE`](https://docs.durohub.com/advanced-topics/error-handling.md#identifier-query-errors) rather than truncating. Exactly 10,000 succeeds. |

The `ids` values are **identifier-record IDs** — the `id` of an `Identifier` — not component IDs. If you hold components, read their `identifier { id displayValue }` through the component queries instead.

`IdsFilterInput` narrows list mode:

| Field        | Type      | Description                                                                                                                                                                  |
| ------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`       | `IdType`  | `CMP`, `PRD`, or `DOC`. Narrow by this first; it is the cheapest way to stay under the cap.                                                                                  |
| `isArchived` | `Boolean` | `false` returns live identifiers, `true` archived ones. Omitted or `null` returns both.                                                                                      |
| `entityId`   | `String`  | **Deprecated and ignored.** Identifiers carry no entity column, so this field never filtered anything. It is still accepted. Pass `ids` to look up specific records instead. |

{% hint style="warning" %}
Narrowing with `filter` does not lift the cap — a filtered result must also fit within 10,000 rows. A library with more than 10,000 live `CMP` identifiers cannot be listed through this query at all; look up the records you need by `ids`.
{% endhint %}

```graphql
query LiveComponentIdentifiers {
  identifier {
    get(filter: { type: CMP, isArchived: false }) {
      id
      displayValue
    }
  }
}
```

```graphql
query IdentifierLookup($ids: [String!]!) {
  identifier {
    get(ids: $ids) {
      id
      displayValue
    }
  }
}
```

***

## Updating Components

Update existing components using the `update` mutation:

```graphql
mutation UpdateComponent {
  component {
    update(inputs: [{
      id: "123e4567-e89b-12d3-a456-426614174000"
      name: "Motor Assembly v2"
      description: "Updated drive motor with improved efficiency"
      expectedVersion: 1
    }]) {
      id
      name
      description
      version
      updatedAt
    }
  }
}
```

{% hint style="warning" %}
**Optimistic Concurrency**: Use `expectedVersion` to prevent overwriting concurrent changes. If the current version doesn't match, the update will fail with a conflict error.
{% endhint %}

### UpdateComponentInput Fields

| Field                        | Type                     | Description                                                                                                                                                                    |
| ---------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                         | `ID!`                    | Component ID to update (required)                                                                                                                                              |
| `name`                       | `String`                 | New name                                                                                                                                                                       |
| `description`                | `String`                 | New description                                                                                                                                                                |
| `statusId`                   | `ID`                     | New status                                                                                                                                                                     |
| `revisionValue`              | `String`                 | New revision value                                                                                                                                                             |
| `categoryId`                 | `ID`                     | Change category                                                                                                                                                                |
| `attributeValues`            | `[AttributeValueInput!]` | Updated attribute values                                                                                                                                                       |
| `isArchived`                 | `Boolean`                | Archive/unarchive the component                                                                                                                                                |
| `notRevisionManaged`         | `Boolean`                | Turn [Not Revision Managed](#not-revision-managed-nrm) on or off                                                                                                               |
| `eid`                        | `String`                 | External identifier for integrations                                                                                                                                           |
| `identifierOverride`         | `IdOverrideInput`        | Change the CPN with a `freeform` value or `elements` overrides. Allowed only while the component is in Design status                                                           |
| `labelIds`                   | `[ID!]`                  | Labels to add. Labels already on the component are ignored                                                                                                                     |
| `removeLabelIds`             | `[ID!]`                  | Labels to remove. Labels not on the component are ignored                                                                                                                      |
| `producedFromComponentId`    | `ID`                     | For a document, the component it was produced from. Send `null` to clear it — see [Producer tracking](#producer-tracking-for-documents)                                        |
| `expectedVersion`            | `Int`                    | For optimistic concurrency control                                                                                                                                             |
| `saveId`                     | `ID`                     | Optional client-supplied save identifier. Calls that share a `saveId` are recorded as one save in the component's history — see [Save IDs](#save-ids-one-save-one-history-row) |
| `releasedAt`, `releasedById` | `DateTime`, `ID`         | **Deprecated and ignored.** Release metadata is system-owned — see [Release metadata is system-owned](#release-metadata-is-system-owned)                                       |

### Producer tracking for documents

A document component can record the component it was **produced from** — the part a CAD connector exported a STEP or PDF of. The field lives on the component itself and is accepted on all four write inputs:

```graphql
type Component {
  "The component this document was produced from. null when no producer was recorded."
  producedFromComponentId: ID
}

input CreateComponentInput { producedFromComponentId: ID }
input UpdateComponentInput { producedFromComponentId: ID }
input CreateItemInput      { producedFromComponentId: ID }
input UpdateItemInput      { producedFromComponentId: ID }
```

It is nullable and optional everywhere. `null` means *unrecorded*, not *produced from nothing*: documents written before the field existed, or by a tool that never sets it, simply have no producer. Omitting the field on an update leaves the recorded producer unchanged; sending `null` clears it.

The value is validated on every write that sets it:

* the producer must be an **active** component — an archived or deleted id is rejected;
* it must be in the **same library** as the document;
* it cannot be the document **itself**.

A write that fails any of these is rejected as a validation error and nothing in that input is applied.

The producer is what a [per-type document declaration](https://docs.durohub.com/core-concepts/documents.md#scoping-a-declaration-to-a-producer) uses to retract only the documents a connector generated from one specific part. How it differs from `depictsComponentId`, and when to set which, is on the [Documents](https://docs.durohub.com/core-concepts/documents.md#which-component-produced-a-document) page.

***

## Item Mutations: BOM and Documents in One Call

Saving a component from a CAD tool usually means several writes — the component's own fields, its BOM, and a document link for each drawing or exported file. Done as separate `component.create` / `component.update` calls, each is its own transaction and each writes its own history row, so one user action produces a scattered history.

The **`item` mutation namespace** collapses that into a single transaction. `item.create` and `item.update` take everything `component.create` / `component.update` take, plus the relation fields below, and write **one history row per component**.

{% hint style="info" %}
`component.create` and `component.update` are unchanged and remain the right call when you are only writing a component's own fields. They **reject** the relation fields — send `children`, `documents`, `documentComponentIds`, `removeDocumentLinkIds`, or `documentDeclaration` to `item.create` / `item.update` instead.
{% endhint %}

### Additional inputs

| Field                        | Type                              | On             | Description                                                                                                                                                                                                              |
| ---------------------------- | --------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `children`                   | `[ComponentChildInput!]`          | create, update | The component's direct BOM children.                                                                                                                                                                                     |
| `documents`                  | `[ComponentDocumentInput!]`       | create, update | Documents to create from already-uploaded files and link to this component.                                                                                                                                              |
| `documentComponentIds`       | `[ID!]`                           | create, update | Existing DOCUMENT-category components to link to this component.                                                                                                                                                         |
| `removeDocumentLinkIds`      | `[ID!]`                           | update only    | Document links to remove.                                                                                                                                                                                                |
| `documentDeclaration`        | `[DocumentTypeDeclarationInput!]` | update only    | Per file type, the complete set of document links the caller holds for this component. Caller-created links of a declared type that are not listed are removed; other callers' links and undeclared types are untouched. |
| `saveId`                     | `ID`                              | update only    | Optional client-supplied save identifier shared with a sourcing changeset — see [Save IDs](#save-ids-one-save-one-history-row).                                                                                          |
| `releasedAt`, `releasedById` | `DateTime`, `ID`                  | update only    | **Ignored.** Only Duro sets release metadata — see [Release metadata is system-owned](#release-metadata-is-system-owned).                                                                                                |

```graphql
input ComponentChildInput {
  childId: ID!
  quantity: Float
  refDes: String
  itemNumber: String
  notes: String
  childHistoryId: ID
}

input ComponentDocumentInput {
  fileId: ID!
  name: String!
  categoryId: ID
}

input DocumentTypeDeclarationInput {
  "A file extension, such as pdf or .step."
  type: String!
  "Document component ids (not link ids) linked for this type."
  documentComponentIds: [ID!]!
  "Optional. Retract only unlisted documents of this type produced from this component."
  producedFromComponentId: ID
}
```

### Creating a component with its BOM and documents

```graphql
mutation CreateItem {
  item {
    create(inputs: [{
      name: "Motor Assembly"
      categoryId: "assembly-category-uuid"
      children: [
        { childId: "child-uuid-1", quantity: 2, refDes: "M1,M2", itemNumber: "10" }
        { childId: "child-uuid-2", quantity: 1, childHistoryId: "history-uuid" }
      ]
      documents: [
        { fileId: "uploaded-file-uuid", name: "Motor Assembly Drawing" }
      ]
      documentComponentIds: ["existing-document-component-uuid"]
    }]) {
      id
      name
      revisionValue
      version
    }
  }
}
```

### BOM children semantics

* `children` is a **desired-state list of direct children only** — the same semantics as `assemblies.updateBOM`. Anything not in the list is unlinked from this component.
* There is no nesting. To publish an assembly tree, walk it level by level, one call per component.
* Children must already exist. Create them first, then reference them by `childId`.
* `quantity` is a `Float` — assembly links support fractional quantities.
* `childHistoryId` pins the link to a specific revision of the child. Omit it for a link that follows the child's latest revision.

On **update**, the three cases for `children` are distinct:

| You send                | Result                                                                |
| ----------------------- | --------------------------------------------------------------------- |
| A list of children      | The BOM becomes exactly that list; children not present are unlinked. |
| `[]` (empty list)       | All children are unlinked.                                            |
| Nothing (field omitted) | The BOM is left unchanged.                                            |

{% hint style="warning" %}
Because `children` is desired-state, a client that omits a child it did not touch will **unlink** it. Send the component's complete direct-child list, or omit the field entirely when you are not changing the BOM.
{% endhint %}

### Documents

`documents` and `documentComponentIds` are covered on the [Documents](https://docs.durohub.com/core-concepts/documents.md#creating-and-linking-documents-with-item-mutations) page, including why a document cannot be created before its parent.

`documentDeclaration` is the desired-state alternative for a tool that regenerates a known set of files: within each declared type, the caller's links become exactly the listed documents. It is scoped to the acting integration's own links and to the types it names, so it never removes a document attached in Duro or by another integration. A block can be narrowed further with `producedFromComponentId`, so that only documents generated from one specific part are retracted. It runs after the three additive inputs in the same transaction. The full contract — type matching, author scoping, producer scoping, and the legacy links it will not retract — is under [Declaring documents per type](https://docs.durohub.com/core-concepts/documents.md#declaring-documents-per-type).

### History consolidation

An `item.create` or `item.update` call writes **one `component_history` row for the component**, no matter how many of the relation fields it carries — a `documentDeclaration` that adds and removes several links still folds into that one row — and one row for each document component it creates. A batch stays all-or-nothing: if any input in the array fails, the whole call rolls back.

To fold a separate `applySourcingChangeset` call into the same history row, give both calls the same `saveId` — see [Save IDs](#save-ids-one-save-one-history-row).

{% hint style="info" %}
A single call is capped at 10 components, 20 `children` and 20 `documents` per component, and 200 `children` across the call. Anything larger is refused with `ITEM_WRITE_TOO_LARGE` before any work starts, rather than being partially applied. See [Error Handling](https://docs.durohub.com/advanced-topics/error-handling.md#item-write-errors) for the full table and how to split a publish.
{% endhint %}

***

## Deleting Components

Delete components by their IDs. `delete` returns `true` when at least one component was deleted; IDs it cannot find are skipped.

```graphql
mutation DeleteComponents {
  component {
    delete(ids: ["component-uuid-1", "component-uuid-2"])
  }
}
```

Deleting archives each component and cleans up around it, all in one transaction:

* its assembly links are removed, both as a parent and as a child;
* its document links are archived;
* its bookmarks and library pins are removed;
* it is removed from its variant group and from any draft change order.

Only components in Design status can be deleted, and not while they are in an open change order. If any component in the call fails either check, nothing is deleted:

| Code                             | When                                                                          |
| -------------------------------- | ----------------------------------------------------------------------------- |
| `DELETE_NOT_ALLOWED_PAST_DESIGN` | A component has progressed past Design status                                 |
| `COMPONENT_IN_OPEN_CHANGE_ORDER` | A component is in an open change order. Remove it from the change order first |

***

## Component States and Revisions

### State

Components have a `state` field indicating their modification status. It is a `String` with one of these values:

| State      | Description                      |
| ---------- | -------------------------------- |
| `RELEASED` | Component is released and locked |
| `MODIFIED` | Component has unreleased changes |

### Lifecycle state (`derivedState`)

`derivedState` (`DerivedComponentState`) is a read-only lifecycle label. Duro derives it from the component's status family, its last-released baseline, and its NRM flags; it is not settable.

| `derivedState` | When Duro reports it                                                                                        |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `PROPOSED`     | The component's revision or status differs from its last-released baseline, or an NRM migration is pending. |
| `MODIFIED`     | The component has user edits but nothing proposed.                                                          |
| `RELEASED`     | Otherwise.                                                                                                  |

A component in the **Design** status family is always `RELEASED`. `derivedState` describes the component as it is now; don't apply it to a historical snapshot or a history row.

Two companion flags say whether lifecycle writes are frozen, so an integration can refuse a revision or status change before attempting it:

| Field                | `true` when                                                                                                                                                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isReleasedObsolete` | A change order promoting the component to Obsolete has been released. Its revision and status can no longer change.                                                                                                           |
| `isEffectivelyNrm`   | The component is [Not Revision Managed](#not-revision-managed-nrm) and released at Production or Maintenance, so its revision and status are frozen. A pending NRM enable (below Production, or not yet released) is `false`. |

`derivedState`, `isReleasedObsolete` and `isEffectivelyNrm` are `null` when Duro cannot resolve the component's status.

The baseline these labels compare against is readable directly, from the component's history:

| Field                  | Type           | Value                                                |
| ---------------------- | -------------- | ---------------------------------------------------- |
| `lastReleasedRevision` | `String`       | The revision at the component's most recent release. |
| `lastReleasedStatus`   | `CustomStatus` | The status at the component's most recent release.   |

Both are `null` for a component that has never been released.

```graphql
query GetComponentLifecycle {
  component {
    findOne(id: "550e8400-e29b-41d4-a716-446655440000") {
      id
      revisionValue
      state
      derivedState
      status {
        name
      }
      notRevisionManaged
      lastReleasedNotRevisionManaged
      isReleasedObsolete
      isEffectivelyNrm
    }
  }
}
```

### Release metadata is system-owned

A component's release metadata — `releasedAt` and `releasedById` — is set only by Duro. Both `UpdateComponentInput` and `UpdateItemInput` still accept `releasedAt` and `releasedById`, but the values are **ignored**. On `UpdateComponentInput` the two fields are also marked `@deprecated`; drop them from your inputs.

### Revisions

The `revisionValue` field tracks design iterations (e.g., "1.A", "1.B", "2.A"). Revision schemes are configured per-library. See [Revision Scheme](https://docs.durohub.com/library-configuration/revisions.md) for configuration options.

***

## Component History

Every write to a component records a **history row**. A row is a photograph of the component at that moment — its fields, BOM version, document links, labels, and variant group — plus the list of field-level changes that produced it. Read a component's rows through `Component.history`:

```graphql
query GetComponentHistory {
  component {
    findOne(id: "550e8400-e29b-41d4-a716-446655440000") {
      id
      revisionValue
      state
      history(limit: 20) {
        id
        saveId
        createdAt
        createdBy {
          name
        }
        changeOrderId
        bomVersion
        revertedFromHistoryId
        changes {
          field
          oldValue
          newValue
          atVersion
        }
        sourcingSnapshot
        effectiveSourcingSnapshot
      }
    }
  }
}
```

Rows are newest first. The fields most useful to an integration:

| Field                       | Type                 | Description                                                                                                                                                                                                                              |
| --------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                        | `ID!`                | The history row. This is the value `childHistoryId` and `documentHistoryId` pin to.                                                                                                                                                      |
| `saveId`                    | `ID`                 | The save this row belongs to. Rows written by one logical save — a component update and its sourcing changeset, for example — share a `saveId`. `null` for rows written before save IDs existed.                                         |
| `changes`                   | `[ComponentChange!]` | Field-level diffs in this row: `field`, `oldValue`, `newValue`, and `atVersion`.                                                                                                                                                         |
| `changes[].atVersion`       | `Int`                | The component `version` the change was recorded at. When several writes are consolidated into one row, each change keeps the version it actually happened at.                                                                            |
| `sourcingSnapshot`          | `JSON`               | The component's sourcing (parts, quotes, and primary-source ranking) as photographed **by this row**. `null` when the save did not touch sourcing.                                                                                       |
| `effectiveSourcingSnapshot` | `JSON`               | The sourcing that was in effect at this row: this row's own `sourcingSnapshot` if it has one, otherwise the most recent earlier row's. Use this to reconstruct the sourcing of any historical version without walking the list yourself. |
| `bomVersion`                | `Int!`               | The BOM snapshot version this row belongs to. See [BOM line authorship](#bom-line-authorship).                                                                                                                                           |
| `revertedFromHistoryId`     | `ID`                 | Set when this row was written by a revert, pointing at the row that was restored.                                                                                                                                                        |
| `actingIntegrationId`       | `ID`                 | The integration the write was performed as, or `null` for a native Duro action. Preserved through consolidation.                                                                                                                         |

### Save IDs: one save, one history row

A CAD or ERP connector often has to make more than one call to publish a single user action — an `item.update` for the component and its BOM, then an `applySourcingChangeset` for the parts and quotes. Without coordination those land as separate history rows, and the sourcing photo is taken at a different moment from the component photo.

Pass the same **`saveId`** on every call that belongs to the save. `saveId` is optional on `UpdateComponentInput`, `UpdateItemInput`, and [`SourcingChangesetInput`](https://docs.durohub.com/core-concepts/sourcing.md#save-ids-and-sourcing-snapshots). Calls sharing a `saveId` are recorded as one save: the component's history shows a single row carrying both the field changes and the `sourcingSnapshot`.

```graphql
mutation PublishComponent($saveId: ID!) {
  item {
    update(inputs: [{
      id: "550e8400-e29b-41d4-a716-446655440000"
      description: "Drive motor, 24 V"
      children: [{ childId: "child-uuid-1", quantity: 2 }]
      saveId: $saveId
    }]) {
      id
      version
    }
  }
  vendorSourcing {
    applySourcingChangeset(
      componentId: "550e8400-e29b-41d4-a716-446655440000"
      changeset: {
        newParts: [{ tempId: "p1", mpn: "M-2400-24V", manufacturerId: "vendor-uuid" }]
        newQuotes: []
        editedParts: []
        editedQuotes: []
        deletedPartIds: []
        deletedQuoteIds: []
        prioritizedOrder: []
        primary: { kind: NONE }
        saveId: $saveId
      }
    )
  }
}
```

Generate a fresh UUID per save and never reuse it across saves. Omit `saveId` entirely when a call stands on its own — each call is then its own save, as before.

{% hint style="info" %}
`saveId` groups writes for history; it does **not** make separate calls one transaction. If the sourcing changeset fails validation, the `item.update` that shared its `saveId` has still been applied. For all-or-nothing BOM and document writes, keep them inside a single `item.update`.
{% endhint %}

### Reverting to the last released state

`component.revert(id)` restores a `MODIFIED` component to its last released state and writes a history row with `revertedFromHistoryId` set. Query `Component.revertPreview` first: it reports whether the revert will proceed, and lists **warnings** for parts of the released state that cannot be restored. The revert still runs with warnings, and they are recorded with the revert row.

```graphql
query PreviewRevert {
  component {
    findOne(id: "550e8400-e29b-41d4-a716-446655440000") {
      revertPreview {
        available
        lastReleasedRevisionValue
        blockedReason
        blockedItems {
          name
          cpn
        }
        blockedDetail
        blockedDetailParts {
          kind
          attributeNames
          conflictCount
          more
          failures {
            kind
            attributeName
            attributeType
            message
          }
        }
        warnings {
          reason
          items {
            name
            cpn
          }
        }
      }
    }
  }
}
```

`RevertWarningReason` values:

| Reason                                                                     | Meaning                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BOM_NOT_RESTORED`                                                         | The target snapshot does not carry a restorable BOM, so the component's assembly links are not restored by the revert. Typically the target is the component's creation row, or a copy or variant whose BOM was not captured at creation. Re-publish the BOM with `item.update` or `assemblyMutation.updateBOM` after reverting if it must match. |
| `BOM_PIN_NOT_RECONSTRUCTABLE`                                              | BOM links are restored, but a revision pin on one or more of them cannot be rebuilt.                                                                                                                                                                                                                                                              |
| `SOURCING_NOT_RESTORED`                                                    | Parts, quotes, and primary sources are left as they are. Check `effectiveSourcingSnapshot` on the target row for what was in effect.                                                                                                                                                                                                              |
| `LABELS_NOT_CAPTURED`, `LABELS_TRAIL_INCOMPLETE`, `LABEL_NO_LONGER_EXISTS` | Labels as of the released state are unknown, or a label has since been deleted. `items` names the labels where known.                                                                                                                                                                                                                             |
| `ATTRIBUTES_NOT_CAPTURED`, `DOCUMENTS_NOT_CAPTURED`                        | The released row predates capture of attribute values or document links.                                                                                                                                                                                                                                                                          |
| `VARIANT_GROUP_DISSOLVED`                                                  | The variant group the component belonged to no longer exists.                                                                                                                                                                                                                                                                                     |

Newly created components, including variants and duplicates, now capture their labels and document links in their creation row, so a revert to that row restores them.

#### When the revert is refused

If `available` is `false`, `blockedReason` says why. `ATTRIBUTE_VALUES_NOT_RESTORABLE` is the one refusal that is about **values** rather than referents: the released attribute values are invalid, or a value that must be unique is no longer unique. `blockedItems` is empty for it, and the specifics come from two fields:

* `blockedDetailParts: RevertBlockedDetail` — structured details. This field is nullable; use it when it is present.
* `blockedDetail: String` — the existing English description of the refusal. It remains as the fallback when `blockedDetailParts` is `null`.

`RevertBlockedDetail` fields:

| Field            | Meaning                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `kind`           | `UNIQUE_VALUE_TAKEN` when released values are no longer unique; `VALUES_INVALID` when released values are invalid. |
| `attributeNames` | Names of the affected attributes, up to three.                                                                     |
| `failures`       | Up to three `RevertBlockedFailure` entries (see below).                                                            |
| `more`           | Count of additional entries hidden by the three-entry limits.                                                      |
| `conflictCount`  | For uniqueness refusals, the number of distinct components holding the released values. Nullable.                  |

Each `RevertBlockedFailure` has a `kind` of `NOT_IN_CATEGORY`, `ATTRIBUTE_GONE`, or `MESSAGE`, plus `attributeName`, `attributeType`, and `message`, all three of which are nullable.

{% hint style="info" %}
`attributeNames` and `failures` are each capped at three entries. Check `more` for how many were omitted before summarising the refusal to a user.
{% endhint %}

***

## Not Revision Managed (NRM)

A component can be flagged as **Not Revision Managed** (NRM) when you want to track it in Duro without revising it — for example, generic hardware or reference parts. An NRM component keeps a fixed revision and is held at Production status (or Maintenance, if it was already there); its revision is not incremented on release.

NRM is gated per-library and applies only to parts and documents (not assemblies). It is available only when the library has the `notRevisionManaged` entitlement enabled and the caller has the corresponding permission. Setting it on an assembly returns `NRM_NOT_ALLOWED_ON_ASSEMBLY`, and a caller without the permission gets `NRM_PERMISSION_DENIED`.

### NRM fields on component reads

Two fields expose NRM state when querying a component:

| Field                            | Type       | Description                                                                                                                                                                                                                                                           |
| -------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `notRevisionManaged`             | `Boolean!` | Whether the component is currently Not Revision Managed.                                                                                                                                                                                                              |
| `lastReleasedNotRevisionManaged` | `Boolean`  | The NRM flag as of the component's most recent release. Returned only for components that have been released at least once (`null` otherwise). Use it to detect a Revision Managed ↔ NRM transition — for example, to establish the baseline for a change order item. |

```graphql
query GetComponentNrm {
  component {
    findOne(id: "550e8400-e29b-41d4-a716-446655440000") {
      id
      name
      revisionValue
      status {
        name
      }
      notRevisionManaged
      lastReleasedNotRevisionManaged
    }
  }
}
```

### NRM in search results

Search result nodes (`ComponentSearchResultDto`, returned by `componentSearch`) also expose `notRevisionManaged`, so lightweight listing and search contexts can surface an NRM marker without loading the full component:

```graphql
query SearchNrm {
  component {
    componentSearch(search: "resistor", limit: 20) {
      id
      name
      displayValue
      notRevisionManaged
    }
  }
}
```

{% hint style="info" %}
Marking an Obsolete component as NRM is not allowed. Attempting it in an update returns the `NRM_NOT_ALLOWED_ON_OBSOLETE` validation error — see [Error Handling](https://docs.durohub.com/advanced-topics/error-handling.md).
{% endhint %}

***

## Generated document formats

Components do not carry a list of document formats to generate. Which derived files a CAD integration generates (PDF, STEP, …) and where it saves them is a library-level integration setting managed by a library admin, not a value stored on the component or set through the component API. The documents a component actually holds are queried separately — see [Documents](https://docs.durohub.com/core-concepts/documents.md).

***

## Working with Assemblies

Assemblies are components that contain other components. Read an assembly's structure through the `assembly` namespace:

```graphql
query GetAssemblyStructure {
  assembly {
    getAssemblyTrees(assemblyIds: ["assembly-uuid"], depth: 1) {
      parent {
        id
        name
      }
      children {
        assemblyLink {
          quantity
          refDes
        }
        child {
          id
          name
        }
      }
    }
  }
}
```

`depth` defaults to `-1` (the whole tree). `getFlattenedAssemblyTree(rootId:)` returns the same structure as a flat list.

{% hint style="info" %}
For BOM writes, use `item.update` with `children` (see [BOM children semantics](#bom-children-semantics)) or the `assemblyMutation` namespace. To tell which principal authored a given BOM line, see [BOM line authorship](#bom-line-authorship).
{% endhint %}

***

## Complete cURL Example

Here's a complete example creating a component:

```bash
curl 'https://api.durohub.com/graphql' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'x-organization: @acme-corp' \
  -H 'x-library: @acme-corp/main-library' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation CreateComponent($input: [CreateComponentInput!]!) { component { create(inputs: $input) { id name revisionValue } } }",
    "variables": {
      "input": [{
        "name": "Capacitor 100uF",
        "description": "Electrolytic capacitor, 100uF 25V",
        "categoryId": "part-category-uuid"
      }]
    }
  }'
```

***

## Sourcing

Components carry **sourcing** data: the manufacturer parts (MPNs) that source a component, the distributor quotes (DPNs) that price each part, and which source is currently primary. The whole sourcing surface is namespaced under `vendorSourcing` on `Query` and `Mutation` and has its own page — see [Sourcing](https://docs.durohub.com/core-concepts/sourcing.md) for the model, task-oriented examples, and the full operation reference.

{% hint style="warning" %}
`Quote.unitPrice` (and `CreateQuoteInput.unitPrice`) is **nullable** — details and other quote-field notes are on the [Sourcing](https://docs.durohub.com/core-concepts/sourcing.md) page.
{% endhint %}

Components whose price predates sourcing carry placeholder sourcing rows created by the legacy cost migration. `Part.isLegacyImport` and `Quote.isLegacyImport` flag them so you can tell a migrated price from a real vendor offer — see [Legacy-import parts and quotes](https://docs.durohub.com/core-concepts/sourcing.md#legacy-import-parts-and-quotes).

### Components sourced by a vendor

`vendorSourcing.componentSourcingByVendor(vendorId: ID!, first: Int = 10, after: String): ComponentSourcingConnection!` lists a vendor's live manufacturer parts and distributor quotes within the request's library — one row per part the vendor manufactures and one per quote it distributes. It requires the `sourcing.vendor.read` permission in that library.

```graphql
query ComponentsSourcedByVendor($vendorId: ID!, $after: String) {
  vendorSourcing {
    componentSourcingByVendor(vendorId: $vendorId, first: 25, after: $after) {
      edges {
        node {
          componentId
          component {
            id
            name
            identifier {
              displayValue
            }
            imageFile {
              downloadUrl
            }
          }
          vendorType
          sourcingTag
          mpn
          dpn
          leadTimeDays
          unitPrice
          currency
          minQuantity
          packageQuantity
          packageType {
            id
            name
          }
          updatedAt
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

| Argument          | Description                                                                                                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `vendorId: ID!`   | The vendor to list sourcing for. A vendor that isn't in the request's library returns `VENDOR_NOT_FOUND` — see [Error Handling](https://docs.durohub.com/advanced-topics/error-handling.md#sourcing-query-errors). |
| `first: Int = 10` | Page size. Defaults to 10 and is clamped to the range 1–100.                                                                                                                                                       |
| `after: String`   | The `endCursor` of the previous page. An invalid cursor returns `COMPONENT_SOURCING_INVALID_CURSOR`.                                                                                                               |

Each `ComponentSourcing` row carries:

| Field                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentId`                                               | The component the part or quote belongs to                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `component`                                                 | The component itself, resolved by federation through the component service within the request's library. Requires `components.read`: without it, `component` is `null` and the response carries a [`PERMISSION_NOT_FOUND`](https://docs.durohub.com/advanced-topics/error-handling.md#sourcing-query-errors) error. When the component cannot be returned (archived, in another library, or missing), `component` is `null` **as long as `name` is selected**; without `name`, the object comes back with its selected fields `null`. Always select `name` |
| `vendorType`                                                | `MANUFACTURER` for a part row, `DISTRIBUTOR` for a quote row — the vendor's role on this row, not its catalog `types` list                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `sourcingTag`                                               | `PRIMARY`, `PRIORITIZED`, or `NONE`, from the component's primary sources (rank 1 is `PRIMARY`, rank 2 and below `PRIORITIZED`). A manufacturer row takes the best tag among its part's quotes                                                                                                                                                                                                                                                                                                                                                             |
| `mpn`, `dpn`                                                | The manufacturer part number on every row; the distributor part number on quote rows (`null` on manufacturer rows)                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `leadTimeDays`                                              | The quote's lead time for distributor rows; the part's manufacturer lead time for manufacturer rows                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `unitPrice`, `currency`                                     | The quote's price and currency. `null` on manufacturer rows; `unitPrice` is also `null` on an unpriced quote                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `minQuantity`, `packageQuantity`, `packageType { id name }` | The quote's minimum order quantity and package details. `null` on manufacturer rows                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `updatedAt`                                                 | When the part or quote was last updated                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

The connection exposes `pageInfo { hasNextPage endCursor }`. Pass `endCursor` as `after` while `hasNextPage` is `true`. Rows are sorted by `sourcingTag` — `PRIMARY`, then `PRIORITIZED`, then `NONE` — and newest first within each group. There is no `sort` argument and no `totalCount`.

Archived parts and quotes are excluded. The vendor itself need not be active: an archived vendor still returns its live rows. A vendor with no matching rows returns an empty page rather than an error.

## Integration Access and Provenance

A component can be written by more than one party: people working in Duro, and integrations such as a CAD plugin or an ERP connector. Duro reconciles those writers with a **principal model** — every writer, including Duro itself, is a principal with explicit component links and per-attribute access.

{% hint style="info" %}
Attribute management is opt-in per library. Until a library configures it, every attribute is open and an integration that never links components writes exactly as it would otherwise. Once management is configured, a write that touches a managed attribute can fail with one of the [integration access errors](https://docs.durohub.com/advanced-topics/error-handling.md#integration-access-errors).
{% endhint %}

### Principals and links

* **Duro is a principal.** Duro itself is a reserved native integration in every organization, with its own entries in the access matrix and its own component links. There is no special "edited by a human" carve-out.
* **Links are additive.** A component can be linked to several principals at once, and linking one integration never unlinks another.
* **Creation links the creator.** A component created in the Duro web app is linked to Duro; one created by a CAD plugin's *Pull Part* is linked to that integration.
* **Editing never links.** A later write does not silently claim a component — linking is an explicit action (`linkComponent`, or the equivalent toggle in the app).

### Attribute access

For a given principal, each attribute is either **open** or **managed**:

|             | Who can write it                                                                                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Open**    | Any caller with `components.update`. **No component link is required** — including for an integration pushing open attributes to a component it is not linked to. |
| **Managed** | Only principals that are both **linked to the component** and **managers of that attribute**.                                                                     |

A managed attribute with **no linked manager is frozen**, not silently reopened: nothing writes it until a manager is linked. This is deliberate — it is one explicit toggle away from editable, rather than quietly falling back to open.

The write axis is set per principal per attribute, through the `write` field of an `AttributeAccessEntryInput` passed to `setAttributeAccess`. It takes four values:

| Write value       | Meaning for that principal                                                                                                                                                        |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPEN`            | The principal is not designated (the default). It writes the attribute wherever no designated manager is linked to the component; where a manager is linked, the value is theirs. |
| `WRITE`           | The principal is a manager: it writes the attribute on components it is linked to. Other principals can be managers of the same attribute.                                        |
| `NO_WRITE`        | The principal never writes the attribute, whether or not it is linked.                                                                                                            |
| `EXCLUSIVE_WRITE` | The principal is the **sole** manager: it writes the attribute on components it is linked to, and no other principal may hold a write designation on it.                          |

Exclusivity is the designation behind an attribute shown as *exclusively managed* in the app — the setup a library uses when one CAD integration owns a computed value such as `Mass` and nothing else, Duro included, should push it.

{% hint style="warning" %}
**Exclusivity is never granted by demotion.** If another principal already holds `WRITE` or `EXCLUSIVE_WRITE` on the attribute, a `setAttributeAccess` call requesting `EXCLUSIVE_WRITE` is **rejected** — the existing managers are left in place, not silently downgraded. Clear the other principals' designations first, then grant exclusivity. The same guard runs the other way: granting a second principal write on an attribute another principal manages exclusively is rejected too. Both cases surface as [integration access errors](https://docs.durohub.com/advanced-topics/error-handling.md#integration-access-errors).
{% endhint %}

`accessPolicy` reads the stored designation back unchanged, so an attribute set to `EXCLUSIVE_WRITE` round-trips as `EXCLUSIVE_WRITE` — clients that re-submit a policy they just read should send the value through as-is rather than mapping it down to `WRITE`, which would silently drop the exclusivity.

The read axis is configured per library. An integration can be configured receive-only or no-access for an attribute, in which case reads made on that integration's behalf **withhold** the value rather than failing the query — so treat a missing attribute as "not accessible to you", not "not set". The Duro principal always reads and cannot be configured no-read, since the PLM has to render its own data; attempting it returns `STORE_PRINCIPAL_ALWAYS_READS`.

### Reading access state from a component

| Field                                       | Description                                                                                                                                                                                                                                         |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `effectiveAttributeAccess`                  | Component-scoped effective access per attribute for the calling principal. This is the field to branch on when deciding whether to offer an edit — it already accounts for links, management, and the frozen rule.                                  |
| `integrationLock`                           | Which attributes are write-locked on this component (`lockedAttributeIds`, and per attribute `lockedAttributes`), the integrations that manage them (`managingIntegrations`), and every integration linked to the component (`linkedIntegrations`). |
| `originIntegrationId` / `originIntegration` | Provenance — the id of the integration the component originated from, and the resolved integration itself.                                                                                                                                          |

```graphql
query GetComponentAccess {
  component {
    findOne(id: "550e8400-e29b-41d4-a716-446655440000") {
      id
      name
      originIntegrationId
      originIntegration {
        id
        name
      }
      integrationLock {
        lockedAttributeIds
        managingIntegrations {
          id
          name
        }
      }
      effectiveAttributeAccess {
        attributeId
        writable
        state
        managers {
          integration {
            id
            name
          }
          linked
        }
      }
    }
  }
}
```

`effectiveAttributeAccess[].state` is one of `OPEN`, `WRITABLE_MANAGER`, `NOT_LINKED`, `RECEIVE_ONLY` or `MANAGED_BY_OTHER`.

Access that does not depend on a particular component is read from the attribute itself: `Attribute.viewerAccess` (for example through a category's `attributes`) reports the calling principal's `read` and `write` access and, when the attribute is managed by someone else, which integration (`lockedByIntegrationId`, `lockedByIntegrationName`) or whether Duro's own policy (`lockedByStore`) holds it.

### Configuring what an integration manages

| Operation                                                    | Description                                                                                                                                                            |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `integrations { recommendedAttributes(integrationId: ID!) }` | The attributes Duro suggests this integration manage — a starting point when setting one up, rather than an enforced list.                                             |
| `integrations { accessPolicy }`                              | The access matrix for the current library: for every attribute with a configured policy, each principal's read and write access.                                       |
| `integrationsM { setAttributeAccess(input:) }` (mutation)    | Sets an integration's access for specific attributes. Requires the `integrations.configure` permission — see [RBAC](https://docs.durohub.com/advanced-topics/rbac.md). |

### Linking and reconcile

| Operation                         | Description                                                                                                                                                                                                                                                                                            |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `linkComponent` (root mutation)   | Links a component to an integration. Additive — existing links are preserved. Required before that integration can write managed attributes.                                                                                                                                                           |
| `unlinkComponent` (root mutation) | Removes the link. Any managed attribute left with no linked manager becomes frozen.                                                                                                                                                                                                                    |
| `reconcile` (root query)          | The sync entry point for integrations: a read-only three-way merge. Submit each component's base version and the attribute values the integration holds, and Duro returns a sync state per component and a directive per attribute (`SET`, `CLEAR`, `KEEP`, `CONFLICT` or `INVALID`). It never writes. |

`reconcile` tells the integration what to change; the writes themselves go through `component.update` or `item.update`, which enforce the access rules. A write the integration is not allowed to make surfaces as one of the [integration access errors](https://docs.durohub.com/advanced-topics/error-handling.md#integration-access-errors).

The result of a `reconcile` call carries one `ReconcileComponentResult` per submitted component. Its `syncState` (`IN_SYNC`, `BEHIND`, `AHEAD`, `DIVERGED`, `UNTRACKED`) describes the **attributes** only — whether the integration's presented values, Duro's stored values, or both have moved since the `baseVersion` the integration last synced against. The per-attribute `directives` tell the integration what to do about it.

### Declaring the BOM on reconcile

Reconcile also compares the integration's view of an assembly's **BOM**, so a child added or removed on the integration side is visible as drift without pushing the whole assembly first. This is opt-in per component: `ReconcileComponentInput.children` takes a list of `ReconcileChildInput` values, and the result reports a separate `bomState`.

| `ReconcileChildInput` field | Type     | Description                                                                                                                                                                                                                                        |
| --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `childId`                   | `ID`     | The Duro id of the child. Optional when `childName` is given.                                                                                                                                                                                      |
| `childName`                 | `String` | The child's name, for children whose Duro id the integration does not have. Resolved to an id before comparison, scoped to the same lines an id would be — so a name can never reach a line another writer authored. An ambiguous name is refused. |
| `quantity`                  | `Float`  | The quantity of that child in this assembly.                                                                                                                                                                                                       |

As with `item.update`, the three ways of sending `children` mean different things:

| You send                | Means                                                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| A list of children      | "This is my BOM" — Duro compares it against the lines it holds for you.                                                           |
| `[]` (empty list)       | "This assembly has **no** children" — a genuine removal of every line you authored.                                               |
| Nothing (field omitted) | "I am not declaring a BOM" — the BOM is not compared, `bomState` is `UNKNOWN` (never drift), and nothing is treated as a removal. |

{% hint style="warning" %}
`[]` and an omitted field are not interchangeable. An integration that cannot read an assembly's tree — or is reconciling a part, which has no BOM of its own — should **omit** `children` rather than send an empty list. Sending `[]` for a tree you could not read declares that its lines should go.
{% endhint %}

**How the comparison works.** Duro sums quantity per child (ten instances of the same fastener are one child at quantity 10) and compares the declared set against the assembly's current lines **authored by the acting integration only** — the same author scoping as `AssemblyLink.createdByIntegrationId` in [BOM line authorship](#bom-line-authorship). A line added in the Duro web app, or by another integration, is neither reported as drift nor removed by your push. A child declared both by id and by name is one child; when both are given, the id wins. A child that cannot be resolved to a component in Duro is not part of the comparison at all — its absence from Duro is never read as a removal.

**Reading `bomState`.** `ReconcileComponentResult.bomState` is a `ReconcileBomState`, alongside and independent of `syncState`:

| `bomState`     | Meaning                                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IN_SYNC`      | The declared BOM matches the lines you authored in Duro.                                                                                                                                          |
| `AHEAD`        | The declared BOM differs from your lines in Duro — the integration has unpushed BOM changes.                                                                                                      |
| `UNKNOWN`      | No comparison was made because `children` was omitted. Treat as "no information", not as in-sync. A declared child that cannot be resolved does not cause this; it is left out of the comparison. |
| `NOT_WRITABLE` | The acting principal is not permitted to write this assembly's BOM, so any difference is reported as not pushable rather than as drift you can resolve.                                           |

A BOM can only ever be **ahead** for an integration. Declarations are one-directional: Duro compares what you declare, but a BOM edited in Duro is never pulled back into the integration through reconcile, so there is no `BEHIND` for BOMs. Pushing the declared list — via `item.update` with the same `children`, or `assemblies.updateBOM` — brings `bomState` back to `IN_SYNC`; because removals are author-scoped, that push retracts only the lines this integration created.

```graphql
# One component's input to reconcile: attributes are presented as before,
# and the BOM is declared alongside them.
{
  componentId: "550e8400-e29b-41d4-a716-446655440000"
  baseVersion: 12
  presented: [ ... ]
  children: [
    { childId: "7c9e6679-7425-40de-944b-e07fc1f90ae7", quantity: 4 }
    { childName: "M3x8 SHCS", quantity: 10 }
  ]
}
```

{% hint style="info" %}
Combine the two states when deciding what to show. `syncState: IN_SYNC` with `bomState: AHEAD` means only the BOM changed; `syncState: BEHIND` with `bomState: AHEAD` means Duro has attribute changes to pull **and** the integration has BOM changes to push — a both-changed condition that neither field reports on its own.
{% endhint %}

### Attribute merge and delete semantics

`attributeValues` on an update is a **merge**, not a replacement:

* An attribute **absent** from the input is left unchanged.
* An attribute **present with a value** is set to that value.
* An attribute **present with a wrapped `null`** — the value key supplied, explicitly `null` — **deletes** the stored value: `{ attributeId: "attr-uuid", value: null }`.

{% hint style="warning" %}
Omitting an attribute and sending `null` for it are different operations. Clients that strip `null` fields before serializing will silently turn a delete into a no-op — make sure your GraphQL client sends the explicit `null` through.
{% endhint %}

#### Reserved `field:*` reconciliation IDs

The `attributeId` on a `reconcile` attribute directive, and on a presented attribute, is normally the UUID of a custom attribute. A small set of **reserved IDs** lets an integration reconcile a component's built-in fields through the same directive list, so one payload can carry both the custom attributes and the core fields the integration manages:

| Reserved ID      | Component field   | Value carried      |
| ---------------- | ----------------- | ------------------ |
| `field:eid`      | EID (external ID) | String             |
| `field:status`   | Status            | ID of the status   |
| `field:revision` | Revision          | String             |
| `field:category` | Category          | ID of the category |

Two rules apply to these IDs:

* **Values are bare scalars.** A `field:*` entry carries the string or ID directly — not the `{ value }` wrapper a custom attribute uses. Merge semantics are otherwise the same: an absent field is left unchanged, and the integration must have write access to the field for the write to apply.
* **The whole `field:` prefix is reserved.** Only the four IDs above are recognized. Any other `field:*` ID is **ignored** rather than rejected — the rest of the reconcile still applies, and no error is raised for the unknown entry.

{% hint style="info" %}
Because unknown `field:*` IDs are silently ignored, a typo such as `field:rev` will not fail the request; it will simply leave the revision untouched. Check the reconcile result rather than relying on an error to catch it.
{% endhint %}

### Access scopes

Some writes are governed per component by an **access scope** rather than per attribute. Two scopes are enforced today:

| Scope       | What it covers                                                                                                                                                                                                                                            | Verdict taken on                                    |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `BOM`       | Adding, removing, swapping or re-quantifying the lines of an assembly's BOM — through `children` on `item.create` / `item.update`, the assembly mutations, a component import that changes a parent's children, and a `reconcile` that declares children. | The parent assembly.                                |
| `DOCUMENTS` | Creating, removing or re-pinning a document link, and pointing a document at a component. See [Who May Change a Component's Documents](https://docs.durohub.com/core-concepts/documents.md#who-may-change-a-components-documents).                        | The component the document is linked to or depicts. |

A scope uses the same designation model as an attribute — `OPEN`, `WRITE`, `NO_WRITE` or `EXCLUSIVE_WRITE` per principal, the same exclusivity guard, and a link to the component required before a designated manager may write it. A library admin sets it with `setScopeAccess` (one transaction, entries applied in order; `integrationId: null` addresses the Duro principal) and reads the matrix back with `scopeAccessPolicy`. With nothing configured a scope is **open**: every caller that could write before still can.

Read the verdict before you write, from the component the write will be judged on:

```graphql
query ScopeAccess {
  component {
    findOne(id: "550e8400-e29b-41d4-a716-446655440000") {
      scopeAccess(scopes: [BOM, DOCUMENTS]) {
        scope
        writable
        state
        managedBy {
          id
          name
        }
        managers {
          integration {
            id
            name
          }
          linked
        }
      }
    }
  }
}
```

| Field       | Meaning                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `writable`  | Whether the principal making this request may write the scope on this component. It is the same decision the write itself would get.                                                                                         |
| `state`     | Why: `OPEN`, `WRITABLE_MANAGER`, `NOT_LINKED`, `RECEIVE_ONLY` or `MANAGED_BY_OTHER`. `FROZEN` remains in the enum for older clients but is no longer produced: a scope whose designated managers are all unlinked is `OPEN`. |
| `managedBy` | The managing integration to show a person, or `null` when the scope is open or receive-only.                                                                                                                                 |
| `managers`  | Every integration designated to write the scope, each with `linked`: whether it is linked to this component. "Managed by" means designated **and** linked.                                                                   |

`writable` depends on who is asking, so the same component can answer `true` to the managing connector and `false` to the web app in the same moment. A refused write returns one of the [access scope errors](https://docs.durohub.com/advanced-topics/error-handling.md#access-scope-errors). `reconcile` applies the same verdict: an assembly whose BOM the caller may not write is reported with `bomState: NOT_WRITABLE` instead of a comparison, since a push would be refused.

### BOM line authorship

The same provenance idea applies one level down, to the individual lines of an assembly's BOM. Three read-only fields record which principal authored a line, so a component/BOM integration can tell its own contribution apart from everyone else's:

| Field                                      | Description                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AssemblyLink.createdByIntegrationId`      | `ID` — the integration that **last wrote** this BOM line. A line changed by a different principal is re-attributed to that principal (last writer owns).                                                                                                                                                     |
| `AssemblyLink.authoredByActingIntegration` | `Boolean!` — `true` when the principal making this request is the line's last writer: the acting integration, or native Duro when the request acts for none. The same rule as [`DocumentLink.authoredByActingIntegration`](https://docs.durohub.com/core-concepts/documents.md#who-created-a-document-link). |
| `AssemblyLinkHistory.actingIntegrationId`  | `ID` — the integration acting when that BOM snapshot version was created. The document counterpart is [`DocumentLinkHistory.actingIntegrationId`](https://docs.durohub.com/core-concepts/documents.md#who-changed-a-document-link).                                                                          |

The two `ID` fields are `null` when the action was **native to Duro** — a line written in the web app, or a snapshot produced by a Duro-side action. Lines written before these fields shipped also read `null`. So read `null` as *"not attributable to an integration"* rather than *"unowned"*.

The practical use is diffing on the integration's side: when pushing a BOM, compare the incoming lines against the lines where `authoredByActingIntegration` is `true` to work out what you added, changed, or no longer declare — and leave lines authored by another principal, or by Duro, alone. A `reconcile` that declares children does this comparison for you and reports it as `bomState`. `AssemblyLinkHistory.actingIntegrationId` gives the same attribution per snapshot version, which is what makes it possible to tell "the line I pushed last time" from "the line someone edited since".

{% hint style="warning" %}
These fields are **provenance, not authority**. They record who last wrote a line; they do not grant or restrict write access, and Duro does not refuse a write based on them. What a caller may do to an assembly's BOM is decided by the `BOM` [access scope](#access-scopes).
{% endhint %}

{% hint style="info" %}
For the exact field-level shape of the access types, the null wrapper, and the `reconcile` / `setAttributeAccess` inputs, introspect the schema in [Apollo Explorer](https://api.durohub.com/graphql). This page documents the behavior; Explorer always reflects the current contract.
{% endhint %}

***

## Next Steps

* Bulk-create and update components with [Importing Components](https://docs.durohub.com/core-concepts/importing-components.md)
* Learn about [Documents](https://docs.durohub.com/core-concepts/documents.md) associated with components
* Explore [Change Orders](https://docs.durohub.com/core-concepts/change-orders.md) for managing component modifications
* See [Searching and Filtering](https://docs.durohub.com/advanced-topics/searching-and-filtering.md) for advanced queries


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.durohub.com/core-concepts/components.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
