> 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/api-reference/tracr-api/delete.md). # Delete Tracr provides an API endpoint to delete diamonds. Upon deletion, a diamond is permanently removed from the inventory and cannot be restored. The intention of this endpoint is to give participants the ability to correct data errors with diamonds they've uploaded to Tracr simply by deleting the diamond and re-uploading it with the corrected information. It is not available to retailers and cannot be used on diamonds that have been unlocked (either manually via the portal or automatically via another action, such as transferring to another participant), or diamonds with descendants (children of that diamond, or children of those children and so on...) that have been unlocked. ## Delete diamond without descendants Call `POST /bulk/diamonds/delete` ```json { "diamonds": [ { "diamond_id": "clmkgill50000ps17ogi4d2yu" } ] } ``` If the diamond was successfully deleted this will be marked in the response: ```json { "results": [ { "diamond_id": "clmkgill50000ps17ogi4d2yu", "participant_id":"cb482ea8-5a95-431b-88df-84fc363ebda9", "status": "success", "descendants": [] } ] } ``` If it could not be deleted, the reason will be given: ```json { "results": [ { "diamond_id": "clmkgill50000ps17ogi4d2yu", "participant_id":"cb482ea8-5a95-431b-88df-84fc363ebda9", "status": "diamond_transferred", "error": "The diamond could not be deleted because it has been transferred.", "descendants": [] } ] } ``` ## Delete diamond with descendants A diamond with descendants cannot be deleted unless those descendants are deleted simultaneously (for example, a rough diamond that was split into two roughs that were subsequently polished cannot be deleted unless those polished diamonds are also deleted). To delete the descendants in addition to the diamond, add a `delete_descendants` flag to the diamond in the request body: call `POST /bulk/diamonds/delete` ```json { "diamonds": [ { "diamond_id": "clmkhpl870002mv17475ur906", "delete_descendants": true } ] } ``` If the delete succeeds then the diamond's descendants are returned: ```json { "results": [ { "diamond_id": "clmkhpl870002mv17475ur906", "participant_id": "71a2e460-902f-4bf2-8fa1-5c226847d050", "status": "success", "descendants": [ { "diamond_id": "clmkh5ln90000mv17o65tslpo", "participant_id": "dc7d63ea-df23-4d21-a04a-c611f5f483cf" }, { "diamond_id": "clmkh74z40001mv17em0uu3tz", "participant_id": "951bf2f2-1c49-43c9-a51e-518c62186b2a" } ] } ] } ``` If one of the descendants cannot be deleted then the diamond and all its descendants remain in the inventory, and the diamonds that could not be deleted are marked in the response: ```json { "results": [ { "diamond_id": "clmkhpl870002mv17475ur906", "participant_id": "71a2e460-902f-4bf2-8fa1-5c226847d050", "status": "descendants_in_active_shipment", "error": "The diamond could not be deleted because one or more of its descendants are in an active shipment.", "descendants": [ { "diamond_id": "clmkh74z40001mv17em0uu3tz", "participant_id": "951bf2f2-1c49-43c9-a51e-518c62186b2a" } ] } ] } ``` Likewise if the request is made with `delete_descendants` set to `false`, or not set at all, deletion fails and the diamonds remain in the inventory: call `POST /bulk/diamonds/delete` {% tabs %} {% tab title="Request" %} ```json { "diamonds": [ { "diamond_id": "clmkhpl870002mv17475ur906", } ] } ``` {% endtab %} {% tab title="Response" %} ```json { "results": [ { "diamond_id": "clmkhpl870002mv17475ur906", "participant_id": "71a2e460-902f-4bf2-8fa1-5c226847d050", "status": "diamond_has_descendants", "error": "The diamond could not be deleted because it has descendants.", "descendants": [ { "diamond_id": "clmkh5ln90000mv17o65tslpo", "participant_id": "dc7d63ea-df23-4d21-a04a-c611f5f483cf" }, { "diamond_id": "clmkh74z40001mv17em0uu3tz", "participant_id": "951bf2f2-1c49-43c9-a51e-518c62186b2a" } ] } ] } ``` {% endtab %} {% endtabs %} ## Delete multiple diamonds The endpoint can handle deletion requests for multiple diamonds (up to 1,000) simultaneously. When sending multiple diamond IDs, each diamond is treated in isolation: call `POST /bulk/diamonds/delete` {% tabs %} {% tab title="Request" %} ```json { "diamonds": [ { "diamond_id": "clmkgill50000ps17ogi4d2yu", }, { "diamond_id": "clmkhpl870002mv17475ur906", "delete_descendants": false }, { "diamond_id": "clmkhq91j0003mv176jo5ir3z", "delete_descendants": true } ] } ``` {% endtab %} {% tab title="Response" %} ```json { "results": [ { "diamond_id": "clmkgill50000ps17ogi4d2yu", "participant_id":"cb482ea8-5a95-431b-88df-84fc363ebda9", "status": "diamond_in_active_shipment", "error": "The diamond could not be deleted because it is in an active shipment.", }, { "diamond_id": "clmkhpl870002mv17475ur906", "participant_id": "71a2e460-902f-4bf2-8fa1-5c226847d050", "status": "diamond_has_descendants", "error": "The diamond could not be deleted because it has descendants.", "descendants": [ { "diamond_id": "clmkh5ln90000mv17o65tslpo", "participant_id": "dc7d63ea-df23-4d21-a04a-c611f5f483cf" }, { "diamond_id": "clmkh74z40001mv17em0uu3tz", "participant_id": "951bf2f2-1c49-43c9-a51e-518c62186b2a" } ] }, { "diamond_id": "clmkhq91j0003mv176jo5ir3z", "participant_id": "f2eccb09-c4a7-405e-8bda-4cd8fbbf9e8e", "status": "success", "descendants": [] } ] } ``` {% endtab %} {% endtabs %} --- # 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/api-reference/tracr-api/delete.md?ask=&goal= ``` `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.