Ada Diamonds Agentic commerce discovery API

openapi: 3.2.0
info:
  title: Ada Diamonds Agent Agentic commerce discovery 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: Agentic commerce discovery
paths:
  /.well-known/acp.json:
    get:
      operationId: acpDiscovery
      summary: ACP discovery document
      description: 'Unauthenticated seller capabilities per the ACP discovery RFC: protocol name and versions (2025-09-12 and 2026-04-17), the REST base URL https://www.adadiamonds.com/api/acp, supported services, currencies, and locales. Also carries an `ada` block pointing at the product feed and naming the webhook events and the public sandbox bearer token. Cached publicly for one hour.'
      tags:
      - Agentic commerce discovery
      security:
      - {}
      responses:
        '200':
          description: Protocol versions, base URL, services.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcpDiscovery'
  /.well-known/ucp:
    get:
      operationId: ucpProfile
      summary: UCP business profile
      description: Unauthenticated UCP profile (version 2026-04-08) declaring the REST shopping service at https://www.adadiamonds.com/api/ucp, the `dev.ucp.shopping.checkout` capability, the order webhook configuration when one is set, and the Google Pay payment handler (Stripe as PAYMENT_GATEWAY) when a publishable key is configured. `keys[]` lists Ada's RFC 7517 signing key when outbound webhook signing is enabled. Cached publicly for one hour.
      tags:
      - Agentic commerce discovery
      security:
      - {}
      responses:
        '200':
          description: Services, capabilities, payment handlers, signing keys.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UcpProfile'
  /feeds/acp-products.jsonl:
    get:
      operationId: acpProductFeed
      summary: ACP product feed (JSON Lines)
      description: 'One product per line: every available diamond, engagement ring setting, and jewelry piece, with the item ids checkout accepts. Public, cached one hour.'
      tags:
      - Agentic commerce discovery
      security:
      - {}
      responses:
        '200':
          description: application/x-ndjson stream
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/AcpFeedProduct'
        '503':
          description: Catalog feeds unavailable.
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    AcpFeedProduct:
      type: object
      required:
      - item_id
      - id
      - title
      - description
      - url
      - link
      - image_url
      - image_link
      - price
      - availability
      - brand
      - seller_name
      - seller_url
      - seller_privacy_policy
      - seller_tos
      - is_eligible_search
      - is_eligible_checkout
      properties:
        is_eligible_search:
          type: string
          enum:
          - 'true'
          - 'false'
        enable_search:
          type: string
          enum:
          - 'true'
          - 'false'
        is_eligible_checkout:
          type: string
          enum:
          - 'true'
          - 'false'
        enable_checkout:
          type: string
          enum:
          - 'true'
          - 'false'
        item_id:
          type: string
          example: diamond:LG123456
        id:
          type: string
        title:
          type: string
          maxLength: 150
        description:
          type: string
          maxLength: 5000
        url:
          type: string
          format: uri
        link:
          type: string
          format: uri
        image_url:
          type: string
          format: uri
        image_link:
          type: string
          format: uri
        price:
          type: string
          example: 4250.00 USD
        availability:
          type: string
          enum:
          - in_stock
          - out_of_stock
        inventory_quantity:
          type: integer
          description: 1 for diamonds (unique stones).
        condition:
          type: string
          enum:
          - new
        brand:
          type: string
        mpn:
          type: string
        product_category:
          type: string
        item_group_id:
          type: string
        shipping:
          type: string
          example: US::Insured FedEx:0.00 USD:1:3:1:3
        return_policy:
          type: string
          format: uri
        return_deadline_in_days:
          type: integer
        seller_name:
          type: string
        seller_url:
          type: string
        seller_privacy_policy:
          type: string
        seller_tos:
          type: string
    AcpDiscovery:
      type: object
      required:
      - protocol
      - api_base_url
      - transports
      - capabilities
      properties:
        protocol:
          type: object
          properties:
            name:
              type: string
              enum:
              - acp
            version:
              type: string
            supported_versions:
              type: array
              items:
                type: string
            documentation_url:
              type: string
        api_base_url:
          type: string
          example: https://www.adadiamonds.com/api/acp
        transports:
          type: array
          items:
            type: string
            enum:
            - rest
        capabilities:
          type: object
          properties:
            services:
              type: array
              items:
                type: string
            extensions:
              type: array
            intervention_types:
              type: array
            supported_currencies:
              type: array
              items:
                type: string
    UcpProfile:
      type: object
      required:
      - ucp
      properties:
        ucp:
          type: object
          required:
          - version
          - services
          - payment_handlers
          properties:
            version:
              type: string
            services:
              type: object
            capabilities:
              type: object
            payment_handlers:
              type: object
        keys:
          type: array
          items:
            type: object
            description: RFC 7517 JWK
  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