openapi: 3.1.0
info:
  title: AURA Elite Nutrition Public API
  version: 1.1.0
  summary: Read-only catalog, delivery and store-information API for AI agents and developers.
  description: "Public API for AURA Elite Nutrition, an Indian sports-nutrition retailer.\n\nNo authentication is required for any operation described here — every endpoint is public and read-mostly. Nothing in this specification places an order or moves money; `invokeAgentTool`'s `calculate_order_payload` prices a basket and returns links a human completes.\n\nDocumentation: https://auraelitenutrition.com/developers · Agent guidance: https://auraelitenutrition.com/agent-instructions.md"
  contact:
    name: AURA Elite Nutrition Support
    email: support@auraelitenutrition.com
    url: https://auraelitenutrition.com/contact
  license:
    name: Proprietary
    url: https://auraelitenutrition.com/policies/terms
servers:
  - url: https://auraelitenutrition.com
    description: Production
externalDocs:
  description: Developer documentation
  url: https://auraelitenutrition.com/developers
tags:
  - name: Agent
    description: WebMCP and MCP interfaces designed for LLM function calling.
  - name: Catalog
    description: Products, search and bundles.
  - name: Meta
    description: Machine-readable descriptions of this API.
paths:
  "/api/agent/tools":
    get:
      operationId: listAgentTools
      tags:
        - Agent
      summary: List the agent tools this store exposes
      description: "Returns the WebMCP manifest: every callable tool with its JSON Schema parameters. Call this first to discover the tool surface, then call invokeAgentTool to run one. Safe to cache for an hour."
      responses:
        "200":
          description: The tool manifest.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ToolManifest"
        "400":
          description: The request was malformed or failed validation.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: Unexpected server error.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
    post:
      operationId: invokeAgentTool
      tags:
        - Agent
      summary: Invoke one agent tool by name
      description: Executes a single tool from the manifest and returns its result. Use this for catalog search, product detail, PIN-code delivery estimates, basket pricing and store information. Unknown tool names return a 400 whose body lists the valid names.
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/ToolInvocation"
      responses:
        "200":
          description: The tool result.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ToolResult"
        "400":
          description: The request was malformed or failed validation.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        "404":
          description: The tool ran but the requested entity does not exist.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: Unexpected server error.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/agent/mcp":
    post:
      operationId: callMcpJsonRpc
      tags:
        - Agent
      summary: Model Context Protocol JSON-RPC 2.0 bridge
      description: Speaks MCP over JSON-RPC 2.0 for clients that already talk MCP. Supports the `tools/list` and `tools/call` methods over the same tools as invokeAgentTool. Prefer this endpoint when wiring the store into an MCP client; prefer invokeAgentTool for plain HTTP function calling.
      requestBody:
        required: true
        content:
          "application/json":
            schema:
              "$ref": "#/components/schemas/JsonRpcRequest"
      responses:
        "200":
          description: A JSON-RPC 2.0 response. Protocol-level and tool-level failures are reported in the `error` member, per JSON-RPC, rather than by HTTP status.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/JsonRpcResponse"
        "500":
          description: Unexpected server error.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/products":
    get:
      operationId: listProducts
      tags:
        - Catalog
      summary: List catalog products
      description: Paginated, filterable listing of published products. Use searchProducts for typeahead and the search_supplements tool for goal- or brand-aware filtering; this operation is the plain paginated view.
      parameters:
        - name: searchQuery
          in: query
          required: false
          description: Free-text match against product name and description.
          schema:
            type: string
        - name: categoryId
          in: query
          required: false
          description: Category identifier or slug to filter by.
          schema:
            type: string
        - name: minPrice
          in: query
          required: false
          description: Lower price bound in INR, inclusive.
          schema:
            type: number
            minimum: 0
        - name: maxPrice
          in: query
          required: false
          description: Upper price bound in INR, inclusive.
          schema:
            type: number
            minimum: 0
        - name: sort
          in: query
          required: false
          description: Result ordering.
          schema:
            type: string
            enum:
              - newest
              - price-low
              - price-high
              - popular
            default: newest
        - name: page
          in: query
          required: false
          description: 1-based page index.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          required: false
          description: Page size.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        "200":
          description: A page of products.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProductPage"
        "400":
          description: The request was malformed or failed validation.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: Unexpected server error.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/products/search":
    get:
      operationId: searchProducts
      tags:
        - Catalog
      summary: Typeahead product search
      description: Returns up to six products matching a free-text query, ordered for autocomplete. An empty or whitespace-only query returns an empty list rather than an error.
      parameters:
        - name: q
          in: query
          required: true
          description: Search term, for example 'whey isolate' or 'creapure'.
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Matching products, at most six.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ProductSearchResult"
        "400":
          description: The request was malformed or failed validation.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: Unexpected server error.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/api/combos":
    get:
      operationId: listCombos
      tags:
        - Catalog
      summary: List bundle offers
      description: Returns the currently merchandised product bundles, each priced below the sum of its parts. Bundles are derived from live catalog stock, so the list changes as inventory does.
      responses:
        "200":
          description: The current bundles.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/ComboList"
        "400":
          description: The request was malformed or failed validation.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
        "500":
          description: Unexpected server error.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
  "/openapi.json":
    get:
      operationId: getOpenApiSpec
      tags:
        - Meta
      summary: Fetch this OpenAPI document
      description: Returns this specification as JSON. The same document is available as YAML at /api/openapi.yaml. Use it to generate function-calling tool definitions without hand-transcribing the endpoints.
      responses:
        "200":
          description: The OpenAPI 3.1 document.
          content:
            "application/json":
              schema:
                type: object
                description: An OpenAPI 3.1 document.
        "500":
          description: Unexpected server error.
          content:
            "application/json":
              schema:
                "$ref": "#/components/schemas/Error"
components:
  schemas:
    Error:
      type: object
      description: Structured error envelope. Returned for every failure on every endpoint; the API never answers a request with an HTML error page.
      required:
        - success
        - error
        - errorCode
        - message
        - documentation
      properties:
        success:
          type: boolean
          enum:
            - false
          description: Always false on an error response.
        error:
          type: string
          description: Human-readable message. Duplicates `message` for backwards compatibility.
        errorCode:
          type: string
          description: Stable machine-readable code to branch on.
          examples:
            - INVALID_REQUEST
            - PRODUCT_NOT_FOUND
            - UNKNOWN_TOOL
            - ROUTE_NOT_FOUND
            - SERVER_ERROR
        message:
          type: string
          description: Human-readable explanation of what went wrong.
        hint:
          type: string
          description: The next call that would succeed, when one exists.
        details:
          description: Field-level validation detail, when the failure was a schema violation.
        documentation:
          type: string
          format: uri
          description: URL of the developer documentation.
    ProductSummary:
      type: object
      description: A catalog product as returned by search and listing operations.
      required:
        - id
        - name
        - slug
        - price
        - inStock
      properties:
        id:
          type: string
          description: Opaque product identifier.
        name:
          type: string
          description: Product display name.
        slug:
          type: string
          description: URL slug; the path is /products/{slug}.
        sku:
          type: string
          description: Stock-keeping unit.
        category:
          type: string
          description: Category display name.
        price:
          type: number
          description: Effective price in INR, after any discount.
        originalPrice:
          type: number
          description: List price (MRP) in INR before discount.
        discountPercent:
          type: number
          description: Discount off the list price, as a percentage.
        hasDiscount:
          type: boolean
          description: True when price is below originalPrice.
        inStock:
          type: boolean
          description: True when at least one unit is available.
        availableStock:
          type: integer
          description: Units currently available.
        rating:
          type: number
          description: Mean review rating; 0 when the product has no reviews.
        reviewCount:
          type: integer
          description: Number of published reviews.
        flavors:
          type: array
          items:
            type: string
          description: Available flavour variants.
        sizes:
          type: array
          items:
            type: string
          description: Available size or weight variants.
        imageUrl:
          type: string
          description: Primary product image URL.
        productUrl:
          type: string
          format: uri
          description: Canonical product page URL.
    Pagination:
      type: object
      description: Offset pagination metadata.
      required:
        - total
        - page
        - limit
      properties:
        total:
          type: integer
          description: Total number of matching products.
        page:
          type: integer
          description: 1-based index of the page returned.
        limit:
          type: integer
          description: Page size used for this response.
        totalPages:
          type: integer
          description: Number of pages at this page size.
    ToolManifest:
      type: object
      description: The WebMCP tool manifest.
      required:
        - status
        - name
        - protocol
        - tools
      properties:
        status:
          type: string
          description: Service status.
          examples:
            - online
        name:
          type: string
          description: Human-readable name of the agent interface.
        version:
          type: string
          description: Manifest version.
        protocol:
          type: string
          description: Protocol the manifest describes.
          examples:
            - WebMCP
        baseUrl:
          type: string
          format: uri
          description: Origin every relative path resolves against.
        tools:
          type: array
          description: Callable tools.
          items:
            type: object
            required:
              - name
              - description
              - parameters
            properties:
              name:
                type: string
                description: Tool identifier, passed as `tool` to invokeAgentTool.
              description:
                type: string
                description: What the tool does and when to reach for it.
              parameters:
                type: object
                description: JSON Schema for the tool's parameters object.
    ToolInvocation:
      type: object
      description: A request to run one tool.
      required:
        - tool
      properties:
        tool:
          type: string
          description: Name of the tool to run, from listAgentTools.
          enum:
            - search_supplements
            - get_product_details
            - check_delivery_pincode
            - calculate_order_payload
            - get_store_info
        parameters:
          type: object
          description: Arguments for the tool, matching that tool's parameter schema. Defaults to an empty object.
          default: {}
    ToolResult:
      type: object
      description: A successful tool invocation.
      required:
        - success
        - tool
        - result
      properties:
        success:
          type: boolean
          enum:
            - true
          description: Always true on success.
        tool:
          type: string
          description: The tool that ran.
        result:
          type: object
          description: Tool-specific payload; see the tool's entry in the manifest.
    JsonRpcRequest:
      type: object
      description: A JSON-RPC 2.0 request envelope.
      required:
        - jsonrpc
        - method
      properties:
        jsonrpc:
          type: string
          enum:
            - "2.0"
          description: Protocol version.
        id:
          description: Correlation identifier echoed back on the response.
          oneOf:
            - type: string
            - type: number
            - type: "null"
        method:
          type: string
          enum:
            - tools/list
            - tools/call
          description: MCP method to invoke.
        params:
          type: object
          description: "Method parameters. For `tools/call`: `{ name, arguments }`."
          properties:
            name:
              type: string
              description: Tool name, for tools/call.
            arguments:
              type: object
              description: Tool arguments, for tools/call.
    JsonRpcResponse:
      type: object
      description: A JSON-RPC 2.0 response envelope.
      required:
        - jsonrpc
      properties:
        jsonrpc:
          type: string
          enum:
            - "2.0"
          description: Protocol version.
        id:
          description: The request's correlation identifier.
          oneOf:
            - type: string
            - type: number
            - type: "null"
        result:
          type: object
          description: Present when the call succeeded.
        error:
          type: object
          description: Present when the call failed.
          required:
            - code
            - message
          properties:
            code:
              type: integer
              description: JSON-RPC error code.
            message:
              type: string
              description: Human-readable failure reason.
            data:
              description: Additional detail, including the tool's own errorCode.
    ProductPage:
      type: object
      description: A page of catalog products.
      required:
        - products
      properties:
        products:
          type: array
          description: Products on this page.
          items:
            "$ref": "#/components/schemas/ProductSummary"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        total:
          type: integer
          description: Total matching products.
        page:
          type: integer
          description: 1-based page index.
        totalPages:
          type: integer
          description: Number of pages.
    ProductSearchResult:
      type: object
      description: Typeahead search results.
      required:
        - success
        - products
      properties:
        success:
          type: boolean
          description: True when the search completed.
        products:
          type: array
          description: Matching products, at most six.
          items:
            "$ref": "#/components/schemas/ProductSummary"
    ComboList:
      type: object
      description: Merchandised product bundles.
      required:
        - success
        - combos
      properties:
        success:
          type: boolean
          description: True when the bundles were built.
        combos:
          type: array
          description: Bundles currently on offer.
          items:
            type: object
            required:
              - id
              - title
              - price
            properties:
              id:
                type: string
                description: Bundle identifier.
              title:
                type: string
                description: Bundle display name.
              badge:
                type: string
                description: Merchandising label.
              price:
                type: number
                description: Bundle price in INR.
              mrp:
                type: number
                description: Sum of list prices in INR.
