> For the complete documentation index, see [llms.txt](https://docs.tracr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tracr.com/tracr-user-guide/12.-editing-assets.md).

# 12. Editing Assets

Every diamond registered on Tracr can have multiple associated assets, including images, videos, scans and plans. The 1.35 release introduced a more flexible way to manage these assets: they can now be added, updated or removed at any point in the diamond’s lifecycle, rather than only while the diamond is in the lifecycle stage to which the asset relates. For example, rough stage images can be managed after the diamond has moved beyond the rough stage.

Scans used for objective verification are the exception. While a diamond is rough, changing or removing a scan removes its rough objective verification state, and adding a new scan causes that state to be recalculated. Once the diamond has been split or polished, its rough scan cannot be changed.

Each asset can be assigned to a gallery. For example, images can be displayed in the rough, split or polished gallery on the diamond details page in the Portal, and in the appropriate gallery in Diamond Experience once the diamond is polished, inscribed and unlocked.

An asset can also be marked as the hero asset. This image or video appears at the top of the diamond details page and on the Your Diamond page in Diamond Experience.

An asset does not have to be assigned to a gallery. If no gallery is set, the asset is not displayed, but it remains attached to the diamond, is returned by the API and is transferred with the diamond.

When you add an asset to the top rough diamond, it is shared with the child diamonds created from that rough. The asset appears in the rough gallery for all child diamonds that are held by the participant who added the asset at the time it is added. If you later remove the asset from the top rough, it is removed from those child diamonds’ rough galleries, unless a child diamond has already been transferred and retains its own copy.

When you add an asset directly to a child diamond and choose the rough gallery, the asset is specific to that child diamond. It appears in that child diamond’s rough gallery only. It does not appear for other diamonds made from the same rough, including child diamonds that already exist or are created later.

### Example API flows

The following examples show the main asset-management operations. Replace \<API\_BASE\_URL>, \<ACCESS\_TOKEN> and the IDs with values from your environment.

### Add an image asset

To add an image to a diamond you use the /v2/diamond-asset/image end point with multipart/form-data. The diamond\_stage describes the lifecycle stage the asset relates to, while gallery controls where it is displayed.

Diamond stage can be one of: rough, or polished.\
Image Type can be one of: default, 3d, b2b, heart, arrow, aset\_scope, plot, face\_up, dark\_field, ideal\_scope, fluorescence, inclusion\_map, diagram, or other

#### **Request**

Make a request to `/v2/diamond-asset/image` with the required and recommended fields

> **Required Fields**
>
> * Diamond ID
> * File
>
> **Recommended Fields**
>
> * Diamond Stage
> * Gallery
> * Gallery Priority
> * Image Type
> * Is Hero
> * Label

{% tabs %}
{% tab title="Response" %}

| Key               | Value                      |
| ----------------- | -------------------------- |
| **diamond\_id**   | c5scudab4autgb1dhpagyg5l   |
| **file**          | /diamonds/defaultimage.jpg |
| diamond\_stage    | rough                      |
| gallery           | rough                      |
| gallery\_priority | 10                         |
| image\_type       | default                    |
| is\_hero          | true                       |
| label             | Default Image              |
| {% endtab %}      |                            |

{% tab title="Response" %}
{% code title="Response (201)" %}

```json
{
  "asset_type": "image",
  "content_hash": "string",
  "created_at": "2026-09-02T14:30:17.158Z",
  "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
  "diamond_stage": "polished",
  "extension": "avif",
  "filename": "string",
  "gallery": "rough",
  "gallery_priority": 0,
  "id": "e1mv3nn4n10kd1lw6mde6sums",
  "image_type": "default",
  "is_hero": false,
  "label": "string",
  "updated_at": "2026-09-02T14:30:17.158Z"
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

If is\_hero is true, the asset becomes the diamond’s hero asset and any other hero asset for that diamond is unset.

#### HTTP response status code

| Code | Descriptions                                                                                                              |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| 401  | Unauthorized: The request has not been applied because it lacks valid authentication credentials for the target resource. |
| 401  | Forbidden: The application does not have sufficient permissions for this operation.                                       |
| 422  | Unprocessable Entity, request JSON body is not as per specification                                                       |
| 500  | Internal Server Error. If this error persists please contact the Platform Admin team.                                     |

### List assets

Retrieve all non-deleted assets, optionally filtering the results by diamond, asset type, gallery, lifecycle stage, hero status or creation and update dates.

Call `/v2/diamond-asset/` with any combination of the below filter parameters

> **Recommended Fields**
>
> * diamond\_id\_\_in
> * asset\_type\_\_in
> * is\_hero
> * diamond\_stage\_\_in
> * diamond\_stage\_\_isnull
> * gallery\_\_in
> * gallery\_\_isnull
> * created\_at\_\_gte
> * created\_at\_\_lt
> * updated\_at\_\_gte
> * updated\_at\_\_lt
> * page
> * size

Call `/v2/diamond-asset/`

{% tabs %}
{% tab title="Request" %}
`/v2/diamond-asset/?diamond_id__in=<DIAMOND_ID>&asset_type__in=image,video&gallery__in=rough&is_hero=true`
{% endtab %}

{% tab title="Response" %}
{% code title="Response (200)" %}

```json
{
  "next": "string",
  "page": 1,
  "pages": 0,
  "previous": "string",
  "results": [
    {
      "asset_type": "image",
      "content_hash": "string",
      "created_at": "2026-09-03T14:48:35.682Z",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_stage": "polished",
      "extension": "avif",
      "filename": "string",
      "gallery": "rough",
      "gallery_priority": 0,
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "image_type": "default",
      "is_hero": false,
      "label": "string",
      "updated_at": "2026-09-03T14:48:35.682Z"
    },
    {
      "asset_type": "video",
      "content_hash": "string",
      "created_at": "2026-09-03T14:48:35.682Z",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_stage": "polished",
      "extension": "mov",
      "filename": "string",
      "gallery": "rough",
      "gallery_priority": 0,
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "is_hero": false,
      "label": "string",
      "updated_at": "2026-09-03T14:48:35.682Z"
    },
    {
      "asset_type": "scan",
      "content_hash": "string",
      "created_at": "2026-09-03T14:48:35.682Z",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_stage": "polished",
      "extension": "ply",
      "filename": "string",
      "gallery": "rough",
      "gallery_priority": 0,
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "is_hero": false,
      "label": "string",
      "scan_device_manufacturer": "string",
      "scan_device_model": "string",
      "updated_at": "2026-09-03T14:48:35.682Z"
    },
    {
      "asset_type": "scan_report",
      "content_hash": "string",
      "created_at": "2026-09-03T14:48:35.682Z",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_stage": "polished",
      "extension": "string",
      "filename": "string",
      "gallery": "rough",
      "gallery_priority": 0,
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "is_hero": false,
      "label": "string",
      "scan_device_manufacturer": "string",
      "scan_device_model": "string",
      "scan_software_name": "string",
      "scan_software_version": "string",
      "updated_at": "2026-09-03T14:48:35.682Z"
    },
    {
      "asset_type": "plan",
      "content_hash": "string",
      "created_at": "2026-09-03T14:48:35.682Z",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_stage": "polished",
      "extension": "mme",
      "filename": "string",
      "gallery": "rough",
      "gallery_priority": 0,
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "is_hero": false,
      "label": "string",
      "plan_software_manufacturer": "string",
      "plan_software_name": "string",
      "plan_software_version": "string",
      "updated_at": "2026-09-03T14:48:35.682Z"
    },
    {
      "asset_type": "plan_report",
      "content_hash": "string",
      "created_at": "2026-09-03T14:48:35.682Z",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_stage": "polished",
      "extension": "string",
      "filename": "string",
      "gallery": "rough",
      "gallery_priority": 0,
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "is_hero": false,
      "label": "string",
      "plan_software_manufacturer": "string",
      "plan_software_name": "string",
      "plan_software_version": "string",
      "scan_device_manufacturer": "string",
      "scan_device_model": "string",
      "updated_at": "2026-09-03T14:48:35.682Z"
    },
    {
      "asset_type": "inscription_number",
      "content_hash": "string",
      "created_at": "2026-09-03T14:48:35.682Z",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_stage": "polished",
      "extension": "json",
      "filename": "string",
      "gallery": "rough",
      "gallery_priority": 0,
      "graded_date": "string",
      "grader_inscription_no": "string",
      "grading_lab": "string",
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "is_hero": false,
      "label": "string",
      "updated_at": "2026-09-03T14:48:35.682Z"
    },
    {
      "asset_type": "three_d_plan",
      "created_at": "2026-09-03T14:48:35.682Z",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_stage": "polished",
      "gallery": "rough",
      "gallery_priority": 0,
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "is_hero": false,
      "label": "string",
      "polished_three_d_plan_content_hash": "string",
      "polished_three_d_plan_extension": "string",
      "polished_three_d_plan_filename": "string",
      "rough_three_d_plan_content_hash": "string",
      "rough_three_d_plan_extension": "string",
      "rough_three_d_plan_filename": "string",
      "updated_at": "2026-09-03T14:48:35.682Z"
    },
    {
      "asset_type": "supplementary",
      "content_hash": "string",
      "created_at": "2026-09-03T14:48:35.682Z",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_stage": "polished",
      "extension": "string",
      "filename": "string",
      "gallery": "rough",
      "gallery_priority": 0,
      "id": "e1mv3nn4n10kd1lw6mde6sums",
      "is_hero": false,
      "label": "string",
      "updated_at": "2026-09-03T14:48:35.682Z"
    }
  ],
  "total": 0
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### HTTP response status codes

| Code | Description                                                                                                               |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| 401  | Unauthorized: The request has not been applied because it lacks valid authentication credentials for the target resource. |
| 403  | Forbidden: The application does not have sufficient permissions for this operation.                                       |
| 422  | Unprocessable Entity, request JSON body is not as per specification                                                       |
| 500  | Internal Server Error. If this error persists please contact the Platform Admin team.                                     |

### Get one asset

To retrieve an asset, use the `/v2/diamond-asset/` end point to retrieve the ID of the asset you want to retrieve, and then use that ID to retrieve to the asset.

Call `/v2/diamond_asset/{diamond_asset_id}`

> **Required Fields**
>
> * diamond\_asset\_id

{% tabs %}
{% tab title="Request" %}
`/v2/diamond-asset/<DIAMOND_ASSET_ID>`
{% endtab %}

{% tab title="Response" %}
{% code title="Response (200)" %}

```json
{
  "asset_type": "image",
  "content_hash": "string",
  "created_at": "2026-09-03T15:35:19.813Z",
  "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
  "diamond_stage": "polished",
  "extension": "avif",
  "filename": "string",
  "gallery": "rough",
  "gallery_priority": 0,
  "id": "e1mv3nn4n10kd1lw6mde6sums",
  "image_type": "default",
  "is_hero": false,
  "label": "string",
  "updated_at": "2026-09-03T15:35:19.813Z"
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### HTTP Response Status Codes

| Code | Description                                                                                                               |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| 401  | Unauthorized: The request has not been applied because it lacks valid authentication credentials for the target resource. |
| 403  | Forbidden: The application does not have sufficient permissions for this operation.                                       |
| 422  | Unprocessable Entity, request JSON body is not as per specification                                                       |
| 500  | Internal Server Error. If this error persists please contact the Platform Admin team.                                     |

If the asset does not exist or has been deleted, the API returns 404 Not Found.

### Delete an asset

To delete an asset, send its asset ID to the bulk-delete endpoint. Although the endpoint supports multiple assets in one request, this example deletes one asset.

A successful request returns a result for each asset. If the asset has already been deleted, the response still reports success.

Call `/bulk/diamond-asset/delete`

> **Required Fields**
>
> * asset\_id

{% tabs %}
{% tab title="Request" %}

| Key          | Value                     |
| ------------ | ------------------------- |
| asset\_id    | e1mv3nn4n10kd1lw6mde6sums |
| {% endtab %} |                           |

{% tab title="Response" %}
{% code title="Response (200)" %}

```json
{
  "results": [
    {
      "diamond_asset_id": "string",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "errors": [
        {
          "error_code": "diamond_asset_not_found",
          "message": "string"
        }
      ],
      "status": "success"
    }
  ]
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

The API may return a different status when the asset cannot be deleted, for example if it does not exist, belongs to an archived or transferred diamond, is currently in a transfer, is a legacy asset, or has an unsupported asset type.

| Code | Description                                                                                                                                               |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | Unauthorized: The request has not been applied because it lacks valid authentication credentials for the target resource.                                 |
| 403  | Forbidden: The application does not have sufficient permissions for this operation.                                                                       |
| 409  | The request was unable to be processed due to one of the diamond assets in the request (or the asset's related diamond) being updated by another process. |
| 422  | Unprocessable Entity, request JSON body is not as per specification                                                                                       |
| 500  | Internal Server Error. If this error persists please contact the Platform Admin team.                                                                     |


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tracr.com/tracr-user-guide/12.-editing-assets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.