Ada Diamonds Appointments API

openapi: 3.2.0
info:
  title: Ada Diamonds Agent Appointments 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: Appointments
  description: Consultation requests.
paths:
  /api/v1/consultations:
    post:
      operationId: requestConsultation
      summary: Request a jeweler consultation
      description: Creates a real consultation request that a jeweler answers by email within one business day. Requires the `appointments:write` scope, which is only issued through the authorization code flow, so the customer has approved the request. Send an `Idempotency-Key` so a retried request cannot create a duplicate lead; sandbox credentials get a 201 without creating anything.
      tags:
      - Appointments
      security:
      - oauth2:
        - appointments:write
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsultationRequest'
      responses:
        '201':
          description: The request was recorded.
          headers:
            Idempotency-Replayed:
              description: '`true` when this is the stored response to an earlier request with the same `Idempotency-Key`.'
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsultationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: A request with this `Idempotency-Key` is still in flight. Retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: This `Idempotency-Key` was already used with a different request body. Use a new key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
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'
    Unauthorized:
      description: A credential is required. The `WWW-Authenticate` header carries the RFC 9728 `resource_metadata` pointer; follow it to the authorization server, or send a self-serve API key.
      headers:
        WWW-Authenticate:
          required: true
          description: 'Bare RFC 6750 challenge: `Bearer realm="Ada Diamonds API", resource_metadata="https://www.adadiamonds.com/.well-known/oauth-protected-resource"`.'
          schema:
            type: string
            example: Bearer realm="Ada Diamonds API", resource_metadata="https://www.adadiamonds.com/.well-known/oauth-protected-resource"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthenticationRequired'
    UpstreamUnavailable:
      description: A catalog or content feed is temporarily unavailable. Retry in a few seconds.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    AuthenticationRequired:
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          authorization_server:
            type: string
            format: uri
            description: RFC 8414 authorization server metadata.
          resource_metadata:
            type: string
            format: uri
            description: RFC 9728 protected resource metadata (same URL as the header parameter).
          auth_guide:
            type: string
            format: uri
          public_endpoints:
            type: array
            items:
              type: string
            description: Endpoints that need no credential.
          self_serve_key:
            type: string
            example: POST /api/v1/keys
    ConsultationRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        phone:
          type: string
        topic:
          type: string
          enum:
          - engagement_ring
          - loose_diamond
          - wedding_band
          - fine_jewelry
          - custom_design
          - other
        message:
          type: string
        budget_usd:
          type: number
        product_url:
          type: string
          format: uri
    ConsultationResponse:
      type: object
      required:
      - object
      - id
      - status
      properties:
        object:
          type: string
          const: consultation_request
        id:
          type: string
        status:
          type: string
          const: received
        sandbox:
          type: boolean
        note:
          type: string
        next_step:
          type: string
        email:
          type: string
          format: email
      additionalProperties: true
    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
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'A client-generated unique key making this request safe to retry. This endpoint creates a Salesforce Lead, so a retry without a key can create a duplicate. Replaying a key with the same body returns the original response with `Idempotency-Replayed: true`; reusing it with a different body returns 422. Keys are honoured for 24 hours.'
      schema:
        type: string
        maxLength: 255
      example: consult-2026-08-22-a1b2c3
  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