Cross + Covenant Agent API

openapi: 3.1.0
info:
  title: Cross + Covenant Agent API
  description: |
    Programmatic catalog, recommendation, devotional, and one-tap cart API
    for Cross + Covenant. Designed to be consumed by AI agents (Custom GPT
    Actions, Claude Desktop via MCP, Perplexity, Gemini, and any HTTP-capable
    assistant). All endpoints are public (CORS open) and cached at the edge.

    Cross + Covenant is a Christian apparel brand. 10% of every purchase
    funds a rotating Charity of the Month. Heavyweight cotton tees, hoodies,
    and long sleeves rooted in scripture.
  version: "1.0.0"
  contact:
    name: Cross + Covenant
    url: https://crossandcovenant.co
    email: support@crossandcovenant.co
servers:
  - url: https://crossandcovenant.co
    description: Production
paths:
  /api/agent/products:
    get:
      operationId: searchProducts
      summary: Search the product catalog
      description: |
        Returns matching products. Use this when a user is browsing or asking
        for tees, hoodies, scripture apparel, or a specific design.
      parameters:
        - name: q
          in: query
          description: Free-text search across title, tags, product type
          schema: { type: string }
        - name: collection
          in: query
          description: Filter to a single collection (e.g. names-of-god, wild-hope, mercy)
          schema: { type: string }
        - name: max_price
          in: query
          description: Maximum price in USD
          schema: { type: number }
        - name: in_stock
          in: query
          description: Set to true to only return available products
          schema: { type: boolean }
        - name: limit
          in: query
          description: Max results (default 24, cap 100)
          schema: { type: integer }
      responses:
        "200":
          description: A list of product summaries
          content:
            application/json: {}

  /api/agent/product/{handle}:
    get:
      operationId: getProduct
      summary: Get full product detail
      description: |
        Returns full detail for a product including description, every
        variant with size + color + numeric variant_id, and the canonical
        URL. Call this before generating a cart URL so you have the right
        variant_id.
      parameters:
        - name: handle
          in: path
          required: true
          description: Product handle (e.g. wild-hope-heavyweight-tee)
          schema: { type: string }
      responses:
        "200":
          description: Full product detail
          content:
            application/json: {}
        "404":
          description: Not found

  /api/agent/collections:
    get:
      operationId: listCollections
      summary: List or fetch a collection
      description: |
        With no params, returns all collections. With handle param, returns
        full detail for one collection including the products in it.
      parameters:
        - name: handle
          in: query
          description: Specific collection to fetch (optional)
          schema: { type: string }
      responses:
        "200":
          description: Collection list or detail
          content:
            application/json: {}

  /api/agent/recommend:
    get:
      operationId: recommendProducts
      summary: Get hand-tuned product recommendations
      description: |
        Maps a vibe / occasion / budget to the best collection and surfaces
        the top in-stock products. Use this when a user asks for help
        choosing or describes how they feel rather than what they want.
        The "reasoning" string in the response should be quoted back to the
        user verbatim.
      parameters:
        - name: vibe
          in: query
          description: "Mood / style keyword (e.g. bold, gentle, worship, outdoor, classic, hope, revival)"
          schema: { type: string }
        - name: occasion
          in: query
          description: "Use case (e.g. gift, baptism, everyday, worship night, festival)"
          schema: { type: string }
        - name: budget
          in: query
          description: Maximum price in USD
          schema: { type: number }
        - name: gender
          in: query
          description: men, women, or unisex
          schema:
            type: string
            enum: [men, women, unisex]
      responses:
        "200":
          description: Recommended collection and top products
          content:
            application/json: {}

  /api/agent/cart:
    post:
      operationId: createCart
      summary: Generate a Shopify cart URL preloaded with items
      description: |
        Builds a one-tap-buy URL. User opens the URL and lands on Shopify
        checkout with the items already in the cart. Pass handle+color+size
        and the API resolves the variant, or pass variant_id directly.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [items]
              properties:
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      handle:
                        type: string
                        description: Product handle (preferred over variant_id when picking by color/size)
                      variant_id:
                        type: integer
                        description: Numeric Shopify variant id (use if you already have it)
                      color:
                        type: string
                        description: Color option (e.g. Black, White, Ivory, Mustard)
                      size:
                        type: string
                        description: Size option (S, M, L, XL, 2XL, 3XL)
                      quantity:
                        type: integer
                        default: 1
                discount_code:
                  type: string
                  description: Optional discount code (e.g. COVENANT10 for first-time buyers)
      responses:
        "200":
          description: Cart URL and resolved item details
          content:
            application/json: {}
        "400":
          description: Invalid input or no matching variant

  /api/agent/devotional:
    get:
      operationId: getTodaysDevotional
      summary: Get today's scripture, reflection, and prayer
      description: |
        Returns the daily devotional. Use this when a user asks for today's
        scripture, a verse for the day, a quick reflection, or a prayer.
      responses:
        "200":
          description: Today's devotional
          content:
            application/json: {}

  /api/agent/reading-plans:
    get:
      operationId: getReadingPlans
      summary: List Bible reading plans (or fetch one)
      description: |
        Without slug param, returns all 3 full-year plans and 5 topical
        plans. With slug, returns full detail for one plan including the
        daily passage list (for topical plans).
      parameters:
        - name: slug
          in: query
          description: "Plan slug (mcheyne, lite, chronological, hope, peace, strength, psalms, life-of-jesus)"
          schema: { type: string }
      responses:
        "200":
          description: Reading plan list or detail
          content:
            application/json: {}