openapi: 3.2.0
info:
  title: Sentiment Analysis API
  version: 1.0.0
  summary: Analyze text sentiment using VADER lexicon-based analysis
  description: |
    The Sentiment Analysis API provides natural language processing capabilities
    to analyze the emotional tone of text content.
  termsOfService: https://pb33f.io/terms
  contact:
    name: pb33f API Support
    url: https://pb33f.io/support
    email: support@pb33f.io
  license:
    name: MIT
    url: https://opensource.org/license/mit

servers:
  - url: https://api.pb33f.io
    description: pb33f platform

security:
  - apiKey: []

tags:
  - name: sentiment
    description: Sentiment analysis operations

paths:
  /sentiment-check:
    post:
      operationId: analyzeSentiment
      summary: Analyze sentiment of text descriptions
      description: |
        Analyzes one or more text descriptions and returns sentiment scores for each.
        The analysis uses the VADER lexicon to compute a compound sentiment score
        ranging from -1 (most negative) to +1 (most positive).

        Text with a compound score below -0.3 is flagged as `tooSad: true`, and
        the specific negative words contributing to the score are identified.

        ## Batch Processing

        Submit multiple descriptions in a single request for efficient processing.
        Each description must have a unique `id` for correlation with results.

        ## Score Interpretation

        | Score Range | Interpretation    |
        |-------------|-------------------|
        | >= 0.05     | Positive          |
        | > -0.05 and < 0.05 | Neutral    |
        | <= -0.05    | Negative          |
        | < -0.3      | Too Sad (flagged) |
      tags:
        - sentiment
      requestBody:
        description: Array of text descriptions to analyze
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SentimentRequestArray'
            examples:
              singleDescription:
                summary: Single description analysis
                description: Analyze a single text description
                value:
                  - id: 1
                    description: "This API is wonderful and makes development a joy!"
              multipleDescriptions:
                summary: Batch analysis
                description: Analyze multiple descriptions in one request
                value:
                  - id: 1
                    description: "This endpoint is easy to use and well documented."
                  - id: 2
                    description: "The error handling is confusing and frustrating."
                  - id: 3
                    description: "Returns data quickly and reliably."
              negativeContent:
                summary: Negative content example
                description: Example with content that will be flagged as too sad
                value:
                  - id: 1
                    description: "This API was written during a mass layoff. Every endpoint represents a piece of my soul that died during the refactoring."
      responses:
        '200':
          description: Sentiment analysis completed successfully
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SentimentResponse'
              examples:
                positiveResult:
                  summary: Positive sentiment result
                  description: Result for text with positive sentiment
                  value:
                    results:
                      - id: 1
                        tooSad: false
                        score: 0.8516
                mixedResults:
                  summary: Mixed sentiment results
                  description: Batch results with varying sentiments
                  value:
                    results:
                      - id: 1
                        tooSad: false
                        score: 0.6369
                      - id: 2
                        tooSad: true
                        score: -0.5423
                        negativeWords:
                          - confusing
                          - frustrating
                      - id: 3
                        tooSad: false
                        score: 0.4019
                sadResult:
                  summary: Flagged as too sad
                  description: Result for overly negative content
                  value:
                    results:
                      - id: 1
                        tooSad: true
                        score: -0.7845
                        negativeWords:
                          - died
                          - layoff
        '400':
          description: Invalid request format or empty request body
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                parseError:
                  summary: JSON parse error
                  description: Request body could not be parsed as JSON
                  value:
                    title: sentiment service error
                    status: 400
                    detail: unable to parse sentiment request
                    type: https://pb33f.io/platform/errors/sentiment
                emptyRequest:
                  summary: Empty request
                  description: No descriptions provided in request
                  value:
                    title: sentiment service error
                    status: 400
                    detail: no descriptions provided
                    type: https://pb33f.io/platform/errors/sentiment
        '401':
          description: Invalid API key
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                title: authentication error
                status: 401
                detail: API key is invalid
                type: https://pb33f.io/platform/errors/auth
        '429':
          description: Rate limit exceeded
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                title: rate limit exceeded
                status: 429
                detail: You have exceeded the rate limit. Please wait before making more requests.
                type: https://pb33f.io/platform/errors/rate-limit
        '500':
          description: Internal server error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                title: internal server error
                status: 500
                detail: An unexpected error occurred while processing your request
                type: https://pb33f.io/platform/errors/internal

components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: x-pb33f-api
      in: header
      description: |
        API key for authentication. Include this header in all requests (if you have one).

  headers:
    X-RateLimit-Limit:
      description: Maximum number of requests allowed per hour for this API key
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100000
        example: 1000

    X-RateLimit-Remaining:
      description: Number of requests remaining in the current rate limit window
      schema:
        type: integer
        format: int32
        minimum: 0
        maximum: 100000
        example: 999

    X-RateLimit-Reset:
      description: Unix timestamp (seconds since epoch) when the rate limit window resets
      schema:
        type: integer
        format: int64
        minimum: 0
        maximum: 4102444800
        example: 1703548800

    Retry-After:
      description: Number of seconds to wait before retrying the request
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 86400
        example: 3600

  schemas:
    SentimentRequestArray:
      type: array
      description: Array of text descriptions to analyze for sentiment
      minItems: 1
      maxItems: 100
      items:
        $ref: '#/components/schemas/SentimentRequest'
      example:
        - id: 1
          description: "This is a sample description to analyze."

    SentimentRequest:
      type: object
      description: A single text description to analyze
      required:
        - id
        - description
      properties:
        id:
          type: integer
          format: int32
          description: |
            Unique identifier for this description within the batch request.
            Used to correlate results with input descriptions.
          minimum: 0
          maximum: 2147483647
          example: 1
        description:
          type: string
          format: byte
          description: |
            The text content to analyze for sentiment. Can be any length,
            though very short texts may produce less reliable results.
          minLength: 1
          maxLength: 10000
          example: "This API makes integration simple and straightforward."

    SentimentResponse:
      type: object
      description: Response containing sentiment analysis results for all submitted descriptions
      required:
        - results
      properties:
        results:
          type: array
          description: Array of sentiment results corresponding to each input description
          maxItems: 100
          items:
            $ref: '#/components/schemas/SentimentResult'
          example:
            - id: 1
              tooSad: false
              score: 0.6369

    SentimentResult:
      type: object
      description: Sentiment analysis result for a single description
      required:
        - id
        - tooSad
        - score
      properties:
        id:
          type: integer
          format: int32
          description: The identifier from the corresponding input description
          minimum: 0
          maximum: 2147483647
          example: 1
        tooSad:
          type: boolean
          description: |
            Flag indicating whether the text sentiment is below the sadness threshold (-0.3).
            When true, the description is considered overly negative and may need revision.
          example: false
        score:
          type: number
          format: double
          description: |
            Compound sentiment score ranging from -1.0 (most negative) to +1.0 (most positive).
            This score normalizes the sum of all lexicon ratings to provide a single
            measure of sentiment intensity.
          minimum: -1.0
          maximum: 1.0
          example: 0.6369
        negativeWords:
          type: array
          description: |
            List of specific words that contributed to negative sentiment.
            Only populated when tooSad is true. Words are lowercased and deduplicated.
          maxItems: 50
          items:
            type: string
            format: byte
            description: A word from the VADER lexicon with negative sentiment score
            maxLength: 100
            example: "frustrating"
          example:
            - "confusing"
            - "frustrating"

    Error:
      type: object
      description: RFC 7807 Problem Details error response
      required:
        - title
        - status
        - detail
        - type
      properties:
        title:
          type: string
          format: byte
          description: A short human-readable summary of the problem type
          maxLength: 200
          example: "sentiment service error"
        status:
          type: integer
          format: int32
          description: The HTTP status code for this error response
          minimum: 400
          maximum: 599
          example: 400
        detail:
          type: string
          format: byte
          description: A human-readable explanation specific to this error occurrence
          maxLength: 1000
          example: "unable to parse sentiment request"
        type:
          type: string
          format: uri
          description: A URI reference that identifies the problem type
          maxLength: 500
          example: "https://pb33f.io/platform/errors/sentiment"