adadiamonds-go

Official Go client for the Ada Diamonds API: live lab grown diamond inventory, engagement ring settings, fine jewelry, showrooms, and the diamond buying guides.

Standard library only (net/http, encoding/json). Go 1.21 or newer.

• Documentation: https://www.adadiamonds.com/developers
• REST reference: https://www.adadiamonds.com/developers/api
• OpenAPI 3.1: https://www.adadiamonds.com/openapi.json
• MCP server (for tool use instead of HTTP): https://www.adadiamonds.com/mcp

Install

go get github.com/adadiamonds/adadiamonds-go

Reading the catalog needs no account and no API key (120 requests per minute). An API key raises that to 600 and unlocks the write endpoints. Every price is in US dollars.

Examples

Search live diamond inventory

package main

import (
	"context"
	"fmt"

	ada "github.com/adadiamonds/adadiamonds-go"
)

func main() {
	client := ada.New() // anonymous
	page, err := client.Diamonds(context.Background(), ada.Params{
		"shape": "Oval", "min_carat": 1, "max_price": 4000, "sort": "price_asc",
	})
	if err != nil {
		panic(err)
	}
	for _, stone := range page.Data {
		fmt.Println(stone["carat"], stone["shape"], stone["price"])
	}
	fmt.Printf("%+v\n", *client.LastRateLimit()) // {Limit:120 Remaining:119 Reset:58 Policy:...}
}

Quote a complete ring

An engagement ring is a setting plus a loose diamond, priced separately. Setting prices never include the center stone.

settings, _ := client.EngagementRings(ctx, ada.Params{"shape": "Oval", "type": "Solitaire", "limit": 1})
stones, _ := client.Diamonds(ctx, ada.Params{"shape": "Oval", "min_carat": 1.5, "max_carat": 1.6, "sort": "price_asc", "limit": 1})
setting := settings.Data[0]
stone := stones.Data[0]
fmt.Println(setting["price_from"].(float64) + stone["price"].(float64)) // US dollars

Authenticate and write

key, _ := ada.New().CreateKey(ctx, "my-agent", "sandbox")
client := ada.New(ada.WithAPIKey(key["api_key"].(string))) // 600 requests/min

_, err := client.RequestConsultation(ctx, map[string]any{
	"email": "test@example.com",
	"topic": "engagement_ring",
}, "consult-42") // idempotency key: a retry cannot create two requests

var apiErr *ada.APIError
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.Status, apiErr.Code, apiErr.Description, apiErr.RetryAfter)
}

Sandbox keys (ada_test_*) return well-formed responses and contact nobody.

Ask a question (NLWeb)

answer, _ := client.Ask(ctx, "oval lab diamond engagement ring under $6,000", nil)

Anything else

Every method maps to one endpoint under /api/v1. For endpoints without a helper, Get and Post take a path relative to /api/v1 (or absolute on the site) and decode into any value:

var out map[string]any
err := client.Get(ctx, "/jewelry", ada.Params{"category": "wedding-bands"}, &out)

Methods

Method	Endpoint
Diamonds, Diamond	GET /api/v1/diamonds, GET /api/v1/diamonds/{id}
EngagementRings, EngagementRing	GET /api/v1/engagement-rings, .../{slug}
Jewelry, JewelryItem	GET /api/v1/jewelry, .../{slug}
KnowledgeBase, Article	GET /api/v1/knowledge-base, .../{slug}
Showrooms	GET /api/v1/showrooms
RequestConsultation	POST /api/v1/consultations
CreateKey	POST /api/v1/keys
Batch	POST /api/v1/batch (up to 20 GETs in one round trip)
Ask	GET /ask (NLWeb)

Errors are *ada.APIError with Status, Code, Description, DocumentationURL, and RetryAfter. Every response's RateLimit-* headers are available from LastRateLimit(); pace yourself rather than retrying into a 429.

Etiquette

Identify your agent with ada.WithUserAgent("my-agent/1.0 (+https://example.com)"). Bulk scraping of the HTML catalog is not permitted; this API and POST /api/v1/exports are the supported way to read it. Diamond inventory changes continuously; re-check a stone before quoting it.

License

MIT. Copyright Ada Diamonds, Inc.