openapi: 3.1.0
info:
  title: SpendFuel API
  version: 0.1.0
  description: |
    Public catalog and recommendation API for SpendFuel (https://spendfuel.app).
    Agent-first: prefer MCP at `/mcp` for tool discovery.
  contact:
    name: SpendFuel
    url: https://spendfuel.app
servers:
  - url: https://spendfuel.app
    description: Production
  - url: /
    description: Current origin
paths:
  /api/v1/health:
    get:
      summary: Health check
      operationId: health
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  product: { type: string }
                  version: { type: string }
                  phase: { type: integer }
  /api/v1/catalog:
    get:
      summary: List tools
      operationId: listCatalog
      parameters:
        - name: q
          in: query
          schema: { type: string }
        - name: category
          in: query
          schema: { type: string }
        - name: max_price
          in: query
          schema: { type: number }
        - name: verified
          in: query
          schema: { type: boolean }
        - name: sort
          in: query
          schema:
            type: string
            enum: [rank, price, success_rate, newest]
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100 }
        - name: offset
          in: query
          schema: { type: integer, minimum: 0 }
      responses:
        "200":
          description: Catalog page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogResponse"
  /api/v1/catalog/categories:
    get:
      summary: List categories with counts
      operationId: listCategories
      responses:
        "200":
          description: Categories
  /api/v1/tools/{slug}:
    get:
      summary: Get tool by slug or id
      operationId: getTool
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Tool
        "404":
          description: Not found
  /api/v1/recommend:
    get:
      summary: Budget-aware recommendations
      operationId: recommend
      parameters:
        - name: goal
          in: query
          schema: { type: string }
        - name: budget_usd
          in: query
          schema: { type: number }
        - name: limit
          in: query
          schema: { type: integer }
      responses:
        "200":
          description: Recommendations
components:
  schemas:
    Tool:
      type: object
      properties:
        id: { type: string }
        slug: { type: string }
        name: { type: string }
        description: { type: string, nullable: true }
        url: { type: string }
        mcp_url: { type: string, nullable: true }
        price_usd: { type: number, nullable: true }
        pricing_model: { type: string, nullable: true }
        category: { type: string, nullable: true }
        tags:
          type: array
          items: { type: string }
        verified: { type: boolean }
        success_rate: { type: number }
        total_calls: { type: integer }
        total_spend_usd: { type: number }
        status: { type: string }
        source: { type: string }
    CatalogResponse:
      type: object
      properties:
        tools:
          type: array
          items: { $ref: "#/components/schemas/Tool" }
        total: { type: integer }
        limit: { type: integer }
        offset: { type: integer }
        sort: { type: string }