Ada Diamonds Bulk API

openapi: 3.2.0
info:
  title: Ada Diamonds Agent Bulk 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: Bulk
  description: Batched reads and asynchronous catalog exports.
paths:
  /api/v1/batch:
    post:
      operationId: batchRequests
      summary: Run several read requests in one call
      description: Executes up to 20 GET requests against the public read endpoints in a single round trip and returns each sub-response with its own status and body. The batch always answers 200 once the envelope is valid, even if individual items fail, so check each item's `status`. Only the read endpoints listed in the `allowed_paths` of an error item can be batched; a batch counts as one request against the rate limit.
      tags:
      - Bulk
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Every sub-response, in request order.
          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/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1/exports:
    post:
      operationId: createExport
      summary: Start a full catalog export (async job)
      description: 'Starts an export of the diamonds, engagement ring, or jewelry catalog with the same filters the list endpoint accepts, and answers **202 Accepted** with a `Location` header pointing at the job''s status URL. Exports complete within seconds: poll `status_url` (honouring `Retry-After`) until `status` is `succeeded`, then download `result_url`. Job ids are self-contained signed tokens valid for 24 hours; there is nothing to cancel.'
      tags:
      - Bulk
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      x-async: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportRequest'
      responses:
        '202':
          description: The export job was accepted. Poll the `Location` URL.
          headers:
            Location:
              description: Job status URL (`GET /api/v1/jobs/{id}`).
              schema:
                type: string
                format: uri
            Retry-After:
              description: Seconds to wait before the first poll (2).
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/exports/{id}:
    get:
      operationId: downloadExport
      summary: Download a finished export
      description: Streams the export as `application/x-ndjson` (one product per line, default) or as a JSON array, depending on the `format` chosen when the job was created. Rows have exactly the field shape of the matching list endpoint, with prices in US dollars. The response is an attachment (`Content-Disposition`) and is never cached.
      tags:
      - Bulk
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      parameters:
      - in: path
        name: id
        required: true
        description: Job id returned by `createExport`.
        schema:
          type: string
        example: job_eyJ0IjoiZXhwb3J0In0.abc
      responses:
        '200':
          description: The export.
          headers:
            Content-Disposition:
              description: e.g. `attachment; filename="ada-diamonds-diamonds-2026-08-25.jsonl"`
              schema:
                type: string
            X-Export-Count:
              description: Number of rows in the export.
              schema:
                type: integer
          content:
            application/x-ndjson:
              schema:
                type: string
                description: One JSON object per line; each is a Diamond, EngagementRing, or JewelryItem.
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/Diamond'
                  - $ref: '#/components/schemas/EngagementRing'
                  - $ref: '#/components/schemas/JewelryItem'
        '401':
          $ref: '#/components/responses/InvalidJobToken'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/v1/jobs/{id}:
    get:
      operationId: getJob
      summary: Get the status of an async job
      description: Reports the state of a job started by `createExport`. A job is `queued` for a moment after creation (the response carries `Retry-After`) and `succeeded` after that, at which point `result_url` is set. Expired jobs (older than 24 hours) return 410; start a new export.
      tags:
      - Bulk
      security:
      - {}
      - apiKey: []
      - oauth2:
        - catalog:read
      parameters:
      - in: path
        name: id
        required: true
        description: Job id returned by `createExport`.
        schema:
          type: string
        example: job_eyJ0IjoiZXhwb3J0In0.abc
      responses:
        '200':
          description: The job.
          headers:
            Retry-After:
              description: 'Present while the job is still `queued`: seconds to wait before polling again.'
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          $ref: '#/components/responses/InvalidJobToken'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          $ref: '#/components/responses/Gone'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    NotFound:
      description: Nothing at that id. `error_description` says where to list what exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidJobToken:
      description: The job id's signature does not verify. Use ids exactly as issued.
      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'
    ServiceUnavailable:
      description: The feature is not configured in this environment. Retry after `Retry-After`.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
    Gone:
      description: The job expired (24 hours). Start a new export.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    BatchResponse:
      type: object
      required:
      - object
      - count
      - responses
      properties:
        object:
          type: string
          const: batch
        count:
          type: integer
        responses:
          type: array
          items:
            $ref: '#/components/schemas/BatchResponseItem'
    VirtualConsultations:
      type: object
      properties:
        available:
          type: boolean
        description:
          type: string
        book_url:
          type: string
          format: uri
        email:
          type: string
          format: email
        telephone:
          type: string
    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'
    Job:
      type: object
      required:
      - object
      - id
      - type
      - status
      - status_url
      - created_at
      - expires_at
      properties:
        object:
          type: string
          const: job
        id:
          type: string
          description: Opaque signed job id. Valid for 24 hours.
        type:
          type: string
          const: export
        status:
          type: string
          enum:
          - queued
          - succeeded
        progress:
          type: integer
          minimum: 0
          maximum: 100
        export:
          type: object
          properties:
            type:
              type: string
              enum:
              - diamonds
              - engagement-rings
              - jewelry
            format:
              type: string
              enum:
              - jsonl
              - json
            filters:
              type: object
              additionalProperties:
                type: string
        status_url:
          type: string
          format: uri
        result_url:
          type:
          - string
          - 'null'
          format: uri
          description: Set once `status` is `succeeded`.
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        expires_at:
          type: string
          format: date-time
        note:
          type: string
    BatchRequestItem:
      type: object
      required:
      - path
      properties:
        id:
          type: string
          description: Echoed back on the matching response. Defaults to the item's index.
          example: stones
        method:
          type: string
          enum:
          - GET
          default: GET
        path:
          type: string
          description: Absolute API path of a public read endpoint.
          example: /api/v1/diamonds
        query:
          type: object
          additionalProperties:
            type:
            - string
            - number
            - boolean
          description: Query parameters, exactly as the endpoint documents them.
          example:
            shape: Oval
            limit: '3'
    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
    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
    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'
    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'
    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'
    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
    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'
    BatchResponseItem:
      type: object
      required:
      - id
      - status
      - body
      properties:
        id:
          type: string
        status:
          type: integer
          description: The HTTP status the endpoint would have returned.
        body:
          description: The endpoint's JSON body, or an Error object for a rejected item.
          oneOf:
          - $ref: '#/components/schemas/DiamondList'
          - $ref: '#/components/schemas/Diamond'
          - $ref: '#/components/schemas/EngagementRingList'
          - $ref: '#/components/schemas/EngagementRing'
          - $ref: '#/components/schemas/JewelryList'
          - $ref: '#/components/schemas/JewelryItem'
          - $ref: '#/components/schemas/ArticleList'
          - $ref: '#/components/schemas/Article'
          - $ref: '#/components/schemas/ShowroomList'
          - $ref: '#/components/schemas/Error'
    BatchRequest:
      type: object
      required:
      - requests
      properties:
        requests:
          type: array
          minItems: 1
          maxItems: 20
          items:
            $ref: '#/components/schemas/BatchRequestItem'
    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'
    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'
    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'
    ExportRequest:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - diamonds
          - engagement-rings
          - jewelry
        format:
          type: string
          enum:
          - jsonl
          - json
          default: jsonl
          description: '`jsonl` streams one product per line; `json` returns one array.'
        filters:
          type: object
          additionalProperties:
            type:
            - string
            - number
          description: Same query keys as the matching list endpoint (e.g. `shape`, `min_price`). Unknown keys are ignored.
          example:
            shape: Oval
            max_price: 5000
    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'
  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