Ada Diamonds Content API
Published guides and company information.
Operations 3
3 of 3 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
Published guides and company information.
3 of 3 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-content-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 Content 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: Content
description: Published guides and company information.
paths:
/api/v1/knowledge-base:
get:
operationId: listArticles
summary: List published guides and articles
description: 'Returns a page of Ada Diamonds'' published guides on lab grown diamonds: the 4Cs, CVD versus HPHT growth, shape guides, certification, and buying advice. Each summary carries a `markdown_url`; call `getArticle` or fetch that URL for the full text.'
tags:
- Content
security:
- {}
- apiKey: []
- oauth2:
- content:read
parameters:
- in: query
name: q
description: Case-insensitive match against title and summary.
required: false
schema:
type: string
example: clarity
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: A page of articles.
headers:
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/ArticleList'
'429':
$ref: '#/components/responses/RateLimited'
'502':
$ref: '#/components/responses/UpstreamUnavailable'
/api/v1/knowledge-base/{slug}:
get:
operationId: getArticle
summary: Get one article as markdown
description: Returns a single knowledge base article with its body rendered as markdown, ready to quote or summarise. The slug is the last segment of the article URL and is also returned by `listArticles`.
tags:
- Content
security:
- {}
- apiKey: []
- oauth2:
- content:read
parameters:
- in: path
name: slug
required: true
description: Article slug.
schema:
type: string
example: cvd-lab-diamonds
responses:
'200':
description: The article, body rendered as markdown.
content:
application/json:
schema:
$ref: '#/components/schemas/Article'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'502':
$ref: '#/components/responses/UpstreamUnavailable'
/api/v1/showrooms:
get:
operationId: listShowrooms
summary: Showroom locations and remote consultation options
description: Returns Ada's physical showroom(s) with address, hours, and phone, plus the virtual consultation details that serve shoppers everywhere else. Use it to answer whether someone outside New York can buy from Ada (yes, by video consultation) and where to book.
tags:
- Content
security:
- {}
- apiKey: []
- oauth2:
- content:read
responses:
'200':
description: Showrooms and virtual consultation details.
content:
application/json:
schema:
$ref: '#/components/schemas/ShowroomList'
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
VirtualConsultations:
type: object
properties:
available:
type: boolean
description:
type: string
book_url:
type: string
format: uri
email:
type: string
format: email
telephone:
type: string
Article:
type: object
required:
- object
- slug
- title
- url
- body_markdown
properties:
object:
type: string
const: article
slug:
type: string
title:
type: string
excerpt:
type:
- string
- 'null'
author:
type:
- string
- 'null'
published_at:
type:
- string
- 'null'
url:
type: string
format: uri
markdown_url:
type: string
format: uri
body_markdown:
type: string
Showroom:
type: object
required:
- name
- url
- streetAddress
- addressLocality
- addressRegion
- postalCode
- addressCountry
- telephone
- hours
- appointmentRequired
properties:
name:
type: string
url:
type: string
format: uri
streetAddress:
type: string
addressLocality:
type: string
addressRegion:
type: string
postalCode:
type: string
addressCountry:
type: string
telephone:
type: string
hours:
type: string
appointmentRequired:
type: boolean
Pagination:
type: object
required:
- total
- limit
- offset
- has_more
properties:
total:
type: integer
description: Matches before pagination.
limit:
type: integer
offset:
type: integer
has_more:
type: boolean
description: Whether `offset + limit` would return more.
ShowroomList:
type: object
required:
- object
- data
- virtual_consultations
properties:
object:
type: string
const: list
data:
type: array
items:
$ref: '#/components/schemas/Showroom'
virtual_consultations:
$ref: '#/components/schemas/VirtualConsultations'
ArticleList:
type: object
required:
- object
- data
- pagination
properties:
object:
type: string
const: list
data:
type: array
items:
$ref: '#/components/schemas/ArticleSummary'
pagination:
$ref: '#/components/schemas/Pagination'
ArticleSummary:
type: object
required:
- slug
- title
- url
- markdown_url
properties:
slug:
type: string
title:
type: string
excerpt:
type:
- string
- 'null'
url:
type: string
format: uri
markdown_url:
type: string
format: uri
updated_at:
type: string
format: date-time
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'
NotFound:
description: Nothing at that id. `error_description` says where to list what exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
UpstreamUnavailable:
description: A catalog or content feed is temporarily unavailable. Retry in a few seconds.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
limit:
in: query
name: limit
required: false
description: Results per page (1–200).
schema:
type: integer
minimum: 1
maximum: 200
default: 25
offset:
in: query
name: offset
required: false
description: Zero-based offset into the result set.
schema:
type: integer
minimum: 0
default: 0
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