---
title: "Collection By Species"
method: GET
path: "/api/v1/gems/collection/by-species"
tags: ["Gemstones"]
---

# Collection By Species

`GET /api/v1/gems/collection/by-species`

## 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/gems/collection/by-species`
- Auth: none declared

GET /api/v1/gems/collection/by-species
Per-species rollup (count + combined estimated value) of the caller's saved
collection. Powers the mobile "In Your Collection" cross-link on the scan
result page. Scoped to the authenticated user, or the X-Device-Id device for
anonymous callers. Additive + read-only.

Auth is optional-strict (LNK-ZEROLIE): callers with no Authorization header
are anonymous and fall back to X-Device-Id, but a caller who presents a
token that no longer works gets a 401 rather than the anonymous empty list.
Returning [] to an expired session made the app paint an empty collection
over a real one.

The "Unidentified" placeholder a stone-free piece carries is not a species,
so it gets no row: "You own 7 Unidentifieds" read as a failure on a shelf of
gold bands. [LNK-NOSTONEROW]

## Headers

- `X-Device-Id` integer, nullable
- `authorization` string, nullable

## Response `200`

Successful Response

- CollectionSpeciesSummary[]
  - `species` string, required
  - `count` integer, required
  - `total_value` number, required

## 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)