Developers

GemColony API

A RESTful API to integrate your systems with GemColony — manage inventory, sales, customers, and lab jobs programmatically.

Public API — Coming Soon

Early access is available to Enterprise customers on request. A public release date has not been set.

REST API

JSON over HTTPS. Standard HTTP methods and response codes.

Bearer Auth

API key + short-lived token authentication. TLS enforced.

Versioned

All endpoints are versioned (v1) so your integrations never break.

Base URL

url

https://api.gemcolony.com

Authentication

POST/auth/token

Exchange your API key for a short-lived Bearer token used in all subsequent requests.

Request Body

json

{
  "api_key": "gc_live_sk_••••••••••••••••"
}

Response

json

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Inventory

GET/v1/gemstones

List all gemstones in your inventory. Supports pagination, filtering, and sorting.

Response

json

{
  "data": [
    {
      "id": "gem_01HX2KZ9P4VREQ8T",
      "sku": "SAP-2024-001",
      "type": "Sapphire",
      "variety": "Blue Sapphire",
      "origin": "Sri Lanka",
      "weight_ct": 3.42,
      "color": "Royal Blue",
      "clarity": "Eye Clean",
      "cut": "Oval",
      "status": "in_stock",
      "cost_price": 1200.00,
      "sell_price": 2800.00,
      "currency": "USD",
      "location_id": "loc_01HX2KZ9P4VREQ8U",
      "treatment": "Heated",
      "certificate_no": "GRS2024-001234",
      "created_at": "2026-01-15T08:30:00Z"
    }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20
  }
}

POST/v1/gemstones

Add a new gemstone to your inventory.

Request Body

json

{
  "type": "Ruby",
  "origin": "Myanmar",
  "weight_ct": 1.85,
  "color": "Pigeon Blood",
  "clarity": "Slightly Included",
  "cut": "Cushion",
  "cost_price": 3500.00,
  "sell_price": 8000.00,
  "treatment": "Heated",
  "location_id": "loc_01HX2KZ9P4VREQ8U"
}

Response

json

{
  "id": "gem_01HX9MZ3P7WQAT5R",
  "sku": "RUB-2026-089",
  "status": "in_stock",
  "created_at": "2026-03-21T10:15:00Z"
}

GET/v1/gemstones/:id

Retrieve full details for a single gemstone by ID.

Response

json

{
  "id": "gem_01HX2KZ9P4VREQ8T",
  "type": "Sapphire",
  "weight_ct": 3.42,
  "status": "in_stock",
  ...
}

PATCH/v1/gemstones/:id

Update one or more fields on an existing gemstone record.

Request Body

json

{
  "sell_price": 3200.00,
  "status": "on_hold"
}

Response

json

{
  "id": "gem_01HX2KZ9P4VREQ8T",
  "sell_price": 3200.00,
  "status": "on_hold",
  "updated_at": "2026-03-21T11:00:00Z"
}

Sales

GET/v1/sales

List all sales. Filter by date range, customer, or status.

Response

json

{
  "data": [
    {
      "id": "sale_01HX5NZ8Q3VRBT9K",
      "customer_id": "cust_01HX2KZ9P4VREQ8T",
      "total": 5600.00,
      "currency": "USD",
      "status": "paid",
      "invoice_no": "INV-2026-0042",
      "created_at": "2026-03-10T14:20:00Z"
    }
  ],
  "meta": { "total": 38, "page": 1, "per_page": 20 }
}

POST/v1/sales

Create a new sale record and automatically update inventory statuses.

Request Body

json

{
  "customer_id": "cust_01HX2KZ9P4VREQ8T",
  "items": [
    {
      "gemstone_id": "gem_01HX2KZ9P4VREQ8T",
      "sell_price": 2800.00,
      "quantity": 1
    }
  ],
  "currency": "USD",
  "payment_status": "unpaid"
}

Response

json

{
  "id": "sale_01HX9RZ7M4WPCU6J",
  "invoice_no": "INV-2026-0043",
  "total": 2800.00,
  "status": "unpaid",
  "created_at": "2026-03-21T12:00:00Z"
}

Customers

GET/v1/customers

List all customers in your CRM with optional search and pagination.

Response

json

{
  "data": [
    {
      "id": "cust_01HX2KZ9P4VREQ8T",
      "name": "Amara Jewels Ltd",
      "email": "[email protected]",
      "phone": "+94 77 123 4567",
      "country": "Sri Lanka",
      "credit_limit": 10000.00,
      "outstanding_balance": 2800.00,
      "created_at": "2026-01-05T09:00:00Z"
    }
  ],
  "meta": { "total": 24, "page": 1, "per_page": 20 }
}

POST/v1/customers

Create a new customer record.

Request Body

json

{
  "name": "Bangkok Gem House",
  "email": "[email protected]",
  "phone": "+66 2 123 4567",
  "country": "Thailand",
  "credit_limit": 5000.00
}

Response

json

{
  "id": "cust_01HX9SZ6N5XQBV7M",
  "name": "Bangkok Gem House",
  "created_at": "2026-03-21T12:30:00Z"
}

Laboratory

GET/v1/lab/jobs

List all laboratory jobs with status filtering (pending, in_progress, completed).

Response

json

{
  "data": [
    {
      "id": "lab_01HX4LZ5R2UQAS8J",
      "gemstone_id": "gem_01HX2KZ9P4VREQ8T",
      "status": "in_progress",
      "current_stage": "Cutting",
      "weight_in_ct": 5.20,
      "weight_out_ct": null,
      "assigned_to": "user_01HX2KZ9",
      "started_at": "2026-03-18T08:00:00Z"
    }
  ]
}

POST/v1/lab/jobs

Create a new lab job and assign it to a staff member.

Request Body

json

{
  "gemstone_id": "gem_01HX2KZ9P4VREQ8T",
  "stages": ["Sawing", "Preforming", "Cutting", "Polishing"],
  "assigned_to": "user_01HX2KZ9",
  "notes": "Handle with care — fracture present on girdle"
}

Response

json

{
  "id": "lab_01HX9TZ8P6YRDW0N",
  "status": "pending",
  "created_at": "2026-03-21T13:00:00Z"
}

Error Codes

Code	Status	Meaning
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid Bearer token
403	Forbidden	Token does not have permission for this action
404	Not Found	Resource does not exist or belongs to another workspace
422	Unprocessable	Validation failed — see errors array in response
429	Rate Limited	Too many requests — default limit: 120 req/min
500	Server Error	Internal error — contact support if it persists

Full Public API — Coming Soon

The GemColony public API is under active development and will be available to all Enterprise plan customers in Q3 2026. Webhook support, SDK libraries (Node.js, Python), and a live API playground are also on the roadmap.

Need early access? Contact us at [email protected]