> 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/inventory.md).

# Inventory

## Individual diamond

To return data about a specific diamond, pass the Tracr Diamond ID to the `/diamonds` endpoint:

Call `GET /diamonds/a2uj544df5t5awu5v792wyj6`

```json
{
    "assurance_level": "assured",
    "box_id": "demo_box",
    "current_stage": "polished",
    "diamond_id": "a2uj544df5t5awu5v792wyj6",
    "diamond_parent_id": "wemz3zvg7cvr5uugivhib1z0",
    "entity_specific_tags": {},
    "id": "14fe49ae-df4b-49f6-93c3-9a712016977e",
    "is_current": true,
    "lifecycle_state": "polished",
    "parent_id": "b0733d6f-a3b1-4532-be2b-d352bad46fd6",
    "participant_id": "demo_1_polished_1",
    "participant_parent_id": "demo_1",
    "participant_timestamp": "2024-05-31T11:59:52.456810+00:00",
    "polished": {
        "carats": 1.01,
        "cut_grade": "EX",
        "shape": "Round",
        "colour": "F",
        "clarity": "SI1",
        "scan_reports": [
            {
                "filename": "demo_polished_scan.xml",
                "description": "Polished diamond scan report",
                "hash": "c47c21bf48f7fe301de1efdce43a153ddd873d599195f7103bbf5053341b6c69",
                "scan_device_manufacturer": "Sarine",
                "scan_device_model": "DiaMension"
            }
        ],
        "videos": [
            {
                "filename": "polished_video.mp4",
                "description": "Polished 360 video",
                "hash": "dc897a179788e760b29497dd8ebfeb25051dd961f949e210203a5ae4e15b3dab"
            }
        ],
        "grading_certificates": [
            {
                "filename": "gia_sample_report.pdf",
                "hash": "84de6762dcebfc18dd385389fa5831ec25286fc4fee2e2c0279474d57ceb4a50",
                "grading_lab": "GIA",
                "graded_date": "2024-05-31",
                "grader_certificate_no": "2141438167",
                "grader_inscription_no": "GIA 2141438167"
            }
        ]
    },
    "possession_state": "held",
    "producer_uuid": "952e8987-9e49-437b-824c-5c9a77ce7eee",
    "provenance": {
        "provenance_name": "DTC",
        "provenance_type": "Entity",
        "is_locked": false,
        "is_country_code_available": false
    },
    "rough": {
        "carats": 1.52,
        "images": [
            {
                "filename": "demo_1_split_1.jpeg",
                "description": "Split Image",
                "hash": "219fe6f8cdc6f32091b310f6c6f5864f4fef97443cb8954a1d64bc9f26731986",
                "image_type": "default"
            }
        ]
    },
    "schema_version": "1.1.0",
    "sight_no": 2,
    "sight_year": 2024,
    "system_timestamp": "2024-05-31T13:35:31.094000+00:00",
    "verification_description": "verified record",
    "verification_status": "Verified",
    "version_id": "e11im52r7v8nmalm2btmjues",
    "verification_status_modified_at": "2024-05-31T12:22:44.693059+00:00",
    "grading": [
        {
            "id": "hpuxljkbhjil53unwyyc11vh",
            "graded_date": "2024-05-31T00:00:00+00:00",
            "grader_certificate_number": "2141438167",
            "grader_inscription_numbers": [
                "GIA 2141438167"
            ],
            "grading_certificate_filename": "gia_sample_report.pdf",
            "grading_certificate_hash": "84de6762dcebfc18dd385389fa5831ec25286fc4fee2e2c0279474d57ceb4a50",
            "grading_lab": "GIA"
        }
    ],
    "unlock_status": "locked",
    "rough_check": false
}
```

Here the API returns an object called a **diamond record**. A diamond record represents the latest version of the digital asset in Tracr.

**Participant ID** – The participant ID is the unique ID of the diamond in the factory's ERP. This used to keep the relationship between a diamond in the ERP and the same diamond in Tracr.

**Participant Timestamp** – The timestamp of the enrolment of the rough diamond in the manufacturing process.

**Diamond ID** – Each diamond on the platform has a unique `diamond_id` (or tracr id) assigned by the API. You need to capture and keep this `diamond_id` since this identifier is used by other endpoints of the API.

**Version** – Each diamond on the platform is versioned after any data modification (metadata, files, and so on) or change of state (Verification Status, LifecycleState, Possession State, and so on). The field `version_id` contains the current version.

**Lifecycle State** - Current state of a diamond. Tracr has 4 lifecycle states

* `rough`
* `split`
* `polished`
* `destroyed`

**Possession State** - Tracr diamonds have 3 possession states

* `held` : Diamond is live and owned by the current instance of Tracr
* `known` : Diamond was previously owned by the instance of Tracr but has been transferred to another peer
* `destroyed` : Diamond has been destroyed and is no longer live in the inventory

**Verification status** – The field `verification_status` provides the current verification status from Tracr based on the traceability data provided during the registration.

## Paginating inventory

The Tracr API offers a paginated endpoint to query your entire inventory. Pagination is controlled by two query parameters:

**size** - The number of diamonds (between 1 and 1,000) to return per request. Defaults to 100 if not provided.

**page** - The page number to return. Defaults to 1 if not provided.

Results are ordered by the time when diamond was first added to the Tracr instance (either by rough registration or polished transfer). For example, `GET /diamonds/?size=1&page=2` returns the second diamond added to the inventory:

Call `/diamonds/?size=1&page=2`

```json
{
    "next": "https://api.manufacturer.uat.tracr.com/diamonds/?size=1&page=3",
    "page": 2,
    "pages": 3,
    "previous": "https://api.manufacturer.uat.tracr.com/diamonds/?size=1&page=1",
    "results": [
        {
            "assurance_level": "assured",
            "box_id": "demo_box",
            "current_stage": "rough",
            "diamond_id": "jo55p0yxbk7slopptdwv0zol",
            "diamond_parent_id": "wemz3zvg7cvr5uugivhib1z0",
            "entity_specific_tags": {},
            "id": "7de1eea0-5247-45ad-a372-3bca147d6647",
            "is_current": true,
            "lifecycle_state": "rough",
            "parent_id": "b0733d6f-a3b1-4532-be2b-d352bad46fd6",
            "participant_id": "demo_1_split_2",
            "participant_parent_id": "demo_1",
            "participant_timestamp": "2024-05-31T12:09:31.688604+00:00",
            "polished": {},
            "possession_state": "held",
            "producer_uuid": "952e8987-9e49-437b-824c-5c9a77ce7eee",
            "provenance": {
                "provenance_name": "DTC",
                "provenance_type": "Entity",
                "is_locked": false,
                "is_country_code_available": false
            },
            "rough": {
                "carats": 0.64,
                "images": [
                    {
                        "filename": "demo_1_split_2.jpeg",
                        "description": "Split Image",
                        "hash": "5746c01245be9d70becb6d5737e0d9e4caf5f8923d4d9da69586874f53d0de52",
                        "image_type": "default"
                    }
                ]
            },
            "schema_version": "1.1.0",
            "sight_no": 2,
            "sight_year": 2024,
            "system_timestamp": "2024-05-31T12:10:07.966000+00:00",
            "verification_description": "verified record",
            "verification_status": "Verified",
            "version_id": "a4kaxhi4rns75dgi52msrege",
            "verification_status_modified_at": "2024-05-31T12:09:46.830574+00:00",
            "unlock_status": "not_eligible_for_unlock",
            "rough_check": false
        }
    ],
    "total": 3
}
```

**next** - The url of the next page to query. This field will not appear in the response if there is no such page.

**page** - The current page number.

**pages** - The total number of pages available.

**previous** - The url of the previous page to query. This field will not appear in the response if there is no such page.

**results** - The paginated result set.

**total** - The total number of diamonds matching the query.

## Query filters

Extra query parameters can be applied to the URL to filter the inventory. Some examples are shown below.

### Querying by lifecycle state

Call to retrieve all live `rough` diamonds.

Call `GET /diamonds/?lifecycle_state=rough`

```json
{
    "page": 1,
    "pages": 1,
    "results": [
        {
            "assurance_level": "assured",
            "box_id": "demo_box",
            "current_stage": "rough",
            "diamond_id": "jo55p0yxbk7slopptdwv0zol",
            "diamond_parent_id": "wemz3zvg7cvr5uugivhib1z0",
            "entity_specific_tags": {},
            "id": "7de1eea0-5247-45ad-a372-3bca147d6647",
            "is_current": true,
            "lifecycle_state": "rough",
            "parent_id": "b0733d6f-a3b1-4532-be2b-d352bad46fd6",
            "participant_id": "demo_1_split_2",
            "participant_parent_id": "demo_1",
            "participant_timestamp": "2024-05-31T12:09:31.688604+00:00",
            "polished": {},
            "possession_state": "held",
            "producer_uuid": "952e8987-9e49-437b-824c-5c9a77ce7eee",
            "provenance": {
                "provenance_name": "DTC",
                "provenance_type": "Entity"
            },
            "rough": {
                "carats": 0.64,
                "images": [
                    {
                        "filename": "demo_1_split_2.jpeg",
                        "description": "Split Image",
                        "hash": "5746c01245be9d70becb6d5737e0d9e4caf5f8923d4d9da69586874f53d0de52",
                        "image_type": "default"
                    }
                ]
            },
            "schema_version": "1.1.0",
            "sight_no": 2,
            "sight_year": 2024,
            "system_timestamp": "2024-05-31T12:10:07.966000+00:00",
            "verification_description": "verified record",
            "verification_status": "Verified",
            "version_id": "a4kaxhi4rns75dgi52msrege",
            "verification_status_modified_at": "2024-05-31T12:09:46.830574+00:00",
            "unlock_status": "not_eligible_for_unlock",
            "rough_check": false
        },
        {
            "assurance_level": "assured",
            "box_id": "demo_box",
            "current_stage": "rough",
            "diamond_id": "og2jywh0nh5zle5ethsutjp9",
            "entity_specific_tags": {},
            "id": "5fef0ef9-c550-4ce0-812e-b7812845200b",
            "is_current": true,
            "lifecycle_state": "rough",
            "participant_id": "demo_2",
            "participant_timestamp": "2024-05-31T13:06:37.505656+00:00",
            "polished": {},
            "possession_state": "held",
            "producer_uuid": "952e8987-9e49-437b-824c-5c9a77ce7eee",
            "provenance": {
                "provenance_name": "DTC",
                "provenance_type": "Entity"
            },
            "rough": {
                "carats": 1.24
            },
            "schema_version": "1.1.0",
            "sight_no": 3,
            "sight_year": 2024,
            "system_timestamp": "2024-05-31T13:16:07.527000+00:00",
            "verification_description": "verified record",
            "verification_status": "Verified",
            "version_id": "cchn4g4s7vi0z2vis7t2e8wk",
            "verification_status_modified_at": "2024-05-31T13:16:07.545936+00:00",
            "unlock_status": "not_eligible_for_unlock",
            "rough_check": false
        }
    ],
    "total": 2
}
```

### Querying by Participant ID (ERP ID)

Call `GET /diamonds/?participant_id=demo_1_split_2`

```json
{
    "page": 1,
    "pages": 1,
    "results": [
        {
            "assurance_level": "assured",
            "box_id": "demo_box",
            "current_stage": "rough",
            "diamond_id": "jo55p0yxbk7slopptdwv0zol",
            "diamond_parent_id": "wemz3zvg7cvr5uugivhib1z0",
            "entity_specific_tags": {},
            "id": "7de1eea0-5247-45ad-a372-3bca147d6647",
            "is_current": true,
            "lifecycle_state": "rough",
            "parent_id": "b0733d6f-a3b1-4532-be2b-d352bad46fd6",
            "participant_id": "demo_1_split_2",
            "participant_parent_id": "demo_1",
            "participant_timestamp": "2024-05-31T12:09:31.688604+00:00",
            "polished": {},
            "possession_state": "held",
            "producer_uuid": "952e8987-9e49-437b-824c-5c9a77ce7eee",
            "provenance": {
                "provenance_name": "DTC",
                "provenance_type": "Entity"
            },
            "rough": {
                "carats": 0.64,
                "images": [
                    {
                        "filename": "demo_1_split_2.jpeg",
                        "description": "Split Image",
                        "hash": "5746c01245be9d70becb6d5737e0d9e4caf5f8923d4d9da69586874f53d0de52",
                        "image_type": "default"
                    }
                ]
            },
            "schema_version": "1.1.0",
            "sight_no": 2,
            "sight_year": 2024,
            "system_timestamp": "2024-05-31T12:10:07.966000+00:00",
            "verification_description": "verified record",
            "verification_status": "Verified",
            "version_id": "a4kaxhi4rns75dgi52msrege",
            "verification_status_modified_at": "2024-05-31T12:09:46.830574+00:00",
            "unlock_status": "not_eligible_for_unlock",
            "rough_check": false
        }
    ],
    "total": 1
}
```


---

# 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/inventory.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.