Ada Diamonds Agentic checkout (hosted link) API

openapi: 3.2.0
info:
  title: Ada Diamonds Agent Agentic checkout (hosted link) 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 checkout (hosted link)
paths:
  /api/v1/checkout_links:
    post:
      operationId: createCheckoutLink
      summary: Create a hosted checkout link
      description: 'Assemble a cart from product-feed item ids (`diamond:`, `setting:`, `jewelry:`) and get back a Stripe-hosted checkout URL the buyer opens to pay; no card data passes through the agent. Requires the shipping address (tax and shipping are priced into the link); buyer email is optional and collected on the payment page when missing. Anonymous callers are allowed, and an anonymous or production-credential request without `env: "sandbox"` creates a LIVE, payable Stripe Checkout session; a sandbox credential or `env: "sandbox"` returns a simulated link and creates no Stripe session. (The MCP `create_checkout_link` tool differs: anonymous MCP calls default to sandbox and need `env: "production"` for a live link.) Links expire after 24 hours. On payment, the order flows through the standard pipeline (order confirmation email, jeweler follow-up on size and metal).'
      tags:
      - Agentic checkout (hosted link)
      parameters:
      - in: header
        name: Idempotency-Key
        required: false
        description: Optional but recommended on state-changing requests; a reused key with a different body is rejected with 409.
        schema:
          type: string
          maxLength: 255
      - in: header
        name: Request-Id
        required: false
        description: Trace id; echoed back when provided.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutLinkCreateRequest'
      responses:
        '200':
          description: The cart needs more input; `problems[]` lists what is missing and `url` is null.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutLink'
        '201':
          description: A payable link was created; `url` is the Stripe-hosted checkout page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutLink'
        '400':
          description: Malformed body, unknown item id, or an unavailable product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AcpAddress:
      type: object
      required:
      - line_one
      - city
      - state
      - country
      - postal_code
      properties:
        name:
          type: string
        line_one:
          type: string
        line_two:
          type: string
        city:
          type: string
        state:
          type: string
          description: ISO 3166-2 region code, e.g. NY
        country:
          type: string
          description: ISO 3166-1 alpha-2
        postal_code:
          type: string
        phone_number:
          type: string
          description: E.164
    CheckoutLink:
      type: object
      required:
      - object
      - id
      - url
      - simulated
      - state
      - totals
      properties:
        object:
          type: string
          enum:
          - checkout_link
        id:
          type: string
          description: Session id, `link_<uuid>`.
        url:
          type: string
          nullable: true
          description: Stripe-hosted checkout URL; null while `state` is `needs_input`.
        simulated:
          type: boolean
          description: 'True in sandbox: nothing is payable.'
        expires_at:
          type: string
          nullable: true
          format: date-time
        state:
          type: string
          enum:
          - ready
          - needs_input
        currency:
          type: string
        totals:
          type: object
          description: 'All cents: items_base_amount, discount, subtotal, fulfillment, tax, total.'
        line_items:
          type: array
          items:
            type: object
        messages:
          type: array
          items:
            type: object
        problems:
          type: array
          items:
            type: object
          description: Blocking problems when `state` is `needs_input`.
    CheckoutLinkCreateRequest:
      type: object
      required:
      - items
      - shipping_address
      properties:
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AcpItem'
          description: A complete engagement ring is one setting item plus one diamond item.
        shipping_address:
          $ref: '#/components/schemas/AcpAddress'
        buyer:
          type: object
          properties:
            email:
              type: string
              description: Optional; Stripe collects it on the payment page when missing.
            full_name:
              type: string
            phone_number:
              type: string
        env:
          type: string
          enum:
          - production
          - sandbox
          description: sandbox returns a simulated link and never touches Stripe. Omitted on this REST endpoint, anonymous and production-credential calls default to production and create a live, payable Stripe session.
    AcpItem:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: diamond:<id>, setting:<slug>, or jewelry:<slug>
          example: diamond:LG123456
        quantity:
          type: integer
          minimum: 1
          default: 1
          description: Diamonds are unique stones; quantity must be 1.
    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
  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