Ada Diamonds Discovery API
API roots and credential checks.
Operations 6
4 of 6 operations are conformant: apis.io called them with no credentials and the responses matched this contract. Checked 2026-11-12. how this works · status file
API roots and credential checks.
4 of 6 operations are conformant: apis.io called them with no credentials and the responses matched this contract. Checked 2026-11-12. how this works · status file
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/adadiamonds-com:adadiamonds-com-discovery-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Ada Diamonds Agent Discovery API
version: 1.1.0
summary: Read Ada Diamonds' lab grown diamond inventory, engagement ring settings, fine jewelry, and buying guides — and request a jeweler consultation.
description: 'The Ada Diamonds Agent API gives AI agents and applications structured access to Ada Diamonds'' live catalog and published content.
**Catalog and content endpoints require no credential.** An agent answering a shopper''s question should not need an onboarding step first. Credentials exist to raise rate limits and to reach the endpoints that touch a specific customer''s data. The API roots (`/api`, `/api/v1`) are the one read that challenges anonymous callers, with a `WWW-Authenticate: Bearer` header that points at the OAuth metadata.
**Pricing model.** An engagement ring is a setting plus a loose diamond, priced separately. `priceFrom` on a setting excludes the center stone. All prices are US dollars.
**Getting a credential.** `POST /api/v1/keys` issues a working API key immediately, no account required. For customer-specific access, register an OAuth client at `/api/oauth/register` and use the authorization code flow with PKCE.
**Sandbox.** Request `{"env":"sandbox"}` when creating a key. Sandbox credentials read the real catalog and accept writes without creating anything.
**Batching.** `POST /api/v1/batch` runs up to 20 public reads in one request and returns each sub-response with its own status. Use it to assemble a quote (a setting plus several stones) in a single round trip. A batch counts as one request against the rate limit.
**Long-running operations.** Whole-catalog exports are asynchronous: `POST /api/v1/exports` answers 202 with a `Location` header for the job. Poll `GET /api/v1/jobs/{id}` (honouring `Retry-After`) until `status` is `succeeded`, then download `result_url`. Exports complete within seconds and job ids stay valid for 24 hours. Operations marked `x-async: true` follow this pattern.
**MCP.** The same catalog is available as an MCP server at https://www.adadiamonds.com/mcp (streamable HTTP); the server card at https://www.adadiamonds.com/.well-known/mcp/server-card.json lists its tools.'
termsOfService: https://www.adadiamonds.com/terms
contact:
name: Ada Diamonds developer support
email: it@adadiamonds.com
url: https://www.adadiamonds.com/developers
license:
name: Ada Diamonds API Terms
url: https://www.adadiamonds.com/terms
servers:
- url: https://www.adadiamonds.com
description: Production
- url: https://www.adadiamonds.com/sandbox
description: 'Sandbox: every path below, mounted under /sandbox. Credential-less requests are treated as the public sandbox key; reads return the live catalog, writes are acknowledged and create nothing. Described at /sandbox.'
security:
- {}
- apiKey: []
- oauth2:
- catalog:read
- content:read
tags:
- name: Discovery
description: API roots and credential checks.
paths:
/api:
get:
operationId: getApiRoot
summary: 'API root: credential check and endpoint index'
description: 'Returns a map of every endpoint with its operationId and auth requirement, plus the resolved credential (`anonymous` when the request carries none). No credential is needed: the roots are the first URLs an agent tries, and every catalog and content endpoint behind them is open. Protected endpoints answer 401 with a bare `WWW-Authenticate: Bearer` challenge whose `resource_metadata` parameter points at the OAuth protected-resource document.'
tags:
- Discovery
security:
- {}
- apiKey: []
- oauth2:
- catalog:read
responses:
'200':
description: The endpoint index.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiIndex'
'429':
$ref: '#/components/responses/RateLimited'
/v1:
get:
operationId: getV1Probe
summary: 'Versioned-root probe: the same endpoint index as /api/v1'
description: Clients that guess `/v1` before reading any docs get the endpoint index, which says where the API is (`/api/v1`) and that it needs no account. The response is identical to `GET /api/v1`, credential resolution included; `/api/v1` remains the canonical root to link and cache.
tags:
- Discovery
security:
- {}
- apiKey: []
- oauth2:
- catalog:read
responses:
'200':
description: The endpoint index.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiIndex'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1:
get:
operationId: getApiV1Root
summary: 'Versioned API root: credential check and endpoint index'
description: 'Returns a map of every endpoint with its operationId and auth requirement, plus the resolved credential (`anonymous` when the request carries none). No credential is needed: the roots are the first URLs an agent tries, and every catalog and content endpoint behind them is open. Protected endpoints answer 401 with a bare `WWW-Authenticate: Bearer` challenge whose `resource_metadata` parameter points at the OAuth protected-resource document.'
tags:
- Discovery
security:
- {}
- apiKey: []
- oauth2:
- catalog:read
responses:
'200':
description: The endpoint index.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiIndex'
'429':
$ref: '#/components/responses/RateLimited'
/pricing.md:
get:
operationId: getPricingMarkdown
summary: Pricing, as markdown
description: The single free developer tier (rate limits, scopes, sandbox) and how products are priced (setting plus loose diamond, US dollars), with live price bands from the catalog feeds.
tags:
- Discovery
security:
- {}
responses:
'200':
description: Markdown document
content:
text/markdown:
schema:
type: string
/?mode=agent:
get:
operationId: getAgentModeView
summary: Structured agent view of the site
description: 'Any page URL with `?mode=agent` returns interfaces, authentication, capabilities, content indexes, rate limits, and contact as a linked HTML page. Send `Accept: application/json` for JSON or `Accept: text/markdown` for markdown.'
tags:
- Discovery
security:
- {}
responses:
'200':
description: Agent view
content:
text/html:
schema:
type: string
application/json:
schema:
type: object
required:
- site
- generated_at
- interfaces
- authentication
- capabilities
- content
- rate_limits
- contact
properties:
site:
type: object
generated_at:
type: string
format: date-time
interfaces:
type: object
authentication:
type: object
capabilities:
type: array
items:
type: object
properties:
name:
type: string
method:
type: string
enum:
- GET
- POST
path:
type: string
format: uri
auth:
type: string
description:
type: string
content:
type: object
rate_limits:
type: object
contact:
type: object
text/markdown:
schema:
type: string
/{section}/llms.txt:
get:
operationId: getSectionLlmsTxt
summary: Section-level llms.txt
description: A scoped llms.txt for one section of the site. Served at /developers/llms.txt, /api/llms.txt, /docs/llms.txt, /knowledge-base/llms.txt, /mcp/llms.txt, and /developers/commerce/llms.txt.
tags:
- Discovery
security:
- {}
parameters:
- name: section
in: path
required: true
schema:
type: string
enum:
- developers
- api
- docs
- knowledge-base
- mcp
- developers/commerce
responses:
'200':
description: llms.txt document
content:
text/plain:
schema:
type: string
'404':
description: Unknown section
components:
schemas:
ApiIndex:
type: object
required:
- object
- version
- endpoints
- documentation_url
- openapi_url
- mcp_url
properties:
object:
type: string
const: api_index
name:
type: string
version:
type: string
example: v1
base_url:
type: string
format: uri
credential:
$ref: '#/components/schemas/Credential'
documentation_url:
type: string
format: uri
openapi_url:
type: string
format: uri
mcp_url:
type: string
format: uri
llms_txt_url:
type: string
format: uri
endpoints:
type: array
items:
$ref: '#/components/schemas/ApiIndexEndpoint'
notes:
type: array
items:
type: string
ApiIndexEndpoint:
type: object
required:
- method
- path
- operationId
- auth
properties:
method:
type: string
path:
type: string
format: uri
operationId:
type: string
auth:
type: string
description: '"none" or the required OAuth scope.'
Credential:
type: object
required:
- kind
- env
- scopes
properties:
kind:
type: string
enum:
- anonymous
- api_key
- access_token
env:
type: string
enum:
- production
- sandbox
scopes:
type: array
items:
type: string
enum:
- catalog:read
- content:read
- profile:read
- orders:read
- cart:write
- appointments:write
Error:
type: object
required:
- error
- error_description
properties:
error:
type: string
description: Stable machine-readable code.
example: not_found
error_description:
type: string
description: What went wrong and what to do about it.
documentation_url:
type: string
format: uri
additionalProperties: true
responses:
RateLimited:
description: Over the rate limit. Wait `Retry-After` seconds; a credential raises the limit.
headers:
Retry-After:
schema:
type: integer
description: Seconds until the window resets.
RateLimit:
description: RFC 9331 combined budget, e.g. `limit=120, remaining=118, reset=42`. Read it to pace yourself.
schema:
type: string
RateLimit-Remaining:
description: Requests left in the current window.
schema:
type: integer
X-API-Version:
description: The API version that served the response.
schema:
type: string
example: v1
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'An Ada API key or OAuth access token sent as `Authorization: Bearer <credential>`. Agentic checkout requires it; sandbox keys (ada_test_*) complete without charging.'
apiKey:
type: apiKey
in: header
name: X-Ada-Api-Key
description: 'Self-serve key from POST /api/v1/keys. Also accepted as `Authorization: Bearer <key>`. Public read scopes only.'
oauth2:
type: oauth2
description: OAuth 2.1. PKCE is mandatory on the authorization code flow. Clients may self-register at /api/oauth/register (RFC 7591).
flows:
authorizationCode:
authorizationUrl: https://www.adadiamonds.com/oauth/authorize
tokenUrl: https://www.adadiamonds.com/api/oauth/token
refreshUrl: https://www.adadiamonds.com/api/oauth/token
scopes:
catalog:read: Read the public product catalog — diamonds, engagement rings, and fine jewelry, with prices and specifications.
content:read: Read published editorial content — knowledge base articles, buying guides, and showroom information.
profile:read: Read the signed-in customer's account profile (name, email, saved preferences).
orders:read: Read the signed-in customer's order history and order status.
cart:write: Create and modify a shopping cart on the signed-in customer's behalf.
appointments:write: Request a consultation or showroom appointment on the signed-in customer's behalf.
clientCredentials:
tokenUrl: https://www.adadiamonds.com/api/oauth/token
scopes:
catalog:read: Read the public product catalog — diamonds, engagement rings, and fine jewelry, with prices and specifications.
content:read: Read published editorial content — knowledge base articles, buying guides, and showroom information.
externalDocs:
description: Ada Diamonds developer documentation
url: https://www.adadiamonds.com/developers