openapi: 3.0.3
info:
  title: Vendr Catalog API
  description: >-
    Provides structured product catalog attributes derived from thousands of unstructured
    software quotes. Enables buyers to understand product breadth, available add-ons,
    pricing tiers, and feature comparisons across the Vendr software catalog. Formerly
    Blissfully, now part of Vendr's SaaS buying and management platform.
  version: '1.0'
  contact:
    name: Vendr API Support
    url: https://developers.vendr.com
  x-generated-from: documentation
servers:
  - url: https://api.vendr.com/v1
    description: Production Server
tags:
  - name: Products
    description: Software product catalog entries
  - name: Vendors
    description: Software vendors and their product portfolios
  - name: Pricing
    description: Pricing intelligence and benchmarks
  - name: Webhooks
    description: Webhook management for event notifications
security:
  - apiKeyAuth: []
paths:
  /products:
    get:
      operationId: listProducts
      summary: Vendr List Software Products
      description: >-
        List software products in the Vendr catalog with structured attributes including
        features, add-ons, pricing tiers, and category information derived from Vendr's
        database of software purchases and quotes.
      tags:
        - Products
      parameters:
        - name: category
          in: query
          description: Filter by product category (e.g., CRM, Security, HR)
          schema:
            type: string
          example: CRM
        - name: vendor_id
          in: query
          description: Filter products by vendor identifier
          schema:
            type: string
          example: vendor-500123
        - name: limit
          in: query
          description: Maximum number of results to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
          example: 20
        - name: offset
          in: query
          description: Number of results to skip for pagination
          schema:
            type: integer
            minimum: 0
          example: 0
      responses:
        '200':
          description: List of software products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'
              examples:
                ListProducts200Example:
                  summary: Default listProducts 200 response
                  x-microcks-default: true
                  value:
                    products:
                      - id: product-500123
                        name: Salesforce Sales Cloud
                        vendor_id: vendor-salesforce
                        category: CRM
                        description: Customer relationship management platform
                    total: 1
                    limit: 20
                    offset: 0
        '401':
          description: Unauthorized - missing or invalid API key
        '429':
          description: Rate limit exceeded - 250 requests per minute
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /products/{product_id}:
    get:
      operationId: getProduct
      summary: Vendr Get Software Product
      description: >-
        Retrieve detailed information for a specific software product including all
        catalog attributes, available add-ons, pricing tiers, and feature list.
      tags:
        - Products
      parameters:
        - name: product_id
          in: path
          required: true
          description: Unique product identifier
          schema:
            type: string
          example: product-500123
      responses:
        '200':
          description: Software product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              examples:
                GetProduct200Example:
                  summary: Default getProduct 200 response
                  x-microcks-default: true
                  value:
                    id: product-500123
                    name: Salesforce Sales Cloud
                    vendor_id: vendor-salesforce
                    category: CRM
                    description: Customer relationship management platform for sales teams
                    features:
                      - Contact Management
                      - Pipeline Management
                      - Reporting and Analytics
        '401':
          description: Unauthorized
        '404':
          description: Product not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /vendors:
    get:
      operationId: listVendors
      summary: Vendr List Software Vendors
      description: >-
        List software vendors in the Vendr catalog with their product portfolios
        and vendor profile information.
      tags:
        - Vendors
      parameters:
        - name: category
          in: query
          description: Filter vendors by category
          schema:
            type: string
          example: CRM
        - name: limit
          in: query
          description: Maximum number of results
          schema:
            type: integer
          example: 20
        - name: offset
          in: query
          description: Offset for pagination
          schema:
            type: integer
          example: 0
      responses:
        '200':
          description: List of vendors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorListResponse'
              examples:
                ListVendors200Example:
                  summary: Default listVendors 200 response
                  x-microcks-default: true
                  value:
                    vendors:
                      - id: vendor-salesforce
                        name: Salesforce
                        website: https://www.salesforce.com
                        category: CRM
                    total: 1
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /pricing:
    post:
      operationId: getPricingInsights
      summary: Vendr Get Pricing Insights
      description: >-
        Retrieve actionable pricing insights including fair price predictions and
        negotiation guidance tailored to the buyer's specific requirements, contract
        size, and company profile. Powered by Vendr's database of real software purchases.
      tags:
        - Pricing
      requestBody:
        required: true
        description: Pricing insight request with product and buyer context
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PricingRequest'
            examples:
              GetPricingInsightsRequestExample:
                summary: Default getPricingInsights request
                x-microcks-default: true
                value:
                  product_id: product-500123
                  seats: 100
                  contract_length_months: 12
                  company_size: mid-market
      responses:
        '200':
          description: Pricing insights and benchmarks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PricingResponse'
              examples:
                GetPricingInsights200Example:
                  summary: Default getPricingInsights 200 response
                  x-microcks-default: true
                  value:
                    product_id: product-500123
                    fair_price_per_seat: 150
                    currency: USD
                    confidence: high
                    negotiation_guidance: Consider asking for a 15-20% discount given your company size and multi-year commitment.
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /webhooks:
    get:
      operationId: listWebhooks
      summary: Vendr List Webhooks
      description: List all configured webhooks for the authenticated account.
      tags:
        - Webhooks
      responses:
        '200':
          description: List of configured webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookListResponse'
              examples:
                ListWebhooks200Example:
                  summary: Default listWebhooks 200 response
                  x-microcks-default: true
                  value:
                    webhooks:
                      - id: webhook-500123
                        url: https://example.com/webhook
                        events:
                          - pricing.updated
                        active: true
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

    post:
      operationId: createWebhook
      summary: Vendr Create Webhook
      description: Create a new webhook to receive event notifications from Vendr's data processing pipeline.
      tags:
        - Webhooks
      requestBody:
        required: true
        description: Webhook configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
            examples:
              CreateWebhookRequestExample:
                summary: Default createWebhook request
                x-microcks-default: true
                value:
                  url: https://example.com/webhook
                  events:
                    - pricing.updated
                    - catalog.updated
                  secret: webhook-secret-abc123
      responses:
        '201':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              examples:
                CreateWebhook201Example:
                  summary: Default createWebhook 201 response
                  x-microcks-default: true
                  value:
                    id: webhook-500123
                    url: https://example.com/webhook
                    events:
                      - pricing.updated
                    active: true
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key for authentication. Contact Vendr support to obtain API access.
        Rate limited to 250 requests per minute and 150,000 per day.

  schemas:
    Product:
      type: object
      description: A software product in the Vendr catalog
      properties:
        id:
          type: string
          description: Unique product identifier
          example: product-500123
        name:
          type: string
          description: Product name
          example: Salesforce Sales Cloud
        vendor_id:
          type: string
          description: Associated vendor identifier
          example: vendor-salesforce
        category:
          type: string
          description: Product category
          example: CRM
        description:
          type: string
          description: Product description
          example: Customer relationship management platform
        features:
          type: array
          description: List of product features
          items:
            type: string
          example:
            - Contact Management
            - Pipeline Management
        add_ons:
          type: array
          description: Available product add-ons
          items:
            type: string

    ProductListResponse:
      type: object
      description: Paginated list of software products
      properties:
        products:
          type: array
          description: List of products
          items:
            $ref: '#/components/schemas/Product'
        total:
          type: integer
          description: Total number of matching products
          example: 250
        limit:
          type: integer
          description: Maximum results per page
          example: 20
        offset:
          type: integer
          description: Current page offset
          example: 0

    Vendor:
      type: object
      description: A software vendor in the Vendr catalog
      properties:
        id:
          type: string
          description: Unique vendor identifier
          example: vendor-salesforce
        name:
          type: string
          description: Vendor name
          example: Salesforce
        website:
          type: string
          format: uri
          description: Vendor website URL
          example: https://www.salesforce.com
        category:
          type: string
          description: Primary product category
          example: CRM

    VendorListResponse:
      type: object
      description: Paginated list of vendors
      properties:
        vendors:
          type: array
          description: List of vendors
          items:
            $ref: '#/components/schemas/Vendor'
        total:
          type: integer
          description: Total number of vendors
          example: 5000

    PricingRequest:
      type: object
      description: Request for pricing insights
      required:
        - product_id
      properties:
        product_id:
          type: string
          description: Product identifier to get pricing for
          example: product-500123
        seats:
          type: integer
          description: Number of seats or licenses
          example: 100
        contract_length_months:
          type: integer
          description: Contract length in months
          example: 12
        company_size:
          type: string
          description: Buyer company size segment
          enum:
            - startup
            - smb
            - mid-market
            - enterprise
          example: mid-market

    PricingResponse:
      type: object
      description: Pricing insights and negotiation guidance
      properties:
        product_id:
          type: string
          description: Product identifier
          example: product-500123
        fair_price_per_seat:
          type: number
          description: Fair market price per seat in USD
          example: 150
        currency:
          type: string
          description: Currency code
          example: USD
        confidence:
          type: string
          description: Confidence level of the pricing prediction
          enum:
            - high
            - medium
            - low
          example: high
        negotiation_guidance:
          type: string
          description: Specific negotiation tips and strategy
          example: Consider asking for a 15-20% discount given your company size.

    WebhookRequest:
      type: object
      description: Webhook creation request
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
          description: HTTPS endpoint to receive webhook events
          example: https://example.com/webhook
        events:
          type: array
          description: List of events to subscribe to
          items:
            type: string
          example:
            - pricing.updated
            - catalog.updated
        secret:
          type: string
          description: Optional signing secret for webhook payload verification
          example: webhook-secret-abc123

    Webhook:
      type: object
      description: A configured webhook
      properties:
        id:
          type: string
          description: Unique webhook identifier
          example: webhook-500123
        url:
          type: string
          format: uri
          description: Webhook endpoint URL
          example: https://example.com/webhook
        events:
          type: array
          description: Subscribed event types
          items:
            type: string
        active:
          type: boolean
          description: Whether the webhook is currently active
          example: true

    WebhookListResponse:
      type: object
      description: List of configured webhooks
      properties:
        webhooks:
          type: array
          description: List of webhooks
          items:
            $ref: '#/components/schemas/Webhook'