Ada Diamonds Discovery API

openapi: 3.2.0
info:
  title: Ada Diamonds Agent 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: Discovery
  description: API roots and credential checks.
paths:
  /api:
    get:
      operationId: getApiRoot
      summary: 'API root: credential check and endpoint index'
      description: 'Returns a map of every endpoint with its operationId and auth requirement, plus the resolved credential (`anonymous` when the request carries none). No credential is needed: the roots are the first URLs an agent tries, and every catalog and content endpoint behind them is open. Protected endpoints answer 401 with a bare `WWW-Authenticate: Bearer` challenge whose `resource_metadata` parameter points at the OAuth protected-resource document.'
      tags:
      - Discovery
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      responses:
        '200':
          description: The endpoint index.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiIndex'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1:
    get:
      operationId: getV1Probe
      summary: 'Versioned-root probe: the same endpoint index as /api/v1'
      description: Clients that guess `/v1` before reading any docs get the endpoint index, which says where the API is (`/api/v1`) and that it needs no account. The response is identical to `GET /api/v1`, credential resolution included; `/api/v1` remains the canonical root to link and cache.
      tags:
      - Discovery
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      responses:
        '200':
          description: The endpoint index.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiIndex'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1:
    get:
      operationId: getApiV1Root
      summary: 'Versioned API root: credential check and endpoint index'
      description: 'Returns a map of every endpoint with its operationId and auth requirement, plus the resolved credential (`anonymous` when the request carries none). No credential is needed: the roots are the first URLs an agent tries, and every catalog and content endpoint behind them is open. Protected endpoints answer 401 with a bare `WWW-Authenticate: Bearer` challenge whose `resource_metadata` parameter points at the OAuth protected-resource document.'
      tags:
      - Discovery
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      responses:
        '200':
          description: The endpoint index.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiIndex'
        '429':
          $ref: '#/components/responses/RateLimited'
  /pricing.md:
    get:
      operationId: getPricingMarkdown
      summary: Pricing, as markdown
      description: The single free developer tier (rate limits, scopes, sandbox) and how products are priced (setting plus loose diamond, US dollars), with live price bands from the catalog feeds.
      tags:
      - Discovery
      security:
      - {}
      responses:
        '200':
          description: Markdown document
          content:
            text/markdown:
              schema:
                type: string
  /?mode=agent:
    get:
      operationId: getAgentModeView
      summary: Structured agent view of the site
      description: 'Any page URL with `?mode=agent` returns interfaces, authentication, capabilities, content indexes, rate limits, and contact as a linked HTML page. Send `Accept: application/json` for JSON or `Accept: text/markdown` for markdown.'
      tags:
      - Discovery
      security:
      - {}
      responses:
        '200':
          description: Agent view
          content:
            text/html:
              schema:
                type: string
            application/json:
              schema:
                type: object
                required:
                - site
                - generated_at
                - interfaces
                - authentication
                - capabilities
                - content
                - rate_limits
                - contact
                properties:
                  site:
                    type: object
                  generated_at:
                    type: string
                    format: date-time
                  interfaces:
                    type: object
                  authentication:
                    type: object
                  capabilities:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        method:
                          type: string
                          enum:
                          - GET
                          - POST
                        path:
                          type: string
                          format: uri
                        auth:
                          type: string
                        description:
                          type: string
                  content:
                    type: object
                  rate_limits:
                    type: object
                  contact:
                    type: object
            text/markdown:
              schema:
                type: string
  /{section}/llms.txt:
    get:
      operationId: getSectionLlmsTxt
      summary: Section-level llms.txt
      description: A scoped llms.txt for one section of the site. Served at /developers/llms.txt, /api/llms.txt, /docs/llms.txt, /knowledge-base/llms.txt, /mcp/llms.txt, and /developers/commerce/llms.txt.
      tags:
      - Discovery
      security:
      - {}
      parameters:
      - name: section
        in: path
        required: true
        schema:
          type: string
          enum:
          - developers
          - api
          - docs
          - knowledge-base
          - mcp
          - developers/commerce
      responses:
        '200':
          description: llms.txt document
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Unknown section
components:
  schemas:
    ApiIndex:
      type: object
      required:
      - object
      - version
      - endpoints
      - documentation_url
      - openapi_url
      - mcp_url
      properties:
        object:
          type: string
          const: api_index
        name:
          type: string
        version:
          type: string
          example: v1
        base_url:
          type: string
          format: uri
        credential:
          $ref: '#/components/schemas/Credential'
        documentation_url:
          type: string
          format: uri
        openapi_url:
          type: string
          format: uri
        mcp_url:
          type: string
          format: uri
        llms_txt_url:
          type: string
          format: uri
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/ApiIndexEndpoint'
        notes:
          type: array
          items:
            type: string
    ApiIndexEndpoint:
      type: object
      required:
      - method
      - path
      - operationId
      - auth
      properties:
        method:
          type: string
        path:
          type: string
          format: uri
        operationId:
          type: string
        auth:
          type: string
          description: '"none" or the required OAuth scope.'
    Credential:
      type: object
      required:
      - kind
      - env
      - scopes
      properties:
        kind:
          type: string
          enum:
          - anonymous
          - api_key
          - access_token
        env:
          type: string
          enum:
          - production
          - sandbox
        scopes:
          type: array
          items:
            type: string
            enum:
            - catalog:read
            - content:read
            - profile:read
            - orders:read
            - cart:write
            - appointments:write
    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'
  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