openapi: 3.0.3
info:
  title: SaaSHub Alternatives 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: Alternatives
  description: Software alternatives discovery
paths:
  /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:
    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'
    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'
    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