Ada Diamonds Catalog API

openapi: 3.2.0
info:
  title: Ada Diamonds Agent Catalog 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: Catalog
  description: Diamonds, engagement rings, and jewelry.
paths:
  /api/v1/diamonds:
    get:
      operationId: listDiamonds
      summary: Search available loose lab diamonds
      description: Returns a page of Ada's live loose lab grown diamond inventory, filtered by shape, carat, price, color, clarity, and cut. Stones sell continuously, so treat results as a snapshot and call `getDiamond` to re-check a specific stone before quoting it. Prices are US dollars for the loose stone only; add a setting from `listEngagementRings` to quote a finished ring.
      tags:
      - Catalog
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      parameters:
      - in: query
        name: shape
        description: Diamond shape. One of Round, Oval, Cushion, Emerald, Pear, Radiant, Asscher, Princess, Marquise (case-insensitive).
        required: false
        schema:
          type: string
        example: Oval
      - in: query
        name: min_carat
        description: Minimum carat weight (inclusive).
        required: false
        schema:
          type: number
          minimum: 0
      - in: query
        name: max_carat
        description: Maximum carat weight (inclusive).
        required: false
        schema:
          type: number
          minimum: 0
      - in: query
        name: min_price
        description: Minimum price in US dollars (inclusive).
        required: false
        schema:
          type: number
          minimum: 0
      - in: query
        name: max_price
        description: Maximum price in US dollars (inclusive).
        required: false
        schema:
          type: number
          minimum: 0
      - in: query
        name: color
        description: Color grade, D through K.
        required: false
        schema:
          type: string
        example: F
      - in: query
        name: clarity
        description: 'Clarity grade: FL, IF, VVS1, VVS2, VS1, VS2, SI1, SI2.'
        required: false
        schema:
          type: string
        example: VS1
      - in: query
        name: cut
        description: 'Cut grade: Ideal, Excellent, Very Good.'
        required: false
        schema:
          type: string
      - in: query
        name: sort
        description: Sort order. Default is the feed order.
        required: false
        schema:
          type: string
          enum:
          - price_asc
          - price_desc
          - carat_asc
          - carat_desc
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A page of available diamonds.
          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/DiamondList'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /api/v1/diamonds/{id}:
    get:
      operationId: getDiamond
      summary: Get one diamond
      description: Returns a single loose diamond by its product id or by the grading report number (GCAL, IGI, or GIA), which is the identifier an agent usually has after reading a product page. A 404 means the stone has sold or the id is wrong; list current inventory with `listDiamonds` and pick again.
      tags:
      - Catalog
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      parameters:
      - in: path
        name: id
        required: true
        description: Product id (from `listDiamonds`) or grading report number.
        schema:
          type: string
        example: LG12345678
      responses:
        '200':
          description: The diamond.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Diamond'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /api/v1/engagement-rings:
    get:
      operationId: listEngagementRings
      summary: Search engagement ring settings
      description: Returns a page of engagement ring settings filtered by the center stone shape they accommodate, style, type, and setting price. `priceFrom` is the setting alone and excludes the center diamond; pair a result with a stone from `listDiamonds` and add the two prices to quote a complete ring. Every setting is made to order in platinum or 14k/18k gold.
      tags:
      - Catalog
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      parameters:
      - in: query
        name: shape
        description: Center stone shape the setting accommodates.
        required: false
        schema:
          type: string
        example: Oval
      - in: query
        name: style
        description: Setting style, e.g. Petite Four Prong, Trellis, Bezel.
        required: false
        schema:
          type: string
      - in: query
        name: type
        description: Setting type, e.g. Solitaire, Halo, Three Stone.
        required: false
        schema:
          type: string
        example: Solitaire
      - in: query
        name: min_price
        description: Minimum price in US dollars (inclusive).
        required: false
        schema:
          type: number
          minimum: 0
      - in: query
        name: max_price
        description: Maximum price in US dollars (inclusive).
        required: false
        schema:
          type: number
          minimum: 0
      - in: query
        name: q
        description: Free-text match against the setting name.
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A page of settings.
          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/EngagementRingList'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /api/v1/engagement-rings/{slug}:
    get:
      operationId: getEngagementRing
      summary: Get one engagement ring setting
      description: Returns a single setting by its URL slug or SKU (`AD-066` or bare `066`). The response includes per-metal images and the platinum and two-tone upcharges, which is everything needed to describe the setting to a shopper; the center diamond is still priced separately.
      tags:
      - Catalog
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      parameters:
      - in: path
        name: slug
        required: true
        description: Product slug or SKU ("AD-066" or "066").
        schema:
          type: string
        example: AD-066
      responses:
        '200':
          description: The setting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementRing'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /api/v1/jewelry:
    get:
      operationId: listJewelry
      summary: Search fine jewelry
      description: Returns a page of fine jewelry (wedding bands, earrings, necklaces, bracelets, fashion rings) filtered by category, type, diamond shape, and price. `priceFrom` and `priceMax` bound the configurable price range in US dollars; every piece is set with lab grown diamonds.
      tags:
      - Catalog
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      parameters:
      - in: query
        name: category
        description: Top-level category, e.g. Bridal, Fashion.
        required: false
        schema:
          type: string
      - in: query
        name: type
        description: Piece type, e.g. Wedding Bands, Earrings, Necklaces.
        required: false
        schema:
          type: string
        example: Wedding Bands
      - in: query
        name: shape
        description: Diamond shape used in the piece.
        required: false
        schema:
          type: string
      - in: query
        name: min_price
        description: Minimum price in US dollars (inclusive).
        required: false
        schema:
          type: number
          minimum: 0
      - in: query
        name: max_price
        description: Maximum price in US dollars (inclusive).
        required: false
        schema:
          type: number
          minimum: 0
      - in: query
        name: q
        description: Free-text match against the piece name.
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A page of jewelry.
          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/JewelryList'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /api/v1/jewelry/{slug}:
    get:
      operationId: getJewelryItem
      summary: Get one jewelry piece
      description: Returns a single jewelry piece by URL slug or SKU. Use it to confirm a piece an agent found through `listJewelry` before presenting it, or to resolve a SKU a shopper quotes back.
      tags:
      - Catalog
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      parameters:
      - in: path
        name: slug
        required: true
        description: Product slug or SKU.
        schema:
          type: string
        example: AD-3101
      responses:
        '200':
          description: The piece.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JewelryItem'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
components:
  schemas:
    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'
    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'
    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'
    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'
    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'
    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'
    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'
    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:
    NotFound:
      description: Nothing at that id. `error_description` says where to list what exists.
      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'
    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