# Ada Diamonds agent API

Base URL: `https://www.adadiamonds.com/api/v1`

## Reading the catalog needs no credential

Catalog and content endpoints are readable anonymously so an agent can answer a shopper's question without an onboarding step.

```
curl "https://www.adadiamonds.com/api/v1/diamonds?shape=oval&min_carat=1&max_price=4000"
curl "https://www.adadiamonds.com/api/v1/engagement-rings?shape=Round&limit=5"
curl "https://www.adadiamonds.com/api/v1/jewelry?type=Wedding%20Bands"
curl "https://www.adadiamonds.com/api/v1/knowledge-base"
curl "https://www.adadiamonds.com/api/v1/showrooms"
```

## How Ada prices a ring

An engagement ring is a **setting** plus a **loose diamond**, priced separately. `price_from` on a setting excludes the center stone. To quote a complete ring, add a setting and a diamond together. All prices are US dollars.

## Credentials, when you want them

- **Self-serve API key** — `POST /api/v1/keys` returns a working key immediately, no account required. Public read scopes only.
- **Zero-friction registration** — `POST /api/register` (also `/register`, `/signup`) with an empty body returns a sandbox key with defaults filled in; `GET /v1`, `/api`, and `/api/v1` answer the endpoint index without a credential.
- **OAuth 2.1** — register at `/api/oauth/register` (RFC 7591), then use `client_credentials` for public scopes, or the authorization code flow (PKCE mandatory) for customer-specific ones.

## 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 |

The last four describe one customer's data and are only issued through the authorization code flow, where that customer approves the request on a consent screen.

## MCP server

Streamable HTTP at `https://www.adadiamonds.com/mcp`. Connects anonymously — no OAuth before you can list tools.

Tools: `search_diamonds`, `search_engagement_rings`, `search_jewelry`, `search_knowledge_base`, `read_article`, `get_company_info`, `request_consultation`.

Resources: `ada://catalog/diamonds`, `ada://catalog/engagement-rings`, `ada://catalog/jewelry`, `ada://content/knowledge-base`, `ada://company/profile`, `ada://developers/api`. Read the catalog resources once at the start of a session for inventory shape — it saves several tool calls.

## Sandbox

Request `{"env":"sandbox"}` when creating a key. Sandbox credentials read the real catalog and accept writes without creating anything.

A public sandbox key works for everyone with no signup:

```
curl "https://www.adadiamonds.com/api/v1/diamonds?limit=1" -H "X-Ada-Api-Key: ada_test_public_sandbox_key"
```

## Rate limits

120 requests/minute anonymous, 600 with a credential. Every response carries RFC 9331 `RateLimit`, `RateLimit-Policy`, and `RateLimit-Remaining` headers — read them and pace yourself rather than retrying into a refusal. A 429 carries `Retry-After`.

## Versioning

`/api/v1` is current with no retirement date. Deprecation is announced with a `Deprecation` header (RFC 9745), then a `Sunset` header (RFC 8594) at least 12 months later. Every response carries `X-API-Version` and a `Link` header pointing at the policy.

## CLI

`npx @ada-diamonds/cli diamonds --shape Oval --max-price 4000` — wraps these same endpoints; `--json` prints raw responses.

## Markdown

Every page on this site serves markdown: append `.md` to any URL, or send `Accept: text/markdown`. Responses carry `Vary: Accept`.

## Errors

Every error carries a stable `error` code, an `error_description` saying what to do next, and a `documentation_url`. A 401 means authenticate and retry; a 403 means the credential lacks the scope, and names the scope needed.

## Machine descriptions

- OpenAPI 3.1: https://www.adadiamonds.com/openapi.json
- MCP server card: https://www.adadiamonds.com/mcp/server-card
- API catalog (RFC 9727): https://www.adadiamonds.com/.well-known/api-catalog
- OAuth metadata: https://www.adadiamonds.com/.well-known/oauth-authorization-server

Full documentation: https://www.adadiamonds.com/developers