Tracr XPS API V2

Get Diamonds V2

get

Multi-value search returning a discriminated union of diamond results.

Mirrors v1's pagination and peer-fan-out, but instead of dropping locked diamonds (v1's behaviour), it surfaces them as RestrictedDiamondSearchResult entries (kind: locked) built from the locked_diamond payload PCS attaches to each locked search row. Ineligible uninscribed diamonds use the same wrapper with kind: uninscribed (which takes precedence over locked). data_access_event rows are recorded only for UnlockedDiamondSearchResult entries.

Authorizations

OptionalAuth0JWTAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

pageinteger · min: 1Optional

Page number

Default: 1

sizeinteger · min: 1 · max: 1000OptionalDefault: 100

searchstringRequired

Responses

200

Successful Response

application/json

nextstring · nullableOptional

The URL for the next page.

pageinteger · min: 1 · nullableRequired

The number of the current page.

pagesinteger · nullableOptional

The total number of pages.

previousstring · nullableOptional

The URL of the previous page.

totalintegerRequired

The total number of results across all pages.

401

Unauthorized: The request has not been applied because it lacks valid authentication credentials for the target resource.

application/json

403

Forbidden: The application does not have sufficient permissions for this operation.

application/json

422

Validation Error

application/json

get/v2/diamonds/

HTTPcURLJavaScriptPython

GET /v2/diamonds/?search=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "next": "text",
  "page": 1,
  "pages": 1,
  "previous": "text",
  "results": [
    {
      "diamond": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "identity_type": "diamond_id",
      "kind": "unlocked"
    }
  ],
  "total": 1
}

Get Diamond History V2

get

Look up a diamond's history in Tracr.

Returns the full TraceabilityHistoryReadView for a diamond with full access, or a reduced RestrictedDiamondView (HTTP 200) when the diamond exists but full data is restricted for the caller. Returns HTTP 404 if the diamond cannot be found on any peer.

Data-access events are recorded only when the response is the full history view; reduced responses do not record an event.

Authorizations

OptionalAuth0JWTAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

diamond_idstringRequiredExample: e1mv3nn4n10kd1lw6mde6sumsPattern: ^[a-z\d]{20,98}$

Responses

200

Full history for a diamond with full access, or a reduced RestrictedDiamondView when the diamond exists but full data is restricted for the caller.

application/json

or

401

Unauthorized: The request has not been applied because it lacks valid authentication credentials for the target resource.

application/json

403

Forbidden: The application does not have sufficient permissions for this operation.

application/json

404

Diamond not found.

application/json

409

It was not possible to determine which Tracr instance holds this diamond.

application/json

422

Validation Error

application/json

get/v2/diamonds/{diamond_id}/history

HTTPcURLJavaScriptPython

GET /v2/diamonds/{diamond_id}/history HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "content": {
    "ANY_ADDITIONAL_PROPERTY": {
      "assets": [
        {
          "asset_type": null,
          "content_hash": null,
          "created_at": null,
          "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
          "diamond_stage": null,
          "extension": null,
          "filename": null,
          "gallery": null,
          "gallery_priority": null,
          "id": "e1mv3nn4n10kd1lw6mde6sums",
          "image_type": null,
          "is_hero": null,
          "label": null,
          "updated_at": null
        }
      ],
      "assurance_level": "assured",
      "current_stage": "bruting",
      "diamond_id": "e1mv3nn4n10kd1lw6mde6sums",
      "diamond_parent_id": "e1mv3nn4n10kd1lw6mde6sums",
      "grading": [
        {
          "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,
          "display_colour": 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,
          "graded_date": null,
          "grader_certificate_number": null,
          "grader_clarity_characteristics": null,
          "grader_colour": null,
          "grader_inscription_numbers": null,
          "grader_report_comments": null,
          "grader_report_number": null,
          "grader_report_type": null,
          "grader_shape": null,
          "grading_certificate_description": null,
          "grading_certificate_filename": null,
          "grading_certificate_hash": null,
          "grading_lab": null,
          "id": null,
          "is_active": null,
          "is_selectable": null,
          "length": null,
          "measurement_text": null,
          "pavillion_angle": null,
          "pavillion_percent": null,
          "polish_quality": null,
          "shape": null,
          "source": null,
          "supplementary_files": null,
          "symmetry": null,
          "table_percent": null,
          "validation_level": null,
          "width": null
        }
      ],
      "lifecycle_state": "destroyed",
      "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,
        "display_colour": 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,
        "images": null,
        "length": null,
        "model": null,
        "pavillion_angle": null,
        "pavillion_percent": null,
        "plan": null,
        "plan_reports": null,
        "polish_quality": null,
        "quality": null,
        "scan": null,
        "scan_reports": null,
        "shape": null,
        "supplementary_files": null,
        "symmetry": null,
        "table_percent": null,
        "videos": null,
        "width": null
      },
      "polished_objective_verification": false,
      "polished_objective_verification_results": [
        {
          "id": "text",
          "source": "diadna",
          "status": "in_progress"
        }
      ],
      "producer_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "provenance": {
        "country_code": "text",
        "is_locked": false,
        "mine_name": "text",
        "provenance_name": "text",
        "provenance_type": "text"
      },
      "rough": {
        "carats": null,
        "colour": null,
        "display_colour": null,
        "fancy_colour": null,
        "fancy_colour_intensity": null,
        "fancy_colour_overtone": null,
        "fluorescence_colour": null,
        "fluorescence_intensity": null,
        "images": null,
        "model": null,
        "plan": null,
        "plan_reports": null,
        "quality": null,
        "scan": null,
        "scan_reports": null,
        "stress": null,
        "supplementary_files": null,
        "videos": null
      },
      "rough_objective_verification": true,
      "rough_objective_verification_results": [
        {
          "id": "text",
          "source": "diadna",
          "status": "in_progress"
        }
      ],
      "unlock_status": "locked"
    }
  }
}