Gradings

A grading is one card submission run through the CHCK grading pipeline. The Partner API lets you list gradings and fetch detail including subgrades and presigned assets.

List gradings

GET /v1/gradings?limit=25&cursor=2026-05-20T10:00:00.000Z

Query	Default	Description
limit	25	Page size, 1–100
cursor	—	ISO 8601 datetime; returns gradings with created_at before this value

Response

{
  "gradings": [
    {
      "id": "d4882286-cfd3-4bde-9ee3-b1d1de1b9922",
      "user_card_id": 6,
      "unique_identifier": 1000017,
      "created_at": "2026-02-17T06:34:29.825Z",
      "updated_at": "2026-02-17T06:34:29.825Z"
    }
  ],
  "next_cursor": "2026-02-17T06:34:29.825Z"
}

When next_cursor is non-null, pass it as the cursor query parameter on the next request. When null, you have reached the end.

Grading detail

GET /v1/gradings/{uuid}

Returns three top-level objects:

Field	Description
grading	Grading id, timestamps, user_card_id, unique_identifier
card	Catalog metadata (brand, year, player, category, …) or null
user_card_grade	Grades, presigned URLs, model_grade or null

Subgrades

Use these fields on user_card_grade for partner-facing grades:

• centering_overall_grade
• corners_overall_grade
• edges_overall_grade
• surface_overall_grade
• full_overall_grade

The nested model_grade object mirrors internal structure; prefer the *_overall_grade fields for integrations.

Presigned URLs

When a grade exists, the API may include:

• damage_report_front_url / damage_report_back_url
• slab_front_url / slab_back_url

URLs are presigned S3 links (default TTL 300 seconds via PRESIGNED_URL_TTL_SECONDS). Fetch or cache images promptly; request the grading again for fresh URLs.

Two-image vs full capture

If only front/back images were supplied (landscape orientation required), you may receive centering only with other subgrades null. Full damage-based subgrades require the complete multi-view capture from the CHCK app.

Image orientation: landscape with the top of the card toward the left edge of the frame. Rotate portrait sources 90° counter-clockwise before upload.

Webhook field name

Outbound webhooks still send grading_session_id (legacy field name). Use that UUID with GET /v1/gradings/{id}.

OpenAPI

Full schemas and try-it-out examples: API reference.