For Dealers

Dealer Write API

Programmatically create, update, and remove stone listings on Chaos without using the dashboard. Ideal for syncing from your existing inventory management system.

Generate your API key

This API is for dealer accounts only. If you are a jeweller looking to embed stone feeds into your website, see the Jeweller API docs.

Connecting your existing inventory system

Many dealers already have their inventory in another platform (Kodllin, RapNet exports, custom in-house tools). You can connect that inventory to Chaos in two ways:

Paste a feed URL into the Sync URL field on your Developer API dashboard. Chaos will fetch your feed (GET or POST), parse it, and upsert stones automatically — optionally every 24 hours. Most JSON shapes work: a plain array, or an object with a stones, data, or result array property.
Use the Chaos write API directly from your own system — the endpoints documented below. Use this when you want to push changes the moment they happen in your source of truth, rather than waiting for the next poll.

Chaos auto-detects common dealer formats — for example, feeds that include stockNo and growthType fields are mapped to the Kodllin / Nancy Diamond format preset automatically (no manual column mapping required). If we don't recognise the shape, we fall through to using the field names as-is, so a feed that already uses Chaos field names works without configuration.

Authentication

Generate a write API key from your Developer API dashboard. Pass it as a Bearer token in the Authorization header on every request.

Authorization: Bearer chaos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Treat the key like a password. Rotate it from the dashboard if it leaks.

Rate limits

120 requests per minute per API key. Exceeded requests receive HTTP 429 with a Retry-After header and body {"error":"Rate limit exceeded","retry_after":60}.

Endpoints

POST/api/dealer/v1/stones

Create a new stone. Required: stone_type, shape, carat_weight, wholesale_price_usd.

Request body

{
  "stone_type": "diamond",
  "shape": "round",
  "carat_weight": 1.05,
  "wholesale_price_usd": 4200,
  "colour_grade": "F",
  "clarity_grade": "VS1",
  "cert_lab": "GIA",
  "cert_number": "2191234567"
}

Response

201 Created
{ "id": "uuid", "stone_type": "diamond", ... }

422 Unprocessable Entity
{ "error": "Validation failed", "errors": [{ "field": "carat_weight", "message": "Must be between 0.01 and 100" }] }

curl

curl -X POST https://chaosgemstones.com/api/dealer/v1/stones \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stone_type":"diamond","shape":"round","carat_weight":1.05,"wholesale_price_usd":4200}'

JavaScript (fetch)

await fetch("https://chaosgemstones.com/api/dealer/v1/stones", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stone_type: "diamond", shape: "round", carat_weight: 1.05, wholesale_price_usd: 4200 }),
});

GET/api/dealer/v1/stones

List your stones. Query params: status (available|reserved|sold|all, default all), limit (max 200, default 50), offset.

Response

{ "total_count": 124, "limit": 50, "offset": 0, "stones": [ { ... } ] }

curl

curl "https://chaosgemstones.com/api/dealer/v1/stones?status=available&limit=50" -H "Authorization: Bearer YOUR_KEY"

JavaScript (fetch)

const res = await fetch("https://chaosgemstones.com/api/dealer/v1/stones?limit=100", { headers: { Authorization: "Bearer YOUR_KEY" } });
const { stones } = await res.json();

GET/api/dealer/v1/stones/:id

Get a single stone by ID. Must belong to your account.

Response

200 OK — full stone object
404 Not Found — { "error": "Stone not found" }

curl

curl https://chaosgemstones.com/api/dealer/v1/stones/STONE_ID -H "Authorization: Bearer YOUR_KEY"

JavaScript (fetch)

const res = await fetch("https://chaosgemstones.com/api/dealer/v1/stones/STONE_ID", { headers: { Authorization: "Bearer YOUR_KEY" } });

PUT/api/dealer/v1/stones/:id

Partial update — only fields you include are changed. Returns the updated stone.

Request body

{ "wholesale_price_usd": 4500, "status": "reserved" }

Response

200 OK — updated stone object

curl

curl -X PUT https://chaosgemstones.com/api/dealer/v1/stones/STONE_ID \
  -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"wholesale_price_usd": 4500}'

JavaScript (fetch)

await fetch("https://chaosgemstones.com/api/dealer/v1/stones/STONE_ID", {
  method: "PUT",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ wholesale_price_usd: 4500 }),
});

DELETE/api/dealer/v1/stones/:id

Delete a stone permanently. Must belong to your account.

Response

{ "deleted": true }

curl

curl -X DELETE https://chaosgemstones.com/api/dealer/v1/stones/STONE_ID -H "Authorization: Bearer YOUR_KEY"

JavaScript (fetch)

await fetch("https://chaosgemstones.com/api/dealer/v1/stones/STONE_ID", { method: "DELETE", headers: { Authorization: "Bearer YOUR_KEY" } });

POST/api/dealer/v1/stones/:id/mark-sold

Mark a stone as sold. Optionally records an order row. Removes the stone from all jeweller feeds.

Request body

{ "sale_price_usd": 1200, "notes": "sold to UK buyer", "jeweller_id": "optional-uuid" }

Response

200 OK — updated stone with status: "sold"

curl

curl -X POST https://chaosgemstones.com/api/dealer/v1/stones/STONE_ID/mark-sold \
  -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"sale_price_usd": 1200}'

JavaScript (fetch)

await fetch("https://chaosgemstones.com/api/dealer/v1/stones/STONE_ID/mark-sold", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ sale_price_usd: 1200 }),
});

POST/api/dealer/v1/stones/bulk

Bulk create or update — up to 200 stones per request. Existing stones are matched by cert_number and updated; new ones are created.

Request body

[
  { "stone_type": "diamond", "shape": "round", "carat_weight": 1.05, "wholesale_price_usd": 4200, "cert_number": "2191234567", "cert_lab": "GIA" },
  { "stone_type": "sapphire", "shape": "oval", "carat_weight": 2.10, "wholesale_price_usd": 3800 }
]

Response

{ "created": 45, "updated": 12, "errors": [ { "row": 3, "field": "carat_weight", "message": "Must be between 0.01 and 100" } ] }

curl

curl -X POST https://chaosgemstones.com/api/dealer/v1/stones/bulk \
  -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" \
  --data @stones.json

JavaScript (fetch)

// Sync your external inventory once a day:
const stones = await loadFromYourSystem(); // [{stone_type, shape, carat_weight, wholesale_price_usd, cert_number, ...}]
const res = await fetch("https://chaosgemstones.com/api/dealer/v1/stones/bulk", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify(stones),
});
const { created, updated, errors } = await res.json();

Field reference

All fields accepted by the create / update / bulk endpoints. Required fields are marked.

Field	Type	Required	Notes
stone_type	string	yes	Stone type
shape	string	yes	Shape
carat_weight	number	yes	Carat weight
wholesale_price_usd	number	yes	Wholesale price (USD)
price_currency	enum	—	One of: USD, GBP, EUR, AUD, CAD, INR, THB, LKR, HKD, SGD, JPY, AED, CHF, ZAR
colour_grade	string	—	Colour grade
clarity_grade	enum	—	One of: FL, IF, VVS1, VVS2, VS1, VS2, SI1, SI2, I1, I2, I3, Eye Clean, Lightly Included, Moderately Included, Heavily Included
cut_grade	string	—	Cut grade
polish	string	—	Polish
symmetry	string	—	Symmetry
fluorescence	string	—	Fluorescence
fluorescence_colour	string	—	Fluorescence colour
cert_lab	enum	—	One of: GIA, IGI, HRD, AGS, GCAL, EGL, GRS, SSEF, Gübelin, AGL, Lotus, GIT, GIA-coloured
cert_number	string	—	Cert number
cert_url	string	—	Certificate URL
origin	string	—	Origin (region)
country_of_origin	string	—	Country of origin
treatment	string	—	Treatment
colour_hue	string	—	Colour hue
colour_tone	string	—	Colour tone
colour_saturation	string	—	Colour saturation
phenomenon	string	—	Phenomenon
measurements_length	number	—	Length (mm)
measurements_width	number	—	Width (mm)
measurements_height	number	—	Height (mm)
lw_ratio	number	—	L/W ratio
depth_pct	number	—	Depth %
table_pct	number	—	Table %
girdle	string	—	Girdle
culet_size	string	—	Culet size
culet_condition	string	—	Culet condition
shade	string	—	Shade
milky	string	—	Milky
eye_clean	string	—	Eye clean
black_inclusion	string	—	Black inclusion
enhancement	string	—	Enhancement
listing_type	string	—	Listing type
parcel_quantity	number	—	Parcel quantity
matching_pair	boolean	—	Matching pair
has_video	boolean	—	Has video
has_360	boolean	—	Has 360°
provenance_report	string	—	Provenance report
video_url	string	—	Video URL
image_url	string	—	Image URL
available_qty	number	—	Available qty
minimum_order_qty	number	—	Minimum order qty
lead_time_days	number	—	Lead time (days)
notes_for_buyers	string	—	Notes for buyers
crown_angle	number	—	Crown angle (°)
pavilion_angle	number	—	Pavilion angle (°)

Enum reference — clarity_grade: FL, IF, VVS1, VVS2, VS1, VS2, SI1, SI2, I1, I2, I3, Eye Clean, Lightly Included, Moderately Included, Heavily Included. cert_lab: GIA, IGI, HRD, AGS, GCAL, EGL, GRS, SSEF, Gübelin, AGL, Lotus, GIT, GIA-coloured. listing_type: single | parcel.