openapi: 3.1.0
info:
  title: negotiate.v1 Shopper API
  description: |
    Find and negotiate at any negotiate.v1-compliant storefront. Use these
    endpoints to drive a full shopping negotiation: discover compliant stores,
    open a chat session with a store's AI sales rep, and exchange messages
    until the deal closes.
  version: 1.0.0
servers:
  - url: https://negotiate.pier39.ai
    description: Pier39 negotiate.v1 proxy
paths:
  /api/proxy/find_stores:
    get:
      operationId: findStores
      summary: Search the public directory for negotiable stores.
      description: |
        Returns stores from the public negotiate.v1 directory matching the
        query and/or category filters. Use this when the shopper hasn't
        specified a particular store.
      parameters:
        - name: query
          in: query
          required: false
          schema: { type: string }
          description: Free-text search across store name, tagline, categories, and product names.
        - name: category
          in: query
          required: false
          schema: { type: string }
          description: Optional category filter (e.g. "appliances", "electronics", "fitness").
      responses:
        "200":
          description: List of matching stores.
  /api/proxy/discover_store:
    get:
      operationId: discoverStore
      summary: Probe a domain for negotiate.v1 compliance.
      description: Fetches the store's protocol descriptor with full product list and limits.
      parameters:
        - name: domain
          in: query
          required: true
          schema: { type: string }
          description: The store's domain (e.g. "negotiate.pier39.ai", with or without scheme).
      responses:
        "200":
          description: The store's negotiate.v1 descriptor.
  /api/proxy/list_products:
    get:
      operationId: listProducts
      summary: List products available for negotiation at a store.
      parameters:
        - name: domain
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          description: List of products with id, name, list_price.
  /api/proxy/start_negotiation:
    post:
      operationId: startNegotiation
      summary: Open a chat session with the store's AI sales rep for a specific product.
      description: |
        Returns a session_id and the merchant's opening greeting. Save the
        session_id and domain — you'll need both to continue the negotiation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain, product_id]
              properties:
                domain:
                  type: string
                  description: The store's domain.
                product_id:
                  type: string
                  description: One of the product ids from listProducts or discoverStore.
      responses:
        "200":
          description: Session opened.
  /api/proxy/send_message:
    post:
      operationId: sendMessage
      summary: Send one shopper turn in an active negotiation.
      description: |
        Returns the merchant's reply. If response includes "closed":true, the
        negotiation has reached a natural end (deal accepted or shopper walked).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain, session_id, message]
              properties:
                domain:
                  type: string
                  description: The store's domain (same as used in startNegotiation).
                session_id:
                  type: string
                  description: From startNegotiation response.
                message:
                  type: string
                  description: Your shopper turn, plain text. Max 2000 chars.
      responses:
        "200":
          description: Merchant reply.
