adadiamonds/agent-tools/ada-diamonds-api
Claude Code and agent skill by adadiamonds/agent-tools
- community
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-apiSKILL.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 withAccept: text/markdown) - Agent guide:
https://www.adadiamonds.com/agents.md - Site index:
https://www.adadiamonds.com/llms.txt
Quickstart (no credential)
Endpoints
| Method and path | Returns | Scope | |
|---|---|---|---|
GET /diamonds | Available loose lab diamonds | public | |
GET /diamonds/{id} | One diamond, by slug or grading report number | public | |
GET /engagement-rings | Engagement ring settings (price excludes center stone) | public | |
GET /engagement-rings/{slug} | One setting, by slug or SKU (AD-066 or 066) | public | |
GET /jewelry | Fine jewelry | public | |
GET /jewelry/{slug} | One piece, by slug or SKU | public | |
GET /knowledge-base | Published guides (q matches title and summary) | public | |
GET /knowledge-base/{slug} | One guide, body as markdown | public | |
GET /showrooms | Showrooms and remote consultation options | public | |
POST /consultations | Request a jeweler consultation | appointments:write | |
POST /keys | Issue a self-serve API key | public | |
POST /batch | Up to 20 GET requests in one round trip | public | |
POST /exports | Queue a full catalog export; 202 with a job to poll | public | |
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 path | Returns | |
|---|---|---|
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.json | A2A agent card; JSON-RPC endpoint at /a2a | |
GET https://www.adadiamonds.com/auth.md | Agent authentication walkthrough | |
GET https://www.adadiamonds.com/pricing.md | Machine-readable pricing rules | |
GET <any page>?mode=agent | Structured agent view of a page instead of marketing HTML |
Full parameter tables and response fields: references/endpoints.md.
Batch
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
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:
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)
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
name(required),env(sandboxorproduction, default sandbox),scopes(optional; onlycatalog:readandcontent:readare self-serve).- The key is returned once and stored only as a hash.
- Send it as
Authorization: Bearer <key>orX-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):
Public scopes with no user involved:
Customer scopes use the authorization code flow: the customer signs in at /oauth/authorize and approves the exact scopes on a consent screen.
Scopes
| Scope | Grants | How to obtain | |
|---|---|---|---|
catalog:read | Products, prices, specifications | API key or client_credentials | |
content:read | Articles, guides, showroom info | API key or client_credentials | |
profile:read | The signed-in customer's profile | Authorization code flow | |
orders:read | The signed-in customer's orders | Authorization code flow | |
cart:write | Build a cart for the customer | Authorization code flow | |
appointments:write | Request a consultation for the customer | Authorization code flow |
Consultations
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
| Caller | Limit | Window | |
|---|---|---|---|
| Anonymous | 120 requests | 60 seconds | |
| API key or access token | 600 requests | 60 seconds |
Every response carries RFC 9331 headers. Read them and pace yourself instead of retrying into a refusal:
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:
| Status | error | Meaning | |
|---|---|---|---|
| 400 | invalid_request | Bad parameter or body; the description says which | |
| 401 | unauthorized | Authenticate 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 | |
| 403 | insufficient_scope | Authenticated but missing the named scope | |
| 404 | not_found | Unknown resource or path; the description lists what to try instead | |
| 429 | rate_limited | Wait 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
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
- SKILL.md in the repositoryCheckingskills/ada-diamonds-api/SKILL.md
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
[](https://verified-skill.com/skills/adadiamonds/agent-tools/ada-diamonds-api)