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

Key

Value

diamond_id

c5scudab4autgb1dhpagyg5l

file

/diamonds/defaultimage.jpg

diamond_stage

rough

gallery

rough

gallery_priority

image_type

default

is_hero

true

label

Default Image

Response (201)

{
  "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"
}

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/

/v2/diamond-asset/?diamond_id__in=<DIAMOND_ID>&asset_type__in=image,video&gallery__in=rough&is_hero=true

Response (200)

{
  "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
}

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

/v2/diamond-asset/<DIAMOND_ASSET_ID>

Response (200)

{
  "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"
}

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

Key

Value

asset_id

e1mv3nn4n10kd1lw6mde6sums

Response (200)

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

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.

Previous11. Tracr Loader

NextLab Eligibility

Last updated 1 month ago