Getting Started

This guide gets you from zero to your first price estimate. No prior knowledge of the API is required.

Authentication

All API requests require an X-API-Key header. Add it to every request:

X-API-Key: <your-api-key>

Only GET /v1 (API info) does not require authentication.

Contact your account manager or check your dashboard to get your API key.

Step 1: Check the API is running

GET https://api.gemmai.io/v1

If it works, you get:

{
  "name": "Gemmai Valuation API",
  "version": "1.0.0",
  "description": "API for valuing cars, watches, and rings"
}

Step 2: Get your first price (no image)

Send only the type of item (category) and a few details (attributes). No photo needed.

POST

/v1/valuations

{
  "category": "wristwatch",
  "attributes": {
    "brand": "Rolex",
    "model": "Submariner",
    "referenceNumber": "116610LN"
  }
}

Response:

{
  "success": true,
  "predictionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "valuation": {
    "currency": "SEK",
    "priceEstimate": 125000,
    "confidence": 0.85,
    "range": { "low": 110000, "high": 140000 }
  },
  "category": "wristwatch",
  "attributes": { "..." : "..." },
  "metadata": { "timestamp": "...", "creditUsed": 1 }
}

priceEstimate — the estimated value.
range — low and high bounds.
predictionId — use this to fetch the same result later.

Step 3: Try with an image (optional)

If you have a photo of the item, the API can use it to fill in more details and then value it.

3a. Send the image URL to Vision:

POST

/v1/vision

{
  "imageUrl": "https://example.com/photos/my-watch.jpg"
}

Response:

{
  "fileId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "completed",
  "objects": [{ "type": "wristwatch" }],
  "usage": { "creditUsed": 1 }
}

3b. Valuate using that fileId:

POST

/v1/valuations

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

The API enriches missing attributes from the image, then values the item. The response shape is the same as in Step 2.

Step 4: Get the same result later

Retrieve a previous valuation by its predictionId:

GET https://api.gemmai.io/v1/valuations/a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-API-Key: <your-api-key>

The response is identical to when you created the valuation.

You want to…	Go to
See more valuation examples (cars, rings, options)	Valuations guide
Use Enrich to get suggested attributes from an image	Enrich guide
Discover which attributes to pass	Attributes
Look up every endpoint and parameter	API reference