openapi: 3.0.1
info:
  title: "Rasa - Server Endpoints"
  version: "1.0.0"
  description: >-
    The Rasa server provides endpoints to retrieve trackers of
    conversations as well as endpoints to modify them. Additionally,
    endpoints for training and testing models are provided.
servers:
  - url: "http://localhost:5005"
    description: "Local development server"

paths:
  /:
    get:
      tags:
      - Server Information
      summary: Health endpoint of Rasa Server
      operationId: getHealth
      description: >-
        This URL can be used as an endpoint to run
        health checks against. When the server is running
        this will return 200.
      responses:
        200:
          description: Up and running
          content:
            text/plain:
              schema:
                type: string
                description: Welcome text of Rasa Server
              example: >-
                Hello from Rasa: 1.0.0

  /version:
    get:
      tags:
      - Server Information
      operationId: getVersion
      summary: Version of Rasa
      description: >-
        Returns the version of Rasa.
      responses:
        200:
          description: Version of Rasa
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    description: >-
                      Rasa version number
                  minimum_compatible_version:
                    type: string
                    description: >-
                      Minimum version this Rasa version is
                      able to load models from
              example:
                version: 1.0.0
                minimum_compatible_version: 1.0.0

  /status:
    get:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: getStatus
      tags:
      - Server Information
      summary: Status of the Rasa server
      description: >-
        Information about the server and the currently loaded Rasa model.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  model_id:
                    type: string
                    description: ID of the loaded model
                    example: 75a985b7b86d442ca013d61ea4781b22
                  model_file:
                    type: string
                    description: Path of the loaded model
                    example: 20190429-103105.tar.gz
                  num_active_training_jobs:
                    type: integer
                    description: Number of running training processes
                    example: 2
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'


  /conversations/{conversation_id}/tracker:
    get:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: getConversationTracker
      tags:
      - Tracker
      summary: Retrieve a conversations tracker
      description: >-
        The tracker represents the state of the conversation.
        The state of the tracker is created by applying a
        sequence of events, which modify the state. These
        events can optionally be included in the response.
      parameters:
      - $ref: '#/components/parameters/conversation_id'
      - $ref: '#/components/parameters/include_events'
      - $ref: '#/components/parameters/until'
      responses:
        200:
          $ref: '#/components/responses/200Tracker'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'

  /conversations/{conversation_id}/tracker/events:
    post:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: addConversationTrackerEvents
      tags:
      - Tracker
      summary: Append events to a tracker
      description: >-
        Appends one or multiple new events to the tracker state of the conversation.
        Any existing events will be kept and the new events will be appended,
        updating the existing state.
        If events are appended to a new conversation ID, the tracker will be
        initialised with a new session.
      parameters:
      - $ref: '#/components/parameters/conversation_id'
      - $ref: '#/components/parameters/include_events'
      - $ref: '#/components/parameters/output_channel'
      - in: query
        name: execute_side_effects
        schema:
          type: boolean
          default: False
          description: >-
            If `true`, any ``BotUttered`` event will be forwarded to the
            channel specified in the ``output_channel`` parameter. Any
            ``ReminderScheduled`` or ``ReminderCancelled`` event will also be
            processed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/Event'
              - $ref: '#/components/schemas/EventList'
      responses:
        200:
          $ref: '#/components/responses/200Tracker'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'

    put:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: replaceConversationTrackerEvents
      tags:
      - Tracker
      summary: Replace a trackers events
      description: >-
        Replaces all events of a tracker with the passed
        list of events. This endpoint should not be used to
        modify trackers in a production setup, but rather
        for creating training data.
      parameters:
      - $ref: '#/components/parameters/conversation_id'
      - $ref: '#/components/parameters/include_events'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventList'
      responses:
        200:
          $ref: '#/components/responses/200Tracker'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'

  /conversations/{conversation_id}/story:
    get:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: getConversationStory
      tags:
      - Tracker
      summary: Retrieve an end-to-end story corresponding to a conversation
      description: >-
        The story represents the whole conversation in end-to-end
        format. This can be posted to the '/test/stories' endpoint and used
        as a test.
      parameters:
      - $ref: '#/components/parameters/conversation_id'
      - $ref: '#/components/parameters/until'
      - $ref: '#/components/parameters/all_sessions'
      responses:
        200:
          $ref: '#/components/responses/200Story'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'

  /conversations/{conversation_id}/execute:
    post:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: executeConversationAction
      tags:
      - Tracker
      summary: Run an action in a conversation
      deprecated: true
      description: >-
        DEPRECATED. Runs the action, calling the action server if necessary.
        Any responses sent by the executed action will be forwarded
        to the channel specified in the output_channel parameter.
        If no output channel is specified, any messages that should be
        sent to the user will be included in the response of this endpoint.
      parameters:
      - $ref: '#/components/parameters/conversation_id'
      - $ref: '#/components/parameters/include_events'
      - $ref: '#/components/parameters/output_channel'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRequest'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  tracker:
                    $ref: '#/components/schemas/Tracker'
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/BotMessage'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'

  /conversations/{conversation_id}/trigger_intent:
    post:
      security:
        - TokenAuth: []
        - JWT: []
      operationId: triggerConversationIntent
      tags:
        - Tracker
      summary: Inject an intent into a conversation
      description: >-
        Sends a specified intent and list of entities in place of a
        user message. The bot then predicts and executes a response action.
        Any responses sent by the executed action will be forwarded
        to the channel specified in the ``output_channel`` parameter.
        If no output channel is specified, any messages that should be
        sent to the user will be included in the response of this endpoint.
      parameters:
        - $ref: '#/components/parameters/conversation_id'
        - $ref: '#/components/parameters/include_events'
        - $ref: '#/components/parameters/output_channel'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntentTriggerRequest'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  tracker:
                    $ref: '#/components/schemas/Tracker'
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/BotMessage'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'

  /conversations/{conversation_id}/predict:
    post:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: predictConversationAction
      tags:
      - Tracker
      summary: Predict the next action
      description: >-
        Runs the conversations tracker through the model's
        policies to predict the scores of all actions present
        in the model's domain. Actions are returned in the
        'scores' array, sorted on their 'score' values.
        The state of the tracker is not modified.
      parameters:
      - $ref: '#/components/parameters/conversation_id'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictResult'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'


  /conversations/{conversation_id}/messages:
    post:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: addConversationMessage
      tags:
      - Tracker
      summary: Add a message to a tracker
      description: >-
        Adds a message to a tracker. This doesn't trigger
        the prediction loop. It will log the message
        on the tracker and return, no actions will be
        predicted or run. This is often used together with the
        predict endpoint.
      parameters:
      - $ref: '#/components/parameters/conversation_id'
      - $ref: '#/components/parameters/include_events'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        200:
          $ref: '#/components/responses/200Tracker'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'

  /model/train:
    post:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: trainModel
      tags:
      - Model
      summary: Train a Rasa model
      description: >-
        Trains a new Rasa model. Depending on the data given only a dialogue model,
        only a NLU model, or a model combining a trained dialogue model with an
        NLU model will be trained. The new model is not loaded by default.
      parameters:
      - in: query
        name: save_to_default_model_directory
        schema:
          type: boolean
          default: True
          description: >-
            If `true` (default) the trained model will be saved in the default model
            directory, if `false` it will be saved in a temporary directory
      - in: query
        name: force_training
        schema:
          type: boolean
          default: False
          description: Force a model training even if the data has not changed
      - in: query
        name: augmentation
        schema:
          type: string
          default: 50
          description: How much data augmentation to use during training
      - in: query
        name: num_threads
        schema:
          type: string
          default: 1
          description: Maximum amount of threads to use when training
      - $ref: '#/components/parameters/callback_url'
      requestBody:
        required: true
        description: >-
          The training data should be in YAML format.
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/YAMLTrainingRequest'
            example: |
              pipeline: []

              policies: []

              intents:
                - greet
                - goodbye

              entities: []
              slots: {}
              actions: []
              forms: {}
              e2e_actions: []

              responses:
                utter_greet:
                - text: "Hey! How are you?"

                utter_goodbye:
                - text: "Bye"

              session_config:
                session_expiration_time: 60
                carry_over_slots_to_new_session: true

              nlu:
              - intent: greet
                examples: |
                  - hey
                  - hello

              - intent: goodbye
                examples: |
                  - bye
                  - goodbye

              rules:

              - rule: Say goodbye anytime the user says goodbye
                steps:
                - intent: goodbye
                - action: utter_goodbye

              stories:

              - story: happy path
                steps:
                - intent: greet
                - action: utter_greet
                - intent: goodbye
                - action: utter_goodbye

      responses:
        200:
          description: Zipped Rasa model
          headers:
            filename:
              schema:
                type: string
              description: File name of the trained model.
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/TrainingResult'
        204:
          $ref: '#/components/responses/204Callback'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        500:
          $ref: '#/components/responses/500ServerError'

  /model/test/stories:
    post:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: testModelStories
      tags:
      - Model
      summary: Evaluate stories
      description: >-
        Evaluates one or multiple stories against the currently
        loaded Rasa model.
      parameters:
      - $ref: '#/components/parameters/e2e'
      requestBody:
        required: true
        content:
          text/yml:
            schema:
              $ref: '#/components/schemas/StoriesTrainingData'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluationStoriesResult'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'

  /model/test/intents:
    post:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: testModelIntent
      tags:
      - Model
      summary: Perform an intent evaluation
      description: >-
        Evaluates NLU model against a model or using cross-validation.
      parameters:
      - $ref: '#/components/parameters/model'
      - $ref: '#/components/parameters/callback_url'
      - in: query
        name: cross_validation_folds
        schema:
          type: integer
          default: null
          description: >-
            Number of cross validation folds. If this parameter is specified
            the given training data will be used for a cross-validation instead of
            using it as test set for the specified model. Note that this is only
            supported for YAML data.
      requestBody:
        required: true
        content:
          application/x-yaml:
            schema:
              type: string
              description: >-
                NLU training data and model configuration. The model configuration is
                only required if cross-validation is used.
              example: >-
                nlu:
                - intent: greet
                  examples: |
                    - hey
                    - hello
                    - hi
                - intent: bye
                  examples: |
                    - goodbye
                    - bye
                    - cheers

                pipeline:
                - name: KeywordIntentClassifier
          application/json:
            schema:
              $ref: '#/components/schemas/RasaNLUData'

      responses:
        200:
          description: NLU evaluation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLUEvaluationResult'
        204:
          $ref: '#/components/responses/204Callback'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'

  /model/predict:
    post:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: predictModelAction
      tags:
      - Model
      summary: Predict an action on a temporary state
      description: >-
        Predicts the next action on the tracker state as it is
        posted to this endpoint. Rasa will create a temporary
        tracker from the provided events and will use it to
        predict an action. No messages will be sent and no
        action will be run.
      parameters:
      - $ref: '#/components/parameters/include_events'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventList'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictResult'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        409:
          $ref: '#/components/responses/409Conflict'
        500:
          $ref: '#/components/responses/500ServerError'

  /model/parse:
    post:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: parseModelMessage
      tags:
      - Model
      summary: Parse a message using the Rasa model
      description: >-
        Predicts the intent and entities of the message
        posted to this endpoint. No messages will be stored
        to a conversation and no action will be run. This will
        just retrieve the NLU parse results.
      parameters:
      - $ref: '#/components/parameters/emulation_mode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: Message to be parsed
                  example: "Hello, I am Rasa!"
                message_id:
                  type: string
                  description: Optional ID for message to be parsed
                  example: "b2831e73-1407-4ba0-a861-0f30a42a2a5a"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParseResult'
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        500:
          $ref: '#/components/responses/500ServerError'

  /model:
    put:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: replaceModel
      tags:
      - Model
      summary: Replace the currently loaded model
      description: >-
        Updates the currently loaded model.
        First, tries to load the model from the local (note: local to Rasa server)
        storage system.
        Secondly, tries to load the model from the provided model server configuration.
        Last, tries to load the model from the provided remote storage.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelRequest'
      responses:
        204:
          description: Model was successfully replaced.
        400:
          $ref: '#/components/responses/400BadRequest'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        500:
          $ref: '#/components/responses/500ServerError'

    delete:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: unloadModel
      tags:
      - Model
      summary: Unload the trained model
      description: >-
        Unloads the currently loaded trained model from the server.
      responses:
        204:
          description: Model was sucessfully unloaded.
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'

  /domain:
    get:
      security:
      - TokenAuth: []
      - JWT: []
      operationId: getDomain
      tags:
      - Domain
      summary: Retrieve the loaded domain
      description: >-
        Returns the domain specification the currently loaded
        model is using.
      responses:
        200:
          description: Domain was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Domain'
            application/yaml:
              schema:
                $ref: '#/components/schemas/Domain'
        401:
          $ref: '#/components/responses/401NotAuthenticated'
        403:
          $ref: '#/components/responses/403NotAuthorized'
        406:
          $ref: '#/components/responses/406InvalidHeader'
        500:
          $ref: '#/components/responses/500ServerError'


components:

  securitySchemes:

    TokenAuth:
      type: apiKey
      in: query
      name: token
      description: |
        A plaintext token to secure your server, specified at startup in the argument `--auth-token thisismysecret`
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        A JWT token that is signed using the JWT secret specified at startup in the argument `--jwt-secret thisismysecret`,
        using the `HS256` algorithm.

        The token's payload must contain an object under the `user` key,
        which in turn must contain the `username` and `role` attributes.
        The following is an example payload for a JWT token:

        ```json
        {
            "user": {
                "username": "<sender_id>",
                "role": "user"
            }
        }
        ```

        If the `role` is `admin`, all endpoints are accessible.
        If the `role` is `user`, endpoints with a `sender_id` parameter are only accessible
        if the `sender_id` matches the payload's `username` property.

  parameters:

    conversation_id:
      in: path
      name: conversation_id
      description: Id of the conversation
      example: default
      schema:
        type: string
      required: true
    batch_size:
      in: query
      name: batch_size
      description: Batch size to use for training.
      example: 5
      schema:
        type: number
        default: 5
      required: false
    epochs:
      in: query
      name: epochs
      description: Number of epochs to train.
      example: 30
      schema:
        type: number
        default: 30
      required: false
    e2e:
      in: query
      name: e2e
      description: Perform an end-to-end evaluation on the posted stories.
      example: false
      schema:
        type: boolean
        default: false
      required: false
    all_sessions:
      in: query
      name: all_sessions
      description: >-
          Whether to fetch all sessions in a conversation, or only the latest session
          
          * `true` - fetch all conversation sessions.

          * `false` - [default] fetch only the latest conversation session.

      example: false
      schema:
        type: boolean
        default: false
      required: false
    model:
      in: query
      name: model
      description: >-
        Model that should be used for evaluation.
        If the parameter is set, the model will be
        fetched with the currently loaded configuration
        setup. However, the currently loaded model
        will not be updated. The state of the server
        will not change. If the parameter is not set,
        the currently loaded model will be used for
        the evaluation.
      example: rasa-model.tar.gz
      schema:
        type: string
      required: false
    include_events:
      in: query
      name: include_events
      description: >-
        Specify which events of the tracker the response
        should contain.

        * `ALL` - every logged event.

        * `APPLIED` - only events that contribute to the trackers state. This excludes reverted utterances and actions that got undone.

        * `AFTER_RESTART` -  all events since the last `restarted` event.
          This includes utterances that got reverted and actions that got undone.

        * `NONE` - no events.

      example: AFTER_RESTART
      schema:
        type: string
        default: AFTER_RESTART
        enum:
          - ALL
          - APPLIED
          - AFTER_RESTART
          - NONE
    emulation_mode:
      in: query
      name: emulation_mode
      description: >-
        Specify the emulation mode to use.
        Emulation mode transforms the response JSON to the format expected by the service specified as the emulation_mode.
        Requests must still be sent in the regular Rasa format.

      example: LUIS
      schema:
        type: string
        enum:
          - WIT
          - LUIS
          - DIALOGFLOW
    until:
      in: query
      name: until
      description: >-
        All events previous to the passed timestamp will be replayed.
        Events that occur exactly at the target time will be included.
      example: 1559744410
      schema:
        type: number
        default: None
      required: false
    output_channel:
      in: query
      name: output_channel
      description: >-
        The bot's utterances will be forwarded to this channel. It uses the credentials
        listed in `credentials.yml` to connect. In case the channel does
        not support this, the utterances will be returned in the response body. Use
        `latest` to try to send the messages to the latest channel the user used.
        Currently supported channels are listed in the permitted values for the
        parameter.
      example: "slack"
      schema:
        type: string
        enum:
          - latest
          - slack
          - callback
          - facebook
          - rocketchat
          - telegram
          - twilio
          - webexteams
          - socketio
    callback_url:
      in: query
      name: callback_url
      description: >-
        If specified the call will return immediately with an empty response and status
        code 204. The actual result or any errors will be sent to the given callback
        URL as the body of a post request.
      example: "https://example.com/rasa_evaluations"
      schema:
        type: string
        default: None
      required: false
  responses:

    200Tracker:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Tracker'
    200Story:
      description: Success
      content:
        text/yml:
          example: >-
            - story: story_00055028
              steps:
              - user: |
                  hello
                intent: greet
              - action: utter_ask_howcanhelp
              - user: |
                  I'm looking for a [moderately priced]{"entity": "price", "value": "moderate"} [Indian]{"entity": "cuisine"} restaurant for [two]({"entity": "people"}) people
                intent: inform
              - action: utter_on_it
              - action: utter_ask_location
    204Callback:
      description: >-
        The incoming request specified a `callback_url` and hence the request will
        return immediately with an empty response. The actual response will be sent to
        the provided `callback_url` via POST request.
    400BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            version: "1.0.0"
            status: "failure"
            reason: "BadRequest"
            code: 400
    401NotAuthenticated:
      description: User is not authenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            version: "1.0.0"
            status: "failure"
            reason: "NotAuthenticated"
            message: >-
              User is not authenticated to access resource.
            code: 401
    403NotAuthorized:
      description: User has insufficient permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            version: "1.0.0"
            status: "failure"
            reason: "NotAuthorized"
            message: >-
              User has insufficient permission to access resource.
            code: 403
    406InvalidHeader:
      description: Invalid header provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            version: "1.0.0"
            status: "failure"
            reason: "InvalidHeader"
            message: >-
              Invalid header was provided with the request.
            code: 406
    409Conflict:
      description: The request conflicts with the currently loaded model.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            version: "1.0.0"
            status: "failure"
            reason: "Conflict"
            message: >-
              The request conflicts with the currently loaded model.
            code: 409
    500ServerError:
      description: An unexpected error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            version: "1.0.0"
            status: "ServerError"
            message: >-
              An unexpected error occurred.
            code: 500


  schemas:

    ModelRequest:
      type: object
      properties:
        model_file:
          type: string
          description: Path to model file
          example: "/absolute-path-to-models-directory/models/20190512.tar.gz"
        model_server:
          $ref: '#/components/schemas/EndpointConfig'
        remote_storage:
          description: Name of remote storage system
          type: string
          example: "aws"
          enum:
            - aws
            - gcs
            - azure

    ActionRequest:
      type: object
      properties:
        name:
          description: Name of the action to be executed.
          type: string
          example: utter_greet
        policy:
          description: Name of the policy that predicted the action.
          type: string
          nullable: true
        confidence:
          description: Confidence of the prediction.
          type: number
          nullable: true
          example: 0.987232
      required: ["name"]

    IntentTriggerRequest:
      type: object
      properties:
        name:
          description: Name of the intent to be executed.
          type: string
          example: greet
        entities:
          description: Entities to be passed on.
          type: object
          nullable: true
          example: {"temperature": "high"}
      required: ["name"]

    Message:
      type: object
      properties:
        text:
          type: string
          description: >-
            Message text
          example: Hello!
        sender:
          type: string
          description: >-
            Origin of the message - who sent it
          example: user
          enum:
            - user
        parse_data:
          $ref: '#/components/schemas/ParseResult'
      required: ["text", "sender"]

    Entity:
      type: object
      description: Entities within a message
      properties:
        start:
          type: integer
          description: Char offset of the start
        end:
          type: integer
          description: Char offset of the end
        value:
          type: string
          description: Found value for entity
        entity:
          type: string
          description: Type of the entity
        confidence:
          type: number
      required: ["start", "end", "value", "entity"]

    Intent:
      type: object
      description: Intent of the text
      properties:
        confidence:
          type: number
          description: Confidence of the intent
          example: 0.6323
        name:
          type: string
          description: Intent name
          example: greet
      required: ["confidence", "name"]

    ParseResult:
      type: object
      properties:
        entities:
          type: array
          description: Parsed entities
          items:
            $ref: '#/components/schemas/Entity'
        intent:
          $ref: '#/components/schemas/Intent'
        intent_ranking:
          type: array
          description: Scores of all intents
          items:
            $ref: '#/components/schemas/Intent'
        text:
          type: string
          description: Text of the message
          example: "Hello!"
      description: >-
        NLU parser information. If set, message
        will not be passed through NLU, but instead
        this parsing information will be used.
      required: ["text"]

    LatestAction:
      type: object
      properties:
        action_name:
          type: string
          description: latest action name
        action_text:
          type: string
          description: text of last bot utterance
      description: >-
        Latest bot action.

    Event:
      anyOf:
        - $ref: '#/components/schemas/UserEvent'
        - $ref: '#/components/schemas/BotEvent'
        - $ref: '#/components/schemas/SessionStartedEvent'
        - $ref: '#/components/schemas/ActionEvent'
        - $ref: '#/components/schemas/SlotEvent'
        - $ref: '#/components/schemas/ResetSlotsEvent'
        - $ref: '#/components/schemas/RestartEvent'
        - $ref: '#/components/schemas/ReminderEvent'
        - $ref: '#/components/schemas/CancelReminderEvent'
        - $ref: '#/components/schemas/PauseEvent'
        - $ref: '#/components/schemas/ResumeEvent'
        - $ref: '#/components/schemas/FollowupEvent'
        - $ref: '#/components/schemas/ExportEvent'
        - $ref: '#/components/schemas/UndoEvent'
        - $ref: '#/components/schemas/RewindEvent'
        - $ref: '#/components/schemas/AgentEvent'
        - $ref: '#/components/schemas/EntitiesAddedEvent'
        - $ref: '#/components/schemas/UserFeaturizationEvent'
        - $ref: '#/components/schemas/ActionExecutionRejectedEvent'
        - $ref: '#/components/schemas/FormValidationEvent'
        - $ref: '#/components/schemas/LoopInterruptedEvent'
        - $ref: '#/components/schemas/FormEvent'
        - $ref: '#/components/schemas/ActiveLoopEvent'

    BasicEvent:
      type: object
      properties:
        event:
          type: string
          description: Event name
          example: "slot"
        timestamp:
          type: integer
          description: Time of application
          example: null
        metadata:
           type: object
           properties: {}
           example:
            arbitrary_metadata_key: "some string"
            more_metadata: 1.0
      required: 
        - event

    UserEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          description: >-
            Event for incoming user message.
          properties:
            event:
              enum:
              - user
              example: "user"
            text:
              type: string
              nullable: true
              description: Text of user message.
            input_channel:
              type: string
              nullable: true
            message_id:
              type: string
              nullable: true
            parse_data:
              $ref: '#/components/schemas/ParseResult'

    ActionEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - action
              example: "action"
            policy:
              type: string
              nullable: true
            confidence:
              type: number
              nullable: true
            name:
              type: string
              nullable: true
            hide_rule_turn:
              type: boolean
            action_text:
              type: string
              nullable: true

    SlotEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - slot
              example: "slot"
            name:
              type: string
            value: {}
          required:
            - name
            - value

    EntitiesAddedEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - entities
              example: "entities"
            entities:
              type: array
              items:
                type: object
                properties:
                  start:
                    type: integer
                  end:
                    type: integer
                  entity:
                    type: string
                  confidence:
                    type: number
                  extractor:
                    type: string
                    nullable: true
                  value: {}
                  role:
                    type: string
                    nullable: true
                  group:
                    type: string
                    nullable: true
                required:
                  - entity
                  - value
          required:
            - entities

    UserFeaturizationEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - user_featurization
              example: "user_featurization"

    CancelReminderEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - cancel_reminder
              example: "cancel_reminder"

    ReminderEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - reminder
              example: "reminder"

    ActionExecutionRejectedEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - action_execution_rejected
              example: "action_execution_rejected"

    FormValidationEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - form_validation
              example: "form_validation"

    LoopInterruptedEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - loop_interrupted
              example: "loop_interrupted"

    FormEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - form
              example: "form"

    ActiveLoopEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - active_loop
              example: "active_loop"

    ResetSlotsEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - reset_slots
              example: "reset_slots"

    ResumeEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - resume
              example: "resume"

    PauseEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - pause
              example: "pause"

    FollowupEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - followup
              example: "followup"

    ExportEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - export
              example: "export"

    RestartEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - restart
              example: "restart"

    UndoEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - undo
              example: "undo"

    RewindEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - rewind
              example: "rewind"

    BotEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - bot
              example: "bot"

    SessionStartedEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - session_started
              example: "session_started"

    AgentEvent:
      allOf:
        - $ref: '#/components/schemas/BasicEvent'
        - type: object
          properties:
            event:
              enum:
              - agent
              example: "agent"

    EventList:
      type: array
      items:
        $ref: '#/components/schemas/Event'

    Domain:
      type: object
      description: The bot's domain.
      properties:
        config:
          type: object
          description: Addional option
          properties:
            store_entities_as_slots:
              type: boolean
              description: Store all entites as slot when found
              example: false
        intents:
          type: array
          description: All intent names and properties
          items:
            $ref: '#/components/schemas/IntentDescription'
        entities:
          type: array
          description: All entity names
          items:
            type: string
          example: ['person', 'location']
        slots:
          description: Slot names and configuration
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SlotDescription'
        responses:
          description: Bot response templates
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TemplateDescription'
        actions:
          description: Available action names
          type: array
          items:
            type: string
          example: ['action_greet', 'action_goodbye', 'action_listen']

    BotMessage:
      type: object
      properties:
        recipient_id:
          type: string
          description: Id of the message receiver
        text:
          type: string
          description: Message
        image:
          type: string
          description: Image URL
        buttons:
          type: array
          description: Quick reply buttons
          items:
            type: object
            properties:
              title:
                type: string
                description: Button caption
              payload:
                type: string
                description: Payload to be sent if button is clicked
        attachement:
          type: array
          description: Additional information
          items:
            type: object
            properties:
              title:
                type: string
                description: Attachement caption
              payload:
                type: string
                description: Attachement payload

    Tracker:
      type: object
      description: Conversation tracker which stores the conversation state.
      properties:
        conversation_id:
          type: string
          description: ID of the conversation
          example: default
        slots:
          type: array
          description: Slot values
          items:
            $ref: '#/components/schemas/Slot'
        latest_message:
          $ref: '#/components/schemas/ParseResult'
        latest_event_time:
          type: number
          description: Most recent event time
          example: 1537645578.314389
        followup_action:
          type: string
          description: Deterministic scheduled next action
        paused:
          type: boolean
          description: Bot is paused
          example: false
        events:
          description: Event history
          $ref: '#/components/schemas/EventList'
        latest_input_channel:
          type: string
          description: Communication channel
          example: rest
        latest_action_name:
          type: string
          description: Name of last bot action
          example: action_listen
        latest_action:
          $ref: '#/components/schemas/LatestAction'
        active_loop:
          type: object
          description: Name of the active loop
          properties:
            name:
              type: string
              description: Name of the active loop
              example: restaurant_form

    Error:
      type: object
      properties:
        version:
          type: string
          description: Rasa version
        status:
          type: string
          enum: ["failure"]
          description: Status of the requested action
        message:
          type: string
          description: Error message
        reason:
          type: string
          description: Error category
        details:
          type: object
          description: Additional error information
        help:
          type: string
          description: Optional URL to additonal material
        code:
          type: number
          description: HTTP status code

    PredictResult:
      type: object
      properties:
        scores:
          type: array
          description: Prediction results
          items:
            type: object
            properties:
              action:
                type: string
                description: Action name
                example: utter_greet
              score:
                type: number
                description: Assigned score
                example: 1.0
        policy:
          type: string
          description: >-
            Policy which predicted the most likely action
          example: policy_2_TEDPolicy
        tracker:
          $ref: '#/components/schemas/Tracker'

    EndpointConfig:
      type: object
      properties:
        url:
          type: string
          description: URL pointing to model
        params:
          type: object
          description: Parameters of request
        headers:
          type: object
          description: HTTP headers
        basic_auth:
          description: Basic authentification data
          type: object
        token:
          description: Token
          type: string
        token_name:
          description: Name of token
          type: string
        wait_time_between_pulls:
          type: integer
          description: Time to wait between pulls from model server

    YAMLTrainingRequest:
      type: object
      properties:
        pipeline:
          description: Pipeline list
          type: array
        policies:
          description: Policies list
          type: array
        entities:
          description: Entity list
          type: array
        slots:
          description: Slots list
          type: array
        actions:
          description: Action list
          type: array
        forms:
          description: Forms list
          type: array
        e2e_actions:
          description: E2E Action list
          type: array
        responses:
          description: Bot response templates
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TemplateDescription'
        session_config:
          description: Session configuration options
          type: object
          properties:
            session_expiration_time:
              type: integer
            carry_over_slots_to_new_session:
              type: boolean
        nlu:
          description: Rasa NLU data, array of intents
          type: array
        rules:
          description: Rule list
          type: array
        stories:
          description: Rasa Core stories in YAML format
          type: array

        force:
          type: boolean
          description: >-
            Force a model training even if the data has not changed
          example: false
          deprecated: True
        save_to_default_model_directory:
          type: boolean
          description:  >-
            If `true` (default) the trained model will be saved in the default model
            directory, if `false` it will be saved in a temporary directory
          deprecated: True

    RetrievalIntentsTrainingData:
      type: string
      description: Rasa response texts for retrieval intents in YAML format
      example:  >-
        chitchat/ask_name:
        - text: my name is Sara, Rasa's documentation bot!
        chitchat/ask_weather:
        - text: it's always sunny where I live

    StoriesTrainingData:
      type: string
      description: Rasa Core stories in YAML format
      example: >-
        - story: happy path
          steps:
          - intent: greet
          - action: utter_greet
          - intent: mood_great
          - action: utter_happy

        - story: sad path 1
          steps:
          - intent: greet
          - action: utter_greet
          - intent: mood_unhappy
          - action: utter_cheer_up
          - action: utter_did_that_help
          - intent: affirm
          - action: utter_happy

        - story: sad path 2
          steps:
          - intent: greet
          - action: utter_greet
          - intent: mood_unhappy
          - action: utter_cheer_up
          - action: utter_did_that_help
          - intent: deny
          - action: utter_goodbye

        - story: say goodbye
          steps:
          - intent: goodbye
          - action: utter_goodbye

    TrainingResult:
      type: string
      format: binary

    NLUEvaluationResult:
      type: object
      properties:
        intent_evaluation:
          description: Rasa NLU intent evaluation
          $ref: '#/components/schemas/EvaluationItem'
        response_selection_evaluation:
          description: Evaluation for the retrieval intents
          $ref: '#/components/schemas/EvaluationItem'
        entity_evaluation:
          description: Rasa NLU entity evaluation.
          type: object
          additionalProperties:
            type: object
            description: Evaluation for a specific extractor
            $ref: '#/components/schemas/EvaluationItem'

    EvaluationItem:
      type: object
      description: Evaluation Result
      properties:
        report:
          $ref: '#/components/schemas/EvaluationReport'
        accuracy:
          type: number
          example: 0.19047619047619047
        f1_score:
          type: number
          example: 0.06095238095238095
        precision:
          type: number
          example: 0.036281179138321996
        predictions:
          type: array
          description: The predictions for each item in the test set
          items:
            type: object
            properties:
              intent:
                type: string
                example: greet
              predicted:
                type: string
                example: greet
              text:
                type: string
                example: "hey"
              confidence:
                type: number
                example: 0.9973567
        errors:
          description: The errors which were made during the testing.
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/IntentTestError'
            - $ref: '#/components/schemas/EntityTestError'
            - $ref: '#/components/schemas/ResponseSelectorTestError'

    IntentTestError:
      description: Intent prediction errors which was made during testing
      type: object
      properties:
        text:
          type: string
          description: Test message
          example: are you alright?
        intent_response_key_target:
          description: Expected intent
          type: string
        intent_response_key_prediction:
          description: Predicted intent
          $ref: '#/components/schemas/Intent'

    EntityTestError:
      description: Entity prediction errors which was made during testing
      type: object
      properties:
        text:
          type: string
          description: Test message
          example: what is the weather in zurich?
        entities:
          description: Expected entities
          type: array
          items:
            $ref: '#/components/schemas/Entity'
        predicted_entities:
          description: Predicted entities
          type: array
          items:
            $ref: '#/components/schemas/Entity'

    ResponseSelectorTestError:
      description: Error during response prediction which was made during testing
      type: object
      properties:
        text:
          type: string
          description: Test message
          example: are you alright?
        intent_response_key_target:
          description: Expected retrieval intent
          type: string
        intent_response_key_prediction:
          description: Predicted retrieval intent
          $ref: '#/components/schemas/Intent'

    EvaluationReport:
      type: object
      description: >-
        Sklearn classification report, see
        http://scikit-learn.org/stable/modules/generated/sklearn.metrics.classification_report.html
      example:
        greet:
          precision: 0.123
          recall: 0.456
          f1-score: 0.12
          support: 100
          confused_with:
            chitchat: 3
            nlu_fallback: 5
        micro avg:
          precision: 0.123
          recall: 0.456
          f1-score: 0.12
          support: 100
        macro avg:
          precision: 0.123
          recall: 0.456
          f1-score: 0.12
          support: 100
        weightedq avg:
          precision: 0.123
          recall: 0.456
          f1-score: 0.12
          support: 100

    EvaluationStoriesResult:
      type: object
      properties:
        actions:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
                description: Name of the actual action
                example: utter_ask_howcanhelp
              predicted:
                type: string
                description: Name of the predicted action
                example: utter_ask_howcanhelp
              policy:
                type: string
                description: Machine-learning policy used in the prediction
                example: policy_0_MemoizationPolicy
              confidence:
                type: string
                description: Confidence score of the prediction
                example: 1.0
          description: >-
            Accuracy of the classification,
            http://scikit-learn.org/stable/modules/generated/sklearn.metrics.accuracy_score.html
        is_end_to_end_evaluation:
          type: boolean
          description: True if evaluation is end-to-end, false otherwise
          example: true
        precision:
          type: number
          description: >-
            Precision of the classification, see
            http://scikit-learn.org/stable/modules/generated/sklearn.metrics.precision_score.html
          example: 1.0
        f1:
          type: number
          description: >-
            F1 score of the classification,
            http://scikit-learn.org/stable/modules/generated/sklearn.metrics.precision_score.html
          example: 0.9333333333333333
        accuracy:
          type: number
          description: >-
            Accuracy of the classification,
            http://scikit-learn.org/stable/modules/generated/sklearn.metrics.accuracy_score.html
          example: 0.9
        in_training_data_fraction:
          type: number
          description: >-
            Fraction of stories that are present in the training data of the
            model loaded at evaluation time.
          example: 0.8571428571428571
        report:
          type: object
          description: >-
            Sklearn classification reported extended with information about conversation accuracy.
          additionalProperties:
            type: object
            properties:
              intent_name:
                type: string
              classification_report:
                $ref: '#/components/schemas/EvaluationReport'
          properties:
            conversation_accuracy:
              $ref: '#/components/schemas/ConversationAccuracyReport'

    ConversationAccuracyReport:
      type: object
      properties:
        accuracy:
          type: number
          example: 0.19047619047619047
        correct:
          type: number
          example: 18
        with_warnings:
          type: number
          example: 1
        total:
          type: number
          example: 20

    Slot:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/SlotValue'
      example:
        slot_name: slot_value

    SlotValue:
      oneOf:
        - type: string
        - type: array
          items:
            type: string

    SlotDescription:
      type: object
      properties:
        auto_fill:
          type: boolean
        initial_value:
          type: string
          nullable: true
        type:
          type: string
        values:
          type: array
          items:
            type: string
      required: ['type', 'auto_fill']

    TemplateDescription:
      type: object
      properties:
        text:
          type: string
          description: Template text
      required: ['text']

    IntentDescription:
      type: object
      additionalProperties:
        type: object
        properties:
          use_entities:
            type: boolean

    RasaNLUData:
      type: object
      properties:
        common_examples:
          type: object
          items:
            type: array
            items:
              $ref: '#/components/schemas/CommonExample'
      example:
        rasa_nlu_data:
          common_examples:
          - text: hey
            intent: greet
            entities: []
          - text: dear sir
            intent: greet
            entities: []
          - text: i'm looking for a place to eat
            intent: restaurant_search
            entities: []
          - text: i'm looking for a place in the north of town
            intent: restaurant_search
            entities:
            - start: 31
              end: 36
              value: north
              entity: location
          - text: show me a mexican place in the centre
            intent: restaurant_search
            entities:
            - start: 31
              end: 37
              value: centre
              entity: location
            - start: 10
              end: 17
              value: mexican
              entity: cuisine

    CommonExample:
      type: object
      properties:
        entities:
          description: Expected entities
          type: array
          items:
            $ref: '#/components/schemas/Entity'
        intent:
          type: string
          description: Intent name
        text:
          type: string
          description: Text of the message
          example: "Hello!"