---
title: "Get Piece State"
method: GET
path: "/api/v1/assistant/gems/{gem_id}"
tags: ["Collection Assistant"]
---

# Get Piece State

`GET /api/v1/assistant/gems/{gem_id}`

## Request

- Base URL: `https://api.gemstoneaiapp.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gemstoneaiapp.com/api/v1/assistant/gems/{gem_id}`
- Auth: HTTP bearer

## Path parameters

- `gem_id` integer, required

## Headers

- `X-App-Version` string, nullable
- `X-Agent-Cards` string, nullable

## Response `200`

Successful Response

- PieceStateOut
  - `gem_id` integer, required
  - `capabilities` CapabilitiesOut, required
    - `reminders` boolean, required
    - `discoveries` boolean, required
    - `cards` string[]
  - `question` QuestionOut
    - `kind` 'confirm_identity', required
    - `title` string, required
    - `body` string, required
    - `species` string, required
    - `alternatives` string[]
  - `market` MarketOut
    - `sold` PriceBandOut
      - `count` integer, required
      - `low` integer, required
      - `high` integer, required
    - `listed` PriceBandOut
      - `count` integer, required
      - `low` integer, required
      - `high` integer, required
    - `estimate` integer, nullable
    - `estimate_position` 'below' | 'within' | 'above', nullable
  - `metal` MetalOut
    - `metal` 'gold' | 'silver' | 'platinum', required
    - `change_pct` number, required
    - `since` string, required
    - `grams` number, nullable
    - `melt_now` integer, nullable
    - `melt_then` integer, nullable
  - `community` CommunityOut
    - `count` integer, required
    - `label` string, required
  - `reminders` ReminderOut[], required
    - `id` integer, required
    - `gem_id` integer, required
    - `kind` 'reminder' | 'attention', required
    - `status` string, required
    - `criteria` object
    - `due_at` string, date-time, nullable
    - `timezone` string, nullable
    - `closed_reason` string, nullable
    - `created_at` string, date-time, required
  - `findings` FindingOut[], required
    - `id` integer, required
    - `gem_id` integer, required
    - `gem_ids` integer[]
    - `kind` string, required
    - `title` string, required
    - `body` string, nullable
    - `created_at` string, date-time, required
    - `seen` boolean, required
    - `feedback` string, nullable
    - `thumbnail_url` string, nullable
    - `price` number, nullable
    - `price_label` string, nullable
    - `source_name` string, nullable
    - `moment` object, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api.md) · [All operations](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/revisions/fcb441f55161?raw)