Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/adadiamonds-com:adadiamonds-com-appointments-api"
All apis
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.
Get an API 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 Specification
openapi: 3.2.0
info:
title: Ada Diamonds Agent Appointments 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: Appointments
description: Consultation requests.
paths:
/api/v1/consultations:
post:
operationId: requestConsultation
summary: Request a jeweler consultation
description: Creates a real consultation request that a jeweler answers by email within one business day. Requires the `appointments:write` scope, which is only issued through the authorization code flow, so the customer has approved the request. Send an `Idempotency-Key` so a retried request cannot create a duplicate lead; sandbox credentials get a 201 without creating anything.
tags:
- Appointments
security:
- oauth2:
- appointments:write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConsultationRequest'
responses:
'201':
description: The request was recorded.
headers:
Idempotency-Replayed:
description: '`true` when this is the stored response to an earlier request with the same `Idempotency-Key`.'
schema:
type: string
enum:
- 'true'
content:
application/json:
schema:
$ref: '#/components/schemas/ConsultationResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: A request with this `Idempotency-Key` is still in flight. Retry shortly.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: This `Idempotency-Key` was already used with a different request body. Use a new key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/RateLimited'
'502':
$ref: '#/components/responses/UpstreamUnavailable'
components:
responses:
BadRequest:
description: The request was malformed. `error_description` says which field.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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'
Forbidden:
description: The credential is valid but lacks the required scope, or the scope cannot be self-issued.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: A credential is required. The `WWW-Authenticate` header carries the RFC 9728 `resource_metadata` pointer; follow it to the authorization server, or send a self-serve API key.
headers:
WWW-Authenticate:
required: true
description: 'Bare RFC 6750 challenge: `Bearer realm="Ada Diamonds API", resource_metadata="https://www.adadiamonds.com/.well-known/oauth-protected-resource"`.'
schema:
type: string
example: Bearer realm="Ada Diamonds API", resource_metadata="https://www.adadiamonds.com/.well-known/oauth-protected-resource"
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationRequired'
UpstreamUnavailable:
description: A catalog or content feed is temporarily unavailable. Retry in a few seconds.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
AuthenticationRequired:
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
authorization_server:
type: string
format: uri
description: RFC 8414 authorization server metadata.
resource_metadata:
type: string
format: uri
description: RFC 9728 protected resource metadata (same URL as the header parameter).
auth_guide:
type: string
format: uri
public_endpoints:
type: array
items:
type: string
description: Endpoints that need no credential.
self_serve_key:
type: string
example: POST /api/v1/keys
ConsultationRequest:
type: object
required:
- email
properties:
email:
type: string
format: email
name:
type: string
phone:
type: string
topic:
type: string
enum:
- engagement_ring
- loose_diamond
- wedding_band
- fine_jewelry
- custom_design
- other
message:
type: string
budget_usd:
type: number
product_url:
type: string
format: uri
ConsultationResponse:
type: object
required:
- object
- id
- status
properties:
object:
type: string
const: consultation_request
id:
type: string
status:
type: string
const: received
sandbox:
type: boolean
note:
type: string
next_step:
type: string
email:
type: string
format: email
additionalProperties: true
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
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: 'A client-generated unique key making this request safe to retry. This endpoint creates a Salesforce Lead, so a retry without a key can create a duplicate. Replaying a key with the same body returns the original response with `Idempotency-Replayed: true`; reusing it with a different body returns 422. Keys are honoured for 24 hours.'
schema:
type: string
maxLength: 255
example: consult-2026-08-22-a1b2c3
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