openapi: "3.1.0"
info:
  title: GEO Agent
  version: "0.1.0"
  description: Shopify app for AI visibility audits, recommendation benchmarking, and structured product metadata fixes.
servers:
  - url: https://geo-agent.fly.dev
paths:
  /.well-known/agent.json:
    get:
      summary: Agent-facing manifest
      responses:
        "200":
          description: Agent manifest with Shopify billing commerce endpoints.
          content:
            application/json:
              schema:
                type: object
  /.well-known/commerce.json:
    get:
      summary: Agent-readable commerce manifest
      responses:
        "200":
          description: Shopify Billing catalog and checkout constraints.
          content:
            application/json:
              schema:
                type: object
  /api/v1/catalog:
    get:
      summary: List Geo Agent subscription plans
      responses:
        "200":
          description: Static catalog of Shopify Billing plans.
          content:
            application/json:
              schema:
                type: object
  /api/v1/quote:
    get:
      summary: Static quote catalog
      responses:
        "200":
          description: Static pricing for Starter, Growth, and Enterprise plans.
          content:
            application/json:
              schema:
                type: object
  /api/v1/checkout:
    get:
      summary: Shopify Billing checkout handoff
      responses:
        "200":
          description: Stripe Payment Link or Stripe SPT settlement for the one-time audit plus Shopify install URL and billing-approval constraints for app subscriptions. x402 is not enabled.
          content:
            application/json:
              schema:
                type: object
    post:
      summary: Settle one-time AI visibility audit with Stripe SPT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [payment_mode, shared_payment_granted_token, buyer_email]
              properties:
                product_id:
                  type: string
                  enum: [geo_agent_visibility_audit]
                payment_mode:
                  type: string
                  enum: [stripe_spt]
                shared_payment_granted_token:
                  type: string
                buyer_email:
                  type: string
      responses:
        "201":
          description: PaymentIntent succeeded and audit order was recorded in Stripe metadata.
  /:
    get:
      summary: Public product entrypoint
      responses:
        "200":
          description: Product landing page or Shopify install form.
  /auth/login:
    post:
      summary: Start Shopify OAuth
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                shop:
                  type: string
                  example: example.myshopify.com
      responses:
        "302":
          description: Redirects to Shopify OAuth.
  /api/llms-txt:
    get:
      summary: Return generated llms.txt for an installed Shopify shop
      responses:
        "200":
          description: Generated llms.txt content.
          content:
            text/plain:
              schema:
                type: string
        "401":
          description: Missing Shopify app-proxy session.
  /api/product-schema/{handle}:
    get:
      summary: Return product JSON-LD for an installed Shopify shop
      parameters:
        - name: handle
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Product schema response.
          content:
            application/json:
              schema:
                type: object
        "401":
          description: Missing Shopify app-proxy session.
  /api/ucp:
    get:
      summary: Return UCP profile metadata for an installed Shopify shop
      responses:
        "200":
          description: UCP profile response.
          content:
            application/json:
              schema:
                type: object
        "401":
          description: Missing Shopify app-proxy session.