adadiamonds/agent-tools/ada-diamonds-api

Claude Code and agent skill by adadiamonds/agent-tools

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Reference for the Ada Diamonds public REST API (https://www.adadiamonds.com/api/v1) covering every endpoint, self-serve API keys and OAuth 2.1 scopes, the public sandbox key, rate limits, error shapes, versioning, and working curl examples. Use when integrating with Ada Diamonds over HTTP, generating client code, debugging a 401/403/429, or when the ada-diamonds-shopping skill needs exact parameter or response details.

Install

npx vskill@latest install adadiamonds/agent-tools/ada-diamonds-api

SKILL.md

The same SKILL.md was published earlier as adadiamonds/agent-tools/ada-diamonds-api.

Ada Diamonds REST API

Base URL: https://www.adadiamonds.com/api/v1. All responses are JSON. All prices are US dollars as decimals.

Authoritative machine descriptions (prefer these over memory when generating code):

  • OpenAPI 3.1: https://www.adadiamonds.com/openapi.json
  • RFC 9727 API catalog: https://www.adadiamonds.com/.well-known/api-catalog
  • Human docs: https://www.adadiamonds.com/developers (also served as markdown with Accept: text/markdown)
  • Agent guide: https://www.adadiamonds.com/agents.md
  • Site index: https://www.adadiamonds.com/llms.txt

Quickstart (no credential)

bash
curl "https://www.adadiamonds.com/api/v1/diamonds?shape=Oval&min_carat=1&max_price=4000&sort=price_asc"

Endpoints

Method and pathReturnsScope
GET /diamondsAvailable loose lab diamondspublic
GET /diamonds/{id}One diamond, by slug or grading report numberpublic
GET /engagement-ringsEngagement ring settings (price excludes center stone)public
GET /engagement-rings/{slug}One setting, by slug or SKU (AD-066 or 066)public
GET /jewelryFine jewelrypublic
GET /jewelry/{slug}One piece, by slug or SKUpublic
GET /knowledge-basePublished guides (q matches title and summary)public
GET /knowledge-base/{slug}One guide, body as markdownpublic
GET /showroomsShowrooms and remote consultation optionspublic
POST /consultationsRequest a jeweler consultationappointments:write
POST /keysIssue a self-serve API keypublic
POST /batchUp to 20 GET requests in one round trippublic
POST /exportsQueue a full catalog export; 202 with a job to pollpublic
GET /jobs/{id}Status of an export job (queued or succeeded)public
GET /exports/{id}Download a finished export (NDJSON or JSON)public

Outside /api/v1, on the site root:

Method and pathReturns
GET https://www.adadiamonds.com/ask?query=...NLWeb natural-language answer over the catalog and guides (JSON, or SSE with streaming=true)
GET https://www.adadiamonds.com/.well-known/agent-card.jsonA2A agent card; JSON-RPC endpoint at /a2a
GET https://www.adadiamonds.com/auth.mdAgent authentication walkthrough
GET https://www.adadiamonds.com/pricing.mdMachine-readable pricing rules
GET <any page>?mode=agentStructured agent view of a page instead of marketing HTML

Full parameter tables and response fields: references/endpoints.md.

Batch
bash
curl -X POST https://www.adadiamonds.com/api/v1/batch \
-H "Content-Type: application/json" \
-d '{"requests":[
{"id":"setting","method":"GET","path":"/api/v1/engagement-rings","query":{"shape":"Oval","type":"Solitaire","limit":1}},
{"id":"stone","method":"GET","path":"/api/v1/diamonds","query":{"shape":"Oval","min_carat":1.5,"max_carat":1.6,"sort":"price_asc","limit":1}}
]}'
# 200 { "object": "batch", "count": 2, "responses": [ { "id": "setting", "status": 200, "body": {...} }, { "id": "stone", "status": 200, "body": {...} } ] }

GET only, catalog and content paths only, at most 20 entries. Each entry returns its own status and body in the same order, so one failure never hides the others; the batch itself is 200. The batch counts as one rate-limit unit.

Exports and jobs
bash
curl -X POST https://www.adadiamonds.com/api/v1/exports \
-H "Content-Type: application/json" \
-d '{"type":"diamonds","format":"jsonl","filters":{"shape":"Oval"}}'
# 202, Location + Retry-After headers, body: { "job": { "id", "status": "queued", "status_url", "result_url": null, "expires_at" } }
curl https://www.adadiamonds.com/api/v1/jobs/<id> # "queued" (with Retry-After) then "succeeded" with result_url
curl https://www.adadiamonds.com/api/v1/exports/<id> # application/x-ndjson, one product per line

type is diamonds, engagement-rings, or jewelry; format is jsonl (default) or json; filters accepts the same query parameters as the matching list endpoint. Exports complete within seconds and expire 24 hours after creation. Honour Retry-After instead of polling in a loop. Use this instead of walking offset through the whole catalog.

Pagination

List endpoints take limit (1-200, default 25) and offset, and return:

json
{
"object": "list",
"currency": "USD",
"data": [ ... ],
"pagination": { "total": 412, "limit": 25, "offset": 0, "has_more": true }
}

Engagement ring lists also carry a price_note reminding that price_from excludes the center diamond.

Authentication

Reading the catalog and content needs nothing. Credentials raise the rate limit and unlock customer-specific endpoints.

Public sandbox key (works for everyone, no signup)
bash
curl "https://www.adadiamonds.com/api/v1/diamonds?limit=1" \
-H "X-Ada-Api-Key: ada_test_public_sandbox_key"

It carries only catalog:read and content:read. Sandbox credentials read the real catalog and accept writes without creating anything: a sandbox POST /consultations returns 201 { "sandbox": true, ... } and no jeweler is contacted.

Self-serve API key
bash
curl -X POST https://www.adadiamonds.com/api/v1/keys \
-H "Content-Type: application/json" \
-d '{"name":"my-agent","env":"sandbox"}'
  • name (required), env (sandbox or production, default sandbox), scopes (optional; only catalog:read and content:read are self-serve).
  • The key is returned once and stored only as a hash.
  • Send it as Authorization: Bearer <key> or X-Ada-Api-Key: <key>.
OAuth 2.1

Metadata: https://www.adadiamonds.com/.well-known/oauth-authorization-server. PKCE is mandatory. Dynamic client registration (RFC 7591):

bash
curl -X POST https://www.adadiamonds.com/api/oauth/register \
-H "Content-Type: application/json" \
-d '{"client_name":"My shopping agent","redirect_uris":["https://example.com/callback"],"grant_types":["authorization_code","refresh_token"],"scope":"catalog:read content:read"}'

Public scopes with no user involved:

bash
curl -X POST https://www.adadiamonds.com/api/oauth/token \
-d "grant_type=client_credentials" -d "client_id=ada_client_..." -d "scope=catalog:read content:read"

Customer scopes use the authorization code flow: the customer signs in at /oauth/authorize and approves the exact scopes on a consent screen.

Scopes
ScopeGrantsHow to obtain
catalog:readProducts, prices, specificationsAPI key or client_credentials
content:readArticles, guides, showroom infoAPI key or client_credentials
profile:readThe signed-in customer's profileAuthorization code flow
orders:readThe signed-in customer's ordersAuthorization code flow
cart:writeBuild a cart for the customerAuthorization code flow
appointments:writeRequest a consultation for the customerAuthorization code flow

Consultations

bash
curl -X POST https://www.adadiamonds.com/api/v1/consultations \
-H "Authorization: Bearer <token with appointments:write>" \
-H "Idempotency-Key: 6f1c0e3a-..." \
-H "Content-Type: application/json" \
-d '{"email":"shopper@example.com","name":"Sam","topic":"engagement_ring","message":"1.5ct oval, under $6k total"}'

Fields: email (required), name, phone, topic (engagement_ring, loose_diamond, wedding_band, fine_jewelry, custom_design, other), message, preferred_contact. Always send Idempotency-Key; without it a retry can create a duplicate request that a jeweler follows up on twice. A jeweler replies by email within one business day.

Rate limits

CallerLimitWindow
Anonymous120 requests60 seconds
API key or access token600 requests60 seconds

Every response carries RFC 9331 headers. Read them and pace yourself instead of retrying into a refusal:

RateLimit: limit=120, remaining=118, reset=47
RateLimit-Policy: "anonymous";q=120;w=60
RateLimit-Limit: 120
RateLimit-Remaining: 118
RateLimit-Reset: 47

A 429 carries Retry-After and retry_after_seconds. Counters are per serverless instance, so treat the headers as a cooperative signal rather than a hard guarantee.

Errors

Always JSON, including 404s on unknown paths:

json
{
"error": "not_found",
"error_description": "Diamond \"abc\" was not found. Lab diamond inventory turns over as stones sell. List what is currently available at https://www.adadiamonds.com/api/v1/diamonds.",
"documentation_url": "https://www.adadiamonds.com/developers"
}
StatuserrorMeaning
400invalid_requestBad parameter or body; the description says which
401unauthorizedAuthenticate and retry. WWW-Authenticate: Bearer resource_metadata="https://www.adadiamonds.com/.well-known/oauth-protected-resource" points at the RFC 9728 metadata, which names the authorization server
403insufficient_scopeAuthenticated but missing the named scope
404not_foundUnknown resource or path; the description lists what to try instead
429rate_limitedWait Retry-After seconds

Versioning

/api/v1 is current with no retirement date. Additive changes ship without a bump, so ignore unknown fields. Every response carries X-API-Version: v1 and Link: <https://www.adadiamonds.com/developers#versioning>; rel="deprecation-policy". Retirement, if ever, is signalled by a Deprecation header (RFC 9745) then a Sunset header (RFC 8594) at least 12 months later.

Catalog data is edge-cached for up to an hour. Diamond inventory is the volatile part; re-check a stone before quoting it.

Markdown for every page

bash
curl -H "Accept: text/markdown" https://www.adadiamonds.com/knowledge-base/cvd-lab-diamonds
curl https://www.adadiamonds.com/knowledge-base/cvd-lab-diamonds.md

Responses send Vary: Accept and a Link: rel="alternate" header pointing at the markdown twin.

Etiquette

Identify your agent with a descriptive User-Agent. Bulk scraping of the HTML catalog is not permitted; these endpoints and POST /exports are the supported way to read it.

Official clients: npx @ada-diamonds/cli (Node 18+, no dependencies; also published unscoped as adadiamonds-cli), the ada-diamonds Python package (pip install ada-diamonds, https://pypi.org/project/ada-diamonds/), the github.com/adadiamonds/ada-go Go module (standard library only, Go 1.21+), and the adadiamonds Ruby gem (gem install adadiamonds, https://rubygems.org/gems/adadiamonds). Developer questions: it@adadiamonds.com.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
2
7-day trend score
5

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/adadiamonds/agent-tools/ada-diamonds-api/badge)](https://verified-skill.com/skills/adadiamonds/agent-tools/ada-diamonds-api)

Something wrong with this skill or its page? Tell us.