Attributes

This page explains how to find out which attributes to send for each category when calling Valuations or Enrich.

Get the schema from the API

Use the API to fetch the validation schema for a category. That schema defines every attribute name, type, and allowed values.

List categories:

GET /v1/categories
X-API-Key: <your-api-key>

{
  "categories": ["car", "wristwatch", "ring", "necklace"]
}

Get schema for a category:

curl https://api.gemmai.io/v1/categories/wristwatch/schema \
  -H "X-API-Key: <your-api-key>"

{
  "category": "wristwatch",
  "schema": {
    "type": "object",
    "properties": {
      "brand": { "type": "string", "description": "the brand of the wristwatch" },
      "model": { "type": "string", "description": "the model of the wristwatch" },
      "referenceNumber": { "type": "string" },
      "strap": { "type": "string", "enum": ["steel", "leather", "fabric", "..."] },
      "movement": { "type": "string", "enum": ["automatic", "manual", "quartz", "smart", "solar"] }
    },
    "required": ["brand"],
    "additionalProperties": false
  }
}

• properties — every attribute you can send; keys are the attribute names.
• required — attributes you must include for that category.
• enum — for string fields, the only allowed values.

Look up values (reference data)

Only attributes with an enumRef in the schema support lookup via the reference endpoint. Currently brand and model (for wristwatch and car) have enumRef. Other fields (e.g. strap, condition) use fixed enums in the schema.

curl "https://api.gemmai.io/v1/reference/brand?q=rol&category=wristwatch" \
  -H "X-API-Key: <your-api-key>"

Response is a list of { value, probability } items. Use the exact value strings when sending attributes to Valuations or Enrich.

Using Enrich to fill in attributes

If you have a photo but don't know all the attributes, use Enrich to get a full set from the image.

1. POST /v1/vision with imageUrl → get fileId
2. POST /v1/enrich with category and fileId → get normalizedAttributes
3. Pass normalizedAttributes directly to POST /v1/valuations, or show them to the user for editing first

{
  "category": "wristwatch",
  "fileId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

→ Response normalizedAttributes includes brand, model, strap, dialColor, movement, condition — all in the correct format for the schema. See the Enrich guide for the full flow.

Quick reference by category

For exact enum values, use the schema endpoint above. The tables below are a human-readable summary.

Wristwatch

Only brand is required. More attributes give a tighter price range and higher confidence.

{
  "category": "wristwatch",
  "attributes": { "brand": "Rolex" }
}

Car

All listed attributes are required for a full car valuation.

{
  "category": "car",
  "attributes": {
    "licensePlate": "ABC123",
    "brand": "Volvo",
    "model": "XC60",
    "yearOfManufacture": 2020,
    "odometerReading": 45000,
    "fuelType": "Plug-in Hybrid (PHEV)",
    "drive": "AWD",
    "gearbox": "Automatic",
    "enginePower": 340,
    "color": "black",
    "additionalWheelset": false
  }
}

Ring

{
  "category": "ring",
  "attributes": {
    "style": "solitairering",
    "engraving": false,
    "material": "white gold",
    "materialPurity": "18k",
    "weight": 4.2,
    "condition": "excellent",
    "diamondCarat": 0.5
  }
}

Necklace

If your deployment supports the necklace category, call GET /v1/categories/necklace/schema for the exact schema.