openapi: 3.0.3
info:
  title: SaaSHub API
  description: >-
    The SaaSHub public API provides programmatic access to SaaSHub's software
    discovery platform. The API offers two primary endpoints: a product
    endpoint that returns data for the first product matching a query, and an
    alternatives endpoint that returns the matching product along with its top
    10 relevant alternatives. Responses follow the JSON:API specification.
    Authentication requires an API key obtained from the SaaSHub user profile.
  version: 1.0.0
  contact:
    name: SaaSHub Support
    url: https://www.saashub.com/site/api
  termsOfService: https://www.saashub.com/site/privacy
servers:
  - url: https://www.saashub.com/api
    description: SaaSHub production API server
tags:
  - name: Products
    description: Software product lookup
  - name: Alternatives
    description: Software alternatives discovery
paths:
  /product/{query}:
    get:
      operationId: getProduct
      summary: Get Product by Name
      description: >-
        Returns data for the first software product matching the query string.
        Returns product details including name, tagline, SaaSHub URL, pricing,
        categories, and basic metadata.
      tags:
        - Products
      parameters:
        - name: query
          in: path
          required: true
          description: >-
            Product name to search for (e.g., "basecamp", "slack", "notion").
            URL-encode spaces and special characters.
          schema:
            type: string
            example: basecamp
        - name: api_key
          in: query
          required: true
          description: >-
            Your SaaSHub API key. Obtain from
            https://www.saashub.com/profile/api_key
          schema:
            type: string
            example: your_api_key_here
      responses:
        '200':
          description: Product data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductResponse'
        '401':
          description: Unauthorized - invalid API key
        '404':
          description: No matching product found
  /alternatives/{query}:
    get:
      operationId: getProductAlternatives
      summary: Get Product Alternatives
      description: >-
        Returns the first matching product for the query along with its top 10
        relevant software alternatives. Useful for competitive analysis and
        software discovery workflows.
      tags:
        - Alternatives
      parameters:
        - name: query
          in: path
          required: true
          description: >-
            Product name to search for and find alternatives to (e.g.,
            "basecamp", "jira", "trello").
          schema:
            type: string
            example: basecamp
        - name: api_key
          in: query
          required: true
          description: Your SaaSHub API key
          schema:
            type: string
            example: your_api_key_here
      responses:
        '200':
          description: Product data with alternatives
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlternativesResponse'
        '401':
          description: Unauthorized - invalid API key
        '404':
          description: No matching product found
components:
  schemas:
    ProductResponse:
      type: object
      description: JSON:API compliant product response
      properties:
        data:
          $ref: '#/components/schemas/ProductData'
    AlternativesResponse:
      type: object
      description: JSON:API compliant alternatives response
      properties:
        data:
          $ref: '#/components/schemas/ProductData'
        included:
          type: array
          description: Top 10 alternative products
          maxItems: 10
          items:
            $ref: '#/components/schemas/ProductData'
    ProductData:
      type: object
      description: JSON:API resource object for a software product
      properties:
        id:
          type: string
          description: Unique product identifier on SaaSHub
          example: basecamp
        type:
          type: string
          description: JSON:API resource type
          example: products
        attributes:
          $ref: '#/components/schemas/ProductAttributes'
    ProductAttributes:
      type: object
      properties:
        name:
          type: string
          description: Product name
          example: Basecamp
        saashubUrl:
          type: string
          format: uri
          description: URL to the product's SaaSHub listing
          example: https://www.saashub.com/basecamp
        tagline:
          type: string
          description: Short product description or tagline
          example: The all-in-one toolkit for working remotely
        status:
          type: string
          description: Product status on SaaSHub
          enum:
            - active
            - discontinued
          example: active
        websiteUrl:
          type: string
          format: uri
          description: Official product website URL
          example: https://basecamp.com
        category:
          type: string
          description: Primary software category
          example: Project Management
        categories:
          type: array
          description: All categories the product belongs to
          items:
            type: string
          example:
            - Project Management
            - Team Collaboration
            - Remote Work
        pricing:
          type: string
          description: Pricing model description
          example: Paid with free trial
        license:
          type: string
          description: Software license type
          example: Proprietary
        openSource:
          type: boolean
          description: Whether the product is open source
          example: false
        upvoteCount:
          type: integer
          description: Number of upvotes on SaaSHub
          example: 1247
        alternativeCount:
          type: integer
          description: Number of alternatives listed
          example: 89