GemID API

Quick Start

Three measurements are enough to identify most gems. All 19 session fields are optional — supply only what you have.

curl -X POST https://gemid-labs.com/v1/identify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "riReading": 1.765,
    "sgReading": 4.00,
    "colorCategory": "red_pink"
  }'

// JavaScript (fetch)
const res = await fetch('https://gemid-labs.com/v1/identify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    riReading: 1.765,
    sgReading: 4.00,
    colorCategory: 'red_pink',
  }),
});
const { candidates, nextTest, conclusion } = await res.json();
console.log(candidates[0].name);   // "Ruby"
console.log(nextTest?.testName);  // "UV Fluorescence"

# Python (requests)
import requests

resp = requests.post(
    'https://gemid-labs.com/v1/identify',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'riReading': 1.765,
        'sgReading': 4.00,
        'colorCategory': 'red_pink',
    },
)
data = resp.json()
print(data['candidates'])  # ranked list of matching gems
print(data['nextTest'])    # recommended next measurement
print(data['conclusion'])  # set when a single candidate remains

The response always includes candidates (ranked matches), eliminatedCount, and nextTest. When observations narrow the field to one gem, conclusion and conclusionNote are also set.

How Identification Works

The /v1/identify endpoint runs the same decision engine as the GemID app. Add more fields in subsequent calls to progressively narrow the candidate list.

RI and SG use range overlap — a gem is kept if its documented property range overlaps your reading. Call GET /v1/reference (no key required) for all valid enum values for colorCategory, fluorescenceLw, opticCharacter, and other enumerated fields.

Authentication

All /v1/identify and /v1/gems requests require a Bearer token:

Authorization: Bearer YOUR_API_KEY

Keys are issued in the GemID app under Settings → Developer. Open GemID →

GET /v1/reference is public — no key required.

When rate limited you receive HTTP 429 with a Retry-After header containing the number of seconds to wait before retrying.

Full API Reference

All endpoints, request and response schemas, enumerated values, and error codes are in the interactive OpenAPI spec below.