Ada Diamonds Content API

openapi: 3.2.0
info:
  title: Ada Diamonds Agent Content 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: Content
  description: Published guides and company information.
paths:
  /api/v1/knowledge-base:
    get:
      operationId: listArticles
      summary: List published guides and articles
      description: 'Returns a page of Ada Diamonds'' published guides on lab grown diamonds: the 4Cs, CVD versus HPHT growth, shape guides, certification, and buying advice. Each summary carries a `markdown_url`; call `getArticle` or fetch that URL for the full text.'
      tags:
      - Content
      security:
      - {}
      - apiKey: []
      - oauth2:
        - content:read
      parameters:
      - in: query
        name: q
        description: Case-insensitive match against title and summary.
        required: false
        schema:
          type: string
        example: clarity
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A page of articles.
          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/ArticleList'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /api/v1/knowledge-base/{slug}:
    get:
      operationId: getArticle
      summary: Get one article as markdown
      description: Returns a single knowledge base article with its body rendered as markdown, ready to quote or summarise. The slug is the last segment of the article URL and is also returned by `listArticles`.
      tags:
      - Content
      security:
      - {}
      - apiKey: []
      - oauth2:
        - content:read
      parameters:
      - in: path
        name: slug
        required: true
        description: Article slug.
        schema:
          type: string
        example: cvd-lab-diamonds
      responses:
        '200':
          description: The article, body rendered as markdown.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
  /api/v1/showrooms:
    get:
      operationId: listShowrooms
      summary: Showroom locations and remote consultation options
      description: Returns Ada's physical showroom(s) with address, hours, and phone, plus the virtual consultation details that serve shoppers everywhere else. Use it to answer whether someone outside New York can buy from Ada (yes, by video consultation) and where to book.
      tags:
      - Content
      security:
      - {}
      - apiKey: []
      - oauth2:
        - content:read
      responses:
        '200':
          description: Showrooms and virtual consultation details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShowroomList'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    VirtualConsultations:
      type: object
      properties:
        available:
          type: boolean
        description:
          type: string
        book_url:
          type: string
          format: uri
        email:
          type: string
          format: email
        telephone:
          type: string
    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
    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.
    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'
    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'
    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
    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:
    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'
    NotFound:
      description: Nothing at that id. `error_description` says where to list what exists.
      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