V1_Focus.yml

swagger: '2.0'
info:
  x-copyright: 'Copyright IBM Corp. 2017'
  title: Focus
  description: |
    The Focus API provides a mechanism for our Cognitive service to analyze your text to see if there are any potential areas of focus.

    You can send the Focus API a text string that contains one or more sentences, and the service will analyze each sentence.  It will view the text through several different lenses.  A lens is a particular way of looking at the text.  A focus is a result of that lens applied to the given text where the lens has found something interesting. If the lens is "action" or "question", then a particular action or question identified by the lens is a "focus".  The API returns a list of focuses found during the analysis.  That list can be empty (no focuses found), or it might contain one or more focuses.  A confidence level for each focus prediction is included in the response.

  version: 1.0.0
host: api.watsonwork.ibm.com
schemes:
  - https

definitions:
  RequestEntity:
    type: object
    description: "Entity that represents the text to be analyzed"
    properties:
      text:
        description: "The text to be analyzed.  May contain multiple sentences."
        type: string
        maxLength: 10000
        minimum: 1
        maximum: 1
  FocusResponse:
    type: object
    description: "Results of cognitive analysis"
    properties:
      requestId:
        description: "Identifier of this cognitive request, automatically generated by the service."
        type: string
        maxLength: 64
        minimum: 1
        maximum: 1
      focuses:
        type: array
        items:
          $ref: '#/definitions/Focus'
  Focus:
    type: object
    description: "Entity that represents a single focus found for the analyzed text"
    properties:
      lens:
        description: "The symbolic name of the lens that produced this focus."
        type: string
        enum:
          - ActionRequest
          - Commitment
          - Question
      category:
        description: "The particular type of focus that was identified by the lens.  This field may not exist for some lens types."
        type: string
        enum:
          - Schedule
          - Share
      start:
        description: "In the provided text, the index of the starting character of this phrase."
        type: integer
      end:
        description: "In the provided text, the index after the last character of this phrase."
        type: integer
      phrase:
        description: "The phrase in the provided text which matched this focus."
        type: string
      confidence:
        description: "The level of confidence for this focus, on a scale from 0 to 1."
        type: number
      focusVersion:
        description: "The version of the Focus object."
        type: number
      lensId:
        description: "The auto-generated ID of the registered Watson Conversation instance."
        type: string
      applicationId:
        description: "ID of the registered application with which the custom lens is associated."
        type: string

parameters:
  JWT:
    name: Authorization
    in: header
    type: string
    description: |
      Authorization header, in form of `Bearer {access_token}`

      The `access_token` is issued as result of an oauth flow by Watson Work Services.
    required: true
  JsonContentType:
    name: Content-Type
    description: "has to be `application/json`"
    in: header
    type: string
    required: true
  RequestEntity:
    name: RequestEntity
    description: "Representation of the text to be analyzed."
    in: body
    required: true
    schema:
      $ref: '#/definitions/RequestEntity'

responses:
  BadRequest:
    description: "Bad Request: one ore more input values is/are invalid."
  Forbidden:
    description: "Forbidden: caller is not authenticated"
  InternalServerError:
    description: "Internal server error."

paths:
  '/v1/focus':
    post:
      summary: Analyze the provided text, and return any focuses.
      description: |
        Analyze the provided text through several different lenses, returning any focuses found.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/JWT'
        - $ref: '#/parameters/JsonContentType'
        - $ref: "#/parameters/RequestEntity"
      responses:
        '200':
          description: "Text was analyzed successfully."
          schema:
            $ref: '#/definitions/FocusResponse'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/Forbidden'
        '500':
          $ref: '#/responses/InternalServerError'