Ada Diamonds Bulk API
Batched reads and asynchronous catalog exports.
Batched reads and asynchronous catalog exports.
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-bulk-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 Bulk 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: Bulk
description: Batched reads and asynchronous catalog exports.
paths:
/api/v1/batch:
post:
operationId: batchRequests
summary: Run several read requests in one call
description: Executes up to 20 GET requests against the public read endpoints in a single round trip and returns each sub-response with its own status and body. The batch always answers 200 once the envelope is valid, even if individual items fail, so check each item's `status`. Only the read endpoints listed in the `allowed_paths` of an error item can be batched; a batch counts as one request against the rate limit.
tags:
- Bulk
security:
- {}
- apiKey: []
- oauth2:
- catalog:read
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BatchRequest'
responses:
'200':
description: Every sub-response, in request order.
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/BatchResponse'
'400':
$ref: '#/components/responses/BadRequest'
'429':
$ref: '#/components/responses/RateLimited'
/api/v1/exports:
post:
operationId: createExport
summary: Start a full catalog export (async job)
description: 'Starts an export of the diamonds, engagement ring, or jewelry catalog with the same filters the list endpoint accepts, and answers **202 Accepted** with a `Location` header pointing at the job''s status URL. Exports complete within seconds: poll `status_url` (honouring `Retry-After`) until `status` is `succeeded`, then download `result_url`. Job ids are self-contained signed tokens valid for 24 hours; there is nothing to cancel.'
tags:
- Bulk
security:
- {}
- apiKey: []
- oauth2:
- catalog:read
x-async: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExportRequest'
responses:
'202':
description: The export job was accepted. Poll the `Location` URL.
headers:
Location:
description: Job status URL (`GET /api/v1/jobs/{id}`).
schema:
type: string
format: uri
Retry-After:
description: Seconds to wait before the first poll (2).
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'400':
$ref: '#/components/responses/BadRequest'
'429':
$ref: '#/components/responses/RateLimited'
'503':
$ref: '#/components/responses/ServiceUnavailable'
/api/v1/exports/{id}:
get:
operationId: downloadExport
summary: Download a finished export
description: Streams the export as `application/x-ndjson` (one product per line, default) or as a JSON array, depending on the `format` chosen when the job was created. Rows have exactly the field shape of the matching list endpoint, with prices in US dollars. The response is an attachment (`Content-Disposition`) and is never cached.
tags:
- Bulk
security:
- {}
- apiKey: []
- oauth2:
- catalog:read
parameters:
- in: path
name: id
required: true
description: Job id returned by `createExport`.
schema:
type: string
example: job_eyJ0IjoiZXhwb3J0In0.abc
responses:
'200':
description: The export.
headers:
Content-Disposition:
description: e.g. `attachment; filename="ada-diamonds-diamonds-2026-08-25.jsonl"`
schema:
type: string
X-Export-Count:
description: Number of rows in the export.
schema:
type: integer
content:
application/x-ndjson:
schema:
type: string
description: One JSON object per line; each is a Diamond, EngagementRing, or JewelryItem.
application/json:
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/Diamond'
- $ref: '#/components/schemas/EngagementRing'
- $ref: '#/components/schemas/JewelryItem'
'401':
$ref: '#/components/responses/InvalidJobToken'
'404':
$ref: '#/components/responses/NotFound'
'410':
$ref: '#/components/responses/Gone'
'429':
$ref: '#/components/responses/RateLimited'
'502':
$ref: '#/components/responses/UpstreamUnavailable'
'503':
$ref: '#/components/responses/ServiceUnavailable'
/api/v1/jobs/{id}:
get:
operationId: getJob
summary: Get the status of an async job
description: Reports the state of a job started by `createExport`. A job is `queued` for a moment after creation (the response carries `Retry-After`) and `succeeded` after that, at which point `result_url` is set. Expired jobs (older than 24 hours) return 410; start a new export.
tags:
- Bulk
security:
- {}
- apiKey: []
- oauth2:
- catalog:read
parameters:
- in: path
name: id
required: true
description: Job id returned by `createExport`.
schema:
type: string
example: job_eyJ0IjoiZXhwb3J0In0.abc
responses:
'200':
description: The job.
headers:
Retry-After:
description: 'Present while the job is still `queued`: seconds to wait before polling again.'
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'401':
$ref: '#/components/responses/InvalidJobToken'
'404':
$ref: '#/components/responses/NotFound'
'410':
$ref: '#/components/responses/Gone'
'429':
$ref: '#/components/responses/RateLimited'
'503':
$ref: '#/components/responses/ServiceUnavailable'
components:
responses:
NotFound:
description: Nothing at that id. `error_description` says where to list what exists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
InvalidJobToken:
description: The job id's signature does not verify. Use ids exactly as issued.
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'
ServiceUnavailable:
description: The feature is not configured in this environment. Retry after `Retry-After`.
headers:
Retry-After:
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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'
Gone:
description: The job expired (24 hours). Start a new export.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
BatchResponse:
type: object
required:
- object
- count
- responses
properties:
object:
type: string
const: batch
count:
type: integer
responses:
type: array
items:
$ref: '#/components/schemas/BatchResponseItem'
VirtualConsultations:
type: object
properties:
available:
type: boolean
description:
type: string
book_url:
type: string
format: uri
email:
type: string
format: email
telephone:
type: string
EngagementRingList:
type: object
required:
- object
- currency
- data
- pagination
properties:
object:
type: string
const: list
currency:
type: string
const: USD
price_note:
type: string
data:
type: array
items:
$ref: '#/components/schemas/EngagementRing'
pagination:
$ref: '#/components/schemas/Pagination'
Job:
type: object
required:
- object
- id
- type
- status
- status_url
- created_at
- expires_at
properties:
object:
type: string
const: job
id:
type: string
description: Opaque signed job id. Valid for 24 hours.
type:
type: string
const: export
status:
type: string
enum:
- queued
- succeeded
progress:
type: integer
minimum: 0
maximum: 100
export:
type: object
properties:
type:
type: string
enum:
- diamonds
- engagement-rings
- jewelry
format:
type: string
enum:
- jsonl
- json
filters:
type: object
additionalProperties:
type: string
status_url:
type: string
format: uri
result_url:
type:
- string
- 'null'
format: uri
description: Set once `status` is `succeeded`.
created_at:
type: string
format: date-time
completed_at:
type:
- string
- 'null'
format: date-time
expires_at:
type: string
format: date-time
note:
type: string
BatchRequestItem:
type: object
required:
- path
properties:
id:
type: string
description: Echoed back on the matching response. Defaults to the item's index.
example: stones
method:
type: string
enum:
- GET
default: GET
path:
type: string
description: Absolute API path of a public read endpoint.
example: /api/v1/diamonds
query:
type: object
additionalProperties:
type:
- string
- number
- boolean
description: Query parameters, exactly as the endpoint documents them.
example:
shape: Oval
limit: '3'
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
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
ProductImage:
type: object
required:
- metal
- view
- url
properties:
metal:
type: string
example: white
view:
type: string
enum:
- primary
- alternate
url:
type: string
format: uri
alt:
type:
- string
- 'null'
JewelryList:
type: object
required:
- object
- currency
- data
- pagination
properties:
object:
type: string
const: list
currency:
type: string
const: USD
data:
type: array
items:
$ref: '#/components/schemas/JewelryItem'
pagination:
$ref: '#/components/schemas/Pagination'
Diamond:
type: object
required:
- id
- name
- url
- price
properties:
object:
type: string
const: diamond
description: Present on single-item responses.
currency:
type: string
const: USD
id:
type: string
name:
type: string
example: 1.02ct F VS1 Ideal Round
url:
type: string
format: uri
price:
type:
- number
- 'null'
description: USD, loose stone only.
carat:
type:
- number
- 'null'
shape:
type:
- string
- 'null'
color:
type:
- string
- 'null'
clarity:
type:
- string
- 'null'
cut:
type:
- string
- 'null'
certificate:
type:
- string
- 'null'
description: Grading report number.
lab:
type:
- string
- 'null'
description: Grading laboratory (GCAL, IGI, GIA).
measurements:
type:
- string
- 'null'
lengthToWidthRatio:
type:
- number
- 'null'
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
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.
DiamondList:
type: object
required:
- object
- currency
- data
- pagination
properties:
object:
type: string
const: list
currency:
type: string
const: USD
data:
type: array
items:
$ref: '#/components/schemas/Diamond'
pagination:
$ref: '#/components/schemas/Pagination'
BatchResponseItem:
type: object
required:
- id
- status
- body
properties:
id:
type: string
status:
type: integer
description: The HTTP status the endpoint would have returned.
body:
description: The endpoint's JSON body, or an Error object for a rejected item.
oneOf:
- $ref: '#/components/schemas/DiamondList'
- $ref: '#/components/schemas/Diamond'
- $ref: '#/components/schemas/EngagementRingList'
- $ref: '#/components/schemas/EngagementRing'
- $ref: '#/components/schemas/JewelryList'
- $ref: '#/components/schemas/JewelryItem'
- $ref: '#/components/schemas/ArticleList'
- $ref: '#/components/schemas/Article'
- $ref: '#/components/schemas/ShowroomList'
- $ref: '#/components/schemas/Error'
BatchRequest:
type: object
required:
- requests
properties:
requests:
type: array
minItems: 1
maxItems: 20
items:
$ref: '#/components/schemas/BatchRequestItem'
EngagementRing:
type: object
required:
- sku
- title
- url
- shapes
- priceFrom
- images
properties:
object:
type: string
const: engagement_ring
currency:
type: string
const: USD
price_note:
type: string
sku:
type: string
example: AD-066
title:
type: string
url:
type: string
format: uri
shapes:
type: array
items:
type: string
style:
type:
- string
- 'null'
type:
type:
- string
- 'null'
priceFrom:
type:
- number
- 'null'
description: USD. Setting only; excludes the center diamond.
platinumUpcharge:
type:
- number
- 'null'
description: USD added for platinum.
twoToneUpcharge:
type:
- number
- 'null'
description: USD added for a two-tone setting.
images:
type: array
items:
$ref: '#/components/schemas/ProductImage'
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'
JewelryItem:
type: object
required:
- sku
- title
- url
- shapes
- priceFrom
- images
properties:
object:
type: string
const: jewelry_item
currency:
type: string
const: USD
sku:
type: string
title:
type: string
url:
type: string
format: uri
category:
type:
- string
- 'null'
type:
type:
- string
- 'null'
subtype:
type:
- string
- 'null'
shapes:
type: array
items:
type: string
priceFrom:
type:
- number
- 'null'
description: USD.
priceMax:
type:
- number
- 'null'
description: USD.
images:
type: array
items:
$ref: '#/components/schemas/ProductImage'
ExportRequest:
type: object
required:
- type
properties:
type:
type: string
enum:
- diamonds
- engagement-rings
- jewelry
format:
type: string
enum:
- jsonl
- json
default: jsonl
description: '`jsonl` streams one product per line; `json` returns one array.'
filters:
type: object
additionalProperties:
type:
- string
- number
description: Same query keys as the matching list endpoint (e.g. `shape`, `min_price`). Unknown keys are ignored.
example:
shape: Oval
max_price: 5000
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'
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