openapi: 3.0.1
info:
  title: Connexun Text Analysis APIs
  description: Connexun APIs for text-analysis, which summarizes contents in various languages, and get sentiements of text or tweets.
  version: '2022-10-02T09:00:00Z'
  contact:
    name: Technical Lead
    email: tech.dept@connexun.com
servers:
  - url: 'https://api.connexun.com/text-analysis'
tags:
- name: Text Analysis APIs
paths:
  /summarize:
    post:
      tags:
        - Post articles to be summarized
      summary: Get summary of text along with the ranking of sentences based on sentence number.
      description: Summarizes a valid input content and returns the highest ranked sentences from the text. These sentences in the order of appearence in the main text are then combined, which represents the most weighted sentences of the text also called summary.
      requestBody:
        content:
          application/json:
            schema:
                oneOf:
                    - $ref: '#/components/schemas/SummaryBodyText'
                    - $ref: '#/components/schemas/SummaryBodyUrl'
        required: true
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/summaryResBody'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sentiment:
    post:
      tags:
        - Post text to evaluate its sentiment
      summary: Returns the sentiment of the input text as positive or negative.
      description: This endpoint takes as input text in english language, and evaluates if the overall sentiment of the text is positive or negative. This sentiment along with the score obtained is returned in response as JSON object. The main value which reflect sentiment of a text is score which could be below zero - mostly negative sentiment or above zero - mostly positive. We convert continuous score to two classes negative sentiment (score<=0.0), positive 0.0). Such division is subjective and could be used as it is for text classification by sentiments.
      requestBody:
        content:
          application/json:
            schema:
                oneOf:
                    - $ref: '#/components/schemas/SentimentBodyText'
                    - $ref: '#/components/schemas/SentimentBodyTweetUrl'
                    - $ref: '#/components/schemas/SentimentBodyTweetId'
        required: true
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sentimentResBody'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    AuthTokenHeader:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    SummaryBodyText:
      title: SummaryBodySchemaText
      required:
        - text
        - output_sentences
      type: object
      properties:
        output_sentences:
          type: integer
          description: 'Number of sentences that are required in the output of the summary. This number cannot exceed the total number of sentences that are detected by our tokenizer in the text. In such case an error is returned. Use this parameter define the upper limit of the output sentneces required, which the system then caps to 50% of input sentences. '
        text:
          type: string
          description: Text of article or any other content that needs to be summarized.            
    SummaryBodyUrl:
      title: SummaryBodySchemaURL
      required:
        - url
        - output_sentences
      type: object
      properties:
        output_sentences:
          type: integer
          description: 'Number of sentences that are required in the output of the summary. This number cannot exceed the total number of sentences that are detected by our tokenizer in the text. In such case an error is returned. Use this parameter define the upper limit of the output sentneces required, which the system then caps to 50% of input sentences. '
        url:
            type: string
            description: Link to the article which needs to be summarized. Must be in URL format.
    summaryResBody:
      title: SummarySuccessSchema
      type: object
      properties:
        language:
          type: string
          description: Two letter language code of the language detected in the text.
        sentenceLength:
          type: integer
          description: Number of output sentences that are present in the final summary
        summary:
          type: string
          description: Summary of the text generated.
    SentimentBodyText:
      title: SentimentReqSchemaText
      required:
        - text
      type: object
      properties:
        text:
          type: string
          description: Enter text in English for which sentiments needs to be evaluated. A maximum of 1000 characters including spaces is supported.
    SentimentBodyTweetUrl:
      title: SentimentReqSchemaTweetUrl
      required:
        - tweetUrl
      type: object
      properties:
        tweetUrl:
          type: string
          description: Twitter url of the tweet for which sentiment needs to be evaluated.
    SentimentBodyTweetId:
      title: SentimentReqSchemaTweetId
      required:
        - tweetId
      type: object
      properties:
        tweetId:
          type: string
          description: Id of the tweet extracted from url for which sentiment needs to be evaluated.
    sentimentResBody:
      title: SentimentSuccessSchema
      type: object
      properties:
        Sentiment:
          type: string
        Value:
          type: integer
    Error:
      title: Error Schema
      type: object
      properties:
        message:
          type: string 
    HTTPValidationError:
      title: HTTPValidationError
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            "$ref": "#/components/schemas/ValidationError"
    ValidationError:
      title: ValidationError
      required:
      - loc
      - msg
      - type
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            type: string
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
security:
  - AuthTokenHeader: []
