openapi: 3.0.0
info:
  title: Aura Gateway Api
  description: Set of endpoints that support the aura gateway api
  version: 3.11.0-main-routing-by-filter-userid-30493.0
tags:
  - name: aura-gateway-core
    description: General aura gateway API operations
  - name: dapr
    description: Dapr pub/sub related operations
  - name: generative
    description: Endpoints related to generative-api.
  - name: feedback
    description: Endpoints related to feedback-api.
servers:
  - url: http://localhost:8989
    description: Local server
  - url: https://svc-ap-current.auracognitive.com
    description: ap-current
paths:
  /healthz:
    get:
      tags:
        - aura-gateway-core
      description: API Health Check.
      operationId: healthz
      x-router-controller: routes
      responses:
        '200':
          description: OK
          headers: {}
  /favicon.ico:
    get:
      tags:
        - aura-gateway-core
      description: Get favicon.
      operationId: favicon
      x-router-controller: routes
      responses:
        '204':
          description: favicon
          headers: {}
  /shutdown:
    get:
      tags:
        - aura-gateway-core
      description: API Shutdown Graceful.
      operationId: shutdown
      x-router-controller: routes
      responses:
        '200':
          description: OK
          headers: {}
  /metrics:
    get:
      tags:
        - aura-gateway-core
      description: Metrics of service.
      operationId: metrics
      x-router-controller: routes
      responses:
        '200':
          description: metrics
          content:
            string:
              schema:
                $ref: '#/components/schemas/MetricsMessage'
  /dapr/subscribe:
    get:
      tags:
        - dapr
        - subscribe
      description: Get the Dapr subscriptions
      operationId: daprSubscribe
      x-router-controller: routes
      parameters:
        - name: correlator
          in: header
          description: Unique identifier of a request to be used as correlator in all systems
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          $ref: '#/components/responses/DaprSubscribeResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /dapr/events:
    post:
      tags:
        - dapr
        - events
      description: Send an event to the Dapr PubSub Service.
      operationId: daprEvents
      x-router-controller: routes
      parameters:
        - name: correlator
          in: header
          description: Unique identifier of a request to be used as correlator in all systems
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DaprEvent'
      responses:
        '200':
          $ref: '#/components/responses/DaprEventsResponse'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /aura-services/v2/aiservices/generative/prompts:
    post:
      tags:
        - generative
      description: Generate new prompt and sent it to OpenAI.
      operationId: postPrompts
      x-router-controller: routes
      security:
        - ApiKeyHeaderAuth: []
      parameters:
        - name: correlator
          in: header
          description: Unique identifier of a request to be used as correlator in all systems
          required: false
          schema:
            type: string
            format: uuid
        - name: x-token-info
          in: header
          description: User authentication data. It might contain JWT object, plain or encoded (to keep backwards compatibility).
          required: true
          schema:
            type: string
        - name: x-correlator
          in: header
          description: unique identifier of a request to be used as correlator in all systems
          required: false
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerativeApiMessage'
            example:
              message: What is aura?
              application:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                preset: openai-gpt-3
      responses:
        '200':
          $ref: '#/components/responses/ValidRequestGenerative'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /aura-services/v2/aiservices/sessions/{session_id}/feedback:
    post:
      tags:
        - feedback
      description: Endpoint to receive a feedback message.
      operationId: postFeedbackMessage
      x-router-controller: routes
      security:
        - ApiKeyHeaderAuth: []
      parameters:
        - name: correlator
          in: header
          description: Unique identifier of a request to be used as correlator in all systems
          schema:
            type: string
            format: uuid
        - name: x-token-info
          in: header
          description: User authentication data. It might contain JWT object, plain or encoded (to keep backwards compatibility).
          required: true
          schema:
            type: string
        - name: x-correlator
          in: header
          description: unique identifier of a request to be used as correlator in all systems
          required: false
          schema:
            type: string
            format: uuid
        - name: session_id
          in: path
          description: Session identifier. Unique string that identifies the session.
          required: true
          schema:
            $ref: '#/components/schemas/StringWithoutSpaces'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackApiMessage'
      responses:
        '204':
          description: Successfully feedback message
          headers:
            correlator:
              description: Correlation id for the different services
              schema:
                type: string
          x-correlator:
            description: Correlation id for the different services
            schema:
              type: string
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  securitySchemes:
    ApiKeyHeaderAuth:
      type: apiKey
      name: Authorization
      in: header
  responses:
    DaprEventsResponse:
      description: Dapr events response
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DaprEventsResponse'
    DaprSubscribeResponse:
      description: Dapr subscriptions response
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DaprSubscriptions'
    InvalidRequest:
      description: Incoming HTTP request format is not valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuraError'
    NotFound:
      description: Incoming HTTP request is not found
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuraError'
    InternalError:
      description: Incoming HTTP request produces an internal error
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuraError'
    TooManyRequests:
      description: The user has sent too many requests in a given amount of time
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuraError'
    ValidRequestGenerative:
      description: Incoming HTTP request format is valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenerativeApiResponse'
          example:
            message: Hello I am Aura, how can I help you?
            session:
              id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
              sequence: 1
              parameters:
                window: 10
                timeout: 30
            prompt_info:
              sizes:
                completion: 100
                prompt: 50
                total: 150
              model_params:
                max_tokens: 100
                temperature: 0.5
                top_p: 0.5
              prompt:
                - role: user
                  content: I want to know more about the beach
              input: I want to know more about the beach
    Unauthorized:
      description: Incoming HTTP request authorization is not valid
      headers:
        correlator:
          description: Correlation id for the different services
          schema:
            type: string
        x-correlator:
          description: Correlation id for the different services
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuraError'
  schemas:
    MetricsMessage:
      type: object
    AuraError:
      type: object
      description: Error response
      properties:
        code:
          type: string
          description: Unique id of the error
        message:
          type: string
          description: Specific and descriptive text of the error
        errors:
          description: With validation error. Swagger error information
          type: array
          items:
            type: object
    DaprEvent:
      type: object
      description: Dapr event object
      properties:
        id:
          type: string
          description: Unique identifier of the event
          format: uuid
        source:
          type: string
          description: Source of the event
        pubsubname:
          type: string
          description: Name of the pubsub
        topic:
          type: string
          description: Name of the topic
        data:
          type: object
          description: Data of the event, can be any JSON object
      additionalProperties: true
    DaprEventsResponse:
      type: object
      description: Dapr events response
      properties:
        status:
          $ref: '#/components/schemas/DaprEventsResponseStatus'
    DaprEventsResponseStatus:
      type: string
      description: Status of the Dapr event processing
      enum:
        - SUCCESS
        - DROP
        - RETRY
    DaprSubscriptions:
      type: array
      description: List of Dapr subscriptions
      items:
        type: object
        properties:
          pubsubname:
            type: string
            description: Name of the pubsub
          topic:
            type: string
            description: Name of the topic
          routes:
            $ref: '#/components/schemas/DaprSubscriptionRoutes'
      required:
        - pubsubname
        - topic
        - routes
    DaprSubscriptionRoutes:
      type: object
      properties:
        default:
          type: string
          description: Default route for the topic
      required:
        - default
    BasicMessage:
      type: object
      description: Contains the basic object message to be sent
      required:
        - message
      properties:
        message:
          type: string
          description: Contains the message to be sent
          pattern: ^(?!\s*$).+
          minLength: 1
    GenerativeApiMessage:
      description: Contains the message to be sent to the generative API
      allOf:
        - $ref: '#/components/schemas/BasicMessage'
        - type: object
          required:
            - application
            - message
          properties:
            userId:
              type: string
              description: Identifier of the user sending the message
            application:
              $ref: '#/components/schemas/ApplicationGenerative'
            session_id:
              description: Contains the session id. Unique string to identify the session. If not provided, a new session will be created.
              allOf:
                - $ref: '#/components/schemas/StringWithoutSpaces'
            reset:
              type: boolean
              example: true
              description: If true, the session will be reset before processing the query. All previous requests will be deleted of the context.
            prompt_params:
              $ref: '#/components/schemas/PromptParams'
            model_params:
              type: object
              description: Contains parameters to configure the request to the llm.
              minProperties: 1
              additionalProperties: true
    Application:
      type: object
      description: Contains the application who is sending the message
      anyOf:
        - properties:
            id:
              description: The application identifier
              type: string
          required:
            - id
        - properties:
            name:
              description: The application name
              type: string
          required:
            - name
    ApplicationGenerative:
      description: Contains the application who is sending the generative message
      allOf:
        - $ref: '#/components/schemas/Application'
        - type: object
          required:
            - preset
          properties:
            preset:
              type: string
              description: The preset to use for this application
    PromptParams:
      type: object
      description: Contains the prompt parameters to be used
      properties:
        preamble:
          type: string
          description: This will override the system part of the prompt that was defined in the preset
          example: I am Aura, how can I help {name} ?
        template:
          type: string
          description: >-
            This will override (or add, if not defined) the template for the user message, as defined in the preset (note: templates allow
            framing the user message to mitigate prompt injection attacks)
        fields_mapped:
          type: object
          description: >-
            A dictionary of parameters to be inserted into the user and/or system templates when building the prompt With this example, the
            preamble will be "I am Aura, how can I help John ?"
          example:
            name: John
        examples:
          type: array
          description: >-
            This will override (or add, if not defined) the examples added to the system prompt, as defined in the preset. Note: they can
            also be included at the end of the preamble, with the same effect)
          items:
            type: string
            description: >-
              This will override (or add, if not defined) the examples added to the system prompt, as defined in the preset. Note: they can
              also be included at the end of the preamble, with the same effect)
    SessionParams:
      type: object
      description: Contains the session parameters
      properties:
        window:
          type: number
          example: 2
          description: The size of the session window, in queries
        timeout:
          type: number
          example: 3600
          description: The time in seconds after which the session will be closed if no queries are received
    Session:
      type: object
      description: Contains the session information
      required:
        - id
        - sequence
      properties:
        id:
          description: session identifier. Unique string that identifies the session.
          allOf:
            - $ref: '#/components/schemas/StringWithoutSpaces'
        sequence:
          type: number
          description: The sequence number message of the session
        parameters:
          $ref: '#/components/schemas/SessionParams'
    PromptInfo:
      type: object
      description: Contains the prompt information
      required:
        - input
      properties:
        sizes:
          $ref: '#/components/schemas/GenerateResponseSizes'
        model_params:
          type: object
          description: Contains parameters to configure the request to the llm.
          minProperties: 1
          additionalProperties: true
        prompt:
          description: The prompts used to generate the output
          type: array
          items:
            $ref: '#/components/schemas/Prompt'
        input:
          type: string
          description: Repeats the user query
    Prompt:
      type: object
      description: The prompt used to generate the output
      required:
        - role
        - content
      properties:
        role:
          type: string
          description: 'The role of the prompt: either user or system'
        content:
          type: string
          description: The text of the prompt
    GenerateResponseSizes:
      description: A dictionary containing the number of input, output and total tokens involved in the generation
      type: object
      required:
        - completion
        - prompt
        - total
      properties:
        completion:
          type: number
          description: Number of tokens in the completion
        prompt:
          type: number
          description: Number of tokens in the prompt
        total:
          type: number
          description: Total number of tokens involved in the generation
    GenerativeApiResponse:
      description: Message response
      type: object
      required:
        - message
        - session
      properties:
        message:
          description: Contains the message.
          type: string
        session:
          $ref: '#/components/schemas/Session'
        prompt_info:
          $ref: '#/components/schemas/PromptInfo'
        references:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Reference'
    StringWithoutSpaces:
      type: string
      example: 79e2646a-a8bb-4355-b79f-42722c066155
      pattern: ^\S+$
      minLength: 1
    Reference:
      type: object
      description: Contains the reference information
      required:
        - title
      properties:
        url:
          type: string
          description: The url of the file that has been used to generate the response
          example: https://my.server.org/docs/project/example-data.pdf
        title:
          type: string
          description: The name of the document that has been used to generate the response
          example: example-data.pdf
        metadata:
          type: object
          description: The metadata of the document that has been used to generate the response
          example:
            page-number: 1
    FeedbackApiMessage:
      type: object
      required:
        - application
        - value
        - msg_corrid
      properties:
        userId:
          type: string
          description: Identifier of the user sending the message
        application:
          $ref: '#/components/schemas/Application'
        value:
          type: boolean
          description: An indicator true/false that signals whether the user considers the response good or not
        msg_corrid:
          example: 79e2646a-a8bb-4355-b79f-42722c066155
          description: Correlator of the request associated with the message for which feedback is given. Unique string that identifies the message.
          allOf:
            - $ref: '#/components/schemas/StringWithoutSpaces'
