Ada Diamonds Onboarding API

openapi: 3.2.0
info:
  title: Ada Diamonds Agent Onboarding 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: Onboarding
  description: Self-serve credentials.
paths:
  /api/v1/keys:
    post:
      operationId: createApiKey
      summary: Issue a self-serve API key
      description: 'Returns a working API key immediately, with no account and no human approval. Keys are limited to the public read scopes and mainly buy a higher rate limit; the key is shown once and stored only as a hash, so save it. Request `env: "sandbox"` to get a key whose writes are acknowledged and discarded.'
      tags:
      - Onboarding
      security:
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyRequest'
      responses:
        '201':
          description: The key. Store it now; it is not retrievable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/register:
    get:
      operationId: describeRegistration
      summary: How self-serve registration works
      description: 'A short JSON description of the registration endpoint: what to POST, the defaults, and the related OAuth client registration endpoint. Read it once if the 201 body of the POST is not self-explanatory; nothing is created by a GET.'
      tags:
      - Onboarding
      security:
      - {}
      responses:
        '200':
          description: The description.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegistrationDescription'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: registerAgent
      summary: 'Register an agent: a sandbox API key with no body required'
      description: 'Zero-friction registration. POST with an empty body, plain text, a form, or the same JSON as `/api/v1/keys` and get a working key back at once: no account, no email, no approval. `name` defaults to `self-serve agent key` and `env` to `sandbox`; send `env: "production"` for a production key with the same public read scopes. A body shaped like RFC 7591 client metadata (`redirect_uris`, `client_name`) is treated as OAuth dynamic client registration instead. Also served at `/register`, `/signup`, and `/api/agents/register`.'
      tags:
      - Onboarding
      security:
      - {}
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyRequest'
      responses:
        '201':
          description: The key. Store it now; it is not retrievable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/agents/register:
    post:
      operationId: registerAgentAlias
      summary: Alias of POST /api/register
      description: 'Identical to `POST /api/register`: an empty body returns a sandbox API key at once. Kept because some clients try this path first; `/register` and `/signup` are the same door.'
      tags:
      - Onboarding
      security:
      - {}
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyRequest'
      responses:
        '201':
          description: The key. Store it now; it is not retrievable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
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'
  schemas:
    RegistrationDescription:
      type: object
      description: 'How to register: method, defaults, and related endpoints.'
      properties:
        object:
          type: string
          enum:
          - registration_endpoint
        method:
          type: string
          enum:
          - POST
        url:
          type: string
          format: uri
        defaults:
          type: object
          additionalProperties: true
        documentation_url:
          type: string
          format: uri
      additionalProperties: true
    ApiKey:
      type: object
      required:
      - object
      - api_key
      - key_id
      - scopes
      - env
      properties:
        object:
          type: string
          const: api_key
        api_key:
          type: string
          description: Shown once. Store it.
        key_id:
          type: string
        name:
          type: string
        scopes:
          type: array
          items:
            type: string
        env:
          type: string
          enum:
          - sandbox
          - production
        usage:
          type: string
        documentation_url:
          type: string
          format: uri
      additionalProperties: true
    ApiKeyRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: A short label for this key.
          example: my-shopping-agent
        env:
          type: string
          enum:
          - sandbox
          - production
          default: sandbox
        scopes:
          type: array
          items:
            type: string
            enum:
            - catalog:read
            - content:read
        contact_email:
          type: string
          format: email
    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