> 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/get-started-with-tracr-search-authenticated_copy.md).

# Get Started with Tracr Search Authenticated\_copy

> **Who is this document for?**
>
> 3rd Party Blockchain Integrations

Tracr Search V1 Authenticated is an API allowing non-Tracr participants to search for a diamond across all of Tracr's instances and return traceability data for both locked and unlocked diamonds.

There is no transferring of a digital asset

{% hint style="warning" %}
**You need to know**

The Tracr Search API V1 Authenticated is only available for authenticated users. For more details please contact <support@tracr.com>.
{% endhint %}

## Before you start

* Contact Tracr Support (<support@tracr.com>) to obtain authentication credentials.
* Obtain the Tracr ID of the diamond that you want to look up.

{% hint style="info" %}

### API security

The API use OAuth 2.0 authentication. Tracr Support will provide a Client ID and Client Secret during the technical onboarding.
{% endhint %}

### Generate a JWT token

Call `POST https://auth.tracr.com/oauth/token`

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

```json
{
  "client_id":"<client_id>",        
  "client_secret":"<client_secret>",
  "audience":"https://search.tracr.network/v1",
  "grant_type":"client_credentials"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "access_token": "<access_token>",
  "token_type": "Bearer"
}
```

{% endtab %}
{% endtabs %}

### Pass the token to the endpoint

To pass the token to the API, provide it in the Authorization header.

```
Authorization: <access_token>
```

## Look up a diamond in Tracr

### [Retrieve single diamond details](broken://pages/220ec9d6f7a84841bd6a72e7f4fde3ca1f29ef16)

Call `GET /v1/diamonds/sm9og0cgxhpqy78vvo51btem1`

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

```json
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "diamond_id": "sm9og0cgxhpqy78vvo51btem1",
  "diamond_parent_id": "snbp04qev51mz7whoz1ttmjhy",
  "lifecycle_state": "polished",
  "current_stage": "polished",
  "assurance_level": "assured",
  "provenance": {
    "provenance_name": "DTC",
    "provenance_type": "Entity",
    "mine_name": null
  },
  "rough": {
    "carats": 23.42,
    "colour": "D",
    "fancy_colour": null,
    "fancy_colour_intensity": null,
    "fancy_colour_overtone": null,
    "fluorescence_colour": null,
    "fluorescence_intensity": "N",
    "images": [
      {
        "filename": "demo-split-206-1F.jpg",
        "description": null,
        "hash": "7c869b7844242c3355c9333d6444ae3883df9cff5e7f9343e4cb68c4ad35ca3e",
        "image_type": "default"
      }
    ],
    "model": null,
    "plan": null,
    "plan_reports": null,
    "quality": null,
    "scan": null,
    "scan_reports": null,
    "silhouettes": null,
    "stress": null,
    "supplementary_files": null,
    "videos": null
  },
  "polished": {
    "carats": 10.1,
    "clarity": "FL",
    "colour": "D",
    "crown_angle": null,
    "crown_height": null,
    "culet_condition": null,
    "culet_size": null,
    "cut_grade": "EX",
    "depth": null,
    "depth_percent": null,
    "diameter_maximum": null,
    "diameter_minimum": null,
    "fancy_colour": null,
    "fancy_colour_intensity": null,
    "fancy_colour_overtone": null,
    "fluorescence_colour": null,
    "fluorescence_intensity": "N",
    "girdle_condition": null,
    "girdle_thickness_from": null,
    "girdle_thickness_to": null,
    "grading_certificates": [
      {
        "filename": "5212039959.pdf",
        "description": null,
        "hash": "476da635d609cd9fd113bb1a916d7e650a5440140f2ec81fa83719386377ccce",
        "grading_lab": "GIA",
        "graded_date": null,
        "grader_certificate_no": null,
        "grader_report_no": "5212039959",
        "grader_inscription_no": null
      }
    ],
    "length": null,
    "model": null,
    "pavillion_angle": null,
    "pavillion_percent": null,
    "polish_quality": "EX",
    "plan": null,
    "plan_reports": null,
    "quality": null,
    "scan": {
      "filename": "demo-polished-206-1F.stl",
      "description": null,
      "hash": "cf32f03ad4230538cdc195a024f3c126133c8228386b89348f0063f0b81f56f6",
      "scan_device_manufacturer": null,
      "scan_device_model": null,
      "scan_software_name": null,
      "scan_software_version": null
    },
    "scan_reports": [
      {
        "filename": "demo-polished-206-1F.html",
        "description": null,
        "hash": "275eab5473a8d5845256f99e375f650e29cb2abe2b55a53a01f9018e9b823495",
        "scan_device_manufacturer": null,
        "scan_device_model": null,
        "scan_software_name": null,
        "scan_software_version": null
      }
    ],
    "shape": "Emerald",
    "silhouettes": null,
    "symmetry": "EX",
    "table_percent": null,
    "supplementary_files": null,
    "unlocked_status": "unlocked",
    "width": null,
    "images": [
      {
        "filename": "demo-polished-206-1F_P.jpg",
        "description": null,
        "hash": "d3d3db369db95f944bf7f153622d933971eb3622ce435ab9cfd95149a8ea0db5",
        "image_type": "default"
      }
    ],
    "videos": null
  }
}
```

{% endtab %}
{% endtabs %}

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

**Diamond ID** – Each diamond on the platform has a unique `diamond_id` (or tracr id).

**Diamond Parent ID** – The identifier of the parent diamond.

**Lifecycle State** – The current state of a diamond. Tracr has four lifecycle states:

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

**Rough** – The object related to the rough state of the diamond before being polished. For a rough diamond having multiple cuts, the rough section represents one of the cuts. The parent diamond will represent the original rough diamond.

**Polished** – The object related to the polished state of the diamond.

### [Retrieve diamond ancestors](broken://pages/14f94d3c706966a518d6b202d4adc4a10f746d7d)

Call `GET /v1/diamonds/sm9og0cgxhpqy78vvo51btem1/history`

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

```json
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "content": {
    "current": {
      "diamond_id": "sm9og0cgxhpqy78vvo51btem1",
      "diamond_parent_id": "snbp04qev51mz7whoz1ttmjhy",
      "lifecycle_state": "polished",
      "current_stage": "polished",
      "assurance_level": "assured",
      "provenance": {
        "provenance_name": "DTC",
        "provenance_type": "Entity",
        "mine_name": null
      },
      "rough": {
        "carats": 23.42,
        "colour": "D",
        "fancy_colour": null,
        "fancy_colour_intensity": null,
        "fancy_colour_overtone": null,
        "fluorescence_colour": null,
        "fluorescence_intensity": "N",
        "images": [
          {
            "filename": "demo-split-206-1F.jpg",
            "description": null,
            "hash": "7c869b7844242c3355c9333d6444ae3883df9cff5e7f9343e4cb68c4ad35ca3e",
            "image_type": "default"
          }
        ],
        "model": null,
        "plan": null,
        "plan_reports": null,
        "quality": null,
        "scan": null,
        "scan_reports": null,
        "silhouettes": null,
        "stress": null,
        "supplementary_files": null,
        "videos": null
      },
      "polished": {
        "carats": 10.1,
        "clarity": "FL",
        "colour": "D",
        "crown_angle": null,
        "crown_height": null,
        "culet_condition": null,
        "culet_size": null,
        "cut_grade": "EX",
        "depth": null,
        "depth_percent": null,
        "diameter_maximum": null,
        "diameter_minimum": null,
        "fancy_colour": null,
        "fancy_colour_intensity": null,
        "fancy_colour_overtone": null,
        "fluorescence_colour": null,
        "fluorescence_intensity": "N",
        "girdle_condition": null,
        "girdle_thickness_from": null,
        "girdle_thickness_to": null,
        "grading_certificates": [
          {
            "filename": "5212039959.pdf",
            "description": null,
            "hash": "476da635d609cd9fd113bb1a916d7e650a5440140f2ec81fa83719386377ccce",
            "grading_lab": "GIA",
            "graded_date": null,
            "grader_certificate_no": null,
            "grader_report_no": "5212039959",
            "grader_inscription_no": null
          }
        ],
        "length": null,
        "model": null,
        "pavillion_angle": null,
        "pavillion_percent": null,
        "polish_quality": "EX",
        "plan": null,
        "plan_reports": null,
        "quality": null,
        "scan": {
            "filename": "demo-polished-206-1F.stl",
            "description": null,
            "hash": "cf32f03ad4230538cdc195a024f3c126133c8228386b89348f0063f0b81f56f6",
            "scan_device_manufacturer": null,
            "scan_device_model": null,
            "scan_software_name": null,
            "scan_software_version": null
        },
        "scan_reports": [
          {
            "filename": "demo-polished-206-1F.html",
            "description": null,
            "hash": "275eab5473a8d5845256f99e375f650e29cb2abe2b55a53a01f9018e9b823495",
            "scan_device_manufacturer": null,
            "scan_device_model": null,
            "scan_software_name": null,
            "scan_software_version": null
          }
        ],
        "shape": "Emerald",
        "silhouettes": null,
        "symmetry": "EX",
        "table_percent": null,
        "supplementary_files": null,
        "unlocked_status": "unlocked",
        "width": null,
        "images": [
          {
            "filename": "demo-polished-206-1F_P.jpg",
            "description": null,
            "hash": "d3d3db369db95f944bf7f153622d933971eb3622ce435ab9cfd95149a8ea0db5",
            "image_type": "default"
          }
        ],
        "videos": null
      }
    },
    "snbp04qev51mz7whoz1ttmjhy": {
      "diamond_id": "snbp04qev51mz7whoz1ttmjhy",
      "diamond_parent_id": null,
      "lifecycle_state": "split",
      "current_stage": "rough",
      "assurance_level": "assured",
      "provenance": {
        "provenance_name": "DTC",
        "provenance_type": "Entity",
        "mine_name": null
      },
      "rough": {
        "carats": 129.71,
        "colour": "D",
        "fancy_colour": null,
        "fancy_colour_intensity": null,
        "fancy_colour_overtone": null,
        "fluorescence_colour": null,
        "fluorescence_intensity": "N",
        "images": [
          {
            "filename": "demo-rough-206-1.jpg",
            "description": null,
            "hash": "60505ac214dda6a8b72a6ded5da32dc1a15bc0480f26027909d786ce510511c4",
            "image_type": "default"
          }
        ],
        "model": null,
        "plan": null,
        "plan_reports": null,
        "quality": null,
        "scan": null,
        "scan_reports": null,
        "silhouettes": null,
        "stress": null,
        "supplementary_files": null,
        "videos": [
          {
              "filename": "demo-rough-206-1.mp4",
              "description": null,
              "hash": "5ce066c86dfcdc245f1985199a59fd1fbf62f046303eb06d88ce9fd8f7549691"
          }
        ]
      },
      "polished": {
        "carats": null,
        "clarity": null,
        "colour": null,
        "crown_angle": null,
        "crown_height": null,
        "culet_condition": null,
        "culet_size": null,
        "cut_grade": null,
        "depth": null,
        "depth_percent": null,
        "diameter_maximum": null,
        "diameter_minimum": null,
        "fancy_colour": null,
        "fancy_colour_intensity": null,
        "fancy_colour_overtone": null,
        "fluorescence_colour": null,
        "fluorescence_intensity": null,
        "girdle_condition": null,
        "girdle_thickness_from": null,
        "girdle_thickness_to": null,
        "grading_certificates": null,
        "length": null,
        "model": null,
        "pavillion_angle": null,
        "pavillion_percent": null,
        "polish_quality": null,
        "plan": null,
        "plan_reports": null,
        "quality": null,
        "scan": null,
        "scan_reports": null,
        "shape": null,
        "silhouettes": null,
        "symmetry": null,
        "table_percent": null,
        "supplementary_files": null,
        "width": null,
        "images": null,
        "videos": null
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

### [Retrieve a file](broken://pages/558fac70a5d950cf70b4406f1e9ed3a6c75a0625)

Call `GET /v1/diamonds/sm9og0cgxhpqy78vvo51btem1/files/476da635d609cd9fd113bb1a916d7e650a5440140f2ec81fa83719386377ccce`

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

```json
```

{% endtab %}

{% tab title="Response" %}

```
HTTP Code : 302

Headers:

location: https://5aa4ed9b-c04a-45b0-82fb-b09c771600dd.tracr.com/diamond-assets/87f7a020-09fe-4c59-a5b0-74942ca57fae/476da635d609cd9fd113bb1a916d7e650a5440140f2ec81fa83719386377ccce


```

{% 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/get-started-with-tracr-search-authenticated_copy.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.