Loupewise API

Quick Start

Three measurements are enough to identify most gems. All 31 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 Loupewise 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 Loupewise app under Settings → Developer. Open Loupewise →

A key carries a tier, and the tier decides which endpoints it can call. The tier follows your Loupewise subscription: a Pro subscription issues a professional key, and any other subscription state issues a developer key.

A developer key calling either identify endpoint receives HTTP 403 with permission_error. Rate limits are per minute by tier: developer 60, professional 300.

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.

Use of the API is governed by the API Terms of Service — acceptable use, rate limits, API keys and key revocation, and the limits of what a property match can tell you. The underlying property table is also published as a CC BY 4.0 dataset, which is the better route if you want the whole table rather than per-request calls.