Operations 4
1 of 4 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
1 of 4 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-onboarding-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 Onboarding 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: Onboarding
description: Self-serve credentials.
paths:
/api/v1/keys:
post:
operationId: createApiKey
summary: Issue a self-serve API key
description: 'Returns a working API key immediately, with no account and no human approval. Keys are limited to the public read scopes and mainly buy a higher rate limit; the key is shown once and stored only as a hash, so save it. Request `env: "sandbox"` to get a key whose writes are acknowledged and discarded.'
tags:
- Onboarding
security:
- {}
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyRequest'
responses:
'201':
description: The key. Store it now; it is not retrievable.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
/api/register:
get:
operationId: describeRegistration
summary: How self-serve registration works
description: 'A short JSON description of the registration endpoint: what to POST, the defaults, and the related OAuth client registration endpoint. Read it once if the 201 body of the POST is not self-explanatory; nothing is created by a GET.'
tags:
- Onboarding
security:
- {}
responses:
'200':
description: The description.
content:
application/json:
schema:
$ref: '#/components/schemas/RegistrationDescription'
'429':
$ref: '#/components/responses/RateLimited'
post:
operationId: registerAgent
summary: 'Register an agent: a sandbox API key with no body required'
description: 'Zero-friction registration. POST with an empty body, plain text, a form, or the same JSON as `/api/v1/keys` and get a working key back at once: no account, no email, no approval. `name` defaults to `self-serve agent key` and `env` to `sandbox`; send `env: "production"` for a production key with the same public read scopes. A body shaped like RFC 7591 client metadata (`redirect_uris`, `client_name`) is treated as OAuth dynamic client registration instead. Also served at `/register`, `/signup`, and `/api/agents/register`.'
tags:
- Onboarding
security:
- {}
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyRequest'
responses:
'201':
description: The key. Store it now; it is not retrievable.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
/api/agents/register:
post:
operationId: registerAgentAlias
summary: Alias of POST /api/register
description: 'Identical to `POST /api/register`: an empty body returns a sandbox API key at once. Kept because some clients try this path first; `/register` and `/signup` are the same door.'
tags:
- Onboarding
security:
- {}
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyRequest'
responses:
'201':
description: The key. Store it now; it is not retrievable.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
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'
schemas:
RegistrationDescription:
type: object
description: 'How to register: method, defaults, and related endpoints.'
properties:
object:
type: string
enum:
- registration_endpoint
method:
type: string
enum:
- POST
url:
type: string
format: uri
defaults:
type: object
additionalProperties: true
documentation_url:
type: string
format: uri
additionalProperties: true
ApiKey:
type: object
required:
- object
- api_key
- key_id
- scopes
- env
properties:
object:
type: string
const: api_key
api_key:
type: string
description: Shown once. Store it.
key_id:
type: string
name:
type: string
scopes:
type: array
items:
type: string
env:
type: string
enum:
- sandbox
- production
usage:
type: string
documentation_url:
type: string
format: uri
additionalProperties: true
ApiKeyRequest:
type: object
required:
- name
properties:
name:
type: string
description: A short label for this key.
example: my-shopping-agent
env:
type: string
enum:
- sandbox
- production
default: sandbox
scopes:
type: array
items:
type: string
enum:
- catalog:read
- content:read
contact_email:
type: string
format: email
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
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